Vitest API

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

• test при запуске тестов
• benchmark при запуске бенчмарков экспериментально

Новое в Vitest 3

Vitest 3 приблизился к стабилизации публичного API. Для этого мы объявили устаревшими и удалили некоторые из ранее публичных методов класса Vitest. Эти API были сделаны приватными:

• configOverride (используйте setGlobalTestNamePattern или enableSnapshotUpdate)
• coverageProvider
• filenamePattern
• runningPromise
• closingPromise
• isCancelling
• coreWorkspaceProject
• resolvedProjects
• _browserLastPort
• _options
• reporters
• vitenode
• runner
• pool
• setServer
• _initBrowserServers
• rerunTask
• changeProjectName
• changeNamePattern
• changeFilenamePattern
• rerunFailed
• _createRootProject (переименован в _ensureRootProject, но все еще приватный)
• filterTestsBySource (это было перемещено в новый внутренний экземпляр vitest.specifications)
• runFiles (используйте runTestSpecifications вместо этого)
• onAfterSetServer

Эти API были устаревшими:

• invalidates
• changedTests (используйте onFilterWatchedSpecification вместо этого)
• server (используйте vite вместо этого)
• getProjectsByTestFile (используйте getModuleSpecifications вместо этого)
• getFileWorkspaceSpecs (используйте getModuleSpecifications вместо этого)
• getModuleProjects (фильтруйте по this.projects самостоятельно)
• updateLastChanged (переименован в invalidateFile)
• globTestSpecs (используйте globTestSpecifications вместо этого)
• globTestFiles (используйте globTestSpecifications вместо этого)
• listFile (используйте getRelevantTestSpecifications вместо этого)

mode

test

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

benchmark экспериментально

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

config

Корневая (или глобальная) конфигурация. Если проекты определены, они будут ссылаться на эту конфигурацию как на globalConfig.

WARNING

Это конфигурация Vitest; она не расширяет конфигурацию Vite. В ней содержатся только разрешенные значения из свойства test.

vite

Это глобальный ViteDevServer.

state экспериментально

WARNING

Публичный state является экспериментальным API (за исключением vitest.state.getReportedEntity). Ломающие изменения могут не соответствовать SemVer, поэтому, пожалуйста, зафиксируйте версию Vitest при его использовании.

Глобальное состояние содержит информацию о текущих тестах. По умолчанию оно использует тот же API из @vitest/runner, но мы рекомендуем использовать Reported Tasks API вместо этого, вызывая state.getReportedEntity() для API @vitest/runner:

const task = vitest.state.idMap.get(taskId); // старый API
const testCase = vitest.state.getReportedEntity(task); // новый API

В будущем старый API больше не будет предоставляться.

snapshot

Глобальный менеджер снимков. Vitest управляет всеми снимками с помощью метода snapshot.add.

Вы можете получить последнюю сводку снимков через свойство vitest.snapshot.summary.

cache

Менеджер кеша, который содержит информацию о последних результатах тестов и статистике тестовых файлов. В самом Vitest он используется только стандартным секвенсором для сортировки тестов.

projects

Массив тестовых проектов, относящихся к проектам пользователя. Если пользователь не указал их явно, этот массив будет содержать только корневой проект.

Vitest обеспечивает наличие как минимум одного проекта в этом массиве. Если пользователь укажет несуществующее имя --project, Vitest сгенерирует ошибку до того, как этот массив будет определен.

getRootProject

function getRootProject(): TestProject;

Этот метод возвращает корневой тестовый проект. Корневой проект обычно не запускает никаких тестов и не включается в vitest.projects, если пользователь явно не включит корневую конфигурацию в свои настройки, или если проекты вообще не определены.

Основная цель корневого проекта — инициализировать глобальную конфигурацию. Фактически, rootProject.config ссылается на rootProject.globalConfig и vitest.config напрямую:

