TestProject 3.0.0+

WARNING

Ce guide décrit l'API Node.js avancée. Si votre objectif est simplement de créer des projets, veuillez consulter le guide "Projets de test".

name

Le nom est une chaîne unique attribuée par l'utilisateur ou déterminée par Vitest. Si l'utilisateur n'a pas fourni de nom, Vitest tente de charger un fichier package.json à la racine du projet et d'en extraire la propriété name. En l'absence de package.json, Vitest utilise par défaut le nom du dossier. Les projets intégrés (inline) sont nommés avec des nombres (convertis en chaînes de caractères).

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // contient un package.json avec "@pkg/server"
      './utils', // ne contient pas de fichier package.json
      {
        // le nom n'est pas personnalisé
        test: {
          pool: 'threads',
        },
      },
      {
        // nom personnalisé
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Si le projet racine ne fait pas partie des projets utilisateur, son name ne sera pas résolu.

vitest

vitest fait référence à l'instance globale de Vitest.

serializedConfig

Il s'agit de la configuration que les processus de test reçoivent. Vitest sérialise manuellement la configuration en supprimant toutes les fonctions et propriétés non sérialisables. Étant donné que cette valeur est disponible à la fois dans les tests et dans Node, son type est exporté depuis le point d'entrée principal.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

La propriété serializedConfig est un accesseur (getter). Chaque fois qu'elle est accédée, Vitest resérialise la configuration pour prendre en compte d'éventuelles modifications. Cela implique également qu'elle renvoie toujours une référence différente :

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

La configuration de test avec laquelle Vitest a été initialisé. S'il s'agit du projet racine, globalConfig et config feront référence au même objet. Cette configuration est utile pour les valeurs qui ne peuvent pas être définies au niveau du projet, comme coverage ou reporters.

import type { ResolvedConfig } from 'vitest/node';

vitest.config === vitest.projects[0].globalConfig;

config

C'est la configuration de test résolue du projet.

hash 3.2.0+

Le hachage unique de ce projet. Cette valeur reste constante entre les réexécutions.

Il est calculé à partir de la racine du projet et de son nom. Notez que le chemin racine n'est pas cohérent entre les différents systèmes d'exploitation, ce qui entraînera un hachage différent.

vite

C'est le ViteDevServer du projet. Tous les projets ont leurs propres serveurs Vite.

browser

Cette valeur n'est définie que si les tests s'exécutent dans le navigateur. Si browser est activé, mais que les tests n'ont pas encore été exécutés, cette valeur sera undefined. Pour vérifier si le projet prend en charge les tests de navigateur, utilisez la méthode project.isBrowserEnabled().

WARNING

L'API du navigateur est encore plus expérimentale et ne suit pas SemVer. L'API du navigateur sera standardisée séparément du reste des API.

provide

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

Permet de fournir des valeurs personnalisées aux tests en complément du champ config.provide. Toutes les valeurs sont validées avec structuredClone avant d'être stockées, mais les valeurs du providedContext elles-mêmes ne sont pas clonées.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

Les valeurs peuvent être fournies de manière dynamique. La valeur fournie dans les tests sera mise à jour lors de la prochaine exécution.

TIP

Cette méthode est également disponible pour les fichiers de configuration globale dans les cas où vous ne pouvez pas utiliser l'API publique :

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

getProvidedContext

function getProvidedContext(): ProvidedContext;

Cette méthode renvoie l'objet de contexte. Chaque projet hérite également du contexte global fourni par vitest.provide.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

Les valeurs de contexte du projet prévaudront toujours sur celles du projet racine.

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

Crée une spécification de test qui peut être utilisée dans vitest.runTestSpecifications. La spécification associe le fichier de test à un project spécifique et à des locations de test (facultatif). Les emplacements de test sont les numéros de ligne où le test est déclaré dans le code source. Si des emplacements sont fournis, Vitest n'exécutera que les tests situés sur ces lignes. Notez que si testNamePattern est défini, il sera également appliqué.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // lignes de test facultatives
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification requiert un ID de module résolu. Il ne résout pas automatiquement le fichier et ne vérifie pas son existence sur le système de fichiers.

Notez également que project.createSpecification renvoie toujours une nouvelle instance.

isRootProject

function isRootProject(): boolean;

Vérifie si le projet actuel est le projet racine. Vous pouvez également obtenir le projet racine en appelant vitest.getRootProject().

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * Fichiers de test qui correspondent aux filtres.
   */
  testFiles: string[];
  /**
   * Fichiers de test de vérification de type qui correspondent aux filtres. Ce sera vide sauf si `typecheck.enabled` est `true`.
   */
  typecheckTestFiles: string[];
};

Détecte tous les fichiers de test. Cette fonction renvoie un objet contenant les tests standards et les tests de vérification de type.

Cette méthode accepte des filters. Les filtres ne peuvent spécifier qu'une partie du chemin du fichier, contrairement aux autres méthodes de l'instance Vitest :

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest utilise fast-glob pour trouver les fichiers de test. test.dir, test.root, root ou process.cwd() déterminent l'option cwd.

Cette méthode examine plusieurs options de configuration :

• test.include, test.exclude pour trouver les fichiers de test réguliers
• test.includeSource, test.exclude pour trouver les tests in-source
• test.typecheck.include, test.typecheck.exclude pour trouver les tests de vérification de type

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

Cette méthode vérifie si le fichier est un fichier de test standard. Elle utilise les mêmes propriétés de configuration que globTestFiles à des fins de validation.

Cette méthode accepte également un second paramètre, qui correspond au code source. Ce paramètre est utilisé pour valider si le fichier est un test in-source. Si vous appelez cette méthode à plusieurs reprises pour différents projets, il est recommandé de lire le fichier une fois et de le transmettre directement. Si le fichier n'est pas un fichier de test, mais correspond au glob includeSource, Vitest lira le fichier de manière synchrone, sauf si la source est fournie.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // true si `includeSource` est défini

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 du projet spécifié 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 importer le même module en utilisant une importation régulière produira un module différent :

import * as staticExample from './example.js';
const dynamicExample = await project.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 pour autant qu'ils appartiennent au même serveur Vite.

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

Ceci est un raccourci pour project.vitest.onTestsRerun. Il accepte une fonction de rappel qui sera exécutée lorsque les tests auront été planifiés pour une nouvelle exécution (généralement, en raison d'une modification de fichier).

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

Renvoie true si ce projet exécute des tests dans le navigateur.

close

function close(): Promise<void>;

Ferme le projet et toutes les ressources associées. Cette méthode ne peut être appelée qu'une seule fois ; la promesse de fermeture est mise en cache jusqu'à un redémarrage du serveur. Si les ressources sont requises à nouveau, créez un nouveau projet.

En détail, cette méthode ferme le serveur Vite, arrête le service de vérification de type, ferme le navigateur s'il est actif, supprime le répertoire temporaire qui contient le code source et réinitialise le contexte fourni.