Test-Runner
WARNING
Dies ist eine fortgeschrittene API. Wenn Sie lediglich Tests ausführen möchten, benötigen Sie diese wahrscheinlich nicht. Sie wird hauptsächlich von Bibliotheksautoren verwendet.
Sie können den Pfad zu Ihrem Test-Runner mit der Option runner in Ihrer Konfigurationsdatei angeben. Diese Datei sollte einen Standard-Export mit einem Klassenkonstruktor enthalten, der die folgenden Methoden implementiert:
export interface VitestRunner {
/**
* Wird als Erstes aufgerufen, bevor Tests tatsächlich gesammelt und ausgeführt werden.
*/
onBeforeCollect?: (paths: string[]) => unknown;
/**
* Wird nach dem Sammeln von Tests und vor "onBeforeRun" aufgerufen.
*/
onCollected?: (files: File[]) => unknown;
/**
* Wird aufgerufen, wenn der Test-Runner die nächsten Testläufe abbrechen soll.
* Der Runner sollte auf diese Methode reagieren und Tests und Suiten in
* "onBeforeRunSuite" und "onBeforeRunTask" als übersprungen markieren, sobald sie aufgerufen wurde.
*/
onCancel?: (reason: CancelReason) => unknown;
/**
* Wird vor dem Ausführen eines einzelnen Tests aufgerufen. Das "result"-Feld ist zu diesem Zeitpunkt noch nicht vorhanden.
*/
onBeforeRunTest?: (test: TaskPopulated) => unknown;
/**
* Wird vor dem eigentlichen Ausführen der Testfunktion aufgerufen. Das "result"-Feld ist bereits vorhanden und enthält "state" und "startTime".
*/
onBeforeTryTask?: (
test: TaskPopulated,
options: { retry: number; repeats: number }
) => unknown;
/**
* Wird aufgerufen, nachdem Ergebnis und Zustand gesetzt wurden.
*/
onAfterRunTask?: (test: TaskPopulated) => unknown;
/**
* Wird direkt nach dem Ausführen der Testfunktion aufgerufen. Der neue Zustand ist zu diesem Zeitpunkt noch nicht verfügbar. Wird nicht aufgerufen, wenn die Testfunktion einen Fehler wirft.
*/
onAfterTryTask?: (
test: TaskPopulated,
options: { retry: number; repeats: number }
) => unknown;
/**
* Wird vor dem Ausführen einer einzelnen Suite aufgerufen. Das "result"-Feld ist zu diesem Zeitpunkt noch nicht vorhanden.
*/
onBeforeRunSuite?: (suite: Suite) => unknown;
/**
* Wird nach dem Ausführen einer einzelnen Suite aufgerufen. Verfügt über Zustand und Ergebnis.
*/
onAfterRunSuite?: (suite: Suite) => unknown;
/**
* Wenn definiert, wird anstelle der üblichen Vitest-Suite-Partitionierung und -Behandlung aufgerufen.
* "before"- und "after"-Hooks werden nicht ignoriert.
*/
runSuite?: (suite: Suite) => Promise<void>;
/**
* Wenn definiert, wird anstelle der üblichen Vitest-Behandlung aufgerufen. Nützlich, wenn Sie Ihre eigene Testfunktion haben.
* "before"- und "after"-Hooks werden nicht ignoriert.
*/
runTask?: (test: TaskPopulated) => Promise<void>;
/**
* Wird aufgerufen, wenn eine Aufgabe aktualisiert wird. Das Gleiche wie "onTaskUpdate" in einem Reporter, aber dies läuft im selben Thread wie die Tests.
*/
onTaskUpdate?: (task: [string, TaskResult | undefined][]) => Promise<void>;
/**
* Wird vor dem Ausführen aller Tests in gesammelten Pfaden aufgerufen.
*/
onBeforeRunFiles?: (files: File[]) => unknown;
/**
* Wird direkt nach dem Ausführen aller Tests in gesammelten Pfaden aufgerufen.
*/
onAfterRunFiles?: (files: File[]) => unknown;
/**
* Wird aufgerufen, wenn ein neuer Kontext für einen Test festgelegt wird. Nützlich, wenn Sie dem Kontext benutzerdefinierte Eigenschaften hinzufügen möchten.
* Wenn Sie nur einen benutzerdefinierten Kontext mit einem Runner definieren möchten, sollten Sie stattdessen "beforeAll" in "setupFiles" verwenden.
*
* Diese Methode wird sowohl für "test" als auch für "custom" Handler aufgerufen.
*
* @see https://www.getbook.com/en/book/vitest-2/advanced/runner#your-task-function
*/
extendTaskContext?: <T extends Test | Custom>(
context: TaskContext<T>
) => TaskContext<T>;
/**
* Wird aufgerufen, wenn bestimmte Dateien importiert werden. Kann in zwei Situationen aufgerufen werden: beim Sammeln von Tests und beim Importieren von Setup-Dateien.
*/
importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
/**
* Öffentlich zugängliche Konfiguration.
*/
config: VitestRunnerConfig;
}Beim Instanziieren dieser Klasse übergibt Vitest die Vitest-Konfiguration – Sie sollten sie als config-Eigenschaft verfügbar machen.
WARNING
Vitest injiziert auch eine Instanz von ViteNodeRunner als Eigenschaft __vitest_executor. Sie können diese verwenden, um Dateien in der Methode importFile zu verarbeiten (dies ist das Standardverhalten von TestRunner und BenchmarkRunner).
ViteNodeRunner stellt die Methode executeId zur Verfügung, die verwendet wird, um Testdateien in einer Vite-freundlichen Umgebung zu importieren. Das bedeutet, dass sie Importe auflöst und den Dateiinhalt zur Laufzeit transformiert, damit Node ihn verstehen kann.
TIP
Snapshot-Unterstützung und einige andere Funktionen hängen vom Runner ab. Wenn Sie diese nicht verlieren möchten, können Sie Ihren Runner von VitestTestRunner erweitern, das von vitest/runners importiert wird. Es stellt auch BenchmarkNodeRunner zur Verfügung, wenn Sie die Benchmark-Funktionalität erweitern möchten.
Aufgaben
Suites und Tests werden intern tasks genannt. Der Vitest-Runner initialisiert eine File-Aufgabe, bevor er Tests sammelt – dies ist eine Obermenge von Suite mit einigen zusätzlichen Eigenschaften. Sie ist auf jeder Aufgabe (einschließlich File) als Eigenschaft file verfügbar.
interface File extends Suite {
/**
* Der Name des Pools, zu dem die Datei gehört.
* @default 'forks'
*/
pool?: string;
/**
* Der Pfad zur Datei im UNIX-Format.
*/
filepath: string;
/**
* Der Name des Workspace-Projekts, zu dem die Datei gehört.
*/
projectName: string | undefined;
/**
* Die Dauer in Millisekunden für das Sammeln aller Tests in der Datei.
* Diese Zeit beinhaltet auch das Importieren aller Dateiabhängigkeiten.
*/
collectDuration?: number;
/**
* Die Zeit in Millisekunden, die zum Importieren der Setup-Datei benötigt wurde.
*/
setupDuration?: number;
/**
* Zeigt an, ob die Datei initialisiert wurde, ohne Tests auszuführen.
* Dies geschieht, um den Zustand auf der Serverseite von Vitest zu füllen.
*/
local?: boolean;
}Jede Suite hat eine Eigenschaft tasks, die während der Sammelphase gefüllt wird. Es ist nützlich, den Aufgabenbaum von oben nach unten zu durchlaufen.
interface Suite extends TaskBase {
type: 'suite';
/**
* Datei-Aufgabe. Dies ist die Wurzelaufgabe der Datei.
*/
file: File;
/**
* Ein Array von Aufgaben, die Teil der Suite sind.
*/
tasks: Task[];
}Jede Aufgabe hat eine Eigenschaft suite, die auf die Suite verweist, in der sie sich befindet. Wenn test oder describe auf oberster Ebene initialisiert werden, haben sie keine Eigenschaft suite (sie wird nicht gleich file sein!). File hat ebenfalls nie eine Eigenschaft suite. Es ist nützlich, die Aufgaben von unten nach oben zu durchlaufen.
interface Test<ExtraContext = object> extends TaskBase {
type: 'test';
/**
* Testkontext, der an die Testfunktion übergeben wird.
*/
context: TaskContext<Test> & ExtraContext & TestContext;
/**
* Datei-Aufgabe. Dies ist die Wurzelaufgabe der Datei.
*/
file: File;
/**
* Gibt an, ob die Aufgabe durch Aufruf von `t.skip()` übersprungen wurde.
*/
pending?: boolean;
/**
* Gibt an, ob die Aufgabe als erfolgreich gelten soll, wenn sie fehlschlägt. Wenn die Aufgabe fehlschlägt, wird sie als bestanden markiert.
*/
fails?: boolean;
/**
* Hooks, die ausgeführt werden, wenn die Aufgabe fehlschlägt. Die Reihenfolge hängt von der Option `sequence.hooks` ab.
*/
onFailed?: OnTestFailedHandler[];
/**
* Hooks, die ausgeführt werden, nachdem die Aufgabe abgeschlossen ist. Die Reihenfolge hängt von der Option `sequence.hooks` ab.
*/
onFinished?: OnTestFinishedHandler[];
/**
* Enthält Promises (von asynchronen Erwartungen), um auf sie zu warten, bevor der Test abgeschlossen wird.
*/
promises?: Promise<any>[];
}Jede Aufgabe kann ein Feld result haben. Suiten können dieses Feld nur haben, wenn ein Fehler, der innerhalb eines Suite-Callbacks oder beforeAll/afterAll-Callbacks geworfen wird, sie daran hindert, Tests zu sammeln. Tests haben dieses Feld immer, nachdem ihre Callbacks aufgerufen wurden – die Felder state und errors sind je nach Ergebnis vorhanden. Wenn ein Fehler in beforeEach oder afterEach-Callbacks geworfen wurde, wird der geworfene Fehler in task.result.errors vorhanden sein.
export interface TaskResult {
/**
* Zustand der Aufgabe. Erbt den `task.mode` während der Sammlung.
* Nach Abschluss der Aufgabe wird er in `pass` oder `fail` geändert.
* - **pass**: Aufgabe erfolgreich ausgeführt
* - **fail**: Aufgabe fehlgeschlagen
*/
state: TaskState;
/**
* Fehler, die während der Ausführung der Aufgabe aufgetreten sind. Es ist möglich, mehrere Fehler zu haben,
* wenn `expect.soft()` mehrmals fehlgeschlagen ist.
*/
errors?: ErrorWithDiff[];
/**
* Wie lange in Millisekunden die Ausführung der Aufgabe dauerte.
*/
duration?: number;
/**
* Zeit in Millisekunden, zu der die Aufgabe gestartet wurde.
*/
startTime?: number;
/**
* Heap-Größe in Bytes nach Abschluss der Aufgabe.
* Nur verfügbar, wenn die Option `logHeapUsage` gesetzt ist und `process.memoryUsage` definiert ist.
*/
heap?: number;
/**
* Zustand der mit dieser Aufgabe verbundenen Hooks. Nützlich während der Berichterstattung.
*/
hooks?: Partial<
Record<'afterAll' | 'beforeAll' | 'beforeEach' | 'afterEach', TaskState>
>;
/**
* Die Anzahl der Wiederholungen der Aufgabe. Die Aufgabe wird nur wiederholt, wenn sie
* fehlgeschlagen ist und die Option `retry` gesetzt ist.
*/
retryCount?: number;
/**
* Die Anzahl der Wiederholungen der Aufgabe. Die Aufgabe wird nur wiederholt, wenn
* die Option `repeats` gesetzt ist. Diese Zahl enthält auch `retryCount`.
*/
repeatCount?: number;
}Ihre Aufgabenfunktion
Vitest stellt einen Custom-Aufgabentyp zur Verfügung, der es Benutzern ermöglicht, integrierte Reporter wiederzuverwenden. Er entspricht im Wesentlichen Test, hat aber den Typ 'custom'.
Eine Aufgabe ist ein Objekt, das zu einer Suite gehört. Sie wird automatisch mit der Methode suite.task zur aktuellen Suite hinzugefügt:
// ./utils/custom.js
import { createTaskCollector, getCurrentSuite, setFn } from 'vitest/suite';
export { afterAll, beforeAll, describe } from 'vitest';
// Diese Funktion wird während der Sammelphase aufgerufen:
// Hier sollte der Funktionshandler nicht aufgerufen werden, fügen Sie ihn den Aufgaben der Suite hinzu
// mit der Methode "getCurrentSuite().task()"
// Hinweis: createTaskCollector bietet Unterstützung für "todo"/"each"/...
export const myCustomTask = createTaskCollector(function (name, fn, timeout) {
getCurrentSuite().task(name, {
...this, // um "todo"/"skip"/... korrekt zu berücksichtigen
meta: {
customPropertyToDifferentiateTask: true,
},
handler: fn,
timeout,
});
});// ./garden/tasks.test.js
import { afterAll, beforeAll, describe, myCustomTask } from '../custom.js';
import { gardener } from './gardener.js';
describe('take care of the garden', () => {
beforeAll(() => {
gardener.putWorkingClothes();
});
myCustomTask('weed the grass', () => {
gardener.weedTheGrass();
});
myCustomTask.todo('mow the lawn', () => {
gardener.mowerTheLawn();
});
myCustomTask('water flowers', () => {
gardener.waterFlowers();
});
afterAll(() => {
gardener.goHome();
});
});vitest ./garden/tasks.test.jsWARNING
Wenn Sie keinen benutzerdefinierten Runner haben oder die Methode runTest nicht definiert ist, versucht Vitest, eine Aufgabe automatisch auszuführen. Wenn Sie keine Funktion mit setFn hinzugefügt haben, schlägt dies fehl.