(rootProject.config === rootProject.globalConfig) === rootProject.vitest.config;

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Vitest предоставляет метод provide, который является сокращенной записью для vitest.getRootProject().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 является методом TestProject, поэтому его действие ограничено конкретным проектом. Однако все проекты наследуют значения от корневого проекта, что делает vitest.provide универсальным средством для передачи значений в тесты.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Этот метод возвращает корневой объект контекста. Это сокращение для vitest.getRootProject().getProvidedContext.

getProjectByName

function getProjectByName(name: string): TestProject;

Этот метод возвращает тестовый проект по его имени. Аналогично тому, как если бы вы вызвали vitest.projects.find.

WARNING

В случае, если проект не существует, этот метод вернет корневой проект — убедитесь, что вы еще раз проверили имена, если возвращенный проект не является искомым.

Если пользователь не задал имя, Vitest присвоит пустую строку в качестве имени.

globTestSpecifications

function globTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Этот метод формирует новые спецификации тестов, собирая все тесты во всех проектах с помощью project.globTestFiles. Он принимает строковые фильтры для сопоставления тестовых файлов — это те же фильтры, которые поддерживает CLI.

Этот метод автоматически кеширует все спецификации тестов. При следующем вызове getModuleSpecifications он вернет те же спецификации, если только до этого не был вызван clearSpecificationsCache.

WARNING

Начиная с Vitest 3, возможно наличие нескольких спецификаций тестов с одним и тем же идентификатором модуля (путем к файлу), если poolMatchGlob имеет несколько пулов или если включена typecheck. Эта функциональность будет удалена в Vitest 4.

const specifications = await vitest.globTestSpecifications(['my-filter']);
// [TestSpecification{ moduleId: '/tests/my-filter.test.ts' }]
console.log(specifications);

getRelevantTestSpecifications

function getRelevantTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Этот метод определяет каждую спецификацию теста, вызывая project.globTestFiles. Он принимает строковые фильтры для сопоставления тестовых файлов — это те же фильтры, которые поддерживает CLI. Если был указан флаг --changed, список будет отфильтрован, чтобы содержать только измененные файлы. getRelevantTestSpecifications не выполняет никаких тестовых файлов.

WARNING

Этот метод может быть медленным, поскольку ему требуется фильтровать флаги --changed. Не используйте его, если вам просто нужен список тестовых файлов.

• Если вам нужно получить список спецификаций для известных тестовых файлов, используйте getModuleSpecifications вместо этого.
• Если вам нужно получить список всех возможных тестовых файлов, используйте globTestSpecifications.

mergeReports

function mergeReports(directory?: string): Promise<TestRunResult>;

Метод объединяет отчеты из нескольких запусков, расположенных в указанном каталоге (значение из --merge-reports, если не указано). Это значение также может быть установлено в config.mergeReports (по умолчанию оно будет использовать папку .vitest-reports).

Обратите внимание, что directory всегда будет определяться относительно рабочего каталога.

Этот метод вызывается автоматически startVitest, если установлен config.mergeReports.

collect

function collect(filters?: string[]): Promise<TestRunResult>;

Метод выполняет тестовые файлы без вызова колбэков тестов. collect возвращает необработанные ошибки и массив тестовых модулей. Он принимает строковые фильтры для сопоставления тестовых файлов — это те же фильтры, которые поддерживает CLI.

Этот метод определяет спецификации тестов на основе значений include, exclude и includeSource в конфигурации. Подробнее читайте в project.globTestFiles. Если был указан флаг --changed, список будет отфильтрован, чтобы включить только измененные файлы.

WARNING

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

Это делает этот метод очень медленным, если только вы не отключите изоляцию перед сбором тестов.

start

function start(filters?: string[]): Promise<TestRunResult>;

Метод инициализирует репортеры, провайдер покрытия и запускает тесты. Этот метод принимает строковые фильтры для сопоставления тестовых файлов — это те же фильтры, которые поддерживает CLI.

WARNING

