Exécuter les tests

WARNING

Ce guide explique comment utiliser l'API avancée pour exécuter des tests via un script Node.js. Si vous souhaitez simplement exécuter des tests, cette approche n'est probablement pas nécessaire. Elle est principalement destinée aux auteurs de bibliothèques.

Les changements majeurs peuvent ne pas suivre SemVer. Il est donc recommandé de verrouiller la version de Vitest lorsque vous utilisez cette API expérimentale.

Vitest expose deux méthodes pour initialiser Vitest :

• startVitest initialise Vitest, vérifie l'installation des paquets requis et exécute immédiatement les tests.
• createVitest initialise uniquement Vitest sans exécuter de tests.

startVitest

import { startVitest } from 'vitest/node';

const vitest = await startVitest(
  'test',
  [], // Filtres CLI
  {}, // Surcharge de la configuration de test
  {}, // Surcharge de la configuration de Vite
  {} // Options Vitest personnalisées
);
const testModules = vitest.state.getTestModules();
for (const testModule of testModules) {
  console.log(testModule.moduleId, testModule.ok() ? 'passed' : 'failed');
}

TIP

Les API TestModule, TestSuite et TestCase ne sont pas expérimentales et suivent SemVer depuis Vitest 2.1.

createVitest

Cette méthode permet de créer une instance Vitest sans exécuter les tests.

La méthode createVitest ne vérifie pas l'installation des paquets requis. Elle ne prend pas non plus en compte config.standalone ou config.mergeReports. De plus, Vitest ne se fermera pas automatiquement, même si le mode watch est désactivé.

import { createVitest } from 'vitest/node';

const vitest = await createVitest(
  'test',
  {}, // Surcharge de la configuration de test
  {}, // Surcharge de la configuration de Vite
  {} // Options Vitest personnalisées
);

// Appelé lorsque `vitest.cancelCurrentRun()` est invoqué
vitest.onCancel(() => {});
// Appelé lors de l'invocation de `vitest.close()`
vitest.onClose(() => {});
// Appelé lorsque Vitest réexécute les fichiers de test
vitest.onTestsRerun(files => {});

try {
  // Cela définira process.exitCode à 1 si les tests échouent,
  // et ne fermera pas le processus automatiquement.
  await vitest.start(['my-filter']);
} catch (err) {
  // Cela peut lever :
  // "FilesNotFoundError" si aucun fichier n'a été trouvé.
  // "GitNotFoundError" si `--changed` est utilisé et le dépôt n'est pas initialisé.
} finally {
  await vitest.close();
}

Si vous souhaitez conserver l'instance Vitest, assurez-vous d'appeler au moins init. Cette méthode initialise les rapporteurs et le fournisseur de couverture, mais n'exécute aucun test. Il est également recommandé d'activer le mode watch même si vous n'avez pas l'intention d'utiliser le surveillant de Vitest, mais que vous souhaitez maintenir l'instance en cours d'exécution. Vitest s'appuie sur ce drapeau pour que certaines de ses fonctionnalités opèrent correctement dans un processus continu.

Une fois les rapporteurs initialisés, utilisez runTestSpecifications ou rerunTestSpecifications pour exécuter les tests si un lancement manuel est nécessaire :

watcher.on('change', async file => {
  const specifications = vitest.getModuleSpecifications(file);
  if (specifications.length) {
    vitest.invalidateFile(file);
    // Vous pouvez utiliser runTestSpecifications si les hooks "reporter.onWatcher*"
    // ne doivent pas être appelés.
    await vitest.rerunTestSpecifications(specifications);
  }
});

WARNING

L'exemple ci-dessus illustre un cas d'usage possible si vous désactivez le comportement par défaut du surveillant. Par défaut, Vitest réexécute déjà les tests si les fichiers sont modifiés.

Notez également que getModuleSpecifications ne résoudra pas les fichiers de test à moins qu'ils n'aient déjà été traités par globTestSpecifications. Si le fichier vient d'être créé, utilisez plutôt project.matchesGlobPattern :

watcher.on('add', async file => {
  const specifications = [];
  for (const project of vitest.projects) {
    if (project.matchesGlobPattern(file)) {
      specifications.push(project.createSpecification(file));
    }
  }

  if (specifications.length) {
    await vitest.rerunTestSpecifications(specifications);
  }
});

Dans les cas où vous devez désactiver le surveillant, vous pouvez passer server.watch: null (disponible depuis Vite 5.3) ou server.watch: { ignored: ['*/*'] } à une configuration Vite :

await createVitest(
  'test',
  {},
  {
    plugins: [
      {
        name: 'stop-watcher',
        async configureServer(server) {
          await server.watcher.close();
        },
      },
    ],
    server: {
      watch: null,
    },
  }
);