TestProject 3.0.0+

WARNING

Ten przewodnik opisuje zaawansowane API dla Node.js. Jeśli chcesz tylko zdefiniować projekty, postępuj zgodnie z przewodnikiem "Projekty testowe".

name

Nazwa jest unikalnym ciągiem znaków przypisanym przez użytkownika lub interpretowanym przez Vitest. Jeśli użytkownik nie podał nazwy, Vitest próbuje załadować package.json z katalogu głównego projektu i pobiera z niego właściwość name. Jeśli plik package.json nie istnieje, Vitest domyślnie używa nazwy folderu. Projekty wbudowane używają liczb jako nazw (przekonwertowanych na ciągi znaków).

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', // posiada package.json z "@pkg/server"
      './utils', // nie posiada pliku package.json
      {
        // nie dostosowuje nazwy
        test: {
          pool: 'threads',
        },
      },
      {
        // dostosowana nazwa
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Jeśli projekt główny nie jest częścią projektów użytkownika, jego name nie zostanie rozwiązany.

vitest

vitest odwołuje się do globalnego procesu Vitest.

serializedConfig

Jest to konfiguracja, którą otrzymują procesy testowe. Vitest serializuje konfigurację ręcznie, usuwając wszystkie funkcje i właściwości, których nie można serializować. Ponieważ ta wartość jest dostępna zarówno w testach, jak i w Node.js, jej typ jest eksportowany z głównego punktu wejścia.

import type { SerializedConfig } from 'vitest';

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

WARNING

Właściwość serializedConfig to getter. Za każdym razem, gdy jest dostępna, Vitest ponownie serializuje konfigurację na wypadek jej zmiany. Oznacza to również, że zawsze zwraca inną referencję:

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

globalConfig

Konfiguracja testowa, z którą został zainicjowany Vitest. Jeśli jest to projekt główny, globalConfig i config będą odwoływać się do tego samego obiektu. Ta konfiguracja jest przydatna dla wartości, które nie mogą być ustawione na poziomie projektu, takich jak coverage lub reporters.

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

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

config

Jest to rozwiązana konfiguracja testowa projektu.

hash 3.2.0+

Unikalny hash tego projektu. Ta wartość jest spójna między kolejnymi uruchomieniami.

Jest oparty na katalogu głównym projektu i jego nazwie. Należy pamiętać, że ścieżka główna nie jest spójna między różnymi systemami operacyjnymi, więc hash również będzie się różnić.

vite

Jest to ViteDevServer projektu. Wszystkie projekty mają własne serwery Vite.

browser

Ta wartość zostanie ustawiona tylko wtedy, gdy testy są uruchamiane w przeglądarce. Jeśli browser jest włączony, ale testy jeszcze się nie uruchomiły, jego wartość będzie undefined. Jeśli chcesz sprawdzić, czy projekt obsługuje testy w przeglądarce, użyj metody project.isBrowserEnabled().

WARNING

API przeglądarki jest jeszcze bardziej eksperymentalne i nie jest zgodne z SemVer. API przeglądarki zostanie ustandaryzowane oddzielnie od reszty API.

provide

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

Sposób dostarczania niestandardowych wartości do testów oprócz pola config.provide. Wszystkie wartości są walidowane za pomocą structuredClone przed ich zapisaniem, ale same wartości w providedContext nie są klonowane.

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');

Wartości mogą być dostarczane dynamicznie. Dostarczona wartość w testach zostanie zaktualizowana przy ich kolejnym uruchomieniu.

TIP

Ta metoda jest również dostępna dla plików globalnego setupu w przypadkach, gdy nie można użyć publicznego API:

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

getProvidedContext

function getProvidedContext(): ProvidedContext;

Zwraca obiekt kontekstu. Każdy projekt dziedziczy również globalny kontekst ustawiony przez 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

Wartości kontekstu projektu zawsze nadpisują kontekst projektu głównego.

createSpecification

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

Tworzy specyfikację testową, którą można wykorzystać w vitest.runTestSpecifications. Specyfikacja ogranicza plik testowy do określonego project i (opcjonalnie) locations testu. Lokalizacje testu to numery linii kodu, w których test jest zdefiniowany w kodzie źródłowym. Jeśli podano lokalizacje, Vitest uruchomi tylko testy zdefiniowane w tych liniach. Należy również pamiętać, że jeśli zdefiniowano testNamePattern, zostanie on zastosowany.

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] // opcjonalne linie testowe
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification oczekuje rozwiązanej identyfikatora modułu. Nie rozwiązuje automatycznie pliku ani nie sprawdza jego istnienia w systemie plików.