Этот метод не следует вызывать, если vitest.init() также был вызван. Используйте runTestSpecifications или rerunTestSpecifications вместо этого, если требуется запустить тесты после инициализации Vitest.

Этот метод вызывается автоматически startVitest, если config.mergeReports и config.standalone не установлены.

init

function init(): Promise<void>;

Метод инициализирует репортеры и провайдер покрытия. Этот метод не выполняет никаких тестов. Если предоставлен флаг --watch, Vitest все равно будет запускать измененные тесты, даже если этот метод не был вызван.

Внутри этот метод вызывается только при включении флага --standalone.

WARNING

Этот метод не следует вызывать, если также вызывается vitest.start().

Этот метод вызывается автоматически startVitest, если установлен config.standalone.

getModuleSpecifications

function getModuleSpecifications(moduleId: string): TestSpecification[];

Метод возвращает список спецификаций тестов, связанных с идентификатором модуля. Идентификатор уже должен быть преобразован в абсолютный путь к файлу. Если идентификатор не соответствует шаблонам include или includeSource, возвращаемый массив будет пустым.

Этот метод может возвращать уже кешированные спецификации, основанные на moduleId и pool. Но обратите внимание, что project.createSpecification всегда возвращает новый экземпляр и не кешируется автоматически. Однако спецификации автоматически кешируются, когда вызывается runTestSpecifications.

WARNING

Начиная с Vitest 3, этот метод использует кеш для проверки, является ли файл тестом. Чтобы убедиться, что кеш не пуст, вызовите globTestSpecifications хотя бы один раз.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest автоматически кеширует спецификации тестов для каждого файла, когда вызывается globTestSpecifications или runTestSpecifications. Этот метод очищает кеш для данного файла или весь кеш полностью, в зависимости от первого аргумента.

runTestSpecifications

function runTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Этот метод выполняет каждый тест на основе полученных спецификаций. Второй аргумент, allTestsRun, используется провайдером покрытия для определения необходимости инструментирования покрытия каждого файла в корне (это имеет значение только если покрытие включено и coverage.all установлено в true).

WARNING

Этот метод не инициирует вызов колбэков onWatcherRerun, onWatcherStart и onTestsRerun. Если вы перезапускаете тесты из-за изменения файла, рассмотрите возможность использования rerunTestSpecifications вместо этого.

rerunTestSpecifications

function rerunTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Этот метод генерирует события reporter.onWatcherRerun и onTestsRerun, а затем запускает тесты с помощью runTestSpecifications. Если в основном процессе не возникло ошибок, он сгенерирует событие reporter.onWatcherStart.

updateSnapshot

function updateSnapshot(files?: string[]): Promise<TestRunResult>;

Метод обновляет снимки в указанных файлах. Если файлы не предоставлены, он обновит файлы с проваленными тестами и устаревшими снимками.

collectTests

function collectTests(
  specifications: TestSpecification[]
): Promise<TestRunResult>;

Метод выполняет тестовые файлы без вызова колбэков тестов. collectTests возвращает необработанные ошибки и массив тестовых модулей.

Этот метод работает точно так же, как collect, но требует, чтобы вы предоставили спецификации тестов самостоятельно.

WARNING

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

Это делает этот метод очень медленным, если вы не отключите изоляцию перед сбором тестов.

cancelCurrentRun

function cancelCurrentRun(reason: CancelReason): Promise<void>;

Этот метод корректно отменит все текущие тесты. Он дождется завершения запущенных тестов и не будет запускать тесты, которые были запланированы, но еще не начались.

setGlobalTestNamePattern

function setGlobalTestNamePattern(pattern: string | RegExp): void;

Метод переопределяет глобальный шаблон имени теста.

WARNING

Этот метод не инициирует выполнение тестов. Чтобы запустить тесты с обновленным шаблоном, необходимо вызвать runTestSpecifications.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Метод сбрасывает шаблон имени теста. Это означает, что Vitest теперь не будет пропускать тесты.

