API Vitest

L'instance de Vitest est liée au mode d'exécution actuel. Ce mode peut être :

test lors de l'exécution de tests unitaires ou d'intégration.
benchmark lors de l'exécution de benchmarks expérimental

Nouveautés dans Vitest 3

Vitest 3 marque une étape importante vers la stabilisation de l'API publique. Dans cette optique, nous avons déprécié et supprimé certaines méthodes précédemment publiques de la classe Vitest. Ces API sont désormais considérées comme privées :

configOverride (utilisez setGlobalTestNamePattern ou enableSnapshotUpdate)
coverageProvider
filenamePattern
runningPromise
closingPromise
isCancelling
coreWorkspaceProject
resolvedProjects
_browserLastPort
_options
reporters
vitenode
runner
pool
setServer
_initBrowserServers
rerunTask
changeProjectName
changeNamePattern
changeFilenamePattern
rerunFailed
_createRootProject (renommé en _ensureRootProject, mais reste privé)
filterTestsBySource (cette fonctionnalité a été déplacée vers la nouvelle instance interne vitest.specifications)
runFiles (utilisez runTestSpecifications à la place)
onAfterSetServer

Les API suivantes ont été dépréciées :

invalidates
changedTests (utilisez onFilterWatchedSpecification à la place)
server (utilisez vite à la place)
getProjectsByTestFile (utilisez getModuleSpecifications à la place)
getFileWorkspaceSpecs (utilisez getModuleSpecifications à la place)
getModuleProjects (filtrez par this.projects vous-même)
updateLastChanged (renommé en invalidateFile)
globTestSpecs (utilisez globTestSpecifications à la place)
globTestFiles (utilisez globTestSpecifications à la place)
listFile (utilisez getRelevantTestSpecifications à la place)

mode

test

En mode test, seules les fonctions définies avec test ou it seront exécutées. Une erreur sera levée si une fonction bench est rencontrée. Ce mode utilise les options include et exclude de la configuration pour identifier les fichiers de test.

benchmark expérimental

Le mode benchmark exécute les fonctions bench et lève une erreur si des fonctions test ou it sont rencontrées. Ce mode utilise les options benchmark.include et benchmark.exclude de la configuration pour identifier les fichiers de benchmark.

config

La configuration racine (ou globale) de Vitest. Si des projets sont définis, ils feront référence à cette configuration en tant que globalConfig.

WARNING

Il s'agit de la configuration spécifique à Vitest ; elle n'étend pas la configuration Vite. Elle contient uniquement les valeurs résolues de la propriété test.

vite

Il s'agit de l'instance globale de ViteDevServer.

state expérimental

WARNING

L'API publique state est expérimentale (à l'exception de vitest.state.getReportedEntity). Des changements majeurs pourraient ne pas respecter SemVer. Il est recommandé d'épingler la version de Vitest lorsque vous utilisez cette API.

L'état global maintient les informations sur les tests en cours d'exécution. Par défaut, il utilise la même API que @vitest/runner. Cependant, nous recommandons d'utiliser l'API des tâches rapportées en appelant state.getReportedEntity() sur l'API @vitest/runner :

const task = vitest.state.idMap.get(taskId); // ancienne API
const testCase = vitest.state.getReportedEntity(task); // nouvelle API

À l'avenir, l'ancienne API ne sera plus exposée.

snapshot

Le gestionnaire global de snapshots. Vitest enregistre tous les snapshots via la méthode snapshot.add.

Vous pouvez obtenir le dernier résumé des snapshots via la propriété vitest.snapshot.summary.

cache

Le système de cache stocke des informations sur les derniers résultats de test et les statistiques des fichiers de test. Au sein de Vitest, il est uniquement utilisé par le séquenceur par défaut pour ordonner les tests.

projects

Une liste de projets de test appartenant à la configuration de l'utilisateur. Si l'utilisateur n'a pas spécifié de projets, ce tableau ne contiendra qu'un seul projet racine.

