Vitest API

Die Vitest-Instanz erfordert den aktuellen Testmodus, der wie folgt festgelegt werden kann:

test für die Ausführung von Laufzeittests.
benchmark für die Ausführung von Benchmarks. Experimentell

Neu in Vitest 3

Vitest 3 ist der Stabilisierung der öffentlichen API einen Schritt näher gekommen. Um dies zu erreichen, wurden einige der zuvor öffentlichen Methoden der Vitest-Klasse als veraltet markiert und entfernt. Die folgenden APIs wurden als privat deklariert:

configOverride (verwenden Sie stattdessen setGlobalTestNamePattern oder enableSnapshotUpdate)
coverageProvider
filenamePattern
runningPromise
closingPromise
isCancelling
coreWorkspaceProject
resolvedProjects
_browserLastPort
_options
reporters
vitenode
runner
pool
setServer
_initBrowserServers
rerunTask
changeProjectName
changeNamePattern
changeFilenamePattern
rerunFailed
_createRootProject (umbenannt in _ensureRootProject, bleibt aber privat)
filterTestsBySource (wurde in die neue interne vitest.specifications-Instanz verschoben)
runFiles (verwenden Sie stattdessen runTestSpecifications)
onAfterSetServer

Die folgenden APIs wurden als veraltet markiert:

invalidates
changedTests (verwenden Sie stattdessen onFilterWatchedSpecification)
server (verwenden Sie stattdessen vite)
getProjectsByTestFile (verwenden Sie stattdessen getModuleSpecifications)
getFileWorkspaceSpecs (verwenden Sie stattdessen getModuleSpecifications)
getModuleProjects (filtern Sie selbst nach this.projects)
updateLastChanged (umbenannt in invalidateFile)
globTestSpecs (verwenden Sie stattdessen globTestSpecifications)
globTestFiles (verwenden Sie stattdessen globTestSpecifications)
listFile (verwenden Sie stattdessen getRelevantTestSpecifications)

mode

test

Im Testmodus werden nur Funktionen innerhalb von test oder it ausgeführt. Wenn bench angetroffen wird, wird ein Fehler ausgelöst. Dieser Modus verwendet die Konfigurationsoptionen include und exclude, um Testdateien zu identifizieren.

benchmark Experimentell

Im Benchmark-Modus werden bench-Funktionen ausgeführt. Wenn test oder it angetroffen wird, wird ein Fehler ausgelöst. Dieser Modus verwendet die Konfigurationsoptionen benchmark.include und benchmark.exclude, um Benchmark-Dateien zu identifizieren.

config

Die Root- (oder globale) Konfiguration. Wenn Projekte definiert sind, wird diese als globalConfig bezeichnet.

WARNING

Dies ist die Vitest-Konfiguration; sie erweitert nicht die Vite-Konfiguration. Sie enthält nur die ermittelten Werte aus der test-Eigenschaft.

vite

Dies ist ein globaler ViteDevServer.

state Experimentell

WARNING

Die öffentliche state-API ist experimentell (mit Ausnahme von vitest.state.getReportedEntity). Breaking Changes folgen möglicherweise nicht dem SemVer. Bitte fixieren Sie die Vitest-Version, wenn Sie sie verwenden.

Der globale Zustand speichert Informationen über die aktuellen Tests. Er verwendet standardmäßig dieselbe API von @vitest/runner, aber wir empfehlen, stattdessen die Reported Tasks API zu verwenden, indem Sie state.getReportedEntity() von der @vitest/runner-API aufrufen:

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

Zukünftig wird die alte API nicht mehr öffentlich zugänglich sein.

snapshot

Der globale Snapshot-Manager. Vitest verwaltet alle Snapshots mithilfe der Methode snapshot.add.

Sie können die neueste Zusammenfassung der Snapshots über die Eigenschaft vitest.snapshot.summary abrufen.

cache

Der Cache-Manager speichert Informationen über die neuesten Testergebnisse und Statistiken zu Testdateien. In Vitest selbst wird dies nur vom Standard-Sequenzer verwendet, um Tests zu sortieren.

projects

Ein Array von Testprojekten, die den Projekten des Benutzers zugeordnet sind. Wenn der Benutzer keine Projekte angegeben hat, enthält dieses Array nur ein Root-Projekt.

