📖 Manuel

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

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 :

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