Vitest garantit qu'il y a toujours au moins un projet dans ce tableau. Si l'utilisateur spécifie un nom de --project inexistant, Vitest lèvera une erreur avant que ce tableau ne soit défini.

getRootProject

function getRootProject(): TestProject;

Cette fonction renvoie le projet de test racine. Le projet racine n'exécute généralement aucun test et n'est pas inclus dans vitest.projects, sauf si l'utilisateur inclut explicitement la configuration racine dans sa configuration, ou si aucun projet n'est défini.

Le rôle principal du projet racine est de configurer la configuration globale. En fait, rootProject.config fait référence à rootProject.globalConfig et vitest.config directement :

(rootProject.config === rootProject.globalConfig) === rootProject.vitest.config;

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Vitest expose la méthode provide, qui est un raccourci pour vitest.getRootProject().provide. Cette méthode permet de transmettre des valeurs du thread 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 une meilleure sécurité de type, 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 appartient à TestProject, elle est donc limitée au projet spécifique. Cependant, tous les projets héritent des valeurs du projet racine, ce qui fait de vitest.provide un moyen universel de transmettre des valeurs aux tests.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Cette fonction renvoie l'objet de contexte racine. C'est un raccourci pour vitest.getRootProject().getProvidedContext.

getProjectByName

function getProjectByName(name: string): TestProject;

Cette méthode retourne le projet correspondant au nom donné. Elle est similaire à l'appel de vitest.projects.find.

WARNING

Si le projet n'existe pas, cette méthode renverra le projet racine. Assurez-vous de vérifier les noms si le projet renvoyé n'est pas celui que vous attendiez.

Si l'utilisateur n'a pas personnalisé un nom, Vitest attribuera une chaîne vide comme nom.

globTestSpecifications

function globTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Cette méthode génère de nouvelles spécifications de test en collectant chaque test dans tous les projets via project.globTestFiles. Elle accepte des filtres de chaîne pour faire correspondre les fichiers de test, qui sont les mêmes filtres que ceux pris en charge par la CLI.

Cette méthode met automatiquement en cache toutes les spécifications de test. Lors du prochain appel à getModuleSpecifications, elle renverra les mêmes spécifications, à moins que clearSpecificationsCache n'ait été appelé auparavant.

WARNING

À partir de Vitest 3, il est possible d'avoir plusieurs spécifications de test avec le même ID de module (chemin de fichier) si poolMatchGlob a plusieurs pools ou si typecheck est activé. Cette possibilité sera supprimée dans Vitest 4.

const specifications = await vitest.globTestSpecifications(['my-filter']);
// [TestSpecification{ moduleId: '/tests/my-filter.test.ts' }]
console.log(specifications);

getRelevantTestSpecifications

function getRelevantTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Cette méthode traite chaque spécification de test en appelant project.globTestFiles. Elle accepte des filtres de chaîne pour faire correspondre les fichiers de test, qui sont les mêmes filtres que ceux pris en charge par la CLI. Si l'indicateur --changed a été spécifié, la liste sera filtrée pour inclure uniquement les fichiers modifiés. getRelevantTestSpecifications n'exécute aucun fichier de test.

WARNING

Cette méthode peut être lente car elle doit filtrer les indicateurs --changed. Ne l'utilisez pas si vous avez simplement besoin d'une liste de fichiers de test.

Si vous avez besoin d'obtenir la liste des spécifications pour des fichiers de test connus, utilisez getModuleSpecifications à la place.
Si vous avez besoin d'obtenir la liste de tous les fichiers de test possibles, utilisez globTestSpecifications.

mergeReports

function mergeReports(directory?: string): Promise<TestRunResult>;

Fusionne les rapports de plusieurs exécutions de tests situés dans le répertoire spécifié (la valeur de --merge-reports si non spécifié). Cette valeur peut également être définie via config.mergeReports (par défaut, elle lira le dossier .vitest-reports).

Notez que le répertoire sera toujours résolu par rapport au répertoire de travail.

Cette méthode est appelée automatiquement par startVitest si config.mergeReports est défini.

