API avancée

WARNING

Ce guide présente les API avancées pour exécuter des tests via un script Node.js. Si vous souhaitez simplement exécuter des tests, vous n'en avez probablement pas besoin. Il est principalement destiné aux auteurs de bibliothèques.

Vous pouvez importer n'importe quelle méthode depuis le point d'entrée vitest/node.

startVitest

function startVitest(
  mode: VitestRunMode,
  cliFilters: string[] = [],
  options: CliOptions = {},
  viteOverrides?: ViteUserConfig,
  vitestOptions?: VitestOptions
): Promise<Vitest>;

Vous pouvez démarrer l'exécution de 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.

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

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

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

De plus, vous pouvez utiliser le troisième argument pour transmettre des arguments CLI, qui prévaudront sur toutes les options de configuration des tests. Alternativement, vous pouvez transmettre la configuration Vite complète comme quatrième argument, qui primera sur toutes les autres options définies par l'utilisateur.

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

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

const vitest = await startVitest('test');

console.log(vitest.state.getTestModules()); // [TestModule]

TIP

Le guide "Exécution des tests" contient un exemple d'utilisation.

createVitest

function createVitest(
  mode: VitestRunMode,
  options: CliOptions,
  viteOverrides: ViteUserConfig = {},
  vitestOptions: VitestOptions = {}
): Promise<Vitest>;

Vous pouvez créer une instance Vitest en utilisant la fonction createVitest. Cette fonction retourne la même instance Vitest que startVitest, mais elle ne démarre pas les tests et ne valide pas les paquets installés.

import { createVitest } from 'vitest/node';

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

TIP

Le guide "Exécution des tests" contient un exemple d'utilisation.

resolveConfig

function resolveConfig(
  options: UserConfig = {},
  viteOverrides: ViteUserConfig = {}
): Promise<{
  vitestConfig: ResolvedConfig;
  viteConfig: ResolvedViteConfig;
}>;

Cette méthode détermine la configuration en utilisant des paramètres personnalisés. Si aucun paramètre n'est fourni, la racine sera process.cwd().

import { resolveConfig } from 'vitest/node';

// vitestConfig ne contient que les propriétés "test" résolues
const { vitestConfig, viteConfig } = await resolveConfig({
  mode: 'custom',
  configFile: false,
  resolve: {
    conditions: ['custom'],
  },
  test: {
    setupFiles: ['/my-setup-file.js'],
    pool: 'threads',
  },
});

INFO

En raison du fonctionnement de createServer de Vite, Vitest doit résoudre la configuration pendant le hook configResolve du plugin. Par conséquent, cette méthode n'est pas réellement utilisée en interne et est exposée uniquement en tant qu'API publique.

Si vous transmettez la configuration aux API startVitest ou createVitest, Vitest résoudra à nouveau la configuration.

WARNING

resolveConfig ne résout pas les projects. Pour résoudre les configurations de projects, Vitest a besoin d'un serveur Vite établi.

Notez également que viteConfig.test ne sera pas entièrement résolu. Si vous avez besoin de la configuration de Vitest, utilisez vitestConfig à la place.

parseCLI

function parseCLI(
  argv: string | string[],
  config: CliParseOptions = {}
): {
  filter: string[];
  options: CliOptions;
};

Vous pouvez utiliser cette méthode pour interpréter les arguments de la ligne de commande. Elle accepte une chaîne (où les arguments sont séparés par un 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 pourrez ensuite transmettre aux méthodes createVitest ou startVitest.

import { parseCLI } from 'vitest/node';

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

result.options;
// {
//   coverage: { enabled: true },
//   browser: { name: 'chrome', enabled: true }
// }

result.filter;
// ['./files.ts']