Métadonnées de tâche

WARNING

Vitest expose une API privée expérimentale. Les changements majeurs peuvent ne pas respecter SemVer. Il est recommandé d'épingler la version de Vitest lorsque vous utilisez cette API.

Si vous développez un générateur de rapports personnalisé ou utilisez l'API Node.js de Vitest, il peut être utile de transmettre des données des tests exécutés dans différents contextes à votre générateur de rapports ou à votre gestionnaire Vitest personnalisé.

Pour ce faire, s'appuyer sur le contexte de test n'est pas possible car il ne peut pas être sérialisé. Cependant, avec Vitest, vous pouvez utiliser la propriété meta disponible sur chaque tâche (suite ou test) pour partager des données entre vos tests et le processus Node.js. Il est important de noter que cette communication est à sens unique : la propriété meta ne peut être modifiée que depuis le contexte de test. Toute modification effectuée dans le contexte Node.js ne sera pas visible dans vos tests.

Vous pouvez définir la propriété meta sur le contexte de test ou à l'intérieur des hooks beforeAll/afterAll pour les tâches de suite.

afterAll(suite => {
  suite.meta.done = true;
});

test('custom', ({ task }) => {
  task.meta.custom = 'some-custom-handler';
});

Une fois qu'un test est terminé, Vitest enverra une tâche incluant le résultat et meta au processus Node.js via RPC. Ces informations seront ensuite signalées dans onTestCaseResult et d'autres hooks ayant accès aux tâches. Pour traiter ce cas de test, vous pouvez utiliser la méthode onTestCaseResult disponible dans votre implémentation de générateur de rapports :

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

export default {
  onTestCaseResult(testCase: TestCase) {
    // custom === 'some-custom-handler' ✅
    const { custom } = testCase.meta();
  },
  onTestRunEnd(testModule: TestModule) {
    testModule.meta().done === true;
    testModule.children.at(0).meta().custom === 'some-custom-handler';
  },
} satisfies Reporter;

ATTENTION

Vitest utilise différentes méthodes pour communiquer avec le processus Node.js :

• Si Vitest exécute des tests dans des threads d'exécution (worker threads), les données seront envoyées via un port de message.
• Si Vitest utilise un processus enfant, les données seront envoyées sous forme de buffer sérialisé via l'API process.send.
• Si Vitest exécute des tests dans le navigateur, les données seront sérialisées à l'aide du package flatted.

Cette propriété est également présente sur chaque test dans le générateur de rapports json. Assurez-vous que les données peuvent être sérialisées en JSON.

Pensez également à sérialiser les propriétés d'erreur avant de les définir.

Vous pouvez également obtenir ces informations à partir de l'état de Vitest une fois les tests terminés :

const vitest = await createVitest('test');
const { testModules } = await vitest.start();

const testModule = testModules[0];
testModule.meta().done === true;
testModule.children.at(0).meta().custom === 'some-custom-handler';

Il est également possible d'étendre les définitions de type lors de l'utilisation de TypeScript :

declare module 'vitest' {
  interface TaskMeta {
    done?: boolean;
    custom?: string;
  }
}