Test Runner

WARNING

Dies ist eine API für fortgeschrittene Anwendungsfälle. Wenn Sie lediglich Tests ausführen möchten, benötigen Sie diese Funktionalität wahrscheinlich nicht. Sie wird hauptsächlich von Bibliotheksentwicklern verwendet.

Sie können den Pfad zu Ihrem Test Runner über die Option runner in Ihrer Konfigurationsdatei angeben. Diese Datei sollte einen Standardexport mit einer Klasse enthalten, die folgende Methoden implementiert:

export interface VitestRunner {
  /**
   * Wird als Erstes aufgerufen, bevor Tests gesammelt und ausgeführt werden.
   */
  onBeforeCollect?: (paths: string[]) => unknown;
  /**
   * Wird nach dem Sammeln der 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 werden.
   */
  onCancel?: (reason: CancelReason) => unknown;

  /**
   * Wird vor der Ausführung eines einzelnen Tests aufgerufen. Besitzt noch kein 'Ergebnis'.
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Wird aufgerufen, bevor die Testfunktion tatsächlich ausgeführt wird. Verfügt bereits über ein 'result'-Objekt mit den Eigenschaften 'state' und 'startTime'.
   */
  onBeforeTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;
  /**
   * Wird aufgerufen, nachdem Ergebnis und Status gesetzt wurden.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Wird unmittelbar nach dem Aufruf der Testfunktion aufgerufen. Hat noch keinen neuen Status. Wird nicht aufgerufen, wenn die Testfunktion einen Fehler auslöst.
   */
  onAfterTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;

  /**
   * Wird vor der Ausführung einer einzelnen Suite aufgerufen. Besitzt noch kein 'Ergebnis'.
   */
  onBeforeRunSuite?: (suite: Suite) => unknown;
  /**
   * Wird nach der Ausführung einer einzelnen Suite aufgerufen. Hat Status und Ergebnis.
   */
  onAfterRunSuite?: (suite: Suite) => unknown;

  /**
   * Falls definiert, wird diese Funktion anstelle der normalen Vitest-Suite-Verarbeitung aufgerufen.
   * "before"- und "after"-Hooks werden nicht ignoriert.
   */
  runSuite?: (suite: Suite) => Promise<void>;
  /**
   * Falls definiert, wird diese Funktion anstelle der üblichen Vitest-Handhabung aufgerufen. Nützlich für eigene Testfunktionen.
   * "before"- und "after"-Hooks werden nicht ignoriert.
   */
  runTask?: (test: TaskPopulated) => Promise<void>;

  /**
   * Wird aufgerufen, wenn eine Aufgabe aktualisiert wird. Dies entspricht "onTaskUpdate" in einem Reporter, aber diese Funktion läuft im selben Thread wie die Tests.
   */
  onTaskUpdate?: (task: [string, TaskResult | undefined][]) => Promise<void>;

  /**
   * Wird aufgerufen, bevor alle Tests in den gesammelten Pfaden ausgeführt werden.
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * Wird direkt nach der Ausführung aller Tests in den gesammelten Pfaden aufgerufen.
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * Wird aufgerufen, wenn ein neuer Kontext für einen Test definiert 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/de/book/vitest-1/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 Initialisieren dieser Klasse übergibt Vitest die Vitest-Konfiguration – Sie sollten diese als config-Eigenschaft bereitstellen.

WARNING

Vitest fügt auch ViteNodeRunner unter der Eigenschaft __vitest_executor hinzu. Sie können diese verwenden, um Dateien in der importFile-Methode zu verarbeiten (dies ist das Standardverhalten von TestRunner und BenchmarkRunner).

ViteNodeRunner stellt die executeId-Methode bereit, die verwendet wird, um Testdateien in einer Vite-kompatiblen Umgebung zu importieren. Dies bedeutet, dass ViteNodeRunner Importe auflöst und Dateiinhalte zur Laufzeit transformiert, sodass Node sie verstehen kann.

TIP

Snapshot-Unterstützung und weitere Funktionen sind vom Runner abhängig. Wenn Sie diese nicht verlieren möchten, können Sie Ihren Runner von VitestTestRunner ableiten, der von vitest/runners importiert wird. Es stellt auch BenchmarkNodeRunner bereit, wenn Sie die Funktionalität für Benchmarks erweitern möchten.

Ihre Task-Funktion

Sie können das Vitest-Aufgabensystem um eigene Aufgaben erweitern. Eine Aufgabe ist ein Objekt innerhalb einer Suite. Sie wird automatisch mit der suite.task-Methode zur aktuellen Suite hinzugefügt:

// ./utils/custom.js
import { createTaskCollector, getCurrentSuite, setFn } from 'vitest/suite';

export { describe, beforeAll, afterAll } from 'vitest';

// Diese Funktion wird während der Sammelphase aufgerufen:
// Rufen Sie hier keinen Funktionshandler auf, sondern fügen Sie ihn den Suite-Aufgaben 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, // so "todo"/"skip"/... is tracked correctly
    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.js

WARNING

Falls kein benutzerdefinierter Runner vorhanden ist oder die runTest-Methode nicht definiert wurde, versucht Vitest, eine Aufgabe automatisch zu laden. Wenn Sie keine Funktion mit setFn hinzugefügt haben, schlägt der Aufruf fehl.

TIP

Das benutzerdefinierte Task-System unterstützt Hooks und Kontexte. Wenn Sie die Eigenschaftenverkettung unterstützen möchten (wie only, skip und eigene Eigenschaften), können Sie createChainable von vitest/suite importieren und Ihre Funktion damit umschließen. Wenn Sie sich dafür entscheiden, müssen Sie custom mit custom.call(this) aufrufen, um den korrekten Kontext zu gewährleisten.