TestSuite

La classe TestSuite représente une suite de tests. Cette classe est exclusivement 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 TestSuite possède toujours une propriété type dont la valeur est suite. Vous pouvez l'utiliser pour distinguer les différents types de tâches :

if (task.type === 'suite') {
  task; // TestSuite
}

project

Cette propriété fait référence au TestProject auquel le test appartient.

module

Ceci est une référence directe au TestModule dans lequel le test est défini.

name

Il s'agit du nom de la suite tel que passé à la fonction describe.

import { describe } from 'vitest';

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

fullName

Le nom complet de la suite, incluant toutes les suites parentes, séparées par le symbole >. Par exemple, cette suite aura pour nom complet "the validation logic > validating cities" :

import { describe, test } from 'vitest';

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

id

C'est l'identifiant unique de la suite. Cet ID est déterministe et restera identique pour la même suite lors d'exécutions multiples. L'ID est généré à partir du nom du projet, de l'identifiant du module et de l'ordre de la suite.

L'ID se présente sous la forme suivante :

1223128da3_0_0_0
^^^^^^^^^^ hachage du fichier
           ^ index de la suite
             ^ index de la suite imbriquée
               ^ index du test

TIP

Vous pouvez générer le hachage de 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 défini
);

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ù la suite a été définie. Les emplacements ne sont collectés que si includeTaskLocation est activé dans la configuration. Notez que cette option est automatiquement activée si les drapeaux --reporter=html, --ui ou --browser sont utilisés.

L'emplacement de cette suite sera { line: 3, column: 1 } :

import { describe } from 'vitest'

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

parent

La suite parente. Si la suite est appelée 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 la suite a été collectée.

children

Ceci est une collection de toutes les suites et tests contenus dans la suite actuelle.

for (const task of suite.children) {
  if (task.type === 'test') {
    console.log('test', task.fullName);
  } else {
    // task est TestSuite
    console.log('suite', task.name);
  }
}

WARNING

Notez que suite.children n'itérera que le premier niveau d'imbrication, sans aller plus loin. Si vous avez besoin d'itérer sur tous les tests ou suites, utilisez children.allTests() ou children.allSuites(). Pour itérer sur tous les éléments, utilisez une fonction récursive :

function visit(collection: TestCollection) {
  for (const task of collection) {
    if (task.type === 'suite') {
      // traiter une suite
      visit(task.children);
    } else {
      // traiter un test
    }
  }
}

ok

function ok(): boolean;

Vérifie si la suite contient des tests échoués. Cette fonction retournera également false si la suite a échoué pendant sa collecte. Dans ce cas, consultez la méthode errors() pour les erreurs levées.

state

function state(): TestSuiteState;

Retourne l'état d'exécution de la suite. Valeurs de retour possibles :

• pending : les tests de cette suite n'ont pas encore terminé leur exécution.
• failed : cette suite contient des tests échoués ou n'a pas pu être collectée. Si errors() n'est pas vide, cela indique que la suite n'a pas réussi à collecter les tests.
• passed : tous les tests de cette suite ont réussi.
• skipped : cette suite a été ignorée pendant la collecte.

WARNING

Notez que le module de test possède également une méthode state qui retourne les mêmes valeurs, mais il peut aussi retourner un état queued supplémentaire si le module n'a pas encore été exécuté.

errors

function errors(): TestError[];

Erreurs survenues en dehors de l'exécution des tests pendant la collecte, telles que des erreurs de syntaxe.

import { describe } from 'vitest';

describe('collection failed', () => {
  throw new Error('a custom error');
});

WARNING

Notez que les erreurs sont sérialisées en objets simples : instanceof Error retournera toujours false.

meta 3.1.0+

function meta(): TaskMeta;

Métadonnées personnalisées qui ont été attachées à la suite pendant son exécution ou sa collecte. Les métadonnées peuvent être attachées en assignant une propriété à l'objet task.meta pendant l'exécution d'un test :

import { test } from 'vitest';

describe('the validation works correctly', task => {
  // assigner "decorated" pendant la collecte
  task.meta.decorated = false;

  test('some test', ({ task }) => {
    // assigner "decorated" pendant l'exécution du test, il sera disponible
    // uniquement dans le hook onTestCaseReady
    task.suite.meta.decorated = false;
  });
});

TIP

Si des métadonnées ont été attachées pendant la collecte (en dehors de la fonction test), elles seront disponibles dans le hook onTestModuleCollected du rapporteur personnalisé.