Vitest stellt sicher, dass immer mindestens ein Projekt in diesem Array vorhanden ist. Wenn der Benutzer einen nicht existierenden --project-Namen angibt, löst Vitest einen Fehler aus, bevor dieses Array definiert wird.

getRootProject

function getRootProject(): TestProject;

Diese Methode gibt das Root-Testprojekt zurück. Das Root-Projekt führt im Allgemeinen keine Tests aus und ist nicht in vitest.projects enthalten, es sei denn, der Benutzer schließt die Root-Konfiguration explizit in seine Konfiguration ein oder es sind überhaupt keine Projekte definiert.

Das Hauptziel des Root-Projekts ist es, die globale Konfiguration einzurichten. Tatsächlich verweist rootProject.config direkt auf rootProject.globalConfig und vitest.config:

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

provide

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

Vitest stellt die Methode provide zur Verfügung, die eine Kurzform für vitest.getRootProject().provide ist. Mit dieser Methode können Sie Werte vom Haupt-Thread an Tests übergeben. Alle Werte werden vor dem Speichern mit structuredClone validiert, aber die Werte selbst werden nicht geklont.

Um die Werte im Test zu empfangen, müssen Sie die Methode inject aus dem vitest-Einstiegspunkt importieren:

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

Für eine bessere Typsicherheit empfehlen wir Ihnen, den Typ von ProvidedContext zu ergänzen:

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

Technisch gesehen ist provide eine Methode von TestProject und somit auf das spezifische Projekt beschränkt. Alle Projekte erben jedoch die Werte vom Root-Projekt, wodurch vitest.provide zu einer universellen Methode wird, um Werte an Tests weiterzugeben.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Dies gibt das Root-Kontextobjekt zurück. Dies ist eine Kurzform für vitest.getRootProject().getProvidedContext.

getProjectByName

function getProjectByName(name: string): TestProject;

Diese Methode gibt das Projekt anhand seines Namens zurück. Dies ist vergleichbar mit dem Aufruf von vitest.projects.find.

WARNING

Falls das Projekt nicht existiert, gibt diese Methode das Root-Projekt zurück – stellen Sie sicher, dass Sie die Namen erneut überprüfen, um zu bestätigen, dass das zurückgegebene Projekt das von Ihnen gesuchte ist.

Wenn der Benutzer keinen Namen vergeben hat, weist Vitest einen leeren String als Namen zu.

globTestSpecifications

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

Diese Methode erstellt neue Testspezifikationen, indem sie jeden Test in allen Projekten mittels project.globTestFiles erfasst. Sie akzeptiert String-Filter, um die Testdateien zu filtern – dies sind dieselben Filter, die von der CLI unterstützt werden.

Diese Methode speichert automatisch alle Testspezifikationen im Cache. Wenn Sie getModuleSpecifications das nächste Mal aufrufen, werden dieselben Spezifikationen zurückgegeben, es sei denn, clearSpecificationsCache wurde zuvor aufgerufen.

WARNING

Ab Vitest 3 ist es möglich, dass mehrere Testspezifikationen mit derselben Modul-ID (Dateipfad) vorhanden sind, wenn poolMatchGlob mehrere Pools hat oder wenn typecheck aktiviert ist. Diese Möglichkeit wird in Vitest 4 entfallen.

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

getRelevantTestSpecifications

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

Diese Methode löst jede Testspezifikation auf, indem sie project.globTestFiles aufruft. Sie akzeptiert String-Filter, um die Testdateien zu filtern – dies sind dieselben Filter, die von der CLI unterstützt werden. Wenn das Flag --changed angegeben wurde, wird die Liste gefiltert, um nur geänderte Dateien einzuschließen. getRelevantTestSpecifications führt keine Testdateien aus.

WARNING

Diese Methode kann langsam sein, da sie die --changed-Flags berücksichtigen muss. Verwenden Sie sie nicht, wenn Sie nur eine Liste von Testdateien benötigen.

Wenn Sie die Liste der Spezifikationen für bekannte Testdateien benötigen, verwenden Sie stattdessen getModuleSpecifications.
Wenn Sie die Liste aller möglichen Testdateien abrufen müssen, verwenden Sie globTestSpecifications.

mergeReports

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

