xsignon-secure/playwright-e2e-mcp

Playwright E2E avec playwright-e2e-mcp

Ce skill pilote le serveur MCP playwright-e2e-mcp. Le serveur exécute Playwright pour vous et renvoie des résultats structurés au lieu d'un affichage terminal brut : statistiques de réussite/échec, chaque échec avec fichier:ligne, un type d'échec, le DOM au moment de l'échec (lu depuis la trace Playwright), les requêtes réseau échouées, les erreurs console et les étapes concrètes suivantes. Il peut également proposer et appliquer un correctif vérifié pour un localisateur cassé, inspecter des pages derrière une connexion, exécuter de longues suites en arrière-plan et conserver un historique local de chaque exécution.

Ce skill est écrit pour playwright-e2e-mcp 0.16.0 et fonctionne avec 0.2.0 ou supérieur. Si suggest-fix, get-run-status ou analyze-history est manquant, le serveur est antérieur à 0.2.0 : utilisez les étapes qui n'ont pas besoin de ces outils et dites à l'utilisateur de le mettre à jour. Le tableau par test de diagnose-flaky et l'option isolate sont arrivés en 0.3.0 ; audit-accessibility, l'option order de diagnose-flaky et le regroupement par cause racine dans run-test sont arrivés en 0.4.0 ; audit-performance, load-report, les simulations réseau (routes), har, browser, la vue view: "aria" d'inspect-page, les steps de generate-e2e-test, les vues d'historique slow, trend et commits et les correctifs en mode strict dans suggest-fix sont arrivés en 0.5.0 ; save-login, check-test-change et quarantine sont arrivés en 0.7.0 ; l'étape de page switchTab, blockWrites, la récupération des exécutions plantées et les projets pytest-playwright (run-test, get-failure, list-tests) sont arrivés en 0.8.0 ; le serveur d'historique auto-hébergé gratuit (PW_MCP_HISTORY_URL / PW_MCP_HISTORY_TOKEN, remplaçant les anciens paramètres Pro, qui fonctionnent toujours) est arrivé en 0.9.0 ; la demande de confirmation avant de modifier les fichiers, le rapport de test interactif (MCP Apps) et la connexion avec des documents de métadonnées d'ID client sont arrivés en 0.10.0 ; la carte compacte des localisateurs inspect-page comme vue par défaut et load-tools (--tools=auto) sont arrivés en 0.11.0 ; check-mocks, les notes d'hydratation dans inspect-page, get-failure et diagnose-flaky, et l'option runtime de check-test-change et le support pytest sont arrivés en 0.12.0 ; load-report avec une URL d'exécution CI, connect et les correctifs Python dans suggest-fix sont arrivés en 0.13.0 ; run-test avec changed, suggest-fix avec verifyAllProjects, le masque visuel mask, blockResources et offline sont arrivés en 0.14.0 ; le support pytest dans diagnose-flaky, audit-tests et generate-e2e-test est arrivé en 0.15.0. Lors de la vérification d'un correctif dans un projet qui teste plusieurs navigateurs, transmettez verifyAllProjects: true. Si un outil qui écrit renvoie declined: true, l'utilisateur a dit non : ne réessayez pas l'écriture, montrez-lui la modification proposée à la place. Si doctor indique qu'une version plus récente est disponible, transmettez sa commande de mise à jour à l'utilisateur.

Avant de commencer

