Test Runner

Vous pouvez spécifier un chemin vers votre test runner avec l’option runner dans votre fichier de configuration. Ce fichier doit avoir un export par défaut avec un constructeur de classe implémentant ces méthodes :

export interface VitestRunner {
  /**
   * Première chose qui est appelée avant de collecter et d'exécuter réellement les tests.
   */
  onBeforeCollect?: (paths: string[]) => unknown
  /**
   * Appelée après la collecte des tests et avant "onBeforeRun".
   */
  onCollected?: (files: File[]) => unknown

  /**
   * Appelée lorsque le test runner doit annuler les prochains exécutions de tests.
   * Le runner doit écouter cette méthode et marquer les tests et les suites comme ignorés dans
   * "onBeforeRunSuite" et "onBeforeRunTask" lorsqu'elle est appelée.
   */
  onCancel?: (reason: CancelReason) => unknown

  /**
   * Appelée avant d'exécuter un test unique. N'a pas encore de "result".
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown
  /**
   * Appelée avant d'exécuter réellement la fonction de test. A déjà "result" avec "state" et "startTime".
   */
  onBeforeTryTask?: (test: TaskPopulated, options: { retry: number; repeats: number }) => unknown
  /**
   * Appelée après que le résultat et l'état sont définis.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown
  /**
   * Appelée juste après l'exécution de la fonction de test. N'a pas encore de nouvel état. Ne sera pas appelée si la fonction de test échoue.
   */
  onAfterTryTask?: (test: TaskPopulated, options: { retry: number; repeats: number }) => unknown

  /**
   * Appelée avant d'exécuter une suite unique. N'a pas encore de "result".
   */
  onBeforeRunSuite?: (suite: Suite) => unknown
  /**
   * Appelée après avoir exécuté une suite unique. A l'état et au résultat.
   */
  onAfterRunSuite?: (suite: Suite) => unknown

  /**
   * Si défini, sera appelée à la place de la partition et du traitement habituel de la suite Vitest.
   * Les hooks "before" et "after" ne seront pas ignorés.
   */
  runSuite?: (suite: Suite) => Promise<void>
  /**
   * Si défini, sera appelée à la place du traitement habituel de Vitest. Utile, si vous avez votre propre fonction de test.
   * Les hooks "before" et "after" ne seront pas ignorés.
   */
  runTask?: (test: TaskPopulated) => Promise<void>

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

  /**
   * Appelée avant d'exécuter tous les tests dans les chemins collectés.
   */
  onBeforeRunFiles?: (files: File[]) => unknown
  /**
   * Appelée juste après l'exécution de tous les tests dans les chemins collectés.
   */
  onAfterRunFiles?: (files: File[]) => unknown
  /**
   * Appelée lorsque un nouveau contexte pour un test est défini. Utile, si vous souhaitez ajouter des propriétés personnalisées au contexte.
   * Si vous voulez seulement définir un contexte personnalisé avec un runner, envisagez d'utiliser "beforeAll" dans "setupFiles" à la place.
   *
   * Cette méthode est appelée à la fois pour les gestionnaires "test" et "custom".
   *
   * @see https://vitest.dev/advanced/runner.html#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(context: TaskContext<T>) => TaskContext<T>
  /**
   * 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 de fichiers de configuration.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown
  /**
   * Configuration disponible publiquement.
   */
  config: VitestRunnerConfig
}

Lors de l’initialisation de cette classe, Vitest transmet la configuration de Vitest, - vous devez l’exposer comme propriété config.

Tâches

Les suites et les tests sont appelés tasks en interne. Le runner Vitest initie une tâche File avant de collecter des tests - c’est un surensemble de Suite avec quelques propriétés supplémentaires. Elle est disponible sur chaque tâche (y compris File) en tant que propriété file.

interface File extends Suite {
  /**
   * Le nom du pool auquel le fichier appartient.
   * @default 'forks'
   */
  pool?: string
  /**
   * Le chemin vers le fichier au format UNIX.
   */
  filepath: string
  /**
   * Le nom du projet workspace auquel appartient le fichier.
   */
  projectName: string | undefined
  /**
   * Le temps qu'il a fallu pour collecter tous les tests dans le fichier.
   * Ce temps inclut également l'importation de toutes les dépendances du fichier.
   */
  collectDuration?: number
  /**
   * Le temps qu'il a fallu pour importer le fichier de configuration.
   */
  setupDuration?: number
  /**
   * Si le fichier est initié sans exécuter de tests.
   * Ceci est fait pour remplir l'état du côté serveur par Vitest.
   */
  local?: boolean
}

Chaque suite a une propriété tasks qui est peuplée pendant la phase de collecte. Elle est utile pour parcourir l’arborescence des tâches de haut en bas.

interface Suite extends TaskBase {
  type: 'suite'
  /**
   * Tâche de fichier. C'est la tâche racine du fichier.
   */
  file: File
  /**
   * Un tableau de tâches qui font partie de la suite.
   */
  tasks: Task[]
}

