Секция test в конфигурации

Секция test в конфигурации Vite используется для настройки среды тестирования при работе с Vitest. Несмотря на то что Vitest тесно интегрирован с Vite и наследует многие его механизмы, тестовая среда имеет собственный набор параметров, влияющих на запуск тестов, обработку модулей, окружение исполнения, покрытие кода, мокирование, таймауты и поведение раннера.

Конфигурация располагается внутри vite.config.js, vite.config.ts или отдельного файла vitest.config.ts.

Пример базовой структуры:

import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
  },
})

При использовании vitest/config конфигурация выглядит следующим образом:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
  },
})

Подключение Vitest к Vite

Vitest использует инфраструктуру Vite:

  • систему резолвинга модулей;
  • алиасы;
  • плагины;
  • трансформацию ES-модулей;
  • HMR-инфраструктуру;
  • оптимизацию зависимостей.

Благодаря этому тесты работают в среде, максимально близкой к реальному приложению.

Пример:

import { defineConfig } from 'vitest/config'
import path from 'node:path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },

  test: {
    globals: true,
  },
})

Тот же алиас автоматически будет доступен в тестах:

import { sum } from '@/utils/sum'

Параметр globals

Параметр globals включает глобальные функции тестирования:

test: {
  globals: true,
}

После этого становятся доступны:

  • describe
  • it
  • test
  • expect
  • beforeEach
  • afterEach
  • vi

Без необходимости импортировать их вручную.

Пример:

describe('math', () => {
  it('adds numbers', () => {
    expect(1 + 1).toBe(2)
  })
})

Если globals: false, требуется импорт:

import { describe, it, expect } from 'vitest'

Преимущества отключения globals

Во многих крупных проектах глобальный режим отключают:

test: {
  globals: false,
}

Это позволяет:

  • избегать конфликтов имён;
  • улучшать автодополнение IDE;
  • делать зависимости файла явными;
  • упрощать миграцию между тестовыми раннерами.

Параметр environment

Определяет окружение выполнения тестов.

node

Среда Node.js.

test: {
  environment: 'node',
}

Подходит для:

  • backend-логики;
  • утилит;
  • серверных модулей;
  • файловой системы;
  • API Node.js.

Пример:

import fs from 'node:fs'

test('reads file', () => {
  const content = fs.readFileSync('./test.txt', 'utf8')

  expect(content).toContain('hello')
})

jsdom

Эмуляция браузера через JSDOM.

test: {
  environment: 'jsdom',
}

Используется для:

  • React;
  • Vue;
  • DOM API;
  • browser events;
  • компонентного тестирования.

Пример:

document.body.innerHTML = `
  <button id="btn">Click</button>
`

const button = document.querySelector('#btn')

expect(button?.textContent).toBe('Click')

happy-dom

Более быстрая DOM-реализация.

test: {
  environment: 'happy-dom',
}

Особенности:

  • выше производительность;
  • меньше совместимость;
  • быстрее запуск больших наборов тестов.

Часто применяется в CI-средах.

edge-runtime

Эмуляция Edge Runtime.

test: {
  environment: 'edge-runtime',
}

Подходит для:

  • middleware;
  • edge functions;
  • serverless runtime.

Параметр environmentOptions

Позволяет передавать параметры конкретному окружению.

Пример для JSDOM:

test: {
  environment: 'jsdom',

  environmentOptions: {
    jsdom: {
      url: 'https://example.com',
    },
  },
}

Это влияет на:

window.location.href

Параметр setupFiles

Файлы предварительной инициализации.

test: {
  setupFiles: ['./tests/setup.ts'],
}

Файл выполняется перед тестами.

Пример:

import '@testing-library/jest-dom'

Несколько setup-файлов

test: {
  setupFiles: [
    './tests/dom.ts',
    './tests/mocks.ts',
    './tests/polyfills.ts',
  ],
}

Параметр include

Определяет список тестовых файлов.

test: {
  include: ['src/**/*.test.ts'],
}

По умолчанию Vitest ищет:

*.test.*
*.spec.*

Параметр exclude

Исключение файлов.

test: {
  exclude: [
    'node_modules',
    'dist',
    'e2e',
  ],
}

Параметр watch

Режим наблюдения за файлами.

test: {
  watch: true,
}

При изменении файлов тесты запускаются автоматически.

Для CI обычно отключают:

test: {
  watch: false,
}

Параметр reporters

Настройка форматов вывода.

Базовый reporter

test: {
  reporters: ['default'],
}

Verbose reporter

test: {
  reporters: ['verbose'],
}

Выводит каждый тест отдельно.

JUnit reporter

test: {
  reporters: ['junit'],
}

Используется в CI/CD.

Несколько репортёров

test: {
  reporters: [
    'default',
    'json',
    'html',
  ],
}

Параметр outputFile

Файл сохранения отчёта.

test: {
  reporters: ['json'],

  outputFile: {
    json: './reports/tests.json',
  },
}

Параметр coverage

Настройка покрытия кода.

Включение покрытия

test: {
  coverage: {
    enabled: true,
  },
}

Provider покрытия

V8

coverage: {
  provider: 'v8',
}

Быстрее и используется по умолчанию.

Istanbul

coverage: {
  provider: 'istanbul',
}

Даёт более гибкую аналитику.

Форматы отчётов

coverage: {
  reporter: [
    'text',
    'html',
    'json',
  ],
}

Исключение файлов

coverage: {
  exclude: [
    'tests/',
    'src/types/',
  ],
}

