Démarrer avec Vitest

Vue d’ensemble

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

Vous pouvez en apprendre davantage sur la logique du projet dans la section Pourquoi Vitest.

Essayer Vitest en ligne

Vous pouvez essayer Vitest en ligne sur StackBlitz. Il exécute Vitest directement dans le navigateur, et il est presque identique à la configuration locale mais ne nécessite aucune installation sur votre machine.

Ajouter Vitest à votre projet

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

Astuce

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 énuméré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 spécifiée. Par défaut, npx vérifiera d’abord si la commande existe dans les binaires du projet local. Si elle n’est pas trouvée là-bas, npx recherchera dans le $PATH du système et l’exécutera si elle est trouvée. Si la commande n’est pas trouvée dans les deux emplacements, npx l’installera dans un emplacement temporaire avant exécution.

Écriture de tests

Comme exemple, nous allons écrire un simple test qui vérifie la sortie d’une fonction qui ajoute 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('ajoute 1 + 2 pour égaler 3', () => {
  expect(sum(1, 2)).toBe(3)
})

Astuce

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

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, et Vitest imprimera ce message :

✓ sum.test.js (1)
  ✓ ajoute 1 + 2 pour égaler 3

Fichiers de test  1 passé (1)
     Tests  1 passé (1)
  Démarré à  02:15:44
  Durée  311ms

Attention

Si vous utilisez Bun comme gestionnaire de paquets, assurez-vous d’utiliser la commande bun run test au lieu de bun test, sinon Bun exécutera son propre exécuteur de tests.

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

Configuration de Vitest

L’un des principaux avantages de Vitest est sa configuration unifiée avec Vite. Si présent, vitest lira votre vite.config.ts racine pour s’aligner sur les plugins et la configuration de votre application Vite. Par exemple, votre configuration resolve.alias et plugins fonctionnera immédiatement. Si vous souhaitez une configuration différente pendant les tests, vous pouvez :

• Créer vitest.config.ts, qui aura une priorité 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 (qui sera définie sur test si non remplacé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 construction, vous pouvez configurer Vitest en utilisant la propriété test dans votre fichier de configuration :

import { defineConfig } from 'vitest/config'

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

Astuce

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 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

Attention

Si vous décidez d’avoir deux fichiers de configuration séparés 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, sans l’étendre. Vous pouvez également utiliser la méthode mergeConfig provenant 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 le même fichier pour Vite et Vitest, au lieu de créer deux fichiers séparés.

Support des espaces de travail

Exécutez différentes configurations de projet à l’intérieur du même projet avec Vitest Workspaces. Vous pouvez définir une liste de fichiers et de dossiers qui définissent votre espace de travail dans le fichier vitest.workspace. Le fichier prend en charge les extensions js/ts/json. Cette fonctionnalité fonctionne très bien avec 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 s'attend à une liste de fichiers de configuration
  // ou de répertoires où il y a 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 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 fichier, utilisez vitest run. Vous pouvez spécifier des options CLI supplémentaires telles que --port ou --https. Pour une liste complète des options CLI, exécutez npx vitest --help dans votre projet.

Pour en savoir plus sur l’Interface en ligne de commande.

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 Marketplace VS Code

Pour en savoir plus sur les intégrations IDE.

Exemples

Exemple	Source	Playground
basic	GitHub	Jouer en ligne
fastify	GitHub	Jouer en ligne
in-source-test	GitHub	Jouer en ligne
lit	GitHub	Jouer en ligne
marko	GitHub	Jouer en ligne
preact	GitHub	Jouer en ligne
react	GitHub	Jouer en ligne
solid	GitHub	Jouer en ligne
sveltekit	GitHub	Jouer en ligne
typecheck	GitHub	Jouer en ligne
workspace	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

Si vous ne pouvez pas attendre une nouvelle version pour tester les dernières fonctionnalités, vous devrez cloner le dépôt 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, allez dans le 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 avez besoin d’aide, rejoignez la communauté sur Discord et GitHub Discussions.