Node API

WARNING

Vitest udostępnia eksperymentalne, prywatne API. Zmiany mogą nie być zgodne z SemVer, co może prowadzić do braku kompatybilności wstecznej, dlatego zaleca się przypięcie wersji Vitest podczas korzystania z tego API.

startVitest

Możesz uruchomić testy Vitest za pomocą jego Node API:

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest?.close();

Funkcja startVitest zwraca instancję Vitest, jeśli testy mogą zostać uruchomione. Zwraca undefined, jeśli wystąpi jeden z następujących przypadków:

• Vitest nie znalazł pakietu vite (zwykle instalowanego razem z Vitest).
• Włączone jest pokrycie kodu i tryb uruchomienia 'test', ale pakiet do pokrycia nie jest zainstalowany (@vitest/coverage-v8 lub @vitest/coverage-istanbul).
• Pakiet środowiska testowego nie jest zainstalowany (jsdom/happy-dom/@edge-runtime/vm).

W przypadku, gdy zostanie zwrócone undefined lub testy zakończą się niepowodzeniem podczas uruchamiania, Vitest ustawia process.exitCode na 1.

Jeśli tryb obserwacji nie jest włączony, Vitest wywoła metodę close.

Jeśli tryb obserwacji jest włączony, a terminal obsługuje TTY, Vitest zarejestruje skróty konsolowe.

Możesz przekazać listę filtrów jako drugi argument. Vitest uruchomi tylko te testy, których ścieżka do pliku zawiera przynajmniej jeden z przekazanych ciągów znaków.

Dodatkowo, możesz użyć trzeciego argumentu, aby przekazać argumenty CLI, które nadpiszą wszystkie opcje konfiguracji testów.

Alternatywnie, możesz przekazać pełną konfigurację Vite jako czwarty argument, która będzie miała priorytet przed wszystkimi innymi opcjami zdefiniowanymi przez użytkownika.

Po uruchomieniu testów możesz uzyskać wyniki z API state.getFiles:

const vitest = await startVitest('test');

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

Od wersji Vitest 2.1 zaleca się stosowanie API "Zgłoszonych Zadań" (Reported Tasks) razem z state.getFiles. W przyszłości Vitest będzie zwracać te obiekty bezpośrednio:

const vitest = await startVitest('test');

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

createVitest

Możesz samodzielnie utworzyć instancję Vitest za pomocą funkcji createVitest. Zwraca ona tę samą instancję Vitest co startVitest, ale nie uruchamia testów i nie sprawdza poprawności zainstalowanych pakietów.

import { createVitest } from 'vitest/node';

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

parseCLI

Możesz użyć tej metody do parsowania argumentów CLI (Command Line Interface, Interfejs Linii Poleceń). Akceptuje ciąg znaków (w którym argumenty są oddzielone pojedynczą spacją) lub tablicę ciągów znaków argumentów CLI w formacie używanym przez Vitest CLI. Zwraca filtr oraz options, które możesz później przekazać do metod createVitest lub startVitest.

import { parseCLI } from 'vitest/node';

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

Vitest

Instancja Vitest wymaga określenia aktualnego trybu testów. Może to być:

• test podczas uruchamiania testów środowiska uruchomieniowego (runtime tests)
• benchmark podczas uruchamiania testów wydajnościowych (benchmarks)

mode

test

W trybie testowym wywoływane są tylko funkcje wewnątrz bloków test lub it. Wywołanie bench spowoduje zgłoszenie błędu. Ten tryb używa opcji include i exclude w konfiguracji do wyszukiwania plików testowych.

benchmark

W trybie benchmark wywoływane są funkcje bench. Wywołanie test lub it spowoduje zgłoszenie błędu. Ten tryb używa opcji benchmark.include i benchmark.exclude w konfiguracji do wyszukiwania plików benchmarkowych.

start

Możesz rozpocząć uruchomienie testów lub benchmarków za pomocą metody start. Możesz przekazać tablicę ciągów znaków, aby filtrować pliki testowe.

provide

Vitest udostępnia metodę provide, która jest skrótem do vitest.getCoreWorkspaceProject().provide. Za pomocą tej metody możesz przekazywać wartości z głównego wątku do testów. Wszystkie wartości są sprawdzane za pomocą structuredClone przed ich zapisaniem, ale same wartości nie są klonowane.

Aby otrzymać wartości w teście, musisz zaimportować metodę inject z punktu wejścia vitest:

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

W celu zwiększenia bezpieczeństwa typów zalecamy rozszerzenie typu 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

Z technicznego punktu widzenia, provide jest metodą WorkspaceProject i jest ograniczona do konkretnego projektu. Niemniej jednak, wszystkie projekty dziedziczą wartości z projektu głównego, dzięki czemu vitest.provide stanowi uniwersalny sposób przekazywania wartości do testów.

TIP

Ta metoda jest również dostępna dla globalnych plików konfiguracji w przypadkach, gdy nie chcesz używać publicznego API:

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