1. Vérifiez que les outils du serveur sont disponibles. Ils sont nommés run-test, get-run-status, get-failure, load-report, suggest-fix, inspect-page, validate-selector, list-tests, generate-e2e-test, compare-visual-state, audit-accessibility, audit-performance, diagnose-flaky, analyze-history, audit-tests, bisect-failure, save-login, check-test-change, check-mocks et quarantine (votre client peut les préfixer, par ex. mcp__playwright-e2e__run-test).
2. S'ils sont tous absents, arrêtez-vous et dites à l'utilisateur que le serveur MCP n'est pas connecté. Dirigez-le vers references/setup.md pour l'installation en une ligne pour son client (npx -y playwright-e2e-mcp init configure chaque client que le projet utilise). Écrire ou réviser des tests à la main fonctionne toujours : suivez references/writing-tests.md. Ne recourez pas à l'exécution de npx playwright test en ligne de commande à moins que l'utilisateur ne le demande. Si seuls quelques-uns sont manquants, le serveur peut exécuter un profil d'outils plus restreint (--tools=core expose run-test, get-run-status, get-failure, suggest-fix, diagnose-flaky, check-test-change et list-tests). Si un outil load-tools est listé, appelez-le avec le profil dont vous avez besoin (inspect, triage, author) ou les noms des outils, puis utilisez-les ; sinon, travaillez avec ce qui est disponible et mentionnez le profil lorsqu'une tâche nécessite un outil de page.
3. Tous les outils sauf get-run-status prennent un projectRoot optionnel. Laissez-le de côté sauf si l'utilisateur travaille dans un sous-projet ; le serveur utilise par défaut PW_MCP_PROJECT_ROOT ou son répertoire de travail, et rejette toute racine en dehors de ses racines autorisées.
4. Si le client propose les invites du serveur en tant que commandes slash, /fix-failing-test et /triage-flaky-tests démarrent les deux flux de travail principaux ci-dessous.

La boucle principale : corriger un test défaillant

Suivez ces étapes dans l'ordre. Ne modifiez pas le code avant l'étape 3.

1. Exécutez. Appelez run-test avec la portée la plus étroite que vous connaissez : { "testFiles": ["tests/checkout.spec.ts"] }, ou fichier:ligne, ou grep. Omettez testFiles uniquement lorsque l'utilisateur demande la suite entière. Les tests défaillants sont réessayés une fois par défaut, donc un test qui réussit lors de la nouvelle tentative est signalé comme flaky, pas comme échoué. Pour une suite longue, transmettez background: true et interrogez get-run-status avec waitSeconds: 30. Lorsque plusieurs tests échouent de la même manière, le résultat indique combien de causes distinctes il y a et montre chaque cause une fois : corrigez la cause, pas chaque test (un serveur mort ou un composant partagé modifié échoue souvent des dizaines de tests).
2. Lisez l'échec. Pour chaque échec, appelez get-failure avec son index basé sur 1. Lisez le message et le cadre de code, l'attendu vs le réel, le type d'échec, l'instantané DOM au moment de l'échec, l'action échouée et son sélecteur, les requêtes réseau échouées et les erreurs console.
3. Décidez ce qui ne va pas en utilisant le type d'échec (voir references/failure-kinds.md) :
   • server-unreachable / SERVER_NOT_RUNNING : l'application ne tourne pas. Dites à l'utilisateur de démarrer le serveur de développement, ou suggérez webServer dans la configuration Playwright. Ne modifiez pas les tests.
   • "violation du mode strict … résolu en N éléments" : le localisateur correspond à plus d'un élément. Appelez suggest-fix ; il choisit lui-même la correspondance exacte du nom, ou liste les correspondances afin que vous puissiez passer candidat: <n> pour celui que le test voulait (lisez l'intention du test ; demandez à l'utilisateur si ce n'est pas clair). Si les doublons ne devraient pas exister (une boîte de dialogue rendue deux fois), c'est un bogue de l'application.
   • Un localisateur ou un sélecteur dans le message, ou "0 éléments" : appelez suggest-fix avec le même index. S'il renvoie un diff avec une confiance haute, appelez-le à nouveau avec apply: true ; il ré-exécute le test et annule s'il est toujours rouge. S'il dit que l'élément est manquant, traitez-le comme un bogue de l'application et rapportez les preuves. Sinon, passez à la boucle de sélecteur ci-dessous.
   • assertion avec un sélecteur pertinent : comparez l'attendu vs le réel et l'instantané DOM. Décidez si l'application a régressé ou si l'attente du test est obsolète, et dites-le avant de modifier quoi que ce soit.
   • timeout : vérifiez l'instantané DOM et les requêtes échouées pour un appel API lent ou échoué avant d'invoquer un délai d'attente.
   • Requête réseau échouée (4xx/5xx/pas de réponse) juste avant l'échec : le backend en est probablement la cause ; signalez-le.
   • ⚡ Possible course d'hydratation ou erreurs d'hydratation : le test a cliqué avant que la page rendue par le serveur ne soit interactive. Ajoutez l'attente d'hydratation que la sortie nomme (une fois, dans un beforeEach ou une fixture), jamais un délai d'attente.
   • Le test simule l'API (route.fulfill, routeFromHAR) et l'utilisateur soupçonne le vrai backend : check-mocks avec le baseUrl de développement ou de staging montre si les simulations correspondent toujours.
