TestCase

La classe TestCase représente un test unitaire. Cette classe est uniquement disponible dans le thread principal. Pour interagir avec les tâches d'exécution, veuillez vous référer à l'"API du Runner".

L'instance TestCase possède toujours une propriété type avec la valeur test. Vous pouvez l'utiliser pour distinguer les différents types de tâches :

if (task.type === 'test') {
  task; // TestCase
}

project

Fait référence au TestProject auquel le test appartient.

module

Il s'agit d'une référence directe au TestModule dans lequel le test est défini.

name

Il s'agit du nom du test tel que passé à la fonction test.

import { test } from 'vitest';

// [!code word:'the validation works correctly']
test('the validation works correctly', () => {
  // ...
});

fullName

Le nom complet du test inclut toutes les suites parentes, séparées par le symbole >. Par exemple, ce test aura le nom complet "the validation logic > the validation works correctly" :

import { describe, test } from 'vitest';

// [!code word:'the validation works correctly']
// [!code word:'the validation logic']
describe('the validation logic', () => {
  test('the validation works correctly', () => {
    // ...
  });
});

id

Il s'agit de l'identifiant unique du test. Cet ID est déterministe et restera le même pour un test donné sur plusieurs exécutions. L'ID dépend du nom du projet, de l'identifiant du module et de l'ordre du test.

L'ID se présente comme suit :

1223128da3_0_0
^^^^^^^^^^ le hachage du fichier
           ^ index de la suite
             ^ index du test

TIP

Vous pouvez générer le hachage du fichier avec la fonction generateFileHash de vitest/node, disponible depuis Vitest 3 :

import { generateFileHash } from 'vitest/node';

const hash = generateFileHash(
  '/file/path.js', // chemin relatif
  undefined // le nom du projet ou `undefined` si non spécifié
);

DANGER

N'essayez pas d'analyser l'ID. Il peut commencer par un signe moins : -1223128da3_0_0_0.

location

L'emplacement dans le module où le test a été défini. Les emplacements ne sont collectés que si includeTaskLocation est activé dans les paramètres de configuration. Notez que cette option est automatiquement activée si les drapeaux --reporter=html, --ui ou --browser sont utilisés.

L'emplacement de ce test sera { line: 3, column: 1 } :

import { test } from 'vitest'

test('the validation works correctly', () => {
  // ...
})

parent

La suite parente (suite). Si le test a été appelé directement à l'intérieur du module, le parent sera le module lui-même.

options

interface TaskOptions {
  readonly each: boolean | undefined;
  readonly fails: boolean | undefined;
  readonly concurrent: boolean | undefined;
  readonly shuffle: boolean | undefined;
  readonly retry: number | undefined;
  readonly repeats: number | undefined;
  readonly mode: 'run' | 'only' | 'skip' | 'todo';
}

Les options avec lesquelles le test a été collecté.

ok

function ok(): boolean;

Vérifie si le test n'a pas fait échouer la suite. Si le test n'est pas encore terminé ou a été ignoré, cette fonction retournera true.

meta

function meta(): TaskMeta;

Métadonnées personnalisées attachées au test pendant son exécution. Les métadonnées peuvent être attachées en attribuant une propriété à l'objet ctx.task.meta lors de l'exécution d'un test :

import { test } from 'vitest';

test('the validation works correctly', ({ task }) => {
  // ...

  task.meta.decorated = false;
});

Si le test n'a pas encore terminé son exécution, les métadonnées seront un objet vide.

result

function result(): TestResult;

Résultats du test. Si le test n'est pas encore terminé ou vient d'être collecté, son état sera TestResultPending :

export interface TestResultPending {
  /**
   * Le test a été collecté, mais n'a pas encore terminé son exécution.
   */
  readonly state: 'pending';
  /**
   * Les tests en attente n'ont pas d'erreurs.
   */
  readonly errors: undefined;
}

Si le test a été ignoré, la valeur de retour sera TestResultSkipped :

interface TestResultSkipped {
  /**
   * Le test a été ignoré avec le flag `skip` ou `todo`.
   * L'option `options.mode` indique lequel a été utilisé.
   */
  readonly state: 'skipped';
  /**
   * Les tests ignorés n'ont pas d'erreurs.
   */
  readonly errors: undefined;
  /**
   * Une note personnalisée transmise à `ctx.skip(note)`.
   */
  readonly note: string | undefined;
}

TIP

Si le test a été ignoré parce qu'un autre test possède le flag only, l'option options.mode sera égale à skip.

Si le test a échoué, la valeur de retour sera TestResultFailed :

interface TestResultFailed {
  /**
   * Le test n'a pas pu s'exécuter.
   */
  readonly state: 'failed';
  /**
   * Erreurs qui ont été lancées pendant l'exécution du test.
   */
  readonly errors: ReadonlyArray<TestError>;
}

Si le test a réussi, la valeur de retour sera TestResultPassed :

interface TestResultPassed {
  /**
   * Le test a réussi.
   */
  readonly state: 'passed';
  /**
   * Erreurs qui ont été lancées pendant l'exécution du test.
   */
  readonly errors: ReadonlyArray<TestError> | undefined;
}

WARNING

Notez qu'un test avec l'état passed peut toujours avoir des erreurs associées – cela peut arriver si retry a été déclenché au moins une fois.

diagnostic

function diagnostic(): TestDiagnostic | undefined;

Informations utiles sur le test telles que la durée, l'utilisation de la mémoire, etc. :

interface TestDiagnostic {
  /**
   * Indique si la durée du test est supérieure à `slowTestThreshold`.
   */
  readonly slow: boolean;
  /**
   * La quantité de mémoire utilisée par le test en octets.
   * Cette valeur n'est disponible que si le test a été exécuté avec le flag `logHeapUsage`.
   */
  readonly heap: number | undefined;
  /**
   * Le temps nécessaire pour exécuter le test en ms.
   */
  readonly duration: number;
  /**
   * L'heure en ms à laquelle le test a commencé.
   */
  readonly startTime: number;
  /**
   * Le nombre de fois où le test a été relancé.
   */
  readonly retryCount: number;
  /**
   * Le nombre de fois où le test a été répété conformément à l'option `repeats`.
   * Cette valeur peut être inférieure si le test a échoué pendant la répétition et qu'aucune nouvelle tentative n'est configurée.
   */
  readonly repeatCount: number;
  /**
   * Indique si le test a réussi lors d'une deuxième tentative.
   */
  readonly flaky: boolean;
}

INFO

diagnostic() retournera undefined si le test n'a pas encore été planifié pour être exécuté.