Node API

WARNING

Vitest предоставляет экспериментальный приватный API. Возможны нарушения обратной совместимости без соблюдения SemVer, поэтому при использовании этого API рекомендуется зафиксировать версию Vitest.

startVitest

Вы можете запустить тесты Vitest, используя Node API:

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest?.close();

Функция startVitest возвращает экземпляр Vitest, если запуск тестов возможен. Она возвращает undefined в следующих случаях:

• Vitest не обнаружил пакет vite (обычно устанавливается вместе с Vitest).
• Включено покрытие кода и режим запуска "test", но пакет покрытия кода не установлен (@vitest/coverage-v8 или @vitest/coverage-istanbul).
• Пакет окружения не установлен (jsdom/happy-dom/@edge-runtime/vm).

Если возвращается undefined или тесты завершаются с ошибкой во время запуска, Vitest устанавливает для process.exitCode значение 1.

Если режим наблюдения не включен, Vitest вызывает метод close для завершения работы.

Если режим наблюдения включен и терминал поддерживает TTY, Vitest регистрирует консольные горячие клавиши.

Вы можете указать список фильтров вторым аргументом. Vitest запустит только те тесты, в пути которых содержится хотя бы одна из указанных строк.

Также вы можете использовать третий аргумент для передачи аргументов CLI, которые переопределят параметры конфигурации тестов.

Альтернативно, вы можете передать полную конфигурацию Vite четвертым аргументом, которая переопределит другие пользовательские параметры.

После запуска тестов вы можете получить результаты из API state.getFiles:

const vitest = await startVitest('test');

console.log(vitest.state.getFiles()); // [{ type: 'file', ... }]

Начиная с Vitest 2.1, рекомендуется использовать API "Reported Tasks" (Отчетные задачи) вместе с state.getFiles. В будущем Vitest будет возвращать эти объекты напрямую:

const vitest = await startVitest('test');

const [fileTask] = vitest.state.getFiles();
const testFile = vitest.state.getReportedEntity(fileTask);

createVitest

Вы можете создать экземпляр Vitest, используя функцию createVitest. Она возвращает тот же экземпляр Vitest, что и startVitest, но не запускает тесты и не проверяет установленные пакеты.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test', {
  watch: false,
});

parseCLI

Вы можете использовать этот метод для разбора аргументов CLI. Он принимает строку (с аргументами, разделенными пробелами) или массив строк аргументов CLI в формате Vitest CLI. Он возвращает фильтр и options, которые вы можете передать в методы createVitest или startVitest.

import { parseCLI } from 'vitest/node';

parseCLI('vitest ./files.ts --coverage --browser=chrome');

Vitest

Экземпляр Vitest требует указания текущего режима тестирования. Возможные режимы:

• test - для запуска runtime тестов.
• benchmark - для запуска бенчмарков.

mode

test

В режиме test вызываются только функции внутри test или it. При обнаружении bench выдается ошибка. Этот режим использует параметры include и exclude в конфигурации для поиска файлов тестов.

benchmark

В режиме benchmark вызываются функции bench. При обнаружении test или it выдается ошибка. Этот режим использует параметры benchmark.include и benchmark.exclude в конфигурации для поиска файлов бенчмарков.

start

Вы можете запускать тесты или бенчмарки с помощью метода start. Вы можете передать массив строк для фильтрации файлов тестов.

provide

Vitest предоставляет метод provide, являющийся псевдонимом для vitest.getCoreWorkspaceProject().provide. С помощью этого метода вы можете передавать значения из основного потока в тесты. Все значения проверяются с помощью structuredClone перед сохранением, но сами значения не клонируются.

Чтобы получить значения в тесте, вам нужно импортировать метод inject из точки входа vitest:

import { inject } from 'vitest';
const port = inject('wsPort'); // 3000

Для повышения типобезопасности рекомендуется расширить определение типа ProvidedContext:

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test', {
  watch: false,
});
vitest.provide('wsPort', 3000);

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

WARNING

Технически, provide является методом WorkspaceProject, поэтому он ограничен конкретным проектом. Однако все проекты наследуют значения от основного проекта, что делает vitest.provide универсальным методом передачи значений в тесты.

TIP

Этот метод также доступен для файлов глобальной настройки в случаях, когда вы не хотите использовать публичный API:

export default function setup({ provide }) {
  provide('wsPort', 3000);
}