Démarrage

Vue d'ensemble

Vitest (prononcé "veetest") est un framework de test de nouvelle génération propulsé par Vite.

Vous pouvez en apprendre davantage sur la raison d'être du projet dans la section Pourquoi Vitest.

Essayer Vitest en ligne

Vous pouvez essayer Vitest en ligne sur StackBlitz. Cette approche est presque identique à une installation locale, mais ne nécessite aucune installation sur votre machine.

Ajouter Vitest à votre projet

Apprendre à installer en vidéo

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

TIP

Vitest nécessite Vite >=v5.0.0 et Node >=v18.0.0.

Il est recommandé d'installer une copie de vitest dans votre package.json en utilisant l'une des méthodes listées ci-dessus. Cependant, si vous préférez exécuter vitest directement, vous pouvez utiliser npx vitest (l'outil npx est fourni avec npm et Node.js).

L'outil npx exécutera la commande que vous avez spécifiée. Par défaut, npx vérifiera d'abord si la commande existe dans les binaires du projet local. Si elle n'y est pas trouvée, npx cherchera dans le $PATH du système et l'exécutera si elle est présente. Si la commande n'est trouvée à aucun de ces emplacements, npx l'installera temporairement avant l'exécution.

Écrire des tests

À titre d'exemple, nous allons écrire un test simple qui vérifie le résultat d'une fonction additionnant deux nombres.

export function sum(a, b) {
  return a + b;
}

import { expect, test } from 'vitest';
import { sum } from './sum.js';

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

TIP

Par défaut, les noms de fichiers de test doivent contenir .test. ou .spec..

Ensuite, pour exécuter le test, ajoutez la section suivante à votre package.json :

{
  "scripts": {
    "test": "vitest"
  }
}

Enfin, exécutez npm run test, yarn test ou pnpm test, selon votre gestionnaire de paquets. Vitest affichera alors ce message :

✓ sum.test.js (1)
  ✓ adds 1 + 2 to equal 3

Test Files  1 passed (1)
     Tests  1 passed (1)
  Start at  02:15:44
  Duration  311ms

WARNING

Si vous utilisez Bun comme gestionnaire de paquets, assurez-vous d'utiliser la commande bun run test au lieu de bun test, car bun test exécuterait son propre lanceur de tests.

Pour en savoir plus sur l'utilisation de Vitest, consultez la section API.

Configurer Vitest

L'un des principaux avantages de Vitest est sa configuration unifiée avec Vite. S'il est présent, Vitest lira votre fichier vite.config.ts racine afin d'aligner les plugins et la configuration avec ceux de votre application Vite. Par exemple, vos configurations resolve.alias et plugins de Vite fonctionneront directement. Si vous souhaitez une configuration différente pendant les tests, vous pouvez :

• Créer vitest.config.ts, qui aura la priorité la plus élevée.
• Passer l'option --config à la CLI, par exemple vitest --config ./path/to/vitest.config.ts.
• Utiliser process.env.VITEST ou la propriété mode sur defineConfig (sera définie à test si non surchargée) pour appliquer conditionnellement une configuration différente dans vite.config.ts.

Vitest prend en charge les mêmes extensions pour votre fichier de configuration que Vite : .js, .mjs, .cjs, .ts, .cts, .mts. Vitest ne prend pas en charge l'extension .json.

Si vous n'utilisez pas Vite comme outil de build, vous pouvez configurer Vitest en utilisant la propriété test dans votre fichier de configuration :

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ...
  },
});

TIP

Même si vous n'utilisez pas Vite vous-même, Vitest s'appuie fortement sur lui pour son pipeline de transformation. Pour cette raison, vous pouvez également configurer n'importe quelle propriété décrite dans la documentation Vite.

Si vous utilisez déjà Vite, vous devez ajouter la propriété test dans votre fichier de configuration Vite. Vous devrez également ajouter une référence aux types Vitest en utilisant une directive triple slash en haut de votre fichier de configuration.

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ...
  },
});

La directive <reference types="vitest" /> cessera de fonctionner lors de la prochaine mise à jour majeure, mais vous pouvez commencer à migrer vers vitest/config dès Vitest 2.1 :

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... Spécifiez les options ici.
  },
});

Consultez la liste des options de configuration dans la Référence de configuration

WARNING

