Démarrage

Aperçu

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

Pour en savoir plus sur les motivations derrière ce projet, consultez la section Pourquoi Vitest.

Essayer Vitest en ligne

Vous pouvez tester Vitest directement dans votre navigateur via StackBlitz. L'expérience est quasi identique à une installation locale, sans nécessiter d'installation sur votre machine.

Ajouter Vitest à votre projet

Apprenez à l'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 requiert Vite >=v5.0.0 et Node >=v18.0.0.

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

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

Écrire des tests

Prenons un exemple simple : nous allons écrire un test pour vérifier le résultat d'une fonction qui additionne deux nombres.

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

// sum.test.js
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 fichiers de test doivent inclure ".test." ou ".spec." dans leur nom.

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 le message suivant :

✓ 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 l'exécuteur de tests intégré à Bun.

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. Si un fichier vite.config.ts est présent à la racine de votre projet, vitest le lira pour utiliser les mêmes plugins et la même configuration que votre application Vite. Par exemple, vos configurations resolve.alias et plugins de Vite fonctionneront sans configuration supplémentaire. Si vous souhaitez une configuration différente pendant les tests, vous pouvez :

• Créer un fichier 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 de defineConfig (qui sera définie sur test si non écrasé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 directement, Vitest s'appuie fortement sur lui pour son pipeline de transformation. C'est pourquoi vous pouvez également configurer n'importe quelle propriété décrite dans la documentation Vite.

Si vous utilisez déjà Vite, ajoutez la propriété test à votre configuration Vite. Vous devrez également ajouter une référence aux types Vitest en utilisant une directive à trois barres obliques au début de votre fichier de configuration.

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

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

La directive <reference types="vitest" /> ne fonctionnera plus dans Vitest 3, 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 il écrasera votre fichier Vite au lieu de l'étendre. Vous pouvez également utiliser la méthode mergeConfig des entrées 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 un fichier de configuration unique pour Vite et Vitest, plutôt que d'en créer deux distincts.

Prise en charge des espaces de travail

Exécutez différentes configurations de projet au sein du même projet grâce aux espaces de travail Vitest. Vous pouvez définir votre espace de travail dans le fichier vitest.workspace en spécifiant une liste de fichiers et de dossiers. Ce fichier prend en charge les extensions js/ts/json. Cette fonctionnalité est particulièrement utile pour les configurations monorepo.

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  // Vous pouvez utiliser une liste de motifs glob pour définir vos espaces de travail.
  // Vitest attend une liste de fichiers de configuration
  // ou de répertoires contenant un fichier de configuration.
  'packages/*',
  'tests/*/vitest.config.{e2e,unit}.ts',
  // Vous pouvez même exécuter les mêmes tests,
  // mais 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 de 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 de ligne de commande.

Installation automatique des dépendances

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

Intégrations IDE

Nous avons également fourni 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	Playground
basic	GitHub	Essayer en ligne
fastify	GitHub	Essayer en ligne
in-source-test	GitHub	Essayer en ligne
lit	GitHub	Essayer en ligne
vue	GitHub	Essayer en ligne
marko	GitHub	Essayer en ligne
preact	GitHub	Essayer en ligne
react	GitHub	Essayer en ligne
solid	GitHub	Essayer en ligne
svelte	GitHub	Essayer en ligne
sveltekit	GitHub	Essayer en ligne
profiling	GitHub	Non disponible
typecheck	GitHub	Essayer en ligne
workspace	GitHub	Essayer 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 et chaque PR avec un label cr-tracked est publié sur pkg.pr.new. Vous pouvez l'installer avec npm i https://pkg.pr.new/vitest@{commit}.

Si vous souhaitez tester vos propres modifications localement, vous pouvez les compiler et les 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 # vous pouvez utiliser 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 le gestionnaire de paquets que vous avez utilisé pour lier vitest globalement).

Communauté

Si vous avez des questions ou avez besoin d'aide, n'hésitez pas à contacter la communauté sur Discord et GitHub Discussions.