# CLAUDE.md — Responsive Testing avec Playwright MCP

> Contexte spécialisé pour Claude Code. Coller ce fichier à la racine du projet pour automatiser les tests responsive avec Playwright via MCP.

---

## Section 1 : Setup — Playwright MCP dans Claude Code

- Le plugin Playwright MCP expose ces outils directement dans Claude Code :
  - `browser_navigate` — charge une URL dans le navigateur headless
  - `browser_resize` — change les dimensions de la fenêtre
  - `browser_take_screenshot` — capture la page courante (JPEG/PNG)
  - `browser_evaluate` — exécute du JavaScript dans le contexte de la page
  - `browser_snapshot` — dump accessibility tree (utile pour inspecter le DOM)
- Pas besoin d'installer Playwright en local — le MCP gère le navigateur headless
- Pas de `npx playwright install` requis dans le projet
- Le MCP utilise Chromium par défaut

---

## Section 2 : Résolutions cibles

Tester systématiquement dans cet ordre (desktop → mobile) :

| # | Résolution | Contexte |
|---|-----------|---------|
| 1 | 1920×1080 | Desktop large |
| 2 | 1366×768  | Desktop standard (laptop) |
| 3 | 1024×768  | Tablette paysage / petit desktop |
| 4 | 900×700   | Tablette paysage réduite |
| 5 | 768×1024  | Tablette portrait |
| 6 | 480×812   | Mobile grand format |
| 7 | 375×812   | iPhone standard |
| 8 | 320×568   | Mobile petit (iPhone SE) |

Prompt type à donner à Claude : "Teste la page `http://localhost:8000` à toutes les résolutions de la checklist responsive et liste chaque overflow détecté."

---

## Section 3 : Détection overflow

### One-liner JS de détection

```javascript
document.documentElement.scrollWidth > document.documentElement.clientWidth
```

Retourne `true` si la page a un overflow horizontal, `false` sinon.

### Identifier l'élément responsable

```javascript
Array.from(document.querySelectorAll('*')).filter(el => {
  const rect = el.getBoundingClientRect();
  return rect.right > window.innerWidth;
}).map(el => ({
  tag: el.tagName,
  class: el.className,
  id: el.id,
  right: Math.round(rect.right),
  width: Math.round(rect.width)
}));
```

Injecter via `browser_evaluate` pour obtenir la liste des éléments qui débordent.

### Boucle de test complète (pseudo-code pour Claude)

```
Pour chaque résolution dans [1920x1080, 1366x768, 1024x768, 900x700, 768x1024, 480x812, 375x812, 320x568] :
  1. browser_resize(width, height)
  2. browser_navigate(url)  // ou browser_evaluate('window.scrollTo(0,0)') si déjà chargé
  3. overflow = browser_evaluate('document.documentElement.scrollWidth > document.documentElement.clientWidth')
  4. Si overflow == true :
     - browser_take_screenshot()  // capture de preuve
     - éléments = browser_evaluate(one-liner d'identification)
     - noter les éléments fautifs
  5. Passer à la résolution suivante
```

---

## Section 4 : Fix CSS anti-overflow

Appliquer en priorité dans cet ordre :

### 1. Règle globale (toujours en premier)

```css
body {
    overflow-x: hidden;
}
```

Masque le scroll horizontal sans résoudre le problème structurel — utile en dernier recours ou comme filet de sécurité.

### 2. Blocs de code (cause #1 d'overflow sur mobile)

```css
pre {
    white-space: pre-wrap;
    word-break: break-word;
    max-width: 100%;
    overflow-x: auto;  /* scroll interne si le code ne peut pas wrapper */
}
```

### 3. Conteneurs flex

```css
.container-flex {
    flex-wrap: wrap;
}
```

Sans `flex-wrap: wrap`, les enfants flex ne passent pas à la ligne et débordent sur mobile.

### 4. Boutons avec label texte sur mobile

```css
@media (max-width: 480px) {
    .btn-label {
        display: none;
    }
}
```

Garder uniquement l'icône sur petit écran. Appliquer quand les boutons `.btn` + icônes + texte sont alignés horizontalement.

### 5. Headings

```css
h1, h2, h3, h4 {
    text-wrap: balance;    /* répartition équilibrée des mots */
    word-break: break-word; /* évite les mots très longs qui débordent */
}
```

### 6. Images et médias

```css
img, video, iframe, embed, object {
    max-width: 100%;
    height: auto;
}
```

### 7. Tables (cause fréquente sur mobile)

```html
<div class="table-wrapper" style="overflow-x: auto;">
    <table>...</table>
</div>
```

Ne jamais mettre `overflow-x: hidden` sur une table — wrapper avec scroll interne.

---

## Section 5 : Workflow boucle complète

### Prompt type pour Claude Code

```
Teste la page [URL] à ces 8 résolutions : 1920x1080, 1366x768, 1024x768, 900x700, 768x1024, 480x812, 375x812, 320x568.

Pour chaque résolution avec overflow :
1. Prends un screenshot
2. Identifie l'élément responsable avec browser_evaluate
3. Corrige le CSS dans [fichier.css]
4. Reteste la même résolution pour vérifier le fix

Continue jusqu'à zéro overflow sur toutes les résolutions.
```

### Déploiement ciblé pour test en production (~2s par fichier)

```bash
# Upload un seul fichier CSS via lftp
lftp -e "put -O /www/assets/css assets/css/styles.css; quit" ftp://user:pass@host

# Upload blog.css
lftp -e "put -O /www/blog/assets blog/assets/blog.css; quit" ftp://user:pass@host
```

Après upload, relancer le test Playwright sur l'URL de production pour valider.

### Cycle complet

```
resize → navigate → evaluate overflow → [screenshot si overflow] → fix CSS → upload → retest
```

Répéter jusqu'à ce que `evaluate` retourne `false` sur toutes les résolutions.

---

## Section 6 : Checklist finale

- [ ] Zéro overflow (`scrollWidth > clientWidth === false`) sur les 8 résolutions
- [ ] Boutons flex wrappent correctement à 375px et 320px
- [ ] Blocs `<pre><code>` ne créent pas de scroll horizontal (pre-wrap actif)
- [ ] Headings sans mots orphelins (`text-wrap: balance` appliqué)
- [ ] Images ne débordent pas (`max-width: 100%` sur tous les médias)
- [ ] Tables dans un wrapper avec `overflow-x: auto`
- [ ] Screenshots conservés pour chaque résolution validée (preuve)
- [ ] Test sur l'URL de production après deploy, pas seulement en local