WARNING

Этот метод не инициирует выполнение тестов. Чтобы запустить тесты без шаблона, необходимо вызвать runTestSpecifications.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

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

WARNING

Этот метод не инициирует выполнение тестов. Чтобы обновить снимки, выполните тесты с помощью runTestSpecifications.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Отключает режим, который позволяет обновлять снимки при запуске тестов. Этот метод не запускает никаких тестов.

invalidateFile

function invalidateFile(filepath: string): void;

Этот метод аннулирует файл в кеше каждого проекта. Это особенно полезно, если вы полагаетесь на свой собственный наблюдатель, поскольку кеш Vite сохраняется в оперативной памяти.

DANGER

Если вы отключите наблюдатель Vitest, но оставите Vitest запущенным, важно вручную очистить кеш с помощью этого метода, поскольку отсутствует возможность отключить кеш. Этот метод также аннулирует импортеры файла.

import

function import<T>(moduleId: string): Promise<T>

Метод импортирует файл с помощью Vite module runner. Файл будет преобразован Vite с использованием глобальной конфигурации и выполнен в отдельном контексте. Обратите внимание, что moduleId будет указываться относительно config.root.

DANGER

project.import повторно использует граф модулей Vite, поэтому импорт того же модуля с использованием обычного импорта приведет к получению другого модуля:

import * as staticExample from './example.js';
const dynamicExample = await vitest.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

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

close

function close(): Promise<void>;

Метод закрывает все проекты и связанные с ними ресурсы. Этот метод можно вызвать только один раз; обещание закрытия кешируется до перезапуска сервера.

exit

function exit(force = false): Promise<void>;

Метод закрывает все проекты и завершает процесс. Если force установлено в true, процесс завершится немедленно после закрытия проектов.

Этот метод также принудительно вызовет process.exit(), если процесс все еще активен по истечении config.teardownTimeout миллисекунд.

shouldKeepServer

function shouldKeepServer(): boolean;

Этот метод вернет true, если сервер должен оставаться запущенным после завершения тестов. Обычно это означает, что режим watch был активирован.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Метод регистрирует обработчик, который будет вызван при перезапуске сервера из-за изменения конфигурации.

onCancel

function onCancel(fn: (reason: CancelReason) => Awaitable<void>): void;

Метод регистрирует обработчик, который будет вызван при отмене выполнения теста с помощью vitest.cancelCurrentRun.

onClose

function onClose(fn: () => Awaitable<void>): void;

Метод регистрирует обработчик, который будет вызван при закрытии сервера.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Метод регистрирует обработчик, который будет вызван при повторном запуске тестов. Тесты могут быть перезапущены вручную при вызове rerunTestSpecifications или когда файл изменяется и встроенный наблюдатель планирует перезапуск.

onFilterWatchedSpecification

function onFilterWatchedSpecification(
  fn: (specification: TestSpecification) => boolean
): void;

Метод регистрирует обработчик, который будет вызван при изменении файла. Этот колбэк должен возвращать true или false, указывая, требуется ли перезапуск тестового файла.

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

const continuesTests: string[] = [];

myCustomWrapper.onContinuesRunEnabled(testItem =>
  continuesTests.push(item.fsPath)
);

vitest.onFilterWatchedSpecification(specification =>
  continuesTests.includes(specification.moduleId)
);

Vitest может создавать различные спецификации для одного и того же файла в зависимости от опций pool или locations, поэтому не следует полагаться на прямую ссылку на объект. Vitest также может возвращать кешированную спецификацию из vitest.getModuleSpecifications — кеш формируется на основе moduleId и pool. Обратите внимание, что project.createSpecification всегда возвращает новый экземпляр.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Метод проверяет, соответствует ли имя текущему фильтру проекта. Если фильтр проекта не задан, этот метод всегда будет возвращать true.

Программно изменить опцию CLI --project невозможно.