| name | playwright-browser-automation |
| description | Automatisation de navigateur via Playwright MCP — naviguer, cliquer, remplir des formulaires, prendre des captures d'écran et déboguer des pages web. À utiliser quand l'utilisateur veut interagir avec un navigateur, tester une interface ou automatiser des actions web. Se déclenche aussi avec "ouvre cette page", "teste le formulaire", "automatise le navigateur", "capture d'écran de la page", "remplis le formulaire". Also triggers on "Playwright automation", "automate a browser", "fill a form automatically". |
Automatisation Navigateur avec Playwright MCP
Workflow en étapes
1. Naviguer vers la page cible
Toujours commencer par un navigate vers l'URL exacte. Pour les apps locales, préférer 127.0.0.1 à localhost (évite les problèmes DNS).
playwright_navigate: { url: "http://127.0.0.1:3000/login" }
2. Inspecter avant d'interagir
Utiliser snapshot (arbre d'accessibilité) pour identifier les éléments disponibles. Ne jamais deviner un sélecteur.
playwright_snapshot → renvoie les ref= de chaque élément interactif
Snapshot en priorité sur screenshot : plus léger, donne les ref nécessaires aux clics/fill.
3. Interagir avec les éléments
Cliquer sur un bouton/lien
playwright_click: { element: "Connexion", ref: "e12" }
Remplir un formulaire (field par field)
playwright_fill: { element: "Email", ref: "e5", value: "user@example.com" }
playwright_fill: { element: "Mot de passe", ref: "e6", value: "secret" }
playwright_click: { element: "Se connecter", ref: "e9" }
Menu déroulant
playwright_select: { element: "Rôle", ref: "e8", values: ["admin"] }
Raccourci clavier (ex: soumettre avec Entrée)
playwright_press: { element: "champ", ref: "e6", key: "Enter" }
4. Attendre et vérifier
Après une action asynchrone (soumission, navigation, chargement AJAX), faire un nouveau snapshot avant de valider. Ne jamais supposer que le résultat est immédiat.
5. Déboguer si nécessaire
playwright_console_messages → erreurs JS, warnings, logs
playwright_network_requests → appels API, codes HTTP, payloads
playwright_evaluate: { expression: "document.title" } → JS arbitraire
6. Capture d'écran (visuel uniquement)
Réserver aux vérifications d'apparence ou rapports. Pas un substitut au snapshot.
playwright_screenshot: { name: "resultat-apres-login" }
Critères de décision
| Situation | Action |
|---|
| Trouver un élément cliquable | snapshot → lire les ref |
| Vérifier un texte affiché | snapshot → chercher dans l'arbre |
| Bug CSS / rendu visuel | screenshot |
| Erreur JS inexpliquée | console_messages |
| Appel API qui échoue | network_requests |
| Page SPA (React/Vue/Angular) | snapshot après chaque navigation, l'arbre se reconstruit |
| Champ masqué / disabled | JS via evaluate pour forcer la valeur |
Anti-patterns et pièges
Ne jamais faire :
- Utiliser un sélecteur CSS deviné sans snapshot préalable — les
ref changent à chaque reload.
- Enchaîner des actions sans vérifier l'état intermédiaire sur les pages asynchrones.
- Utiliser
screenshot pour "voir ce qu'il y a" à la place du snapshot — 10× plus lent et pas de ref.
- Supposer qu'un formulaire est soumis parce que
click a fonctionné — toujours lire le snapshot suivant.
Pièges fréquents :
| Symptôme | Cause probable | Remède |
|---|
ref introuvable | Page rechargée depuis le dernier snapshot | Refaire un snapshot |
| Champ rempli mais valeur ignorée | Input contrôlé (React) — fill non déclenche pas onChange | Ajouter un press: Tab après le fill |
| Click sans effet visible | Élément hors viewport | evaluate: element.scrollIntoView() puis re-click |
| Timeout navigation | SPA avec routing client-side | Attendre un élément cible plutôt que networkidle |
| Contenu iframe non visible dans snapshot | Iframe cross-origin | Naviguer directement vers l'URL de l'iframe |
Bonnes pratiques 2026
- Playwright MCP expose des outils discrets (
playwright_navigate, playwright_click, etc.) — chaque appel est atomique, pas de session globale à gérer.
- Préférer les localisateurs sémantiques (label, role, text) aux XPath/CSS quand le
ref n'est pas disponible.
- Sur les SPAs : attendre un élément clé (
snapshot + vérifier sa présence) plutôt qu'un délai fixe.
- Pour les tests répétables : noter la séquence
navigate → snapshot → fill/click → snapshot → assert comme pattern de base.
- En cas de CAPTCHA ou 2FA : signaler à l'utilisateur, ne pas tenter de contourner.
- Après un
playwright_close, le contexte navigateur est détruit — relancer navigate pour recommencer.
Dépannage rapide
| Problème | Solution |
|---|
| Navigateur non démarré | Lancer playwright_navigate — le MCP démarre Chromium automatiquement |
| Domaine local inaccessible | Remplacer localhost par 127.0.0.1 |
| Snapshot vide ou tronqué | Naviguer vers une sous-page plus ciblée |
| Éléments introuvables | Refaire snapshot — la page a peut-être rechargé |
CORS sur evaluate | Normal : le JS s'exécute dans le contexte de la page, pas externe |