Zusammenführung von Berichten aus mehreren Läufen, die sich im angegebenen Verzeichnis befinden (Wert von --merge-reports, falls nicht angegeben). Dieser Wert kann auch in config.mergeReports festgelegt werden (standardmäßig wird der Ordner .vitest-reports ausgelesen).

Beachten Sie, dass das directory immer relativ zum Arbeitsverzeichnis ermittelt wird.

Diese Methode wird automatisch von startVitest aufgerufen, wenn config.mergeReports gesetzt ist.

collect

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

Führt Testdateien aus, ohne Test-Callbacks auszuführen. collect gibt nicht behandelte Fehler und ein Array von Testmodulen zurück. Es akzeptiert String-Filter, um die Testdateien zu filtern – dies sind dieselben Filter, die von der CLI unterstützt werden.

Diese Methode ermittelt Testspezifikationen basierend auf den Konfigurationswerten include, exclude und includeSource. Weitere Informationen finden Sie unter project.globTestFiles. Wenn das Flag --changed angegeben wurde, wird die Liste gefiltert, um nur geänderte Dateien einzuschließen.

WARNING

Beachten Sie, dass Vitest keine statische Analyse verwendet, um Tests zu erfassen. Vitest führt jede Testdatei isoliert aus, genau wie reguläre Tests.

Dies verlangsamt diese Methode erheblich, es sei denn, Sie deaktivieren die Isolation, bevor Sie Tests sammeln.

start

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

Initialisiert Reporter, den Coverage-Anbieter und führt Tests aus. Diese Methode akzeptiert String-Filter, um die Testdateien zu filtern – dies sind dieselben Filter, die von der CLI unterstützt werden.

WARNING

Diese Methode sollte nicht aufgerufen werden, wenn vitest.init() ebenfalls in Anspruch genommen wird. Verwenden Sie stattdessen runTestSpecifications oder rerunTestSpecifications, wenn Sie Tests ausführen müssen, nachdem Vitest initialisiert wurde.

Diese Methode wird automatisch von startVitest aufgerufen, wenn config.mergeReports und config.standalone nicht konfiguriert sind.

init

function init(): Promise<void>;

Initialisiert Reporter und den Coverage-Anbieter. Diese Methode führt keine Tests aus. Wenn das --watch-Flag aktiviert ist, führt Vitest geänderte Tests trotzdem aus, auch wenn diese Methode nicht aufgerufen wurde.

Intern wird diese Methode nur aufgerufen, wenn das Flag --standalone gesetzt ist.

WARNING

Diese Methode sollte nicht aufgerufen werden, wenn vitest.start() ebenfalls aufgerufen wird.

Diese Methode wird automatisch von startVitest aufgerufen, wenn config.standalone gesetzt ist.

getModuleSpecifications

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

Gibt eine Liste von Testspezifikationen zurück, die der Modul-ID zugeordnet sind. Die ID sollte bereits zu einem absoluten Dateipfad ermittelt sein. Wenn die ID nicht den Mustern include oder includeSource entspricht, ist das zurückgegebene Array leer.

Diese Methode kann bereits zwischengespeicherte Spezifikationen basierend auf der moduleId und dem pool zurückgeben. Beachten Sie jedoch, dass project.createSpecification immer eine neue Instanz zurückgibt und nicht automatisch im Cache abgelegt wird. Spezifikationen werden jedoch automatisch im Cache abgelegt, wenn runTestSpecifications aufgerufen wird.

WARNING

Ab Vitest 3 verwendet diese Methode einen Cache, um zu überprüfen, ob es sich bei der Datei um einen Test handelt. Um sicherzustellen, dass der Cache gefüllt ist, rufen Sie globTestSpecifications mindestens einmal auf.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest legt Testspezifikationen für jede Datei automatisch im Cache ab, wenn globTestSpecifications oder runTestSpecifications aufgerufen wird. Diese Methode löscht den Cache für die angegebene Datei oder den gesamten Cache, abhängig vom ersten Argument.

runTestSpecifications

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

Diese Methode führt jeden Test basierend auf den empfangenen Spezifikationen aus. Das zweite Argument, allTestsRun, wird vom Coverage-Provider verwendet, um zu bestimmen, ob er die Coverage für jede Datei im Root-Verzeichnis instrumentieren muss (dies ist nur relevant, wenn Coverage aktiviert ist und coverage.all auf true gesetzt ist).

