Node API

WARNING

Vitest stellt eine experimentelle, private API bereit. Änderungen, die die Kompatibilität brechen, folgen möglicherweise nicht den SemVer-Richtlinien. Bitte verwenden Sie eine feste Vitest-Version, wenn Sie diese API nutzen.

startVitest

Sie können Vitest-Tests über die Node-API starten:

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest?.close();

Die Funktion startVitest gibt eine Vitest-Instanz zurück, wenn die Tests erfolgreich gestartet werden konnten. Sie gibt undefined zurück, wenn eine der folgenden Bedingungen zutrifft:

• Vitest konnte das Paket vite nicht finden (dies ist normalerweise mit Vitest installiert).
• Die Coverage ist aktiviert und der Ausführungsmodus ist "test", aber das Coverage-Paket ist nicht installiert (@vitest/coverage-v8 oder @vitest/coverage-istanbul).
• Das Umgebungspaket ist nicht installiert (jsdom / happy-dom / @edge-runtime/vm).

Wenn undefined zurückgegeben wird oder Tests während der Ausführung fehlschlagen, setzt Vitest process.exitCode auf 1.

Wenn der Watch-Modus nicht aktiviert ist, ruft Vitest die Methode close auf.

Wenn der Watch-Modus aktiviert ist und das Terminal TTY unterstützt, registriert Vitest Tastenkombinationen für die Konsole.

Sie können eine Liste von Filtern als zweites Argument angeben. Vitest führt dann nur Tests aus, deren Dateipfad mindestens einen der übergebenen Strings enthält.

Zusätzlich können Sie das dritte Argument verwenden, um CLI-Argumente zu übergeben, die alle Testkonfigurationsoptionen überschreiben.

Alternativ können Sie die vollständige Vite-Konfiguration als viertes Argument übergeben. Diese hat Vorrang vor allen benutzerdefinierten Optionen.

Nach der Ausführung der Tests können Sie die Ergebnisse über die state.getFiles-API abrufen:

const vitest = await startVitest('test');

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

Seit Vitest 2.1 wird empfohlen, die "Reported Tasks" API zusammen mit state.getFiles zu verwenden. In Zukunft wird Vitest diese Objekte direkt zurückgeben:

const vitest = await startVitest('test');

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

createVitest

Sie können eine Vitest-Instanz selbst mit der Funktion createVitest erstellen. Sie gibt dieselbe Vitest-Instanz wie startVitest zurück, startet jedoch keine Tests und überprüft auch nicht, ob die erforderlichen Pakete installiert sind.

import { createVitest } from 'vitest/node';

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

parseCLI

Sie können diese Methode verwenden, um CLI-Argumente zu parsen. Sie akzeptiert entweder einen String, in dem die Argumente durch ein einzelnes Leerzeichen getrennt sind, oder ein Array von Strings im gleichen Format, das von der Vitest CLI verwendet wird. Sie gibt einen Filter und options zurück, die Sie später an die Methoden createVitest oder startVitest übergeben können.

import { parseCLI } from 'vitest/node';

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

Vitest

Die Vitest-Instanz benötigt den aktuellen Testmodus. Dies kann entweder sein:

• test beim Ausführen von Runtime-Tests
• benchmark beim Ausführen von Benchmarks

mode

test

Der Testmodus führt nur Funktionen innerhalb von test oder it aus und löst einen Fehler aus, wenn bench aufgerufen wird. Dieser Modus verwendet die Optionen include und exclude in der Konfiguration, um Testdateien zu filtern.

benchmark

Der Benchmark-Modus führt bench-Funktionen aus und löst einen Fehler aus, wenn test oder it aufgerufen wird. Dieser Modus verwendet die Optionen benchmark.include und benchmark.exclude in der Konfiguration, um Benchmark-Dateien zu finden.

start

Sie können die Ausführung von Tests oder Benchmarks mit der Methode start starten. Sie können ein Array von Strings übergeben, um Testdateien zu filtern.

provide

Vitest stellt die Methode provide bereit, die eine Abkürzung für vitest.getCoreWorkspaceProject().provide ist. Mit dieser Methode können Sie Werte vom Haupt-Thread an Tests übermitteln. Alle Werte werden mit structuredClone geprüft, bevor sie gespeichert werden, aber die Werte selbst werden nicht geklont.

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

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

Für eine höhere Typsicherheit empfehlen wir Ihnen, den Typ von ProvidedContext zu erweitern:

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 des WorkspaceProject, weshalb sie auf das spezifische Projekt beschränkt ist. Alle Projekte erben jedoch die Werte vom Kernprojekt, wodurch vitest.provide zu einer universellen Möglichkeit wird, Werte an Tests zu übermitteln.

TIP

Diese Methode steht auch für globale Setup-Dateien zur Verfügung, falls Sie die öffentliche API nicht nutzen möchten:

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