Coverage Guard
Garantissez une couverture de tests à 100 % pour tout projet JavaScript/TypeScript. Détecte automatiquement l'exécuteur de tests, met en place l'infrastructure si elle est absente, écrit des tests pour les composants non couverts, et boucle jusqu'à ce que chaque fichier atteigne 100 % de couverture.
Aperçu
Cette compétence suit un pipeline complet :
- Détecter l'exécuteur et l'infrastructure → 2. Analyser les fichiers source et les tests → 3. Configurer si nécessaire → 4. Générer de nouveaux tests → 5. Exécuter la couverture → 6. Combler les lacunes → 7. Vérifier → répéter jusqu'à 100 %
Workflow étape par étape
Phase 1 : Détecter l'environnement
Vérifiez package.json à la racine du projet pour déterminer :
cat package.json
Identifiez l'exécuteur de tests et l'outil de couverture :
| Indicateur | Exécuteur | Commande de couverture |
|---|---|---|
"vitest" dans devDependencies | Vitest | npx vitest --coverage |
"jest" dans devDependencies | Jest | npx jest --coverage |
"react-scripts" dans devDependencies | react-scripts (Jest) | npx react-scripts test --coverage |
"next" dans devDependencies | Next.js (Jest) | npx next test --coverage ou vérifier jest.config |
"@angular/core" dans dependencies | Angular (Karma/Jasmine) | ng test --code-coverage |
"@playwright/test" dans devDependencies | Playwright | npx playwright test (pas de couverture intégrée ; utiliser @playwright/test avec istanbul) |
"mocha" dans devDependencies | Mocha | npx mocha (couverture via c8/nyc) |
"cypress" dans devDependencies | Cypress | npx cypress run (couverture via @cypress/code-coverage) |
"ava" dans devDependencies | AVA | npx ava (couverture via c8) |
| Aucun trouvé | Aucun → passer à la Phase 2 → Phase 3 de configuration |
Phase 2 : Analyser les fichiers source et les tests existants
Trouvez tous les fichiers source (composants, modules, utilitaires) qui nécessitent des tests :
# Répertoires source courants
find src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) ! -name "*.test.*" ! -name "*.spec.*" ! -name "*.d.ts" ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/build/*" ! -path "*/.next/*"
Trouvez tous les fichiers de test existants :
find src -type f \( -name "*.test.*" -o -name "*.spec.*" \) ! -path "*/node_modules/*"
Associez chaque fichier source à un fichier de test :
src/components/Button.tsx→src/components/Button.test.tsxousrc/components/__tests__/Button.test.tsxsrc/utils/format.ts→src/utils/format.test.tsousrc/utils/__tests__/format.test.ts- Suivez la convention existante du projet pour l'emplacement des fichiers de test
Classez chaque fichier source :
- A un test → ajouter à la liste d'analyse de couverture
- Pas de test → marquer pour génération de test
Phase 3 : Configurer l'infrastructure de test (si absente)
Si aucun exécuteur de test n'a été détecté à la Phase 1, demandez à l'utilisateur de manière interactive :
? Aucun framework de test détecté. Lequel souhaitez-vous configurer ?
1) Vitest (Recommandé — rapide, moderne, ESM natif)
2) Jest (Le plus utilisé)
3) react-scripts (Create React App)
4) Aucun — ignorer, je le configurerai manuellement
Une fois l'utilisateur sélectionné, installez les dépendances et créez la configuration :
Configuration Vitest :
npm install -D vitest @vitest/coverage-v8
Créez vitest.config.ts :
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
Ajoutez aux scripts package.json :
{
"scripts": {
"test": "vitest",
"test:coverage": "vitest --coverage"
}
}
Configuration Jest :
npm install -D jest @types/jest ts-jest
npx ts-jest config:init
npm install -D jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom
Créez jest.config.ts :
export default {
testEnvironment: 'jsdom',
transform: {
'^.+\\.tsx?$': 'ts-jest',
},
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],
}
Ajoutez aux scripts package.json :
{
"scripts": {
"test": "jest",
"test:coverage": "jest --coverage"
}
}
Configuration react-scripts :
npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event
La couverture est intégrée :
{
"scripts": {
"test": "react-scripts test",
"test:coverage": "react-scripts test --coverage"
}
}
Après la configuration, exécutez un test rapide pour confirmer que tout fonctionne :
npm test
En cas d'échec, corrigez les problèmes de configuration avant de continuer.
Phase 4 : Écrire des tests pour les fichiers source non testés
Pour chaque fichier source qui n'a pas de fichier de test, analysez le code source :
- Lisez le fichier source
- Identifiez :
- Toutes les fonctions, classes, composants exportés
- Les types de retour et les chemins de retour possibles
- Les paramètres et leurs types (obligatoires, optionnels, valeurs par défaut)
- L'interface des props (pour les composants React)
- Le comportement asynchrone (Promesses, async/await)
- Les effets de bord (appels API, localStorage, etc.)
- Les états d'erreur et les cas limites
- Générez le fichier de test en suivant les conventions du projet :
- Utilisez l'API de l'exécuteur de test détecté (
describe/it/expectpour Jest/Vitest, etc.) - Pour React : utilisez
@testing-library/react(render,screen,fireEvent) - Mockez les dépendances externes
- Couvrez toutes les branches, cas limites et chemins d'erreur
- Utilisez l'API de l'exécuteur de test détecté (
Exemple de composant React (src/components/Button.tsx → src/components/Button.test.tsx) :
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Button', () => {
it('affiche avec un label', () => {
render(<Button label="Cliquez-moi" />)
expect(screen.getByText('Cliquez-moi')).toBeInTheDocument()
})
it('appelle onClick lors du clic', () => {
const onClick = vi.fn() // jest.fn() pour Jest
render(<Button label="Cliquer" onClick={onClick} />)
fireEvent.click(screen.getByText('Cliquer'))
expect(onClick).toHaveBeenCalledTimes(1)
})
it('est désactivé quand la prop disabled est true', () => {
render(<Button label="Cliquer" disabled />)
expect(screen.getByText('Cliquer')).toBeDisabled()
})
})
Exemple de fonction utilitaire (src/utils/format.ts → src/utils/format.test.ts) :
import { formatCurrency, truncate } from './format'
describe('formatCurrency', () => {
it('formate un montant entier', () => {
expect(formatCurrency(1000)).toBe('$1,000.00')
})
it('formate un montant décimal', () => {
expect(formatCurrency(99.95)).toBe('$99.95')
})
it('gère zéro', () => {
expect(formatCurrency(0)).toBe('$0.00')
})
it('gère les valeurs négatives', () => {
expect(formatCurrency(-50)).toBe('-$50.00')
})
})
Phase 5 : Exécuter le rapport de couverture
Exécutez la commande de couverture appropriée en fonction de l'exécuteur détecté :
| Exécuteur | Commande |
|---|---|
| Vitest | npx vitest --coverage --reporter=verbose |
| Jest | npx jest --coverage --verbose |
| react-scripts | npx react-scripts test --coverage --watchAll=false |
| Autres | Utilisez la commande de couverture configurée du projet |
Analysez la sortie pour identifier :
- Les fichiers en dessous de 100 % de couverture
- Les lignes, branches, fonctions et instructions non couvertes
- Les numéros de ligne spécifiques qui nécessitent des tests
- Les fichiers avec 0 % de couverture (aucun test existant)
Phase 6 : Analyser et combler les lacunes de couverture
Pour chaque fichier en dessous de 100 % (y compris les fichiers de la Phase 4 qui ont maintenant des tests mais ne sont pas à 100 %) :
- Lisez le fichier source et son fichier de test côte à côte
- Comprenez ce que font les lignes/fonctions/branches non couvertes
- Identifiez les cas limites manquants dans les tests
- Écrivez des tests ciblés pour combler les lacunes :
- Branches non couvertes : Testez les deux chemins
ifetelse, les conditions ternaires - Fonctions non couvertes : Testez tous les chemins de retour possibles
- Lignes non couvertes : Tracez la logique et écrivez un cas qui les atteint
- Chemins asynchrones non couverts : Testez les branches résolues et rejetées des Promesses
- Gestion d'erreurs non couverte : Testez les callbacks d'erreur, les blocs
catch, les limites d'erreur
Utilisez les motifs de l'exécuteur de test détecté :
- Vitest :
vi.mock(),vi.spyOn(),vi.fn() - Jest :
jest.mock(),jest.spyOn(),jest.fn() - react-scripts : Identique à Jest
Phase 7 : Vérifier
Réexécutez la couverture après avoir ajouté/mis à jour les tests :
# Utilisez la commande détectée
npx vitest --coverage # pour Vitest
npx jest --coverage # pour Jest
Confirmez que tous les fichiers affichent 100 % pour les instructions, les branches, les fonctions et les lignes.
Phase 8 : Répéter
Si la couverture est encore en dessous de 100 %, revenez à la Phase 6.
Configuration par exécuteur
Configuration de couverture Vitest
Assurez-vous que vitest.config.ts contient :
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
Configuration de couverture Jest
Assurez-vous que jest.config.ts contient :
export default {
collectCoverage: true,
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: [
'src/**/*.{ts,tsx,js,jsx}',
'!src/**/*.d.ts',
'!src/**/*.test.*',
'!src/**/*.spec.*',
],
}
Conseils
- Commencez par les fichiers qui ont déjà des tests mais une faible couverture — gains les plus rapides
- Attaquez ensuite les fichiers non testés avec la logique la plus simple en premier
- Pour les composants React : testez le rendu, les interactions utilisateur, le rendu conditionnel, les états d'erreur et les états vides/chargement
- Pour les fonctions utilitaires : testez les cas limites (chaînes vides, null/undefined, valeurs aux limites, caractères spéciaux)
- Pour les services API : testez la réponse de succès, la réponse d'erreur, l'état de chargement, le délai d'attente et l'échec réseau
- Si du code mort est trouvé (impossible à couvrir), suggérez de le supprimer ou d'ajouter un commentaire d'exclusion de couverture :
- Vitest/V8 :
/* c8 ignore next */ou/* c8 ignore next 3 */ - Jest/Istanbul :
/* istanbul ignore next */ou/* istanbul ignore if */
- Vitest/V8 :
- Ne modifiez PAS la logique du code source — ajoutez ou mettez à jour uniquement les tests
- Suivez les motifs de test existants du projet (nommage des fichiers, structure des dossiers, style de mocking)
- Pour les fichiers sans aucun test, créez d'abord un fichier de test complet qui couvre tous les chemins principaux, puis itérez
Priorité de détection
Lors de l'analyse des fichiers source, vérifiez dans cet ordre les structures de répertoires courantes :
src/app/(répertoire d'application Next.js)components/lib/utils/server/(Next.js/Node.js)pages/(répertoire de pages Next.js)- Fichiers
*.ts/*.tsxà la racine
Exemple
Utilisateur : "le rapport de couverture montre login.ts à 72 %, corrige-le"
Actions de l'agent :
- Exécute
npx vitest --coverage --reporter=verbose, voit que login.ts a des lignes non couvertes 45-52 (branche d'erreur devalidateEmail) - Lit le code source, comprend que
validateEmaillance une exception pour les emails invalides - Ajoute des cas de test pour les entrées d'email invalides dans
login.test.ts - Réexécute la couverture — login.ts est maintenant à 100 %
Utilisateur : "nous utilisons jest, vérifie la couverture"
- Exécute
npx jest --coverage --verbose, identifie les fichiers non couverts - Trouve
src/components/Header.tsxà 0 % — aucun test n'existe - Lit le code source de Header.tsx, crée
src/components/Header.test.tsx - Réexécute la couverture — Header.tsx est maintenant à 100 %
Utilisateur : "il n'y a pas de configuration de test dans ce projet, ajoute la couverture"
- Détecte qu'aucun exécuteur de test n'est dans package.json
- Demande à l'utilisateur : "Aucun framework de test détecté. Installer Vitest ? (Recommandé)"
- L'utilisateur confirme → installe vitest + @vitest/coverage-v8, crée vitest.config.ts
- Analyse src/, trouve 8 fichiers source, 0 fichiers de test
- Écrit des tests pour les 8 fichiers
- Exécute la couverture — tous à 100 %