Si vous décidez d'avoir deux fichiers de configuration distincts pour Vite et Vitest, assurez-vous de définir les mêmes options Vite dans votre fichier de configuration Vitest, car celui-ci écrasera votre fichier Vite au lieu de l'étendre. Vous pouvez également utiliser la méthode mergeConfig des modules vite ou vitest/config pour fusionner la configuration Vite avec la configuration Vitest :

vitest.config.mjs

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config.mjs';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // ...
    },
  })
);

vite.config.mjs

import { defineConfig } from 'vite';
import Vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [Vue()],
});

Cependant, nous recommandons d'utiliser le même fichier pour Vite et Vitest, au lieu de créer deux fichiers distincts.

Prise en charge des projets

Exécutez différentes configurations de projet au sein du même projet avec les Projets de Test. Vous pouvez définir une liste de fichiers et de dossiers qui définissent vos projets dans le fichier vitest.config.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      // vous pouvez utiliser une liste de motifs glob pour définir vos projets
      // Vitest attend une liste de fichiers de configuration
      // ou de répertoires où se trouve un fichier de configuration
      'packages/*',
      'tests/*/vitest.config.{e2e,unit}.ts',
      // vous pouvez même exécuter les mêmes tests avec des configurations différentes dans le même processus "vitest"
      {
        test: {
          name: 'happy-dom',
          root: './shared_tests',
          environment: 'happy-dom',
          setupFiles: ['./setup.happy-dom.ts'],
        },
      },
      {
        test: {
          name: 'node',
          root: './shared_tests',
          environment: 'node',
          setupFiles: ['./setup.node.ts'],
        },
      },
    ],
  },
});

Interface en ligne de commande

Dans un projet où Vitest est installé, vous pouvez utiliser le binaire vitest dans vos scripts npm, ou l'exécuter directement avec npx vitest. Voici les scripts npm par défaut dans un projet Vitest généré :

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

Pour exécuter les tests une seule fois sans surveiller les changements de fichiers, utilisez vitest run. Vous pouvez spécifier des options CLI supplémentaires comme --port ou --https. Pour une liste complète des options CLI, exécutez npx vitest --help dans votre projet.

En savoir plus sur l'Interface en ligne de commande

Installation automatique des dépendances

Vitest vous invitera à installer certaines dépendances si elles ne sont pas déjà installées. Vous pouvez désactiver ce comportement en définissant la variable d'environnement VITEST_SKIP_INSTALL_CHECKS=1.

Intégrations IDE

Nous avons également créé une extension officielle pour Visual Studio Code afin d'améliorer votre expérience de test avec Vitest.

Installer depuis le VS Code Marketplace

En savoir plus sur les Intégrations IDE

Exemples

Exemple	Source	Terrain de jeu
basic	GitHub	Jouer en ligne
fastify	GitHub	Jouer en ligne
in-source-test	GitHub	Jouer en ligne
lit	GitHub	Jouer en ligne
vue	GitHub	Jouer en ligne
marko	GitHub	Jouer en ligne
preact	GitHub	Jouer en ligne
react	GitHub	Jouer en ligne
solid	GitHub	Jouer en ligne
svelte	GitHub	Jouer en ligne
sveltekit	GitHub	Jouer en ligne
profiling	GitHub	Non disponible
typecheck	GitHub	Jouer en ligne
projects	GitHub	Jouer en ligne

Projets utilisant Vitest

• unocss
• unplugin-auto-import
• unplugin-vue-components
• vue
• vite
• vitesse
• vitesse-lite
• fluent-vue
• vueuse
• milkdown
• gridjs-svelte
• spring-easing
• bytemd
• faker
• million
• Vitamin
• neodrag
• svelte-multiselect
• iconify
• tdesign-vue-next
• cz-git

Utilisation des commits non publiés

Chaque commit sur la branche principale, ainsi qu'une pull request (PR) avec le label cr-tracked, sont publiés sur pkg.pr.new. Vous pouvez l'installer en utilisant la commande : npm i https://pkg.pr.new/vitest@{commit}.

Si vous souhaitez tester votre propre modification localement, vous pouvez la compiler et la lier vous-même (l'utilisation de pnpm est requise) :

git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # utilisez votre gestionnaire de paquets préféré pour cette étape

Ensuite, dans le projet où vous utilisez Vitest, exécutez pnpm link --global vitest (ou la commande de votre gestionnaire de paquets utilisée pour lier Vitest globalement).

Communauté

Si vous avez des questions ou avez besoin d'aide, contactez la communauté sur Discord et GitHub Discussions.