Vitest API

Instancja Vitest wymaga bieżącego trybu testowego. Może to być:

• test podczas uruchamiania testów
• benchmark podczas uruchamiania benchmarków eksperymentalny

Nowość w Vitest 3

Vitest 3 jest o krok bliżej do stabilizacji publicznego API. Aby to osiągnąć, zdeprecjonowaliśmy i usunęliśmy niektóre z wcześniej publicznych metod w klasie Vitest. Te API zostały uczynione prywatnymi:

• configOverride (użyj setGlobalTestNamePattern lub enableSnapshotUpdate)
• coverageProvider
• filenamePattern
• runningPromise
• closingPromise
• isCancelling
• coreWorkspaceProject
• resolvedProjects
• _browserLastPort
• _options
• reporters
• vitenode
• runner
• pool
• setServer
• _initBrowserServers
• rerunTask
• changeProjectName
• changeNamePattern
• changeFilenamePattern
• rerunFailed
• _createRootProject (zmieniono nazwę na _ensureRootProject, ale nadal prywatne)
• filterTestsBySource (zostało przeniesione do nowej wewnętrznej instancji vitest.specifications)
• runFiles (zamiast tego użyj runTestSpecifications)
• onAfterSetServer

Te API zostały wycofane:

• invalidates
• changedTests (zamiast tego użyj onFilterWatchedSpecification)
• server (zamiast tego użyj vite)
• getProjectsByTestFile (zamiast tego użyj getModuleSpecifications)
• getFileWorkspaceSpecs (zamiast tego użyj getModuleSpecifications)
• getModuleProjects (filtruj samodzielnie według this.projects)
• updateLastChanged (zmieniono nazwę na invalidateFile)
• globTestSpecs (zamiast tego użyj globTestSpecifications)
• globTestFiles (zamiast tego użyj globTestSpecifications)
• listFile (zamiast tego użyj getRelevantTestSpecifications)

mode

test

Tryb testowy wykonuje funkcje tylko wewnątrz test lub it i zgłasza błąd, gdy napotka bench. Ten tryb używa opcji include i exclude w konfiguracji do wyszukiwania plików testowych.

benchmark eksperymentalny

Tryb benchmark wywołuje funkcje bench i zgłasza błąd, gdy napotka test lub it. Ten tryb używa opcji benchmark.include i benchmark.exclude w konfiguracji do wyszukiwania plików benchmarkowych.

config

Konfiguracja bazowa (lub globalna). Jeśli projekty są zdefiniowane, będą odwoływać się do niej jako globalConfig.

WARNING

To jest konfiguracja Vitest, która nie rozszerza konfiguracji Vite. Posiada tylko ustalone wartości z właściwości test.

vite

Jest to globalny ViteDevServer.

state eksperymentalny

WARNING

Publiczny state to eksperymentalne API (z wyjątkiem vitest.state.getReportedEntity). Zmiany powodujące niezgodność mogą nie być zgodne z SemVer, proszę zablokować wersję Vitest podczas korzystania z niego.

Globalny stan przechowuje informacje o aktualnych testach. Domyślnie używa tego samego API z @vitest/runner, ale zalecamy użycie Reported Tasks API zamiast tego, wywołując state.getReportedEntity() na API @vitest/runner:

const task = vitest.state.idMap.get(taskId); // stare API
const testCase = vitest.state.getReportedEntity(task); // nowe API

W przyszłości stare API nie będzie już udostępniane.

snapshot

Globalny menedżer migawek. Vitest śledzi wszystkie migawki za pomocą metody snapshot.add.

Możesz uzyskać najnowsze podsumowanie migawek za pomocą właściwości vitest.snapshot.summary.

cache

Menedżer pamięci podręcznej przechowujący informacje o najnowszych wynikach testów oraz statystykach plików testowych. W samym Vitest jest to używane tylko przez domyślny sekwencer do sortowania testów.

projects

Tablica projektów testowych należących do użytkownika. Jeśli użytkownik ich nie zdefiniował, ta tablica będzie zawierać tylko projekt główny.

Vitest zapewni, że w tej tablicy zawsze będzie co najmniej jeden projekt. Jeśli użytkownik poda nieistniejącą nazwę --project, Vitest zgłosi błąd, zanim ta tablica zostanie zdefiniowana.

getRootProject

function getRootProject(): TestProject;

Ta metoda zwraca główny projekt testowy. Projekt główny zazwyczaj nie uruchamia żadnych testów i nie jest uwzględniany w vitest.projects, chyba że użytkownik jawnie uwzględni konfigurację główną w swojej konfiguracji lub projekty w ogóle nie są zdefiniowane.

