Écrire des tests unitaires efficaces avec Vitest et Testing Library

Les applications web contemporaines empilent des briques heterogènes : un bundler, un transpiler, un runner, une couche d'assertions sur le DOM. Chaque strate ajoute un paramétrage à maintenir et quelques secondes de latence à chaque boucle de développement. Vitest répond à cette accumulation en s'appuyant sur la chaîne de compilation de Vite, tandis que Testing Library installe une manière de tester l'interface centrée sur ce que la personne utilisatrice perçoit.

Ce duo s'est popularisé pour une raison simple : il rapproche le test unitaire de l'exécution réelle du code. Vitest réutilise la configuration de Vite — alias, plugins, variables d'environnement — et démarre à froid en quelques centaines de millisecondes sur un projet de taille moyenne. Testing Library, de son côté, écarte l'inspection de l'état interne d'un composant et impose de passer par des requêtes fondées sur les rôles, les libellés et les textes visibles.

Les deux outils ne remplacent ni les tests d'intégration ni les parcours de bout en bout : ils les relèvent, en vérifiant vite les décisions unitaires et les interactions de l'interface. Le texte qui suit déroule la mise en place, compare les runners disponibles, détaille les requêtes DOM, les mocks et les horloges simulées, puis se termine sur l'industrialisation de la suite dans la chaîne d'intégration continue.

Prérequis : Node.js 18 ou plus récent, un projet TypeScript ou JavaScript géré avec npm, et une dépendance React, Vue ou Svelte si la cible est le DOM. Aucune connaissance préalable de Jest n'est nécessaire.

Vitest dans une chaîne TypeScript

Vitest est développé par l'équipe qui maintient Vite. Conséquence directe : la transformation des modules passe par le même pipeline que celui du bundler, les alias importés dans vite.config.ts fonctionnent dans les tests sans duplication, et les plugins Vite s'appliquent aux fichiers pris en charge. Le surcoût de configuration se réduit à quelques lignes.

La gestion de TypeScript mérite une nuance. Vitest utilise esbuild pour retirer les annotations de type, ce qui rend les tests très rapides, mais ne vérifie pas la correction typographique. Un contrôle strict relève de tsc --noEmit, à lancer dans une étape dédiée de la CI : les deux commandes se complètent au lieu de se concurrencer.

Pour l'outillage environnant — TypeScript, Node.js, conteneurs, intégration continue — les ressources de DéveloppeurWeb.Com fournissent des repères cohérents avec cette organisation.

Installer et configurer l'environnement de test

L'installation tient en une ligne : npm i -D vitest @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom. La configuration se centralise ensuite dans un fichier dédié, 기 le runner shares the same alias resolution as the application.

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./vitest.setup.ts'],
    coverage: { provider: 'v8', reporter: ['text', 'lcov'] },
  },
})

jsdom simule le DOM avec le plus de fidélité ; happy-dom va plus vite mais couvre moins de cas exotiques. Pour une interface React courante, jsdom reste le choix par défaut. Le fichier d'initialisation welcoming les matchers de @testing-library/jest-dom et déclenchant le nettoyage automatique entre les tests.

Les fixtures ne doivent jamais contenir de vrais secrets : jetons de session, clés de chiffrement ou identifiants utilisateurs. L'implémentation complète d'une application de chat chiffrée avec la Web Crypto API montre comment dériver des clés éphémères et reproductibles, une approche directement transposable à des données de test.

Comparer Vitest, Jest, node:test et Web Test Runner

Le choix du runner dépend de l'historique du projet, de la présence d'une base de code sous Jest et du niveau de fidélité DOM attendu. Le comparatif ci-dessous rassemble les différences structurantes.

Critère Vitest Jest node:test Web Test Runner
Démarrage à froid Très rapide via Vite Plus lent avec Babel ou ts-jest Rapide, natif Coûteux, navigateur réel
Modules ESM Natif Possible, configuration heaviest Natif Natif
DOM jsdom ou happy-dom jsdom Via module tiers Vrai navigateur
Assertions Chai intégré expect maison assert de Node Assertions manuelles
Cibles d'exécution Node, Deno, Bun, navigateur Node principalement Node Navigateurs multiples

