Rapporteurs

WARNING

Ceci est une API avancée. Si vous souhaitez simplement configurer les rapporteurs intégrés, veuillez consulter le guide "Rapporteurs".

Vitest possède son propre cycle de vie d'exécution des tests. Celui-ci est représenté par les méthodes des rapporteurs, appelées dans l'ordre suivant :

• onInit
• onTestRunStart
  • onTestModuleQueued
  • onTestModuleCollected
  • onTestModuleStart
    • onTestSuiteReady
      • onHookStart(beforeAll)
      • onHookEnd(beforeAll)
        • onTestCaseReady
          • onTestAnnotate 3.2.0+
          • onHookStart(beforeEach)
          • onHookEnd(beforeEach)
          • onHookStart(afterEach)
          • onHookEnd(afterEach)
        • onTestCaseResult
      • onHookStart(afterAll)
      • onHookEnd(afterAll)
    • onTestSuiteResult
  • onTestModuleEnd
• onTestRunEnd

Les tests et les suites au sein d'un même module sont rapportés dans l'ordre de leur exécution, sauf s'ils ont été ignorés. Tous les tests ignorés sont rapportés à la fin de la suite ou du module.

Notez que, puisque les modules de test peuvent s'exécuter en parallèle, Vitest les rapportera également en parallèle.

Ce guide liste toutes les méthodes de rapporteurs prises en charge. Cependant, n'oubliez pas qu'au lieu de créer votre propre rapporteur, vous pouvez étendre un rapporteur existant :

import { BaseReporter } from 'vitest/reporters';

export default class CustomReporter extends BaseReporter {
  onTestRunEnd(testModules, errors) {
    console.log(testModules.length, 'tests finished running');
    super.onTestRunEnd(testModules, errors);
  }
}

onInit

function onInit(vitest: Vitest): Awaitable<void>;

Cette méthode est appelée lorsque l'instance de Vitest a été initialisée ou démarrée, mais avant que les tests ne soient filtrés.

INFO

En interne, cette méthode est appelée à l'intérieur de vitest.start, vitest.init ou vitest.mergeReports. Si vous utilisez l'API programmatique, assurez-vous d'appeler l'une de ces méthodes en fonction de vos besoins avant d'appeler, par exemple, vitest.runTestSpecifications. L'interface de ligne de commande intégrée exécutera toujours les méthodes dans le bon ordre.

Notez que vous pouvez également accéder à l'instance vitest à partir des cas de test, des suites et des modules de test via une propriété project, mais il peut également être utile de stocker une référence à vitest dans cette méthode.

Exemple

import type { Reporter, TestSpecification, Vitest } from 'vitest/node';

class MyReporter implements Reporter {
  private vitest!: Vitest;

  onInit(vitest: Vitest) {
    this.vitest = vitest;
  }

  onTestRunStart(specifications: TestSpecification[]) {
    console.log(
      specifications.length,
      'fichiers de test seront exécutés dans',
      this.vitest.config.root
    );
  }
}

export default new MyReporter();

onBrowserInit expérimental

function onBrowserInit(project: TestProject): Awaitable<void>;

Cette méthode est appelée lorsque l'instance du navigateur est initialisée. Elle reçoit une instance du projet pour lequel le navigateur est initialisé. project.browser sera toujours défini lorsque cette méthode est appelée.

onTestRunStart

function onTestRunStart(specifications: TestSpecification[]): Awaitable<void>;

Cette méthode est appelée lorsqu'une nouvelle exécution de test a démarré. Elle reçoit un tableau de spécifications de test planifiées pour l'exécution. Ce tableau est en lecture seule et disponible uniquement à des fins d'information.

Si Vitest n'a trouvé aucun fichier de test à exécuter, cet événement sera invoqué avec un tableau vide, puis onTestRunEnd sera appelé immédiatement après.

Exemple

import type { Reporter, TestSpecification } from 'vitest/node';

class MyReporter implements Reporter {
  onTestRunStart(specifications: TestSpecification[]) {
    console.log(specifications.length, 'fichiers de test seront exécutés');
  }
}

export default new MyReporter();

AVIS DE DÉPRÉCATION