Głównym celem projektu głównego jest skonfigurowanie globalnej konfiguracji. Faktycznie rootProject.config odwołuje się bezpośrednio do rootProject.globalConfig i vitest.config:

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

provide

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

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

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

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

Dla lepszego bezpieczeństwa typów, zachęcamy do rozszerzenia interfejsu 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

Technicznie rzecz biorąc, provide jest metodą TestProject, więc jest ograniczona do konkretnego projektu. Jednak wszystkie projekty dziedziczą wartości z projektu głównego, co sprawia, że vitest.provide jest uniwersalnym sposobem przekazywania wartości do testów.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Ta metoda zwraca główny obiekt kontekstu. Jest to skrót dla vitest.getRootProject().getProvidedContext.

getProjectByName

function getProjectByName(name: string): TestProject;

Ta metoda zwraca projekt na podstawie jego nazwy. Jest to równoznaczne z wywołaniem vitest.projects.find.

WARNING

Jeśli projekt nie istnieje, ta metoda zwróci projekt główny - upewnij się, że ponownie sprawdzisz nazwy, aby upewnić się, że zwrócony projekt jest tym, którego szukasz.

Jeśli użytkownik nie dostosował nazwy, Vitest przypisze pusty ciąg jako nazwę.

globTestSpecifications

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

Ta metoda konstruuje nowe specyfikacje testowe poprzez gromadzenie wszystkich testów we wszystkich projektach za pomocą project.globTestFiles. Akceptuje filtry tekstowe do dopasowania plików testowych - są to te same filtry, które obsługuje CLI.

Ta metoda automatycznie buforuje specyfikacje testowe dla każdego pliku. Gdy następnym razem wywołasz getModuleSpecifications, zwróci te same specyfikacje, chyba że wcześniej wywołano clearSpecificationsCache.

WARNING

Od Vitest 3 możliwe jest posiadanie wielu specyfikacji testowych z tym samym identyfikatorem modułu (ścieżką pliku), jeśli poolMatchGlob ma kilka pul lub jeśli typecheck jest włączony. Ta możliwość zostanie usunięta w 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[]>;

Ta metoda znajduje każdą specyfikację testową, wywołując project.globTestFiles. Akceptuje filtry tekstowe do dopasowania plików testowych - są to te same filtry, które obsługuje CLI. Jeśli podano flagę --changed, lista zostanie przefiltrowana, zawierając tylko zmienione pliki. getRelevantTestSpecifications nie uruchamia żadnych plików testowych.

WARNING

Ta metoda może być wolna, ponieważ musi filtrować wyniki na podstawie flagi --changed. Nie używaj jej, jeśli potrzebujesz tylko listy plików testowych.

• Jeśli potrzebujesz uzyskać listę specyfikacji dla znanych plików testowych, użyj zamiast tego getModuleSpecifications.
• Jeśli potrzebujesz uzyskać listę wszystkich możliwych plików testowych, użyj globTestSpecifications.

mergeReports

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

Łączy raporty z wielu uruchomień znajdujących się w określonym katalogu (wartość opcji --merge-reports, jeśli nie określono). Ta wartość może być również ustawiona w config.mergeReports (domyślnie będzie odczytywać folder .vitest-reports).

Zauważ, że directory zawsze będzie rozwiązywany względem katalogu roboczego.

Ta metoda jest wywoływana automatycznie przez startVitest, jeśli config.mergeReports jest ustawione.

collect

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

Wykonuje pliki testowe bez wywoływania callbacków testowych. collect zwraca nieobsłużone błędy i tablicę modułów testowych. Akceptuje filtry tekstowe do dopasowania plików testowych - są to te same filtry, które obsługuje CLI.

Ta metoda określa specyfikacje testów na podstawie wartości include, exclude i includeSource w konfiguracji. Więcej informacji można znaleźć w project.globTestFiles. Jeśli podano flagę --changed, lista zostanie przefiltrowana, aby zawierała tylko zmienione pliki.

WARNING

Należy zauważyć, że Vitest nie używa analizy statycznej do zbierania testów. Vitest uruchomi każdy plik testowy w izolacji, tak jak uruchamia zwykłe testy.

To sprawia, że ta metoda jest bardzo wolna, chyba że wyłączysz izolację przed zbieraniem testów.

start

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

Inicjalizuje reportery, dostawcę danych o pokryciu kodu i uruchamia testy. Ta metoda akceptuje filtry tekstowe do dopasowania plików testowych - są to te same filtry, które obsługuje CLI.

