API Node

WARNING

Vitest expose une API privée expérimentale. Les changements majeurs pourraient ne pas respecter SemVer. Veuillez fixer la version de Vitest lorsque vous l'utilisez.

startVitest

Vous pouvez démarrer les tests Vitest en utilisant son API Node :

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest?.close();

La fonction startVitest retourne une instance Vitest si les tests peuvent être lancés avec succès. Elle retourne undefined dans l'un des cas suivants :

• Vitest n'a pas trouvé le package vite (généralement installé avec Vitest).
• Si la couverture est activée et que le mode d'exécution est "test", mais que le package de couverture n'est pas installé (@vitest/coverage-v8 ou @vitest/coverage-istanbul).
• Si le package d'environnement n'est pas installé (jsdom/happy-dom/@edge-runtime/vm).

Si undefined est retourné ou si des tests échouent pendant l'exécution, Vitest affecte la valeur 1 à process.exitCode.

Si le mode de surveillance n'est pas activé, Vitest appellera la méthode close.

Si le mode watch est activé et que le terminal prend en charge TTY, Vitest enregistrera les raccourcis clavier.

Vous pouvez transmettre une liste de filtres comme deuxième argument. Vitest exécutera uniquement les tests dont le chemin de fichier contient au moins une des chaînes transmises.

De plus, vous pouvez utiliser le troisième argument pour transmettre des arguments CLI, qui prévaudront sur toutes les options de configuration de test.

Vous pouvez également transmettre la configuration Vite complète comme quatrième argument, qui aura priorité sur toutes les autres options définies par l'utilisateur.

Après avoir exécuté les tests, vous pouvez récupérer les résultats via l'API state.getFiles :

const vitest = await startVitest('test');

console.log(vitest.state.getFiles()); // [{ type: 'file', ... }]

À partir de Vitest 2.1, il est conseillé d'utiliser l'API "Tâches reportées" avec state.getFiles. À l'avenir, Vitest retournera directement ces objets :

const vitest = await startVitest('test');

const [fileTask] = vitest.state.getFiles();
const testFile = vitest.state.getReportedEntity(fileTask);

createVitest

Vous pouvez créer votre propre instance Vitest en utilisant la fonction createVitest. Elle retourne la même instance Vitest que startVitest, mais ne démarre pas les tests et ne valide pas la présence des paquets requis.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test', {
  watch: false,
});

parseCLI

Vous pouvez utiliser cette méthode pour analyser les arguments de la ligne de commande (CLI). Elle accepte une chaîne (dans laquelle les arguments sont séparés par un simple espace) ou un tableau de chaînes d'arguments CLI, dans le même format que celui utilisé par Vitest CLI. Elle retourne un filtre et des options que vous pouvez ensuite transmettre aux méthodes createVitest ou startVitest.

import { parseCLI } from 'vitest/node';

parseCLI('vitest ./files.ts --coverage --browser=chrome');

Vitest

L'instance Vitest requiert la définition du mode de test actuel. Ce peut être :

• test lors de l'exécution des tests unitaires.
• benchmark lors de l'exécution des benchmarks.

mode

test

Le mode test exécute uniquement les fonctions test ou it, et génère une erreur si bench est utilisé. Ce mode utilise les options include et exclude dans la configuration pour identifier les fichiers de test.

benchmark

Le mode Benchmark appelle les fonctions bench et lève une erreur s'il rencontre test ou it. Ce mode utilise les options benchmark.include et benchmark.exclude dans la configuration pour identifier les fichiers de benchmark.

start

Vous pouvez lancer les tests ou les benchmarks avec la méthode start. Vous pouvez passer un tableau de chaînes pour filtrer les fichiers de test.

provide

Vitest expose la méthode provide qui est un raccourci pour vitest.getCoreWorkspaceProject().provide. Cette méthode permet de transmettre des valeurs du processus principal aux tests. Toutes les valeurs sont vérifiées avec structuredClone avant d'être stockées, mais les valeurs elles-mêmes ne sont pas clonées.

Pour récupérer les valeurs dans le test, vous devez importer la méthode inject depuis le point d'entrée vitest.

import { inject } from 'vitest';
const port = inject('wsPort'); // 3000

Pour améliorer la sécurité des types, nous vous encourageons à étendre le type ProvidedContext :

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test', {
  watch: false,
});
vitest.provide('wsPort', 3000);

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

WARNING

Techniquement, provide est une méthode du WorkspaceProject, elle est donc limitée à ce projet spécifique. Cependant, tous les projets héritent des valeurs du projet principal, ce qui rend vitest.provide universel pour transmettre des valeurs aux tests.

TIP

Cette méthode est également disponible pour les fichiers de configuration globale si vous ne souhaitez pas utiliser l'API publique :

export default function setup({ provide }) {
  provide('wsPort', 3000);
}