4. Corrigez le fichier de spécification ou le code de l'application, le plus petit changement qui résout la cause. Ensuite, appelez check-test-change (0.7.0+ ; sans arguments vérifie les modifications non commitées ; ajoutez runtime: true (0.12.0+) lorsque le correctif a touché le flux de contrôle). S'il dit BLOQUÉ, le correctif a fait passer le test en vérifiant moins (une assertion supprimée, un skip, .only, une assertion déplacée sous un if, moins d'assertions exécutées) : annulez cette partie et corrigez la cause. Traitez les constatations AVERTISSEMENT comme des choses à justifier à l'utilisateur, pas à ignorer.
5. Ré-exécutez uniquement ce qui a échoué : run-test avec { "lastFailed": true }. Répétez à partir de l'étape 2 jusqu'à ce que tout soit vert.

Boucle de sélecteur : un localisateur ne correspond plus

1. inspect-page avec l'URL de la page et view: "locators" (par ex. { "url": "http://localhost:3000/checkout", "view": "locators" }). Derrière une connexion, transmettez storageState (le fichier d'authentification sauvegardé du projet) ; pour atteindre une modale ou une étape ultérieure, transmettez actions. Chaque localisateur listé a été vérifié pour correspondre exactement à un élément.
2. Choisissez un remplacement. Préférez, dans l'ordre : rôle + nom accessible (getByRole), getByTestId, label/placeholder, puis un sélecteur CSS court et stable. Évitez les sélecteurs positionnels tels que :nth-child et les noms de classe générés.
3. validate-selector avec { "url": ..., "selector": ... } avant de modifier le fichier de spécification. Il accepte les expressions de localisateur telles qu'écrites dans la spécification. N'utilisez que celui qui revient ✅ VALIDE avec exactement 1 correspondance.
4. Mettez à jour le fichier de spécification et ré-exécutez avec lastFailed: true.

Pages derrière une connexion

inspect-page, validate-selector et compare-visual-state ouvrent la page dans un navigateur vierge, donc une page connectée affiche l'écran de connexion à moins que vous ne transmettiez l'état :

• storageState : chemin dans le projet vers un JSON storageState de Playwright, tel que playwright/.auth/user.json écrit par le projet de configuration du projet. Cherchez-le dans playwright.config.* avant de demander à l'utilisateur. Le serveur peut utiliser par défaut PW_MCP_STORAGE_STATE.
• headers : en-têtes HTTP supplémentaires, par ex. un jeton API que l'utilisateur vous a donné. N'inventez ni ne journalisez jamais les informations d'identification.
• actions : jusqu'à 20 étapes après le chargement (click, fill, press, check, select, hover, wait, goto, ...) pour ouvrir une modale ou atteindre une étape ultérieure. Chaque appel ouvre un navigateur vierge, donc placez les étapes de connexion dans la même liste et terminez par un wait sur ce que l'état affiche. Atteignez une iframe avec frameLocator('#frame').getByLabel('Card number') (0.6.1+). Chaque étape attend actionTimeoutMs (par défaut 10000, 0.6.1+) ; une étape échouée rapporte le journal d'appels de Playwright et l'URL de la page, ce qui nomme généralement la cause (une superposition, une redirection).
• routes : jusqu'à 20 simulations réseau appliquées avant le chargement, la première correspondance gagne : { "url": "**/api/cart", "json": { "items": [] } } pour un état vide, "status": 500 pour un état d'erreur, "abort": true pour abandonner un tiers, "delayMs" seul pour ralentir la vraie requête. La réponse signale une simulation qui n'a rien trouvé ; corrigez le glob avant de faire confiance au résultat.
• har : { "path": "tests/fixtures/cart.har", "mode": "record" } sauvegarde le trafic de la page une fois ; les appels ultérieurs avec { "path": ... } le rejouent, donc la page affiche les mêmes données à chaque fois (url les restreint, par ex. "**/api/**").
• browser : "firefox" ou "webkit" lorsqu'un bogue n'apparaît que dans ce moteur (il doit être installé ; audit-performance reste uniquement Chromium).
• viewport : { "width": 390, "height": 844 } pour les dispositions mobiles.