WARNING

Nie należy wywoływać tej metody, jeśli również wywołano vitest.init(). Użyj runTestSpecifications lub rerunTestSpecifications, jeśli musisz uruchomić testy po zainicjowaniu Vitest.

Ta metoda jest wywoływana automatycznie przez startVitest, jeśli config.mergeReports i config.standalone nie są ustawione.

init

function init(): Promise<void>;

Inicjalizuje reportery i dostawcę danych o pokryciu kodu. Ta metoda nie uruchamia żadnych testów. Jeśli podano flagę --watch, Vitest nadal będzie uruchamiać zmienione testy, nawet jeśli ta metoda nie została wywołana.

Wewnętrznie ta metoda jest wywoływana tylko wtedy, gdy flaga --standalone jest włączona.

WARNING

Nie należy wywoływać tej metody, jeśli również wywołano vitest.start().

Ta metoda jest wywoływana automatycznie przez startVitest, jeśli config.standalone jest ustawione.

getModuleSpecifications

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

Zwraca listę specyfikacji testowych związanych z identyfikatorem modułu. Identyfikator powinien być już przekształcony w bezwzględną ścieżkę pliku. Jeśli identyfikator nie pasuje do wzorców include lub includeSource, zwrócona tablica będzie pusta.

Ta metoda może zwracać już zbuforowane specyfikacje na podstawie moduleId i pool. Należy jednak pamiętać, że project.createSpecification zawsze zwraca nową instancję i nie jest automatycznie zapisywana w pamięci podręcznej. Jednak specyfikacje są automatycznie buforowane, gdy wywoływana jest runTestSpecifications.

WARNING

Od Vitest 3, ta metoda używa pamięci podręcznej, aby sprawdzić, czy plik jest testem. Aby upewnić się, że pamięć podręczna nie jest pusta, wywołaj globTestSpecifications przynajmniej raz.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest automatycznie buforuje specyfikacje testowe dla każdego pliku, gdy wywoływana jest globTestSpecifications lub runTestSpecifications. Ta metoda czyści pamięć podręczną dla danego pliku lub całą pamięć podręczną, w zależności od pierwszego argumentu.

runTestSpecifications

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

Ta metoda uruchamia każdy test na podstawie otrzymanych specyfikacji. Drugi argument, allTestsRun, jest używany przez dostawcę pokrycia kodu do określenia, czy musi instrumentować pokrycie kodu dla każdego pliku w katalogu głównym (ma to znaczenie tylko wtedy, gdy pokrycie kodu jest włączone, a coverage.all jest ustawione na true).

WARNING

Ta metoda nie wywołuje funkcji zwrotnych onWatcherRerun, onWatcherStart i onTestsRerun. Jeśli ponownie uruchamiasz testy w odpowiedzi na zmianę pliku, rozważ użycie zamiast tego rerunTestSpecifications.

rerunTestSpecifications

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

Ta metoda wywołuje zdarzenia reporter.onWatcherRerun i onTestsRerun, a następnie uruchamia testy za pomocą runTestSpecifications. Jeśli w głównym procesie nie było błędów, wywoła zdarzenie reporter.onWatcherStart.

updateSnapshot

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

Aktualizuje migawki w podanych plikach. Jeśli nie podano plików, zaktualizuje pliki zawierające nieudane testy i przestarzałe migawki.

collectTests

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

Wykonuje pliki testowe bez wywoływania callbacków testowych. collectTests zwraca nieobsłużone błędy i tablicę modułów testowych.

Ta metoda działa dokładnie tak samo jak collect, ale musisz samodzielnie podać specyfikacje testów.

WARNING

Należy zauważyć, że Vitest nie używa analizy statycznej do zbierania testów. Vitest uruchomi każdy plik testowy w izolacji, tak jak uruchamia zwykłe testy.

To sprawia, że ta metoda jest bardzo wolna, chyba że wyłączysz izolację przed zbieraniem testów.

cancelCurrentRun

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

Ta metoda bezpiecznie anuluje wszystkie trwające testy. Będzie czekać na zakończenie uruchomionych testów i pominie testy, które były zaplanowane, ale jeszcze się nie rozpoczęły.

setGlobalTestNamePattern

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

Ta metoda ustawia globalny wzorzec nazwy testu.

WARNING

Ta metoda nie uruchamia żadnych testów. Aby uruchomić testy ze zaktualizowanym wzorcem, wywołaj runTestSpecifications.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Ta metoda resetuje wzorzec nazwy testu. Oznacza to, że Vitest nie będzie już pomijać żadnych testów.

