Vitest : installation et premier test

Vitest est un lanceur de tests JavaScript et TypeScript rapide, qui réutilise la configuration de Vite, comprend nativement TypeScript et les modules ES, et propose une API proche de Jest. Les exemples utilisent des noms génériques.

Quand choisir Vitest

Besoin	Outil
Projet Vite, Astro, React, Vue, TypeScript	Vitest
Tests sans dépendance sur un petit projet Node.js	Tests natifs de Node.js
Mocks avancés, snapshots, couverture, composants	Vitest

Prérequis

Node.js récent (voir Node.js : installation). Vitest exige une version LTS actuelle de Node.js et de Vite : la version minimale se lit dans la documentation de la version installée.

Installer

npm install -D vitest
npx vitest --version

Ajouter les scripts dans package.json :

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

Commande	Effet
npx vitest	Mode watch (relance les tests concernés à chaque modification) en développement ; mode run en CI
npx vitest run	Exécute une fois et quitte (CI, hook pre-push)
npx vitest related fichier.ts	Teste seulement ce qui dépend de ces fichiers
npx vitest --ui	Interface web (paquet @vitest/ui)

Premier test

src/somme.ts :

export function somme(...nombres: number[]): number {
  return nombres.reduce((total, n) => total + n, 0);
}

src/somme.test.ts :

import { describe, expect, it } from 'vitest';
import { somme } from './somme';

describe('somme', () => {
  it('additionne plusieurs nombres', () => {
    expect(somme(1, 2, 3)).toBe(6);
  });

  it('renvoie 0 sans argument', () => {
    expect(somme()).toBe(0);
  });
});

npm test

Sortie type :

 ✓ src/somme.test.ts (2 tests) 2ms
   ✓ somme > additionne plusieurs nombres
   ✓ somme > renvoie 0 sans argument

 Test Files  1 passed (1)
      Tests  2 passed (2)

Où placer les tests

Par défaut, Vitest détecte les fichiers *.test.* et *.spec.* (extensions js, ts, jsx, tsx, mjs, cjs…) :

Organisation	Exemple	Quand
À côté du code	src/somme.ts et src/somme.test.ts	Tests unitaires, lecture facile
Dossier séparé	tests/api.test.ts	Tests d’intégration et de bout en bout

Les dossiers node_modules, dist et assimilés sont ignorés. Pour changer : option include / exclude (voir Configuration et intégration continue).

Avec les globales (facultatif)

Par défaut, describe, it et expect s’importent. Pour les rendre globales comme dans Jest :

vitest.config.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: { globals: true },
});

et dans tsconfig.json : "types": ["vitest/globals"]. Préférer les imports explicites : plus clairs et sans configuration de types.

Avec un projet Vite ou Astro

Vitest lit vite.config.* : alias, plugins et variables d’environnement sont partagés avec l’application. Pour un projet Astro, créer un vitest.config.ts basé sur getViteConfig :

import { getViteConfig } from 'astro/config';

export default getViteConfig({
  test: { include: ['src/**/*.test.ts'] },
});

Cette configuration charge les plugins d’Astro (voir Astro : installation et structure). Pour React avec Vite : voir Composants et DOM.

TypeScript

Vitest exécute TypeScript sans compilation préalable (via Vite) mais ne vérifie pas les types : lancer tsc --noEmit ou astro check à part (voir ESLint : installation pour l’analyse du code).

Fichiers de configuration minimaux

vitest.config.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'node',
    include: ['src/**/*.test.ts', 'tests/**/*.test.ts'],
    clearMocks: true,
    restoreMocks: true,
  },
});

Dépannage

Symptôme	Piste
No test files found	Nom ne correspondant pas à *.test.*, ou include trop restrictif
Cannot find package 'vitest'	npm install -D vitest, ou mauvais dossier
ReferenceError: describe is not defined	Pas d’import et globals désactivé
SyntaxError: Cannot use import statement outside a module	Fichier de configuration en CommonJS : renommer en .mts ou type: module
Les tests ne se relancent pas en watch	Fichiers hors du graphe d’import du test, ou limite de surveillance de fichiers de Linux (voir Dépannage)
vitest se bloque en CI	Utiliser vitest run (le mode watch attend)

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Ubuntu : Vitest s’exécute avec Node.js. La version de Node.js dépend de la méthode d’installation (voir Node.js : installation).

Pour aller plus loin

• Documentation : vitest.dev
• Suite : Écrire des tests

Dans la même rubrique

• Installation et premier test
• Écrire des tests
• Mocks, espions et temps
• Composants et DOM
• Couverture et snapshots
• Configuration et intégration continue
• Dépannage