Cette méthode a été ajoutée dans Vitest 3, remplaçant onPathsCollected et onSpecsCollected, qui sont toutes deux maintenant dépréciées.

onTestRunEnd

function onTestRunEnd(
  testModules: ReadonlyArray<TestModule>,
  unhandledErrors: ReadonlyArray<SerializedError>,
  reason: TestRunEndReason
): Awaitable<void>;

Cette méthode est appelée après que tous les tests ont terminé leur exécution et que la couverture a fusionné tous les rapports, si elle est activée. Notez que vous pouvez obtenir les informations de couverture dans le hook onCoverage.

Elle reçoit une liste en lecture seule de modules de test. Vous pouvez l'itérer en utilisant la propriété testModule.children pour rapporter l'état et les erreurs, le cas échéant.

Le deuxième argument est une liste en lecture seule d'erreurs non gérées que Vitest n'a pas pu attribuer à un test spécifique. Celles-ci peuvent se produire en dehors de l'exécution du test en raison d'une erreur dans un plugin, ou à l'intérieur de l'exécution du test comme effet secondaire d'une fonction asynchrone non attendue (par exemple, un délai d'attente qui a levé une erreur après la fin de l'exécution du test).

Le troisième argument indique la raison pour laquelle l'exécution du test a été terminée :

• passed : l'exécution du test s'est terminée normalement et il n'y a pas d'erreurs.
• failed : l'exécution du test a au moins une erreur (due à une erreur de syntaxe pendant la collecte ou à une erreur réelle pendant l'exécution du test).
• interrupted : le test a été interrompu par un appel à vitest.cancelCurrentRun ou Ctrl+C a été pressé dans le terminal (notez qu'il est toujours possible d'avoir des tests échoués dans ce cas).

Si Vitest n'a trouvé aucun fichier de test à exécuter, cet événement sera invoqué avec des tableaux de modules et d'erreurs vides, et l'état dépendra de la valeur de config.passWithNoTests.

Exemple

import type {
  Reporter,
  SerializedError,
  TestModule,
  TestRunEndReason,
  TestSpecification,
} from 'vitest/node';

class MyReporter implements Reporter {
  onTestRunEnd(
    testModules: ReadonlyArray<TestModule>,
    unhandledErrors: ReadonlyArray<SerializedError>,
    reason: TestRunEndReason
  ) {
    if (reason === 'passed') {
      testModules.forEach(module => console.log(module.moduleId, 'succeeded'));
    } else if (reason === 'failed') {
      // note that this will skip possible errors in suites
      // you can get them from testSuite.errors()
      for (const testCase of testModules.children.allTests()) {
        if (testCase.result().state === 'failed') {
          console.log(
            testCase.fullName,
            'in',
            testCase.module.moduleId,
            'failed'
          );
          console.log(testCase.result().errors);
        }
      }
    } else {
      console.log('l\'exécution des tests a été interrompue, rapport ignoré');
    }
  }
}

export default new MyReporter();

AVIS DE DÉPRÉCATION

Cette méthode a été ajoutée dans Vitest 3, remplaçant onFinished, qui est maintenant dépréciée.

onCoverage

function onCoverage(coverage: unknown): Awaitable<void>;

Ce hook est appelé après que les résultats de couverture ont été traités. Les rapporteurs du fournisseur de couverture sont appelés après ce hook. Le typage de coverage dépend du coverage.provider. Pour les fournisseurs intégrés par défaut de Vitest, vous pouvez importer les types du package istanbul-lib-coverage :

import type { CoverageMap } from 'istanbul-lib-coverage';

declare function onCoverage(coverage: CoverageMap): Awaitable<void>;

Si Vitest n'a effectué aucune couverture, ce hook n'est pas appelé.

onTestModuleQueued

function onTestModuleQueued(testModule: TestModule): Awaitable<void>;

Cette méthode est appelée juste avant que Vitest n'importe le fichier de configuration et le module de test lui-même. Cela signifie que testModule n'aura pas encore de children, mais vous pouvez commencer à le rapporter comme le prochain test à exécuter.

onTestModuleCollected

function onTestModuleCollected(testModule: TestModule): Awaitable<void>;

