Tests de composants React avec Vitest et Testing Library

Vitest est un exécuteur de tests rapide, natif de Vite, qui vous semblera familier si vous connaissez Jest — et il s’intègre parfaitement avec React Testing Library pour les tests de comportement des composants. Cette introduction couvre l’installation, un cycle pratique rouge-vert, la structure des fichiers, ainsi que la manière d’informer un agent de codage IA afin qu’il aide plutôt que de générer des résultats inutiles.

1. Configuration du projet

Installez la pile de tests React habituelle en tant que dépendances de développement :

npm install -D vitest jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event

Pour un projet React Vite, informez Vitest sur l’application à l’intérieur de vite.config.ts afin que les alias et les plugins correspondent aux builds en production :

For a Vite React project, add Vitest to vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.ts'],
    globals: true,
  },
})

environment: 'jsdom' fournit des API DOM sans navigateur réel. Un petit fichier de configuration enregistre les matchers jest-dom une fois pour chaque suite :

import '@testing-library/jest-dom/vitest'

Faites passer ce fichier via l’option setupFiles de Vitest afin que des assertions comme toBeInTheDocument et toHaveAccessibleName fonctionnent partout.

2. Flux de travail recommandé

Utilisez une boucle stricte : Fonctionnalité → Test → Mise en œuvre → Vérification → Refactorisation.

1. Comprendre la fonctionnalité — énumérez les comportements visibles pour l’utilisateur et les états importants (chargement, succès, erreur, vide, désactivé). Notez les limites de l’API ou du navigateur qui nécessitent des mocks pour que les tests restent déterministes.
2. Rédiger le test en premier — privilégiez les requêtes de React Testing Library ; vérifiez les résultats que l’utilisateur peut observer, et non l’état privé ; utilisez userEvent pour simuler des clics et de la saisie afin d’obtenir un résultat réaliste.

Mettre en œuvre le minimum — concentrer le code de production sur la résolution des tests qui échouent ; éviter les mécanismes uniquement destinés aux tests ou des éléments internes divulgués, sauf s’il n’existe pas de solution plus propre.

Exécuter des tests ciblés au cours de l’itération afin que les retours soient obtenus en quelques secondes et non en minutes :

npx vitest run src/components/Button.test.tsx

During development:

Mode observation pour le cycle de retours locaux :

npx vitest

Run the full suite

Suite complète via le script npm exposé par votre package.json :

npm test

ou une exécution ponctuelle en style CI sans surveillance :

npx vitest run

Check coverage when appropriate

Cobertura lorsque vous avez besoin de mettre en évidence les branches non testées :

npx vitest run --coverage

Considérer la cobertura comme un guide, et non comme un pourcentage superficiel — privilégier des assertions significatives plutôt que de viser 100 %.

3. Structure des tests

Placer les tests à côté des composants qu’ils protègent :

src/
├── components/
│   ├── LoginForm.tsx
│   └── LoginForm.test.tsx
├── hooks/
│   ├── useUser.ts
│   └── useUser.test.ts
├── pages/
│   ├── Dashboard.tsx
│   └── Dashboard.test.tsx
└── test/
    ├── setup.ts
    └── mocks/

For a component, structure tests around behavior:

Structurez les cas en fonction des résultats utilisateurs plutôt que des noms de méthodes :

describe('LoginForm', () => {
  it('allows a user to submit valid credentials', async () => {
    // arrange
    // act
    // assert
  })

  it('shows validation errors for invalid input', async () => {
    // ...
  })  it('disables submission while logging in', async () => {
    // ...
  })
})

Couvrez le parcours normal, les échecs de validation ainsi que les états désactivés ou en chargement dans des blocs it distincts. Lorsqu’un problème survient, le titre correspondant doit décrire un comportement spécifique. Utilisez les outils d’organisation avec modération ; une configuration clairement lisible vaut mieux que des solutions ingénieuses qui cachent l’intention réelle.

4. Travailler avec un agent de codage IA

4. Vitest-agent prompt

Faites fonctionner l’agent comme un ingénieur senior en tests React : écrivez ou mettez à jour d’abord le test qui échoue, apportez la modification minimale nécessaire, puis vérifiez avec Vitest et effectuez une vérification de type :

npx vitest run <target-test>
npx vitest run
npm run typecheck
npm run lint

Demandez-lui de privilégier les requêtes de la Testing Library (getByRole, findByText) par rapport aux sélecteurs CSS fragiles, d’imiter les limites du réseau plutôt que d’accéder à l’état des composants, et de laisser un bref commentaire lorsque un test décrit une contrainte intentionnelle du produit.

Habitudes de clôture

Gardez la configuration de Vitest partagée avec Vite afin que les alias de chemins et les plugins correspondent à l’environnement de production. Préférez run dans les environnements CI et surveillez les résultats localement. Étendez les suites au fur et à mesure que de nouvelles fonctionnalités sont ajoutées, plutôt que de procéder à une réécriture complète d’un coup. Grâce à ce cycle — tester en premier, implémenter, vérifier — les applications React restent réfactorisables sans ralentir le cycle de feedback alimenté par Vite, qui est à l’origine de l’attrait de Vitest.