Test bridge

SpecKit Test Bridge — Spec → Playwright Agents

Objectif

Fermer la boucle entre les spécifications (spec.md) et les tests E2E en exploitant Playwright Agents (v1.56+).

Workflow :

spec.md (AS1.1, AS2.1...)
    ↓ speckit-test-bridge
specs/<feature>.md (format Planner)
    ↓ Playwright Generator Agent
tests/e2e/<feature>.spec.ts (tests standards)

Prérequis

• Playwright v1.56+ installé
• Agent definitions initialisées (npx playwright init-agents --loop=claude)
• Un fichier spec.md existant avec des Acceptance Scenarios (format SpecKit)
• seed.spec.ts configuré pour l'app

Phase 1 : Extraction des Acceptance Scenarios

Entrée

Le fichier spec.md de la feature, qui contient des Acceptance Scenarios au format :

**AS1.1** : L'utilisateur peut créer un post avec titre et contenu
**AS1.2** : Le système rejette un post sans titre

Action

1. Lire le fichier spec.md de la feature
2. Extraire TOUS les Acceptance Scenarios (pattern : AS\d+\.\d+)
3. Pour chaque AS, extraire :
   • L'identifiant (AS1.1)
   • La description
   • Les pré-conditions (si mentionnées)
   • Le résultat attendu
4. Lister les AS trouvés et demander confirmation à l'utilisateur

Phase 2 : Génération des specs Playwright

Format de sortie

Créer specs/<feature-name>.md au format compatible Planner Playwright :

# Test Plan: <Feature Name>
> Source: specs/<feature>/spec.md
> Generated by: speckit-test-bridge

## Scenario: AS1.1 — <description>
**Preconditions:** <user logged in, specific data exists, etc.>

### Steps:
1. Navigate to <url>
2. Fill "<field label>" with "<value>"
3. Click "<button label>"
4. Verify "<expected text>" is visible

### Expected Outcome:
- <assertion 1>
- <assertion 2>

---

## Scenario: AS1.2 — <description>
...

Règles

• Utiliser des locators sémantiques (getByRole, getByLabel, getByText) dans les descriptions
• Chaque scenario DOIT avoir au moins 2 assertions (expected outcomes)
• Les pré-conditions doivent être explicites (état auth, données nécessaires)
• Annoter chaque scenario avec son identifiant AS pour la traçabilité

Phase 3 : Génération des tests (optionnel)

Si l'utilisateur le demande, lancer le Generator Agent :

claude "Use the generator agent to create tests from specs/<feature-name>.md"

Post-génération

1. Vérifier que les tests générés compilent (npx playwright test --list)
2. Ajouter les annotations de traçabilité dans les tests :

test('AS1.1: User can create a post', async ({ page }) => {
  test.info().annotations.push({
    type: 'spec-ref',
    description: 'specs/<feature>/spec.md#AS1.1'
  });
  // ... test code
});

3. Vérifier que chaque AS a un test correspondant

Phase 4 : Gap Analysis

Vérification de traçabilité

1. Lister tous les AS extraits de spec.md
2. Lister tous les spec-ref annotations dans tests/e2e/
3. Identifier les gaps :
   • AS sans test → MANQUANT (action requise)
   • Test sans AS → ORPHELIN (à vérifier)
4. Générer un rapport :

## Test Traceability Report — <Feature>

| AS | Description | Test | Status |
|----|-------------|------|--------|
| AS1.1 | Create post | tests/e2e/posts.spec.ts:12 | ✅ COVERED |
| AS1.2 | Reject empty title | — | ❌ MISSING |
| — | Orphan test | tests/e2e/posts.spec.ts:45 | ⚠️ ORPHAN |

**Coverage:** 3/5 AS covered (60%)
**Action required:** Generate tests for AS1.2, AS2.3

Phase 5 : Mise à jour des tests existants

Quand une feature est modifiée (nouveau spec.md) :

1. Re-exécuter Phase 1-4
2. Identifier les nouveaux AS non couverts
3. Identifier les AS supprimés dont les tests doivent être retirés
4. Lancer le Generator pour les nouveaux AS
5. Lancer le Healer si des tests existants échouent après la modification

Intégration dans le workflow SpecKit

Cette skill s'insère dans le workflow principal :

/speckit-specify   → spec.md avec Acceptance Scenarios
/speckit-plan      → plan.md
/speckit-tasks     → tasks.md + sous-stories
/speckit-test-bridge → specs/*.md + tests/e2e/*.spec.ts  ← ICI
/speckit-convert   → prd.json (inclut les tests comme acceptance criteria)
/ralph-loop        → implémentation + vérification

Commandes

# Générer les specs Playwright depuis un spec.md
/speckit-test-bridge specs/posts/spec.md

# Avec génération automatique des tests
/speckit-test-bridge specs/posts/spec.md --generate

# Gap analysis uniquement (pas de génération)
/speckit-test-bridge specs/posts/spec.md --check-only

# Mise à jour après modification de feature
/speckit-test-bridge specs/posts/spec.md --update

Règles importantes

1. Ne JAMAIS skip cette étape pour les features avec UI — chaque AS doit avoir un test
2. Minimum 2 assertions par test — le volume ne fait pas la qualité
3. Traçabilité obligatoire — chaque test DOIT avoir une annotation spec-ref
4. Locators sémantiques — getByRole, getByLabel, getByText (jamais CSS/XPath)
5. Seed file requis — tests/e2e/seed.spec.ts doit exister et fonctionner