WARNING

Diese Methode ruft keine onWatcherRerun, onWatcherStart und onTestsRerun Callbacks auf. Wenn Sie Tests aufgrund einer Dateiänderung erneut ausführen, sollten Sie stattdessen rerunTestSpecifications verwenden.

rerunTestSpecifications

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

Diese Methode löst reporter.onWatcherRerun und onTestsRerun Ereignisse aus, dann führt sie Tests mit runTestSpecifications aus. Wenn im Hauptprozess keine Fehler auftraten, löst sie das reporter.onWatcherStart Ereignis aus.

updateSnapshot

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

Aktualisiert Snapshots in den spezifizierten Dateien. Wenn keine Dateien angegeben sind, werden Dateien mit fehlgeschlagenen Tests und überholten Snapshots aktualisiert.

collectTests

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

Führt Testdateien aus, ohne Test-Callbacks auszuführen. collectTests gibt nicht behandelte Fehler und ein Array von Testmodulen zurück.

Diese Methode funktioniert identisch mit collect, aber Sie müssen die Testspezifikationen selbst bereitstellen.

WARNING

Beachten Sie, dass Vitest keine statische Analyse verwendet, um Tests zu erfassen. Vitest führt jede Testdatei isoliert aus, genau wie reguläre Tests.

Dies verlangsamt diese Methode erheblich, es sei denn, Sie deaktivieren die Isolation, bevor Sie Tests sammeln.

cancelCurrentRun

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

Diese Methode bricht alle laufenden Tests kontrolliert ab. Sie wartet, bis gestartete Tests abgeschlossen sind, und führt keine Tests aus, die geplant waren, aber noch nicht gestartet wurden.

setGlobalTestNamePattern

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

Diese Methode überschreibt das globale Testnamensmuster.

WARNING

Diese Methode startet keine Tests. Um Tests mit dem aktualisierten Muster auszuführen, rufen Sie runTestSpecifications auf.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Diese Methode setzt das Testnamensmuster zurück. Das bedeutet, dass Vitest nun keine Tests mehr überspringt.

WARNING

Diese Methode startet keine Tests. Um Tests ohne Muster auszuführen, rufen Sie runTestSpecifications auf.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Aktiviert den Modus zum Aktualisieren von Snapshots während der Testausführung. Jeder Test, der nach dem Aufruf dieser Methode läuft, aktualisiert Snapshots. Um den Modus zu deaktivieren, rufen Sie resetSnapshotUpdate auf.

WARNING

Diese Methode startet keine Tests. Um Snapshots zu aktualisieren, führen Sie Tests mit runTestSpecifications aus.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Deaktiviert den Modus, der das Aktualisieren von Snapshots beim Ausführen von Tests ermöglicht. Diese Methode startet keine Tests.

invalidateFile

function invalidateFile(filepath: string): void;

Diese Methode macht die Datei im Cache jedes Projekts ungültig. Dies ist meist nützlich, wenn Sie sich auf Ihren eigenen Watcher verlassen, da der Vite-Cache im Speicher bestehen bleibt.

DANGER

Wenn Sie den Vitest-Watcher deaktivieren, Vitest aber weiterhin ausführen, ist es wichtig, den Cache manuell mit dieser Methode zu leeren, da es keine Möglichkeit gibt, den Cache zu deaktivieren. Diese Methode macht auch die Importe der Datei ungültig.

import

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

Importiert eine Datei über den Vite-Modul-Runner. Die Datei wird von Vite unter Verwendung der globalen Konfiguration transformiert und in einem separaten Kontext ausgeführt. Beachten Sie, dass moduleId relativ zu config.root ist.

DANGER

project.import greift auf den Modulgraphen von Vite zurück, daher gibt der Import desselben Moduls mit einem regulären Import ein anderes Modul zurück:

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

dynamicExample !== staticExample; // ✅

INFO

Intern verwendet Vitest diese Methode, um globale Setups, benutzerdefinierte Coverage-Anbieter und benutzerdefinierte Reporter zu importieren. Dies bedeutet, dass sie alle denselben Modulgraphen teilen, solange sie zum selben Vite-Server gehören.

close

function close(): Promise<void>;