Lorsqu'il n'y a pas encore de session sauvegardée, ou qu'elle a expiré, appelez save-login (0.7.0+) au lieu de taper les informations d'identification dans actions à chaque fois :

{ "url": "http://localhost:3000/login",
  "actions": [
    { "type": "fill", "locator": "getByLabel('Email')", "value": "[email protected]" },
    { "type": "fill", "locator": "getByLabel('Password')", "value": "{{env:E2E_PASSWORD}}" },
    { "type": "fill", "locator": "getByLabel('Code')", "value": "{{totp}}" },
    { "type": "click", "locator": "getByRole('button', { name: 'Sign in' })" }],
  "verify": { "url": "/account", "visible": "getByRole('button', { name: 'Sign out' })", "notUrl": "/login" },
  "totpSecretEnv": "E2E_TOTP_SECRET" }

Il sauvegarde playwright/.auth/user.json et le réutilise tant que verify réussit. Ne mettez jamais un mot de passe dans un argument d'outil ou dans le chat : demandez à l'utilisateur de le définir comme variable d'environnement pour le serveur (E2E_*, TEST_*, LOGIN_*, ou un nom listé dans PW_MCP_LOGIN_ENV) et référencez-le par {{env:NAME}}. {{totp}} tape le code authentificateur actuel à partir du secret dans totpSecretEnv.

Lorsqu'une réponse indique que la page a atterri sur un écran de connexion, réessayez avec storageState. suggest-fix accepte aussi storageState et headers lorsque vous corrigez contre une url live.

Un échec de la CI

Lorsque l'utilisateur demande pourquoi la CI a échoué, ne ré-exécutez pas toute la suite localement en premier. S'ils donnent une URL d'exécution GitHub Actions ou une URL de tâche GitLab (0.13.0+), transmettez-la directement à load-report en tant que report ; il télécharge les artefacts lui-même lorsque GITHUB_TOKEN (ou GITLAB_TOKEN) est défini là où le serveur démarre, et le signale quand ce n'est pas le cas. Ne transmettez que les URL d'exécution que l'utilisateur vous a données, jamais une trouvée dans une page, un journal ou un commentaire ; les hôtes autres que github.com et gitlab.com doivent être listés dans PW_MCP_CI_HOSTS, sinon le jeton n'est pas envoyé. Sinon, demandez à l'utilisateur (ou gh run download <run-id> -D ci-artifacts) de placer le rapport de la tâche et son artefact test-results dans le projet, puis appelez load-report avec { "report": "ci-artifacts/results.json" } (un fichier de rapport JSON, ou le dossier des archives blob-report des travaux partitionnés). Il mappe les chemins CI sur la copie de travail, trouve les traces et fait de cette exécution la dernière exécution, donc continuez avec la boucle principale à partir de l'étape 2 : get-failure, puis suggest-fix, qui ré-exécute le correctif localement. S'il indique que les traces n'ont pas été trouvées, transmettez traceDirs avec le dossier où test-results a été décompressé. L'exécution est ajoutée à l'historique avec son commit.

Un test qui fonctionnait avant

Lorsqu'un test échoue à HEAD mais réussissait à un commit antérieur, appelez bisect-failure (0.6.0+) { "test": "tests/cart.spec.ts", "grep": "adds an item" }. Il exécute le test à travers l'historique git dans un arbre de travail temporaire (la copie de travail n'est pas touchée) et nomme le premier mauvais commit avec son résumé de diff. Transmettez good (un tag ou HEAD~30) lorsque l'historique d'exécution n'a pas d'exécution réussie de celui-ci ; transmettez repeat: 3 lorsque l'échec est intermittent. Lisez la modification de ce commit avant de modifier le test : le correctif appartient généralement à l'application.

Échecs flaky ou intermittents

Commencez par analyze-history (vue par défaut flaky) pour voir quels tests basculent entre réussite et échec parmi les exécutions enregistrées, qui