WARNING

Ta metoda nie uruchamia żadnych testów. Aby uruchomić testy bez wzorca, wywołaj runTestSpecifications.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Włącza tryb, który umożliwia aktualizację migawek podczas uruchamiania testów. Każdy test, który zostanie uruchomiony po wywołaniu tej metody, spowoduje aktualizację migawek. Aby wyłączyć ten tryb, wywołaj resetSnapshotUpdate.

WARNING

Ta metoda nie uruchamia żadnych testów. Aby zaktualizować migawki, uruchom testy za pomocą runTestSpecifications.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Wyłącza tryb, który pozwala na aktualizację migawek podczas uruchamiania testów. Ta metoda nie uruchamia żadnych testów.

invalidateFile

function invalidateFile(filepath: string): void;

Ta metoda unieważnia wpis pliku w pamięci podręcznej każdego projektu. Jest to szczególnie przydatne, jeśli polegasz na własnym obserwatorze, ponieważ pamięć podręczna Vite pozostaje w pamięci.

DANGER

Jeśli wyłączysz obserwatora Vitest, ale Vitest będzie nadal działać, ważne jest, aby ręcznie wyczyścić pamięć podręczną za pomocą tej metody, ponieważ nie ma sposobu na wyłączenie pamięci podręcznej. Ta metoda unieważni również moduły importujące dany plik.

import

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

Importuje plik za pomocą runnera modułów Vite. Plik zostanie przekształcony przez Vite przy użyciu globalnej konfiguracji i wykonany w odrębnym kontekście. Zauważ, ż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 spowoduje załadowanie innej instancji modułu:

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

dynamicExample !== staticExample; // ✅

INFO

Wewnętrznie Vitest używa tej metody do importowania globalnych konfiguracji, niestandardowych dostawców pokrycia kodu testami i niestandardowych reporterów, co oznacza, że wszystkie one współdzielą ten sam graf modułów, o ile należą do tego samego serwera Vite.

close

function close(): Promise<void>;

Zamyka wszystkie projekty i powiązane z nimi zasoby. Może być wywołana tylko raz; promise zamknięcia jest przechowywana w pamięci podręcznej do momentu ponownego uruchomienia serwera.

exit

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

Zamyka wszystkie projekty i wyłącza proces. Jeśli force jest ustawione na true, proces zakończy się natychmiast po zamknięciu projektów.

Ta metoda wymusi również wywołanie process.exit(), jeśli proces jest nadal aktywny po config.teardownTimeout milisekundach.

shouldKeepServer

function shouldKeepServer(): boolean;

Ta metoda zwróci true, jeśli serwer ma pozostać uruchomiony po zakończeniu testów. Zazwyczaj oznacza to, że tryb watch jest włączony.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Rejestruje funkcję obsługi, która zostanie wywołana po ponownym uruchomieniu serwera z powodu zmiany konfiguracji.

onCancel

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

Rejestruje funkcję obsługi, która zostanie wywołana, gdy uruchomienie testu zostanie anulowane za pomocą vitest.cancelCurrentRun.

onClose

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

Rejestruje funkcję obsługi, która zostanie wywołana po zamknięciu serwera.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Rejestruje funkcję obsługi, która zostanie wywołana, gdy testy są ponownie uruchamiane. Testy mogą być ponownie uruchamiane, gdy rerunTestSpecifications zostanie wywołane ręcznie lub gdy plik zostanie zmieniony, a wbudowany obserwator zaplanuje ponowne uruchomienie.

onFilterWatchedSpecification

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

Rejestruje funkcję obsługi, która zostanie wywołana po zmianie pliku. Ta funkcja zwrotna powinna zwrócić true lub false, aby wskazać, czy plik testowy wymaga ponownego uruchomienia.

Dzięki tej metodzie możesz zintegrować się z domyślną logiką obserwatora, aby opóźnić lub odrzucić testy, których użytkownik nie chce w danej chwili monitorować:

const continuesTests: string[] = [];

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

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

Vitest może tworzyć różne specyfikacje dla tego samego pliku w zależności od opcji pool lub locations, więc nie polegaj na tożsamości obiektu. Vitest może również zwrócić zbuforowaną specyfikację z vitest.getModuleSpecifications - pamięć podręczna jest oparta na moduleId i pool. Zauważ, że project.createSpecification zawsze zwraca nową instancję.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Sprawdza, czy nazwa odpowiada bieżącemu filtrowi projektu. Jeśli nie ma filtra projektu, zawsze zwraca true.

Nie jest możliwa programistyczna zmiana opcji CLI --project.