Cette méthode est appelée lorsque tous les tests du fichier ont été collectés, ce qui signifie que la collection testModule.children est renseignée, mais les tests n'ont pas encore de résultats.

onTestModuleStart

function onTestModuleStart(testModule: TestModule): Awaitable<void>;

Cette méthode est appelée juste après onTestModuleCollected, à moins que Vitest ne s'exécute en mode de collecte (vitest.collect() ou vitest collect dans la CLI), auquel cas elle ne sera pas appelée du tout car il n'y a pas de tests à exécuter.

onTestModuleEnd

function onTestModuleEnd(testModule: TestModule): Awaitable<void>;

Cette méthode est appelée lorsque tous les tests du module ont terminé leur exécution. Cela signifie que chaque test à l'intérieur de testModule.children aura un test.result() qui n'est pas égal à pending.

onHookStart

function onHookStart(context: ReportedHookContext): Awaitable<void>;

Cette méthode est appelée lorsque l'un de ces hooks a commencé à s'exécuter :

• beforeAll
• afterAll
• beforeEach
• afterEach

Si beforeAll ou afterAll démarrent, l'entity sera soit une TestSuite soit un TestModule.

Si beforeEach ou afterEach démarrent, l'entity sera toujours un TestCase.

WARNING

La méthode onHookStart ne sera pas appelée si le hook n'a pas été exécuté pendant l'exécution du test.

onHookEnd

function onHookEnd(context: ReportedHookContext): Awaitable<void>;

Cette méthode est appelée lorsque l'un de ces hooks a terminé son exécution :

• beforeAll
• afterAll
• beforeEach
• afterEach

Si beforeAll ou afterAll se terminent, l'entity sera soit une TestSuite soit un TestModule.

Si beforeEach ou afterEach se terminent, l'entity sera toujours un TestCase.

WARNING

La méthode onHookEnd ne sera pas appelée si le hook n'a pas été exécuté pendant l'exécution du test.

onTestSuiteReady

function onTestSuiteReady(testSuite: TestSuite): Awaitable<void>;

Cette méthode est appelée avant que la suite ne commence à exécuter ses tests. Cette méthode est également appelée si la suite est ignorée.

Si le fichier ne contient pas de suites, cette méthode ne sera pas appelée. Envisagez d'utiliser onTestModuleStart pour couvrir ce cas d'utilisation.

onTestSuiteResult

function onTestSuiteResult(testSuite: TestSuite): Awaitable<void>;

Cette méthode est appelée après que la suite a terminé l'exécution des tests. Cette méthode est également appelée si la suite est ignorée.

Si le fichier ne contient pas de suites, cette méthode ne sera pas appelée. Envisagez d'utiliser onTestModuleEnd pour couvrir ce cas d'utilisation.

onTestCaseReady

function onTestCaseReady(testCase: TestCase): Awaitable<void>;

Cette méthode est appelée avant que le test ne commence à s'exécuter ou qu'il ne soit ignoré. Notez que les hooks beforeEach et afterEach font partie du test car ils peuvent influencer son résultat.

WARNING

Notez qu'il est possible que testCase.result() soit déjà dans l'état passed ou failed lorsque onTestCaseReady est appelé. Cela peut se produire si le test s'est exécuté trop rapidement et que onTestCaseReady et onTestCaseResult étaient tous deux planifiés pour s'exécuter dans la même microtâche.

onTestCaseResult

function onTestCaseResult(testCase: TestCase): Awaitable<void>;

Cette méthode est appelée lorsque le test a terminé son exécution ou a été simplement ignoré. Notez que cela sera appelé après la fin du hook afterEach, le cas échéant.

À ce point, testCase.result() aura un état non pending.

onTestAnnotate 3.2.0+

function onTestAnnotate(
  testCase: TestCase,
  annotation: TestAnnotation
): Awaitable<void>;

Le hook onTestAnnotate est lié à la méthode context.annotate. Lorsque annotate est invoqué, Vitest le sérialise et envoie cette pièce jointe au processus principal où le rapporteur peut interagir avec elle.

Si un chemin est spécifié, Vitest le stocke dans un répertoire séparé (configuré par attachmentsDir) et modifie la propriété path pour le référencer.