Schließt alle Projekte und ihre zugehörigen Ressourcen. Dies kann nur einmal aufgerufen werden; das Promise für das Schließen wird bis zum Neustart des Servers zwischengespeichert.

exit

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

Schließt alle Projekte und beendet den Prozess. Wenn force auf true steht, wird der Prozess sofort nach dem Schließen der Projekte beendet.

Diese Methode ruft auch process.exit() erzwungen auf, wenn der Prozess nach config.teardownTimeout Millisekunden noch aktiv ist.

shouldKeepServer

function shouldKeepServer(): boolean;

Diese Methode gibt true zurück, wenn der Server nach Abschluss der Tests aktiv bleiben soll. Dies bedeutet normalerweise, dass der watch-Modus eingeschaltet wurde.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Registriert einen Handler, der bei einem Neustart des Servers aufgrund einer Konfigurationsänderung aufgerufen wird.

onCancel

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

Registriert einen Handler, der aufgerufen wird, wenn der Testlauf mittels vitest.cancelCurrentRun abgebrochen wird.

onClose

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

Registriert einen Handler, der beim Schließen des Servers aufgerufen wird.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Registriert einen Handler, der aufgerufen wird, wenn die Tests erneut laufen. Die Tests können erneut laufen, wenn rerunTestSpecifications manuell aufgerufen wird oder wenn eine Datei geändert wird und der integrierte Watcher eine erneute Ausführung plant.

onFilterWatchedSpecification

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

Registriert einen Handler, der aufgerufen wird, wenn sich eine Datei ändert. Dieser Callback sollte true oder false zurückgeben, der angibt, ob die Testdatei erneut ausgeführt werden muss.

Mit dieser Methode können Sie in die Standard-Watcher-Logik eingreifen, um Tests zu verzögern oder zu verwerfen, die der Benutzer im Moment nicht verfolgen möchte:

const continuesTests: string[] = [];

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

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

Vitest kann je nach den Optionen pool oder locations unterschiedliche Spezifikationen für dieselbe Datei erstellen, verlassen Sie sich daher nicht auf die Referenz. Vitest kann auch Spezifikationen aus dem Cache von vitest.getModuleSpecifications zurückgeben – der Cache basiert auf der moduleId und dem pool. Beachten Sie, dass project.createSpecification immer eine neue Instanz zurückgibt.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Überprüft, ob der Name dem aktuellen Projektfilter entspricht. Wenn kein Projektfilter gesetzt ist, wird immer true zurückgegeben.

Es ist nicht möglich, die --project-CLI-Option programmgesteuert zu ändern.

Vitest API ​

mode ​

test ​

benchmark Experimentell ​

config ​

vite ​

state Experimentell ​

snapshot ​

cache ​

projects ​

getRootProject ​

provide ​

getProvidedContext ​

getProjectByName ​

globTestSpecifications ​

getRelevantTestSpecifications ​

mergeReports ​

collect ​

start ​

init ​

getModuleSpecifications ​

clearSpecificationsCache ​

runTestSpecifications ​

rerunTestSpecifications ​

updateSnapshot ​

collectTests ​

cancelCurrentRun ​

setGlobalTestNamePattern ​

resetGlobalTestNamePattern ​

enableSnapshotUpdate ​

resetSnapshotUpdate ​

invalidateFile ​

import ​

close ​

exit ​

shouldKeepServer ​

onServerRestart ​

onCancel ​

onClose ​

onTestsRerun ​

onFilterWatchedSpecification ​

matchesProjectFilter 3.1.0+ ​

Vitest API

mode

test

benchmark Experimentell

config

vite

state Experimentell

snapshot

cache

projects

getRootProject

provide

getProvidedContext

getProjectByName

globTestSpecifications

getRelevantTestSpecifications

mergeReports

collect

start

init

getModuleSpecifications

clearSpecificationsCache

runTestSpecifications

rerunTestSpecifications

updateSnapshot

collectTests

cancelCurrentRun

setGlobalTestNamePattern

resetGlobalTestNamePattern

enableSnapshotUpdate

resetSnapshotUpdate

invalidateFile

import

close

exit

shouldKeepServer

onServerRestart

onCancel

onClose

onTestsRerun

onFilterWatchedSpecification

matchesProjectFilter 3.1.0+