Workflow de développement piloté par les tests (TDD)
Cette compétence garantit que tout développement de code suit les principes TDD avec une couverture de tests complète.
Quand activer
- Écriture de nouvelles fonctionnalités
- Correction de bugs
- Refactorisation de code existant
- Ajout de points d'accès API
- Création de nouveaux composants
Principes fondamentaux
1. Tests AVANT le code
Écrivez TOUJOURS les tests d'abord, puis implémentez le code pour les faire passer.
2. Exigences de couverture
- Minimum 80 % de couverture (unitaire + intégration + E2E)
- Tous les cas limites couverts
- Scénarios d'erreur testés
- Conditions aux limites vérifiées
3. Types de tests
Tests unitaires
- Fonctions et utilitaires individuels
- Logique de composant
- Fonctions pures
- Helpers et utilitaires
Tests d'intégration
- Points d'accès API
- Opérations de base de données
- Interactions de service
- Appels API externes
Tests E2E (Playwright)
- Parcours utilisateur critiques
- Workflows complets
- Automatisation du navigateur
- Interactions avec l'interface utilisateur
Étapes du workflow TDD
Étape 0 : Détecter le lanceur de tests
Ne présumez pas npm test. Les commandes dans les étapes et exemples ci-dessous utilisent <test>, <test-watch> et <coverage> comme espaces réservés pour le lanceur réel du projet. Résolvez-les une fois avant de commencer :
-
Trouvez le lanceur du projet. Lisez
package.json(packageManager,scripts.test), le fichier de verrouillage,pyproject.toml/pytest.ini,go.mod,Cargo.toml. La première correspondance l'emporte ; ne présumez pasnpm test. -
Distinguez le gestionnaire de paquets du lanceur de tests. Ce ne sont pas la même chose. Un projet peut utiliser Bun pour installer les dépendances mais exécuter Jest ou Vitest. Inspectez
package.jsonscripts.testet les fichiers de test :scripts.testinvoquejest/vitest-> exécutez via le gestionnaire de paquets détecté (npm test,pnpm test,yarn test, oubun run test).scripts.testestbun test, ou les fichiers de testimport { test, expect } from "bun:test", ou il n'y a pas de configuration jest/vitest mais Bun est présent -> utilisez le lanceur natif de Bun (bun test). Voir Modèle de test natif Bun ci-dessous.- Python :
<test>=pytest,<coverage>=pytest --cov --cov-fail-under=80. Go :go test ./...etgo test -cover ./.... Rust :cargo test.
Matrice de commandes du lanceur :
| Lanceur | <test> | <test-watch> | <coverage> | <lint> |
|---|---|---|---|---|
| npm | npm test | npm test -- --watch | npm run test:coverage | npm run lint |
| pnpm | pnpm test | pnpm test --watch | pnpm test:coverage | pnpm lint |
| yarn | yarn test | yarn test --watch | yarn test:coverage | yarn lint |
| Bun (script exécute jest/vitest) | bun run test | bun run test --watch | bun run test:coverage | bun run lint |
Bun (natif bun:test) | bun test | bun test --watch | bun test --coverage | bun run lint |
bun test(le lanceur intégré de Bun) n'est pas la même chose quebun run test(qui exécute le scripttestdepackage.json). Choisir le mauvais est une erreur courante – par exemple, invoquer Jest vianpx/bun rundans un projet ESM uniquement échoue, tandis quebun testexécute la suite nativement. Confirmez celui que le projet attend avant la porte ROUGE, puis remplacez<test>/<coverage>partout oùnpm testapparaît ci-dessous.
Étape 1 : Rédiger les parcours utilisateur
En tant que [rôle], je veux [action], afin de [bénéfice]
Exemple :
En tant qu'utilisateur, je veux rechercher des marchés de manière sémantique,
afin de trouver des marchés pertinents même sans mots-clés exacts.
Étape 2 : Générer les cas de test
Pour chaque parcours utilisateur, créez des cas de test complets :
describe('Recherche sémantique', () => {
it('renvoie les marchés pertinents pour la requête', async () => {
// Implémentation du test
})
it('gère une requête vide gracieusement', async () => {
// Test de cas limite
})
it('revient à la recherche par sous-chaîne quand Redis est indisponible', async () => {
// Test du comportement de repli
})
it('trie les résultats par score de similarité', async () => {
// Test de la logique de tri
})
})
Étape 3 : Exécuter les tests (ils doivent échouer)
<test>
# Les tests doivent échouer - nous n'avons pas encore implémenté
Étape 4 : Implémenter le code
Écrivez le code minimal pour faire passer les tests :
// Implémentation guidée par les tests
export async function searchMarkets(query: string) {
// Implémentation ici
}
Étape 5 : Exécuter les tests à nouveau
<test>
# Les tests doivent maintenant passer
Étape 6 : Refactoriser
Améliorez la qualité du code tout en gardant les tests verts :
- Supprimez les duplications
- Améliorez le nommage
- Optimisez les performances
- Améliorez la lisibilité
Étape 7 : Vérifier la couverture
<coverage>
# Vérifiez que la couverture de 80 %+ est atteinte
Modèles de test
Modèle de test unitaire (Jest/Vitest)
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Composant Button', () => {
it('affiche le texte correct', () => {
render(<Button>Cliquez-moi</Button>)
expect(screen.getByText('Cliquez-moi')).toBeInTheDocument()
})
it('appelle onClick lors du clic', () => {
const handleClick = jest.fn()
render(<Button onClick={handleClick}>Cliquer</Button>)
fireEvent.click(screen.getByRole('button'))
expect(handleClick).toHaveBeenCalledTimes(1)
})
it('est désactivé quand la propriété disabled est true', () => {
render(<Button disabled>Cliquer</Button>)
expect(screen.getByRole('button')).toBeDisabled()
})
})
Modèle de test natif Bun (bun:test)
Quand le projet utilise le lanceur intégré de Bun (voir Étape 0), importez depuis bun:test et exécutez avec bun test – pas avec bun run test. L'API ressemble à Jest, donc describe / it / expect et la plupart des matchers fonctionnent.
import { describe, it, expect, mock } from 'bun:test'
import { searchMarkets } from './search'
describe('searchMarkets', () => {
it('renvoie une liste vide pour une requête vide', async () => {
expect(await searchMarkets('')).toEqual([])
})
it('trie les résultats par score de similarité', async () => {
const results = await searchMarkets('election')
expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
})
})
bun test # exécution unique (porte ROUGE/VERTE)
bun test --watch # mode watch pendant le développement
bun test --coverage # rapport de couverture
- Mockez les modules avec
mock.module(...)/mock(...)depuisbun:testau lieu dejest.mock(...). - Configurez les seuils de couverture dans
bunfig.tomlsous[test](par ex.coverageThreshold) plutôt que dans le bloc de configuration JestcoverageThresholds.
Modèle de test d'intégration API
import { NextRequest } from 'next/server'
import { GET } from './route'
describe('GET /api/markets', () => {
it('renvoie les marchés avec succès', async () => {
const request = new NextRequest('http://localhost/api/markets')
const response = await GET(request)
const data = await response.json()
expect(response.status).toBe(200)
expect(data.success).toBe(true)
expect(Array.isArray(data.data)).toBe(true)
})
it('valide les paramètres de requête', async () => {
const request = new NextRequest('http://localhost/api/markets?limit=invalid')
const response = await GET(request)
expect(response.status).toBe(400)
})
it('gère les erreurs de base de données gracieusement', async () => {
// Mock d'échec de base de données
const request = new NextRequest('http://localhost/api/markets')
// Test de gestion d'erreur
})
})
Modèle de test E2E (Playwright)
import { test, expect } from '@playwright/test'
test('l'utilisateur peut rechercher et filtrer les marchés', async ({ page }) => {
// Naviguer vers la page des marchés
await page.goto('/')
await page.click('a[href="/markets"]')
// Vérifier le chargement de la page
await expect(page.locator('h1')).toContainText('Marchés')
// Rechercher des marchés
await page.fill('input[placeholder="Rechercher des marchés"]', 'élection')
// Attendre le debounce et les résultats
await page.waitForTimeout(600)
// Vérifier l'affichage des résultats
const results = page.locator('[data-testid="market-card"]')
await expect(results).toHaveCount(5, { timeout: 5000 })
// Vérifier que les résultats contiennent le terme de recherche
const firstResult = results.first()
await expect(firstResult).toContainText('élection', { ignoreCase: true })
// Filtrer par statut
await page.click('button:has-text("Actif")')
// Vérifier les résultats filtrés
await expect(results).toHaveCount(3)
})
test('l'utilisateur peut créer un nouveau marché', async ({ page }) => {
// Se connecter d'abord
await page.goto('/tableau-de-bord-createur')
// Remplir le formulaire de création de marché
await page.fill('input[name="name"]', 'Marché de test')
await page.fill('textarea[name="description"]', 'Description de test')
await page.fill('input[name="endDate"]', '2025-12-31')
// Soumettre le formulaire
await page.click('button[type="submit"]')
// Vérifier le message de succès
await expect(page.locator('text=Marché créé avec succès')).toBeVisible()
// Vérifier la redirection vers la page du marché
await expect(page).toHaveURL(/\/markets\/marche-de-test/)
})
Organisation des fichiers de test
src/
├── components/
│ ├── Button/
│ │ ├── Button.tsx
│ │ ├── Button.test.tsx # Tests unitaires
│ │ └── Button.stories.tsx # Storybook
│ └── MarketCard/
│ ├── MarketCard.tsx
│ └── MarketCard.test.tsx
├── app/
│ └── api/
│ └── markets/
│ ├── route.ts
│ └── route.test.ts # Tests d'intégration
└── e2e/
├── markets.spec.ts # Tests E2E
├── trading.spec.ts
└── auth.spec.ts
Moquage des services externes
Mock Supabase
jest.mock('@/lib/supabase', () => ({
supabase: {
from: jest.fn(() => ({
select: jest.fn(() => ({
eq: jest.fn(() => Promise.resolve({
data: [{ id: 1, name: 'Marché de test' }],
error: null
}))
}))
}))
}
}))
Mock Redis
jest.mock('@/lib/redis', () => ({
searchMarketsByVector: jest.fn(() => Promise.resolve([
{ slug: 'marche-de-test', similarity_score: 0.95 }
])),
checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
}))
Mock OpenAI
jest.mock('@/lib/openai', () => ({
generateEmbedding: jest.fn(() => Promise.resolve(
new Array(1536).fill(0.1) // Mock d'embedding 1536 dimensions
))
}))
Vérification de la couverture de tests
Exécuter le rapport de couverture
<coverage>
Seuils de couverture
{
"jest": {
"coverageThresholds": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
}
Erreurs de test courantes à éviter
ÉCHEC : MAUVAIS : Tester les détails d'implémentation
// Ne testez pas l'état interne
expect(component.state.count).toBe(5)
RÉUSSI : CORRECT : Tester le comportement visible par l'utilisateur
// Testez ce que les utilisateurs voient
expect(screen.getByText('Compteur : 5')).toBeInTheDocument()
ÉCHEC : MAUVAIS : Sélecteurs fragiles
// Se casse facilement
await page.click('.css-class-xyz')
RÉUSSI : CORRECT : Sélecteurs sémantiques
// Résilient aux changements
await page.click('button:has-text("Soumettre")')
await page.click('[data-testid="submit-button"]')
ÉCHEC : MAUVAIS : Pas d'isolation des tests
// Les tests dépendent les uns des autres
test('crée un utilisateur', () => { /* ... */ })
test('met à jour le même utilisateur', () => { /* dépend du test précédent */ })
RÉUSSI : CORRECT : Tests indépendants
// Chaque test met en place ses propres données
test('crée un utilisateur', () => {
const user = createTestUser()
// Logique du test
})
test('met à jour un utilisateur', () => {
const user = createTestUser()
// Logique de mise à jour
})
Tests continus
Mode Watch pendant le développement
<test-watch>
# Les tests s'exécutent automatiquement lors des modifications de fichiers
Hook Pre-Commit
# S'exécute avant chaque commit
<test> && <lint>
Intégration CI/CD
# GitHub Actions
- name: Exécuter les tests
run: <coverage>
- name: Téléverser la couverture
uses: codecov/codecov-action@v3
Meilleures pratiques
- Écrivez les tests d'abord – Toujours TDD
- Une assertion par test – Concentrez-vous sur un seul comportement
- Noms de test descriptifs – Expliquez ce qui est testé
- Arrange-Act-Assert – Structure de test claire
- Mockez les dépendances externes – Isolez les tests unitaires
- Testez les cas limites – Null, undefined, vide, grand
- Testez les chemins d'erreur – Pas seulement les chemins heureux
- Gardez les tests rapides – Tests unitaires < 50 ms chacun
- Nettoyez après les tests – Pas d'effets secondaires
- Revoyez les rapports de couverture – Identifiez les lacunes
Métriques de succès
- 80 %+ de couverture de code atteinte
- Tous les tests passent (verts)
- Aucun test ignoré ou désactivé
- Exécution rapide des tests (< 30 s pour les tests unitaires)
- Les tests E2E couvrent les flux utilisateur critiques
- Les tests attrapent les bugs avant la production
Rappelez-vous : Les tests ne sont pas optionnels. Ils sont le filet de sécurité qui permet une refactorisation en confiance, un développement rapide et une fiabilité en production.