tests-guidelines

Compétence de codage pour l'écriture de tests ou le TDD : nouvelles fonctionnalités, corrections de bugs, refactorisations. Applique un développement piloté par les tests avec une couverture de 80 %+ sur les tests unitaires, d'intégration et E2E. Déclenchement sur /tests-guidelines, « tests », « coverage », « test unitaire », « test d'intégration », « TDD ».

Qu'est-ce que tests-guidelines ?

Cette compétence guide le développement piloté par les tests (TDD) afin d'assurer une couverture de code d'au moins 80 % via des tests unitaires, d'intégration et de bout en bout (E2E). Elle détecte automatiquement le lanceur de tests du projet (npm, pnpm, yarn, Bun natif, pytest, go test, cargo test) et applique un flux de travail strict en sept étapes : rédaction des parcours utilisateur, génération des cas de test, exécution en échec (RED), implémentation du code minimal, exécution en succès (GREEN), refactorisation, et vérification de la couverture. La compétence fournit des modèles concrets pour Jest/Vitest, Bun natif, Playwright E2E, ainsi que des exemples de moquage pour Supabase, Redis et OpenAI, et insiste sur l'évitement des erreurs courantes (tests d'implémentation, sélecteurs fragiles, absence d'isolation). Elle est idéale pour Claude Code, Cursor, Codex ou tout agent IA devant garantir la qualité et la maintenabilité du code via une discipline TDD rigoureuse.

Compatible avec✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/orenatobr/tests-guidelines/tree/HEAD/skills/tests-guidelines

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  1. 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 pas npm test.

  2. 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.json scripts.test et les fichiers de test :

    • scripts.test invoque jest / vitest -> exécutez via le gestionnaire de paquets détecté (npm test, pnpm test, yarn test, ou bun run test).
    • scripts.test est bun test, ou les fichiers de test import { 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 ./... et go test -cover ./.... Rust : cargo test.

Matrice de commandes du lanceur :

Lanceur<test><test-watch><coverage><lint>
npmnpm testnpm test -- --watchnpm run test:coveragenpm run lint
pnpmpnpm testpnpm test --watchpnpm test:coveragepnpm lint
yarnyarn testyarn test --watchyarn test:coverageyarn lint
Bun (script exécute jest/vitest)bun run testbun run test --watchbun run test:coveragebun run lint
Bun (natif bun:test)bun testbun test --watchbun test --coveragebun run lint

bun test (le lanceur intégré de Bun) n'est pas la même chose que bun run test (qui exécute le script test de package.json). Choisir le mauvais est une erreur courante – par exemple, invoquer Jest via npx/bun run dans un projet ESM uniquement échoue, tandis que bun test exécute la suite nativement. Confirmez celui que le projet attend avant la porte ROUGE, puis remplacez <test> / <coverage> partout où npm test apparaî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(...) depuis bun:test au lieu de jest.mock(...).
  • Configurez les seuils de couverture dans bunfig.toml sous [test] (par ex. coverageThreshold) plutôt que dans le bloc de configuration Jest coverageThresholds.

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

  1. Écrivez les tests d'abord – Toujours TDD
  2. Une assertion par test – Concentrez-vous sur un seul comportement
  3. Noms de test descriptifs – Expliquez ce qui est testé
  4. Arrange-Act-Assert – Structure de test claire
  5. Mockez les dépendances externes – Isolez les tests unitaires
  6. Testez les cas limites – Null, undefined, vide, grand
  7. Testez les chemins d'erreur – Pas seulement les chemins heureux
  8. Gardez les tests rapides – Tests unitaires < 50 ms chacun
  9. Nettoyez après les tests – Pas d'effets secondaires
  10. 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.

Skills associés