collect

function collect(filters?: string[]): Promise<TestRunResult>;

Exécute les fichiers de test sans appeler les callbacks de test. collect renvoie les erreurs non gérées et un tableau de modules de test. Elle accepte des filtres de chaîne pour faire correspondre les fichiers de test, qui sont les mêmes filtres que ceux pris en charge par la CLI.

Cette méthode résout les spécifications de test en fonction des valeurs include, exclude et includeSource de la configuration. Pour en savoir plus, consultez project.globTestFiles. Si l'indicateur --changed a été spécifié, la liste sera filtrée pour inclure uniquement les fichiers modifiés.

WARNING

Notez que Vitest n'utilise pas d'analyse statique pour collecter les tests. Vitest exécutera chaque fichier de test de manière isolée, tout comme il exécute des tests réguliers.

Cela rend cette méthode très lente, à moins que vous ne désactiviez l'isolation avant de collecter les tests.

start

function start(filters?: string[]): Promise<TestRunResult>;

Initialise les rapporteurs, le fournisseur de couverture et exécute les tests. Cette méthode accepte des filtres de chaîne pour faire correspondre les fichiers de test, qui sont les mêmes filtres que ceux pris en charge par la CLI.

WARNING

Cette méthode ne doit pas être appelée si vitest.init() est également invoqué. Utilisez runTestSpecifications ou rerunTestSpecifications à la place si vous devez exécuter des tests après l'initialisation de Vitest.

Cette méthode est appelée automatiquement par startVitest si config.mergeReports et config.standalone ne sont pas définis.

init

function init(): Promise<void>;

Initialise les rapporteurs et le fournisseur de couverture. Cette méthode n'exécute aucun test. Si l'indicateur --watch est fourni, Vitest exécutera toujours les tests modifiés même si cette méthode n'a pas été appelée.

En interne, cette méthode n'est appelée que si l'indicateur --standalone est activé.

WARNING

Cette méthode ne doit pas être appelée si vitest.start() est également invoqué.

Cette méthode est appelée automatiquement par startVitest si config.standalone est défini.

getModuleSpecifications

function getModuleSpecifications(moduleId: string): TestSpecification[];

Renvoie une liste de spécifications de test liées à l'ID du module. L'ID doit déjà être résolu en un chemin de fichier absolu. Si l'ID ne correspond pas aux modèles include ou includeSource, le tableau renvoyé sera vide.

Cette méthode peut renvoyer des spécifications déjà mises en cache en fonction de moduleId et pool. Notez cependant que project.createSpecification renvoie toujours une nouvelle instance et n'est pas mise en cache automatiquement. Les spécifications sont automatiquement mises en cache lorsque runTestSpecifications est appelé.

WARNING

À partir de Vitest 3, cette méthode utilise un cache pour vérifier si le fichier est un test. Pour vous assurer que le cache n'est pas vide, appelez globTestSpecifications au moins une fois.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest met automatiquement en cache les spécifications de test pour chaque fichier lorsque globTestSpecifications ou runTestSpecifications est appelé. Cette méthode vide le cache pour le fichier donné ou le cache entier, selon le premier argument.

runTestSpecifications

function runTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Cette méthode exécute chaque test en fonction des spécifications reçues. Le deuxième argument, allTestsRun, est utilisé par le fournisseur de couverture pour déterminer s'il doit instrumenter la couverture sur chaque fichier à la racine (cela n'a d'importance que si la couverture est activée et que coverage.all est défini sur true).

WARNING

Cette méthode ne déclenche pas les callbacks onWatcherRerun, onWatcherStart et onTestsRerun. Si vous réexécutez des tests en fonction de la modification du fichier, envisagez d'utiliser rerunTestSpecifications à la place.

rerunTestSpecifications

function rerunTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Cette méthode émet les événements reporter.onWatcherRerun et onTestsRerun, puis elle exécute les tests avec runTestSpecifications. S'il n'y a pas eu d'erreurs dans le processus principal, elle émettra l'événement reporter.onWatcherStart.

