---
name: speckit-test-bridge
description: Pont entre les Acceptance Scenarios SpecKit et Playwright Agents. Convertit les AS de spec.md en specs Markdown compatibles Planner, lance le Generator, et vérifie la traçabilité spec→test. Utiliser après speckit-tasks pour garantir que chaque scenario d'acceptation a un test E2E correspondant.
effort: medium
---

# 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 :
```markdown
**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 :

```markdown
# 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 :
```typescript
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 :

```markdown
## 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

```bash
# 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