La lecture de ce comparatif dépend du contexte. Jest reste la référence la plus documentée pour les bases de code établies, et son coût de démarrage se paie en quelques secondes sur les grands dépôts. node:test s'impose dans une bibliothèque sans interface, où l'absence de dépendance externe compte. Web Test Runner vise la conformité aux standards web, avec un vrai moteur de rendu, au prix d'une lourdeur assumée.

Une migration progressive depuis Jest se fait sans rupture brutale : les matchers de jest-dom fonctionnent sous Vitest, jest.fn() se remplace par vi.fn(), et les codemods Proposal/automatisés accélèrent le renaming des API. Vitest reste le choix par défaut dès lors qu'un projet démarre ou既に utilise Vite.

Interroger le DOM comme une utilisatrice avec Testing Library

La philosophie de Testing Library tient en une phrase : on interroge l'interface comme une personne, pas comme un inspéditeur d'objet. Les requêtes prioritaires sont getByRole, getByLabelText, getByText et getByPlaceholderText. Un data-testid ou un container.querySelector signale presque toujours un couplage excessif avec la structure interne du composant.

Les assertions suivent la même logique : vérifier un rôle, un texte accessible, un état disabled, une présence ou une absence dans le document. Les snapshots restent utiles pour de larges structures stables, mais trop nombreux ils deviennent des miroirs fragiles du rendu.

test('affiche le total après ajout au panier', async () => {
  const user = userEvent.setup()
  render(<Panier articles={fruits} />)

  await user.click(screen.getByRole('button', { name: /ajouter/i }))

  expect(await screen.findByText('3 articles')).toBeInTheDocument()
})

userEvent.setup() reproduit les séquences de clavier, de focus et de frappe, là où fireEvent se contente de dépêcher un événement synthétique. Les requêtes findBy*-awaited couvrent les mises à jour asynchrones, et l'asynchronisation des assertions passe par waitFor plutôt que par des délais fixes.

Mocks, spies et horloges simulées

Vitest fournit trois outils complémentaires : vi.fn() crée une fonction espionnée, vi.spyOn() observe une méthode existante sans la remplacer durablement, et vi.mock() substitue un module entier, avec un mécanisme de hissage qui impose de déclarer la factory avant les imports. Pour les requêtes réseau, Mock Service Worker intercepte au niveau du protocole et se prête mieux à la réutilisation entre tests et environments.

Les horloges se contrôlent de la même manière, ce qui évite les attentes aléatoires :

afterEach(() => {
  vi.useRealTimers()
  vi.restoreAllMocks()
})

it('expire la session après 30 minutes', () => {
  vi.useFakeTimers()
  vi.setSystemTime(new Date('2026-01-01T10:00:00Z'))
  // ...
})

Un mock bien nommé raconte l'intention — onSubmit, fetchProfile, trackEvent — et un test qui en compte quatre ou cinq traduit une règle métier, pas une implémentation. L'image d'une maison hantée bruyante décrit la situation inverse : des simulacres qui hurlent des valeurs arbitraires, des logs verbeux et des assertions qui ne prouvent rien. Une suite lisible ressemble à une pièce calme où chaque objet a sa fonction.

Industrialiser la suite dans la chaîne d'intégration continue

En CI, la commande vitest run --coverage produit un rapport exploitable par les plateformes de build. Les seuils de couverture se déclarent dans la configuration, les reporters junit ou github alimentent les interfaces de fusion de code, et le sharding répartit la suite entre plusieurs machines quand le volume de tests le justifie. Un cache des dépendances et une étape de type-checking séparée complètent l'ensemble.

L'IA ouvre un second chantier : génération de fixtures, échantillonnage de propriétés, détection de cas limites. Des projets comme Hello ML illustrent l'intérêt de corpus versionnés et de pipelines évaluables, quiProvide une matière première reproductible aux tests générés automatiquement. L'humain garde la main sur les scénarios métier, la machine sur l'exploration combinatoire.

Pour suivre ces évolutions au fil des publications, inscrivez-vous au flux RSS de DéveloppeurWeb.Com et à sa newsletter : chaque nouveau guide arrive avec son dépôt d'exemples exécutables, prêt à être cloné. Vos propres retours d'expérience, publiés sur la plateforme, alimentent les guides suivants et font avancer la communauté entière. Commencez par un projet de taille modeste, activez la couverture sur un module critique, mesurez le temps de boucle, puis élargissez progressivement — les tests les plus utiles sont ceux qui restent compétitifs au quotidien.