updateSnapshot

function updateSnapshot(files?: string[]): Promise<TestRunResult>;

Met à jour les snapshots dans les fichiers spécifiés. Si aucun fichier n'est fourni, elle mettra à jour les snapshots des fichiers contenant des tests échoués et des snapshots obsolètes.

collectTests

function collectTests(
  specifications: TestSpecification[]
): Promise<TestRunResult>;

Exécute les fichiers de test sans appeler les callbacks de test. collectTests renvoie les erreurs non gérées et un tableau de modules de test.

Cette méthode fonctionne exactement de la même manière que collect, mais vous devez fournir vous-même les spécifications de test.

WARNING

Notez que Vitest n'utilise pas d'analyse statique pour collecter les tests. Vitest exécutera chaque fichier de test de manière isolée, tout comme il exécute des tests réguliers.

Cela rend cette méthode très lente, à moins que vous ne désactiviez l'isolation avant de collecter les tests.

cancelCurrentRun

function cancelCurrentRun(reason: CancelReason): Promise<void>;

Cette méthode annulera gracieusement tous les tests en cours. Elle attendra que les tests déjà démarrés se terminent et n'exécutera pas les tests qui étaient planifiés mais n'ont pas encore commencé.

setGlobalTestNamePattern

function setGlobalTestNamePattern(pattern: string | RegExp): void;

Cette méthode surcharge le modèle de nom de test global.

WARNING

Cette méthode ne démarre pas l'exécution des tests. Pour exécuter les tests avec le modèle mis à jour, appelez runTestSpecifications.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Cette méthode réinitialise le modèle de nom de test. Cela signifie que Vitest ne sautera plus aucun test.

WARNING

Cette méthode ne démarre pas l'exécution des tests. Pour exécuter les tests sans modèle, appelez runTestSpecifications.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Active le mode qui permet de mettre à jour les snapshots lors de l'exécution des tests. Chaque test exécuté après l'appel de cette méthode mettra à jour les snapshots. Pour désactiver le mode, appelez resetSnapshotUpdate.

WARNING

Cette méthode ne démarre pas l'exécution des tests. Pour mettre à jour les snapshots, exécutez les tests avec runTestSpecifications.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Désactive le mode qui permet de mettre à jour les snapshots lors de l'exécution des tests. Cette méthode ne démarre pas l'exécution des tests.

invalidateFile

function invalidateFile(filepath: string): void;

Cette méthode invalide le fichier dans le cache de chaque projet. Elle est principalement utile si vous utilisez votre propre observateur, car le cache de Vite persiste en mémoire.

DANGER

Si vous désactivez l'observateur de Vitest mais que vous maintenez Vitest en cours d'exécution, il est important de vider manuellement le cache avec cette méthode, car il n'y a aucun moyen de désactiver le cache. Cette méthode invalidera également les importateurs du fichier.

import

function import<T>(moduleId: string): Promise<T>

Importe un fichier en utilisant le module runner de Vite. Le fichier sera transformé par Vite avec la configuration globale et exécuté dans un contexte séparé. Notez que moduleId sera relatif à config.root.

DANGER

project.import réutilise le graphe de modules de Vite, donc l'importation du même module en utilisant une importation régulière renverra un module différent :

import * as staticExample from './example.js';
const dynamicExample = await vitest.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

En interne, Vitest utilise cette méthode pour importer les configurations globales, les fournisseurs de couverture personnalisés et les rapporteurs personnalisés, ce qui signifie qu'ils partagent tous le même graphe de modules tant qu'ils appartiennent au même serveur Vite.

close

function close(): Promise<void>;

Ferme tous les projets et leurs ressources associées. Cette méthode ne peut être appelée qu'une seule fois ; la promesse de fermeture est mise en cache jusqu'au redémarrage du serveur.

exit

function exit(force = false): Promise<void>;

Ferme tous les projets et quitte le processus. Si force est défini sur true, le processus se terminera immédiatement après la fermeture des projets.

