Premiers pas

Aperçu

Vitest est un framework de test de nouvelle génération propulsé par Vite.

Pour comprendre la raison d'être de ce projet, consultez la section Pourquoi Vitest.

Essayer Vitest en ligne

Vous pouvez tester Vitest directement dans votre navigateur grâce à StackBlitz. Cette solution offre une expérience quasi identique à une configuration locale, sans nécessiter d'installation sur votre machine.

Ajouter Vitest à votre projet

Apprenez à installer Vitest grâce à cette vidéo

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

TIP

Vitest 1.0 requiert Vite >=v5.0.0 et Node >=v18.0.0.

Il est recommandé d'installer vitest dans votre package.json en utilisant l'une des méthodes ci-dessus. Si vous préférez exécuter vitest directement, vous pouvez utiliser npx vitest (la commande npx est fournie avec npm et Node.js).

La commande npx exécute la commande à partir du répertoire node_modules/.bin local, en installant les paquets nécessaires à son exécution. Par défaut, npx vérifie si la commande existe dans le $PATH ou dans les binaires du projet local, et l'exécute. Si la commande n'est pas trouvée, elle est installée avant l'exécution.

Écrire des tests

Prenons l'exemple d'un test simple qui vérifie le résultat d'une fonction additionnant deux nombres.

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

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

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

TIP

Par défaut, les tests doivent contenir ".test." ou ".spec." dans leur nom de fichier.

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

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 du projet, vitest le lira pour s'aligner sur les plugins et la configuration de votre application Vite. Par exemple, votre configuration Vite pour resolve.alias et les plugins fonctionnera sans configuration supplémentaire. Si vous souhaitez une configuration différente pour 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 sur defineConfig (définie sur test par défaut) 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. L'extension .json n'est pas prise en charge.

Si vous n'utilisez pas Vite comme outil de build, vous pouvez configurer Vitest avec 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, Vitest en dépend fortement pour son pipeline de transformation. Par conséquent, vous pouvez également configurer n'importe quelle propriété décrite dans la documentation de Vite.

Si vous utilisez déjà Vite, ajoutez la propriété test dans votre 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: {
    // ...
  },
});

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

WARNING

Si vous choisissez 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 remplacera votre fichier Vite, et non l'étendre. Vous pouvez également utiliser la méthode mergeConfig fournie par vite ou vitest/config pour fusionner les configurations de Vite et de 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()],
});

Nous recommandons d'utiliser un seul fichier pour Vite et Vitest plutôt que d'en créer deux distincts.

Prise en charge des espaces de travail

Utilisez Vitest Workspaces pour exécuter différentes configurations de projet dans un même environnement. Vous pouvez définir une liste de fichiers et de dossiers qui définissent votre espace de travail dans le fichier vitest.workspace. 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 (CLI)

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

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

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

En savoir plus sur l'Interface de ligne de commande

Intégrations IDE

Une extension officielle pour Visual Studio Code est disponible pour améliorer votre expérience de test avec Vitest.

Installer depuis VS Code Marketplace

En savoir plus sur les Intégrations IDE

Exemples

Exemple	Source	Playground
basic	GitHub	Play Online
fastify	GitHub	Play Online
lit	GitHub	Play Online
marko	GitHub	Play Online
preact	GitHub	Play Online
react	GitHub	Play Online
solid	GitHub	Play Online
sveltekit	GitHub	Play Online
typecheck	GitHub	Play Online
workspace	GitHub	Play Online

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

Utiliser les commits non publiés

Si vous souhaitez tester les dernières fonctionnalités avant la prochaine version, vous pouvez cloner le référentiel vitest sur votre machine locale, puis le construire et le lier vous-même (pnpm est requis) :

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, accédez au projet où vous utilisez Vitest et 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 besoin d'aide, contactez la communauté sur Discord et GitHub Discussions.