Exécuteur de tests

WARNING

Il s'agit d'une API avancée. Si vous vous contentez d'exécuter des tests, vous n'en aurez probablement pas besoin. Elle est principalement destinée aux auteurs de bibliothèques.

Vous pouvez spécifier un chemin vers votre exécuteur de tests avec l'option runner dans votre fichier de configuration. Ce fichier doit exporter par défaut une classe implémentant les méthodes suivantes :

export interface VitestRunner {
  /**
   * Première méthode appelée avant la collecte et l'exécution des tests.
   */
  onBeforeCollect?(paths: string[]): unknown;
  /**
   * Appelée après la collecte des tests et avant "onBeforeRun".
   */
  onCollected?(files: File[]): unknown;

  /**
   * Appelée lorsque l'exécuteur de tests doit annuler les prochaines exécutions de tests.
   * L'exécuteur doit écouter cette méthode et marquer les tests et les suites comme ignorés dans
   * "onBeforeRunSuite" et "onBeforeRunTest" lorsqu'elle est appelée.
   */
  onCancel?(reason: CancelReason): unknown;

  /**
   * Appelée avant l'exécution d'un test unique. Ne contient pas encore de "result".
   */
  onBeforeRunTest?(test: Test): unknown;
  /**
   * Appelée avant l'exécution de la fonction de test. Contient déjà un "result" avec "state" et "startTime".
   */
  onBeforeTryTest?(test: Test, retryCount: number): unknown;
  /**
   * Appelée après la définition du résultat et de l'état.
   */
  onAfterRunTest?(test: Test): unknown;
  /**
   * Appelée juste après l'exécution de la fonction de test. Ne contient pas encore le nouvel état. Ne sera pas appelée si la fonction de test lève une exception.
   */
  onAfterTryTest?(test: Test, retryCount: number): unknown;

  /**
   * Appelée avant l'exécution d'une suite unique. Ne contient pas encore de "result".
   */
  onBeforeRunSuite?(suite: Suite): unknown;
  /**
   * Appelée après l'exécution d'une suite unique. Contient l'état et le résultat.
   */
  onAfterRunSuite?(suite: Suite): unknown;

  /**
   * Si elle est définie, elle sera appelée à la place du partitionnement et de la gestion habituels de la suite Vitest.
   * Les hooks "before" et "after" ne seront pas ignorés.
   */
  runSuite?(suite: Suite): Promise<void>;
  /**
   * Si elle est définie, elle sera appelée à la place de la gestion habituelle de Vitest. Utile si vous avez votre propre fonction de test personnalisée.
   * Les hooks "before" et "after" ne seront pas ignorés.
   */
  runTest?(test: Test): Promise<void>;

  /**
   * Appelée lorsqu'une tâche est mise à jour. Identique à "onTaskUpdate" dans un reporter, mais s'exécute dans le même thread que les tests.
   */
  onTaskUpdate?(task: [string, TaskResult | undefined][]): Promise<void>;

  /**
   * Appelée avant l'exécution de tous les tests dans les chemins collectés.
   */
  onBeforeRun?(files: File[]): unknown;
  /**
   * Appelée juste après l'exécution de tous les tests dans les chemins collectés.
   */
  onAfterRun?(files: File[]): unknown;
  /**
   * Appelée lorsqu'un nouveau contexte pour un test est défini. Utile si vous souhaitez ajouter des propriétés personnalisées au contexte.
   * Si vous souhaitez uniquement définir un contexte personnalisé avec un exécuteur, envisagez d'utiliser "beforeAll" dans "setupFiles" à la place.
   */
  extendTestContext?(context: TestContext): TestContext;
  /**
   * Appelée lorsque certains fichiers sont importés. Peut être appelée dans deux situations : lors de la collecte des tests et lors de l'importation des fichiers de configuration initiale.
   */
  importFile(filepath: string, source: VitestRunnerImportSource): unknown;
  /**
   * Configuration disponible publiquement.
   */
  config: VitestRunnerConfig;
}

Lors de l'instanciation de cette classe, Vitest transmet la configuration de Vitest - vous devez l'exposer en tant que propriété config.

WARNING

Vitest injecte également une instance de ViteNodeRunner en tant que propriété __vitest_executor. Vous pouvez l'utiliser pour traiter les fichiers dans la méthode importFile (c'est le comportement par défaut de TestRunner et BenchmarkRunner).

ViteNodeRunner expose la méthode executeId, qui est utilisée pour importer des fichiers de test dans un environnement compatible avec Vite. Cela signifie qu'il résoudra les importations et transformera le contenu du fichier au moment de l'exécution afin que Node puisse le comprendre.

TIP

La fonctionnalité de snapshots et d'autres fonctionnalités dépendent de l'exécuteur. Si vous ne voulez pas les perdre, vous pouvez étendre votre exécuteur à partir de VitestTestRunner importé de vitest/runners. Il expose également BenchmarkNodeRunner, si vous souhaitez étendre la fonctionnalité de benchmark.

Votre fonction de tâche

Vous pouvez étendre le système de tâches Vitest avec vos propres tâches. Une tâche est un objet qui fait partie d'une suite. Elle est automatiquement ajoutée à la suite actuelle avec une méthode suite.custom :

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

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

// Cette fonction sera appelée lorsque Vitest collectera les tâches
export const myCustomTask = function (name, fn) {
  const task = getCurrentSuite().custom(name);
  task.meta = {
    customPropertyToDifferentiateTask: true,
  };
  setFn(task, fn || (() => {}));
};

// ./garden/tasks.test.js
import {
  afterAll,
  beforeAll,
  describe,
  myCustomTask,
} from '../utils/custom.js';
import { gardener } from './gardener.js';

describe('take care of the garden', () => {
  beforeAll(() => {
    gardener.putWorkingClothes();
  });

  myCustomTask('weed the grass', () => {
    gardener.weedTheGrass();
  });
  myCustomTask('water flowers', () => {
    gardener.waterFlowers();
  });

  afterAll(() => {
    gardener.goHome();
  });
});

vitest ./garden/tasks.test.js

WARNING

Si vous n'avez pas d'exécuteur personnalisé ou si vous n'avez pas défini la méthode runTest, Vitest essaiera de récupérer une tâche automatiquement. Si vous n'avez pas ajouté de fonction avec setFn, cela échouera.

TIP

Le système de tâches personnalisées prend en charge les hooks et les contextes. Si vous souhaitez prendre en charge le chaînage de propriétés (comme only, skip et vos propriétés personnalisées), vous pouvez importer createChainable de vitest/suite et l'utiliser pour l'envelopper. Vous devrez appeler custom comme custom.call(this) si vous décidez de procéder ainsi.