Порог покрытия

coverage: {
  thresholds: {
    lines: 90,
    functions: 90,
    branches: 80,
    statements: 90,
  },
}

Если покрытие ниже порога — тесты завершаются ошибкой.

Параметр mockReset

Автоматический сброс моков.

test: {
  mockReset: true,
}

Эквивалент:

vi.resetAllMocks()

после каждого теста.

Параметр restoreMocks

Восстанавливает оригинальные реализации.

test: {
  restoreMocks: true,
}

Особенно полезно при spyOn.

Параметр clearMocks

Очищает историю вызовов.

test: {
  clearMocks: true,
}

Сбрасывает:

mock.calls

Различия reset / clear / restore

clearMocks

Очищает историю вызовов:

mock.calls = []

mockReset

Дополнительно удаляет реализации:

mockImplementation(() => {})

restoreMocks

Возвращает оригинальные функции.

Параметр threads

Управление многопоточностью.

test: {
  threads: true,
}

Vitest запускает тесты параллельно.

Отключение потоков

test: {
  threads: false,
}

Полезно для:

  • нестабильных тестов;
  • shared state;
  • тестирования файловой системы;
  • race conditions.

Параметр maxThreads

Максимальное число потоков.

test: {
  maxThreads: 4,
}

Параметр minThreads

Минимальное число потоков.

test: {
  minThreads: 2,
}

Параметр testTimeout

Глобальный таймаут теста.

test: {
  testTimeout: 5000,
}

Параметр hookTimeout

Таймаут lifecycle hooks.

test: {
  hookTimeout: 10000,
}

Применяется к:

  • beforeAll
  • beforeEach
  • afterEach
  • afterAll

Параметр teardownTimeout

Таймаут завершения worker-процессов.

test: {
  teardownTimeout: 10000,
}

Параметр bail

Остановка после определённого количества ошибок.

test: {
  bail: 1,
}

После первого падения выполнение прекращается.

Параметр silent

Подавление логов.

test: {
  silent: true,
}

Параметр logHeapUsage

Логирование потребления памяти.

test: {
  logHeapUsage: true,
}

Полезно при поиске memory leak.

Параметр allowOnly

Контроль .only.

test: {
  allowOnly: false,
}

Запрещает коммит тестов с:

it.only()
describe.only()

Обычно включается в CI.

Параметр passWithNoTests

Разрешает успешный запуск без тестов.

test: {
  passWithNoTests: true,
}

Параметр isolate

Изоляция тестовых файлов.

test: {
  isolate: true,
}

Каждый файл получает отдельный контекст выполнения.

Отключение изоляции

test: {
  isolate: false,
}

Иногда ускоряет запуск, но может приводить к утечкам состояния.

Параметр pool

Тип пула worker-процессов.

threads

test: {
  pool: 'threads',
}

Использует worker threads.

forks

test: {
  pool: 'forks',
}

Использует child process.

Полезно при несовместимости native-модулей с threads.

Параметр deps

Настройка обработки зависимостей.

Inline dependencies

test: {
  deps: {
    inline: ['lodash-es'],
  },
}

Позволяет трансформировать ESM-пакеты.

External dependencies

test: {
  deps: {
    external: ['large-lib'],
  },
}

Параметр alias

Локальные алиасы тестовой среды.

test: {
  alias: {
    '@mocks': '/tests/mocks',
  },
}

Параметр css

Обработка CSS в тестах.

test: {
  css: true,
}

Отключение CSS

test: {
  css: false,
}

Ускоряет выполнение.

Параметр sequence

Контроль порядка выполнения.

test: {
  sequence: {
    shuffle: true,
  },
}

Shuffle

Перемешивание тестов помогает находить скрытые зависимости.

Concurrent

test: {
  sequence: {
    concurrent: true,
  },
}

Параметр benchmark

Настройки benchmark-тестов.

test: {
  benchmark: {
    include: ['bench/**/*.bench.ts'],
  },
}

Параметр typecheck

Проверка типов TypeScript.

test: {
  typecheck: {
    enabled: true,
  },
}

Отдельные include-файлы

typecheck: {
  include: ['src/**/*.test-d.ts'],
}

Полная конфигурация секции test

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,

    environment: 'jsdom',

    setupFiles: [
      './tests/setup.ts',
    ],

    include: [
      'src/**/*.test.ts',
    ],

    exclude: [
      'dist',
      'node_modules',
    ],

    coverage: {
      enabled: true,

      provider: 'v8',

      reporter: [
        'text',
        'html',
      ],

      thresholds: {
        lines: 90,
        functions: 90,
        branches: 80,
        statements: 90,
      },
    },

    clearMocks: true,
    restoreMocks: true,

    threads: true,

    testTimeout: 5000,

    hookTimeout: 10000,

    reporters: [
      'default',
      'html',
    ],

    allowOnly: false,
  },
})

Практическая структура тестовой конфигурации

Конфигурация frontend-приложения

test: {
  globals: true,

  environment: 'jsdom',

  setupFiles: ['./tests/setup.ts'],

  css: true,

  coverage: {
    provider: 'v8',
  },
}

Конфигурация backend-проекта

test: {
  globals: false,

  environment: 'node',

  threads: false,

  isolate: true,
}

Конфигурация CI

test: {
  watch: false,

  allowOnly: false,

  reporters: [
    'default',
    'junit',
  ],

  coverage: {
    enabled: true,
  },
}
Оглавление