Należy również pamiętać, że project.createSpecification zawsze zwraca nową instancję.

isRootProject

function isRootProject(): boolean;

Sprawdza, czy aktualny projekt jest projektem głównym. Projekt główny można również uzyskać, wywołując vitest.getRootProject().

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * Pliki testowe, które pasują do filtrów.
   */
  testFiles: string[];
  /**
   * Pliki testowe sprawdzające typy, które pasują do filtrów. Będzie to puste, chyba że `typecheck.enabled` jest `true`.
   */
  typecheckTestFiles: string[];
};

Wyszukuje wszystkie pliki testowe. Ta funkcja zwraca obiekt z regularnymi testami i testami sprawdzającymi typy.

Ta metoda przyjmuje filters. Filtry mogą stanowić tylko część ścieżki pliku, w przeciwieństwie do innych metod w instancji Vitest:

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

TIP

Vitest używa fast-glob do znajdowania plików testowych. test.dir, test.root, root lub process.cwd() definiują opcję cwd.

Metoda ta uwzględnia kilka opcji konfiguracji:

• test.include, test.exclude do znajdowania regularnych plików testowych
• test.includeSource, test.exclude do znajdowania testów w kodzie źródłowym
• test.typecheck.include, test.typecheck.exclude do znajdowania testów sprawdzających typy

matchesTestGlob

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

Ta metoda sprawdza, czy plik jest regularnym plikiem testowym. Używa tych samych właściwości konfiguracyjnych, których globTestFiles używa do walidacji.

Metoda ta akceptuje również drugi parametr, którym jest kod źródłowy. Służy to do walidacji, czy plik jest testem w kodzie źródłowym. Jeśli wywołujesz tę metodę wielokrotnie dla różnych projektów, zaleca się jednokrotne odczytanie pliku i bezpośrednie przekazanie go. Jeśli plik nie jest plikiem testowym, ale pasuje do globu includeSource, Vitest synchronicznie odczyta plik, chyba że source zostanie podane.

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, jeśli `includeSource` jest ustawione

import

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

Importuje plik przy użyciu modułu uruchamiającego Vite. Plik zostanie przekształcony przez Vite z podaną konfiguracją projektu i wykonany w osobnym kontekście. Należy pamiętać, że moduleId będzie względny w stosunku do config.root.

DANGER

project.import ponownie wykorzystuje graf modułów Vite, więc importowanie tego samego modułu za pomocą zwykłego importu zwróci inny moduł:

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

dynamicExample !== staticExample; // ✅

INFO

Wewnętrznie Vitest używa tej metody do importowania globalnych setupów, niestandardowych dostawców pokrycia i niestandardowych raportów. Oznacza to, że wszystkie one współdzielą ten sam graf modułów, o ile należą do tego samego serwera Vite.

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

To jest skrót od project.vitest.onTestsRerun. Akceptuje wywołanie zwrotne, na które zostanie zaczekane, gdy testy zostaną zaplanowane do ponownego uruchomienia (zazwyczaj z powodu zmiany pliku).

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

isBrowserEnabled

function isBrowserEnabled(): boolean;

Zwraca true, jeśli ten projekt uruchamia testy w przeglądarce.

close

function close(): Promise<void>;

Zamyka projekt i wszystkie powiązane zasoby. Można to wywołać tylko raz; obietnica zamknięcia jest buforowana do momentu ponownego uruchomienia serwera. Jeśli zasoby są ponownie potrzebne, utwórz nowy projekt.

Szczegółowo, ta metoda zamyka serwer Vite, zatrzymuje usługę sprawdzania typów, zamyka przeglądarkę (jeśli jest uruchomiona), usuwa katalog tymczasowy zawierający kod źródłowy i resetuje dostarczony kontekst.