Chaque tâche a une propriété suite qui fait référence à une suite dans laquelle elle se trouve. Si test ou describe sont initiés au niveau supérieur, ils n’auront pas de propriété suite (elle ne sera pas égale à file !). File n’a également jamais de propriété suite. Elle est utile pour parcourir les tâches de bas en haut.

interface Test<ExtraContext = object> extends TaskBase {
  type: 'test'
  /**
   * Contexte du test qui sera passé à la fonction de test.
   */
  context: TaskContext<Test> & ExtraContext & TestContext
  /**
   * Tâche de fichier. C'est la tâche racine du fichier.
   */
  file: File
  /**
   * Si la tâche a été ignorée en appelant `t.skip()`.
   */
  pending?: boolean
  /**
   * Si la tâche doit réussir si elle échoue. Si la tâche échoue, elle sera marquée comme réussie.
   */
  fails?: boolean
  /**
   * Hooks qui s'exécuteront si la tâche échoue. L'ordre dépend de l'option `sequence.hooks`.
   */
  onFailed?: OnTestFailedHandler[]
  /**
   * Hooks qui s'exécuteront après la fin de la tâche. L'ordre dépend de l'option `sequence.hooks`.
   */
  onFinished?: OnTestFinishedHandler[]
  /**
   * Stockez des promesses (provenant de attentes asynchrones) à attendre avant de terminer le test.
   */
  promises?: Promise<any>[]
}

Chaque tâche peut avoir un champ result. Les suites ne peuvent avoir ce champ que si une erreur est lancée dans un callback de suite ou dans les callbacks beforeAll/afterAll qui les empêche de collecter des tests. Les tests ont toujours ce champ après l’appel de leurs callbacks - les champs state et errors sont présents selon le résultat. Si une erreur a été lancée dans les callbacks beforeEach ou afterEach, l’erreur lancée sera présente dans task.result.errors.

export interface TaskResult {
  /**
   * État de la tâche. Hérite de `task.mode` pendant la collecte.
   * Lorsque la tâche est terminée, elle sera changée en `pass` ou `fail`.
   * - **pass** : tâche exécutée avec succès
   * - **fail** : tâche échouée
   */
  state: TaskState
  /**
   * Erreurs survenues lors de l'exécution de la tâche. Il est possible d'avoir plusieurs erreurs
   * si `expect.soft()` a échoué plusieurs fois.
   */
  errors?: ErrorWithDiff[]
  /**
   * Durée en millisecondes que la tâche a pris pour s'exécuter.
   */
  duration?: number
  /**
   * Temps en millisecondes lorsque la tâche a commencé à s'exécuter.
   */
  startTime?: number
  /**
   * Taille de la mémoire en octets après la fin de la tâche.
   * Disponible uniquement si l'option `logHeapUsage` est définie et `process.memoryUsage` est définie.
   */
  heap?: number
  /**
   * État relatif à ces hooks de tâche. Utile pendant le reporting.
   */
  hooks?: Partial<Record<'afterAll' | 'beforeAll' | 'beforeEach' | 'afterEach', TaskState>>
  /**
   * Le nombre de fois que la tâche a été réessayée. La tâche est réessayée uniquement si elle
   * a échoué et que l'option `retry` est définie.
   */
  retryCount?: number
  /**
   * Le nombre de fois que la tâche a été répétée. La tâche est répétée uniquement si
   * l'option `repeats` est définie. Ce nombre contient également `retryCount`.
   */
  repeatCount?: number
}

Votre Fonction de Tâche

Vitest expose un type de tâche Custom qui permet aux utilisateurs de réutiliser les reporters intégrés. Il est pratiquement identique à Test, mais a un type de 'custom'.

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.task :

import { createTaskCollector, getCurrentSuite, setFn } from 'vitest/suite'

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

// cette fonction sera appelée pendant la phase de collecte :
// ne pas appeler le gestionnaire de fonction ici, ajoutez-le aux tâches de la suite
// avec la méthode "getCurrentSuite().task()"
// note : createTaskCollector fournit un support pour "todo"/"each"/...
export const myCustomTask = createTaskCollector(
  function (name, fn, timeout) {
    getCurrentSuite().task(name, {
      ...this, // donc "todo"/"skip"/... est bien suivi
      meta: {
        customPropertyToDifferentiateTask: true
      },
      handler: fn,
      timeout,
    })
  }
)

import { afterAll, beforeAll, describe, myCustomTask } from '../custom.js'
import { gardener } from './gardener.js'

describe('prendre soin du jardin', () => {
  beforeAll(() => {
    gardener.putWorkingClothes()
  })

  myCustomTask('désherber l'herbe', () => {
    gardener.weedTheGrass()
  })
  myCustomTask.todo('tondre le gazon', () => {
    gardener.mowerTheLawn()
  })
  myCustomTask('arroser les fleurs', () => {
    gardener.waterFlowers()
  })

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

vitest ./garden/tasks.test.js