Vitest : dépannage

Procédure de diagnostic

node --version
npx vitest --version
npx vitest run --reporter=verbose                       # liste chaque test
npx vitest run src/fichier.test.ts                      # un seul fichier
npx vitest run -t "nom du test"                         # un seul test
npx vitest run --no-file-parallelism                    # exécution séquentielle
npx vitest --inspect-brk --no-file-parallelism          # débogueur (puis chrome://inspect)

Lire le premier échec : la trace indique le fichier et la ligne de l’assertion.

Les tests ne sont pas trouvés

Symptôme	Piste
`No test files found, exiting with code 1`	Nom différent de `.test.` / `.spec.`, `include` trop restrictif, mauvais dossier courant
Un fichier précis est ignoré	`exclude`, ou fichier hors des dossiers du projet (`projects`)
`vitest` ne trouve pas le paquet	`npm install`, et `npx vitest` depuis la racine
Rien ne se passe en mode watch	Terminal non interactif : utiliser `vitest run`

Imports, modules et alias

Message	Cause et solution
`Failed to resolve import "…" from …`	Chemin ou alias incorrect : déclarer `resolve.alias` (ou réutiliser la configuration Vite) ; extension et casse du nom de fichier (Linux est sensible à la casse)
`Cannot use import statement outside a module`	Dépendance publiée en CommonJS : `test.server.deps.inline: ['paquet']`
`require is not defined`	Code CommonJS dans un fichier ES : utiliser `import`
`Error [ERR_REQUIRE_ESM]`	Paquet ES chargé avec `require` : charger avec `import`
`Cannot find module './x.js'` en TypeScript	Importer `./x` sans extension, ou configurer la résolution
`SyntaxError: Unexpected token 'export'`	Paquet ES non transformé : `server.deps.inline`
`Unknown file extension ".css"`	`css: true/false` selon le besoin, ou plugin de Vite

Assertions et logique

Symptôme	Piste
`expected … to be …` pour deux objets semblables	`toBe` compare l’identité : `toEqual`
`expect(...).toBeInTheDocument is not a function`	`@testing-library/jest-dom/vitest` dans le fichier de setup
Le test passe sans rien vérifier	Promesse non attendue : `await expect(...).resolves/rejects`
`Test timed out in 5000ms`	Promesse jamais résolue, minuteur simulé non avancé, serveur non fermé
Résultat différent à chaque exécution	Aléatoire, date, ordre non garanti, dépendance entre tests
`Unhandled Rejection` signalée à la fin	Promesse rejetée non attrapée dans le code testé
`Cannot access '…' before initialization` dans `vi.mock`	Variable non hoistée : `vi.hoisted`

Environnement DOM

Symptôme	Piste
`document is not defined` / `window is not defined`	`environment: 'jsdom'` (ou commentaire `// @vitest-environment jsdom`)
`localStorage` partagé entre tests	`localStorage.clear()` dans `beforeEach`
`ResizeObserver is not defined`	Non fourni par jsdom : le simuler (`vi.stubGlobal`)
`matchMedia is not a function`	À simuler dans le fichier de setup
`fetch` absent	Node.js trop ancien ; `vi.stubGlobal('fetch', …)`

Performance et mémoire

Symptôme	Piste
Très lent au démarrage	Gros fichier de setup, environnement `jsdom` partout : `node` par défaut
`JavaScript heap out of memory`	Trop de fichiers en parallèle : `--pool=forks --poolOptions.forks.maxForks=2`, réduire la mémoire utilisée par les tests
Fuites entre fichiers	`isolate: false` avec état global partagé : le réactiver
`ENOSPC: System limit for number of file watchers reached`	Augmenter `fs.inotify.max_user_watches` (voir Configuration et intégration continue)
Mode watch qui relance trop de tests	Utiliser `vitest related`, ou filtrer par nom

Local contre CI

Causes fréquentes d’une différence :

Fuseau horaire : fixer TZ=UTC pour les tests de dates (env: { TZ: 'UTC' }).
Langue : formats de nombres et de dates dépendent des paramètres régionaux (toLocaleString) : les fixer explicitement.
Casse des noms de fichiers (macOS et Windows sont insensibles, Linux non).
Variables d’environnement absentes en CI.
Ordre ou parallélisme : tests qui s’influencent mutuellement.
Ressources : machine plus lente, délais trop courts.

TZ=UTC LANG=fr_FR.UTF-8 npx vitest run

Mises à jour de Vitest

npm outdated vitest
npm install -D vitest@latest @vitest/coverage-v8@latest
npx vitest run

Lire le guide de migration de la version visée (vitest.dev/guide/migration).
Mettre à jour vitest et ses paquets associés (@vitest/coverage-v8, @vitest/ui) ensemble (même version).
Vérifier la compatibilité avec la version de Vite et de Node.js.
Corriger les options renommées (par exemple workspace devenu projects).

Obtenir de l’aide

Réduire le problème à un fichier de test minimal.
Indiquer les versions (npx vitest --version, node --version, npm ls vite).
Chercher le texte exact de l’erreur dans la documentation et le dépôt du projet.

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

Aucune propre à Vitest. Sous Linux, vérifier la casse des noms de fichiers et la limite de surveillance des fichiers pour le mode watch.

Pour aller plus loin

Guide de dépannage, Migration
Retour : Installation et premier test