TestProject 3.0.0+

WARNING

Это руководство описывает расширенный API Node.js. Если вы просто хотите определить проекты, следуйте руководству "Тестовые проекты".

name

Имя — это уникальная строка, присваиваемая пользователем или определяемая Vitest. Если пользователь не указал имя, Vitest пытается загрузить package.json из корневого каталога проекта и использует значение свойства name оттуда. Если package.json отсутствует, Vitest по умолчанию использует имя папки. Встроенные проекты используют числа в качестве имен (преобразованные в строку).

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // имеет package.json с "@pkg/server"
      './utils', // не имеет файла package.json
      {
        // не настраивает имя
        test: {
          pool: 'threads',
        },
      },
      {
        // настраивает имя
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Если корневой проект не является частью пользовательских проектов, его name не будет разрешено.

vitest

vitest ссылается на глобальный процесс Vitest.

serializedConfig

Это конфигурация, которую получают тестовые процессы. Vitest вручную сериализует конфигурацию, удаляя все функции и несериализуемые свойства. Поскольку это значение доступно как в тестах, так и в Node, его тип экспортируется из основной точки входа.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

Свойство serializedConfig является геттером. Каждый раз при доступе к нему Vitest повторно сериализует конфигурацию на случай, если она была изменена. Это также означает, что оно всегда возвращает другую ссылку:

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

Конфигурация теста, с которой был инициализирован Vitest. Если это корневой проект, globalConfig и config будут ссылаться на один и тот же объект. Эта конфигурация используется для значений, которые не могут быть установлены на уровне проекта, таких как coverage и reporters.

import type { ResolvedConfig } from 'vitest/node';

vitest.config === vitest.projects[0].globalConfig;

config

Это разрешенная конфигурация теста проекта.

hash 3.2.0+

Уникальный хеш этого проекта. Это значение остается постоянным при повторных запусках.

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

vite

Это ViteDevServer проекта. Все проекты имеют свои собственные серверы Vite.

browser

Это значение будет установлено только если тесты выполняются в браузере. Если browser включен, но тесты еще не запускались, его значение будет undefined. Если вам нужно проверить, поддерживает ли проект браузерные тесты, используйте метод project.isBrowserEnabled().

WARNING

API браузера является еще более экспериментальным и не соответствует SemVer. API браузера будет стандартизирован отдельно от остальных API.

provide

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

Метод для передачи пользовательских значений тестам в дополнение к полю config.provide. Все значения проверяются с помощью structuredClone перед их сохранением, но сами значения в providedContext не клонируются.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

Значения могут предоставляться динамически. Предоставленное значение в тестах будет обновлено при следующем запуске.

TIP

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

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

getProvidedContext

function getProvidedContext(): ProvidedContext;

Возвращает контекстный объект. Каждый проект также наследует глобальный контекст, установленный vitest.provide.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

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

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

Создает спецификацию теста, которая может быть использована в vitest.runTestSpecifications. Спецификация ограничивает тестовый файл определенным project и (необязательно) locations теста. Позиции теста в коде — это строки кода, где тест определен в исходном коде. Если местоположения предоставлены, Vitest будет запускать только тесты, определенные в этих строках. Обратите внимание, что если testNamePattern определен, то он также будет применен.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // необязательные строки теста
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification ожидает разрешенный идентификатор модуля. Он не выполняет автоматическое разрешение файла и не проверяет его существование в файловой системе.

Также обратите внимание, что project.createSpecification всегда возвращает новый экземпляр.

isRootProject

function isRootProject(): boolean;

Проверяет, является ли данный проект корневым. Вы также можете получить корневой проект, вызвав vitest.getRootProject().

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * Тестовые файлы, соответствующие фильтрам.
   */
  testFiles: string[];
  /**
   * Файлы тестов проверки типов, соответствующие фильтрам. Это будет пусто, если `typecheck.enabled` не `true`.
   */
  typecheckTestFiles: string[];
};

Ищет все тестовые файлы по шаблону. Эта функция возвращает объект с обычными тестами и тестами проверки типов.

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

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest использует fast-glob для поиска тестовых файлов. test.dir, test.root, root или process.cwd() определяют опцию cwd.

Этот метод учитывает несколько опций конфигурации:

• test.include, test.exclude для поиска обычных тестовых файлов
• test.includeSource, test.exclude для поиска встроенных тестов
• test.typecheck.include, test.typecheck.exclude для поиска тестов проверки типов

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

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

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

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // true, если установлен `includeSource`

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 project.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

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

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

Это сокращение для project.vitest.onTestsRerun. Он принимает колбэк, который будет ожидаться, когда тесты будут запланированы на повторный запуск (обычно из-за изменения файла).

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

Возвращает true, если этот проект запускает тесты в браузере.

close

function close(): Promise<void>;

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

Подробно, этот метод закрывает сервер Vite, останавливает службу проверки типов, закрывает браузер (если он запущен), удаляет временный каталог, содержащий исходный код, и сбрасывает предоставленный контекст.