Cette méthode appellera également process.exit() de force si le processus est toujours actif après config.teardownTimeout millisecondes.

shouldKeepServer

function shouldKeepServer(): boolean;

Cette méthode retournera true si le serveur doit rester en cours d'exécution après la fin des tests. Cela signifie généralement que le mode watch a été activé.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Définit un gestionnaire qui sera appelé lorsque le serveur est redémarré en raison d'un changement de configuration.

onCancel

function onCancel(fn: (reason: CancelReason) => Awaitable<void>): void;

Définit un gestionnaire qui sera appelé lorsque l'exécution du test est annulée avec vitest.cancelCurrentRun.

onClose

function onClose(fn: () => Awaitable<void>): void;

Définit un gestionnaire qui sera appelé lorsque le serveur est fermé.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Définit un gestionnaire qui sera appelé lorsque les tests sont réexécutés. Les tests peuvent être réexécutés lorsque rerunTestSpecifications est appelé manuellement ou lorsqu'un fichier est modifié et que l'observateur intégré planifie une réexécution.

onFilterWatchedSpecification

function onFilterWatchedSpecification(
  fn: (specification: TestSpecification) => boolean
): void;

Définit un gestionnaire qui sera appelé lorsqu'un fichier est modifié. Ce callback doit retourner true ou false, indiquant si le fichier de test doit être réexécuté.

Avec cette méthode, vous pouvez vous connecter à la logique de l'observateur par défaut pour retarder ou ignorer les tests que l'utilisateur ne souhaite pas suivre pour le moment :

const continuesTests: string[] = [];

myCustomWrapper.onContinuesRunEnabled(testItem =>
  continuesTests.push(item.fsPath)
);

vitest.onFilterWatchedSpecification(specification =>
  continuesTests.includes(specification.moduleId)
);

Vitest peut créer différentes spécifications pour le même fichier en fonction des options pool ou locations, ne vous fiez donc pas à la référence. Vitest peut également renvoyer une spécification mise en cache à partir de vitest.getModuleSpecifications - le cache est basé sur moduleId et pool. Notez que project.createSpecification renvoie toujours une nouvelle instance.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Détermine si le nom correspond au filtre de projet actuel. S'il n'y a pas de filtre de projet, cette méthode retournera toujours true.

Il n'est pas possible de modifier programmatiquement l'option CLI --project.

API Vitest ​

mode ​

test ​

benchmark expérimental ​

config ​

vite ​

state expérimental ​

snapshot ​

cache ​

projects ​

getRootProject ​

provide ​

getProvidedContext ​

getProjectByName ​

globTestSpecifications ​

getRelevantTestSpecifications ​

mergeReports ​

collect ​

start ​

init ​

getModuleSpecifications ​

clearSpecificationsCache ​

runTestSpecifications ​

rerunTestSpecifications ​

updateSnapshot ​

collectTests ​

cancelCurrentRun ​

setGlobalTestNamePattern ​

resetGlobalTestNamePattern ​

enableSnapshotUpdate ​

resetSnapshotUpdate ​

invalidateFile ​

import ​

close ​

exit ​

shouldKeepServer ​

onServerRestart ​

onCancel ​

onClose ​

onTestsRerun ​

onFilterWatchedSpecification ​

matchesProjectFilter 3.1.0+ ​

API Vitest

mode

test

benchmark expérimental

config

vite

state expérimental

snapshot

cache

projects

getRootProject

provide

getProvidedContext

getProjectByName

globTestSpecifications

getRelevantTestSpecifications

mergeReports

collect

start

init

getModuleSpecifications

clearSpecificationsCache

runTestSpecifications

rerunTestSpecifications

updateSnapshot

collectTests

cancelCurrentRun

setGlobalTestNamePattern

resetGlobalTestNamePattern

enableSnapshotUpdate

resetSnapshotUpdate

invalidateFile

import

close

exit

shouldKeepServer

onServerRestart

onCancel

onClose

onTestsRerun

onFilterWatchedSpecification

matchesProjectFilter 3.1.0+