xsignon-secure/playwright-e2e-mcp

Playwright E2E mit playwright-e2e-mcp

Dieses Skill steuert den playwright-e2e-mcp MCP-Server. Der Server führt Playwright für Sie aus und gibt strukturierte Ergebnisse anstelle roher Terminalausgaben zurück: Bestehen/Fehlschlagen-Statistiken, jeder Fehlschlag mit Datei:Zeile, eine Fehlerart, das DOM zum Zeitpunkt des Fehlschlags (aus dem Playwright-Trace gelesen), fehlgeschlagene Netzwerkanfragen, Konsolenfehler und konkrete nächste Schritte. Es kann auch eine verifizierte Korrektur für einen defekten Selektor vorschlagen und anwenden, Seiten hinter einem Login inspizieren, lange Testläufe im Hintergrund ausführen und eine lokale Historie jedes Laufs führen.

Dieses Skill ist für playwright-e2e-mcp 0.16.0 geschrieben und funktioniert mit 0.2.0 oder neuer. Wenn suggest-fix, get-run-status oder analyze-history fehlt, ist der Server älter als 0.2.0: Verwenden Sie die Schritte, die diese Werkzeuge nicht benötigen, und sagen Sie dem Benutzer, er solle es aktualisieren. diagnose-flakys Pro-Test-Tabelle und die isolate-Option kamen in 0.3.0; audit-accessibility, diagnose-flakys order-Option und Ursachengruppierung in run-test kamen in 0.4.0; audit-performance, load-report, Netzwerk-Mocks (routes), har, browser, inspect-pages view: "aria", generate-e2e-tests steps, die slow-, trend- und commits-Historienansichten und Strict-Mode-Korrekturen in suggest-fix kamen in 0.5.0; save-login, check-test-change und quarantine kamen in 0.7.0; der switchTab-Seitenschritt, blockWrites, Wiederherstellung abgestürzter Läufe und pytest-playwright-Projekte (run-test, get-failure, list-tests) kamen in 0.8.0; der kostenlose selbst gehostete History-Server (PW_MCP_HISTORY_URL / PW_MCP_HISTORY_TOKEN, ersetzt die alten Pro-Einstellungen, die noch funktionieren) kam in 0.9.0; Fragen vor dem Ändern von Dateien, der interaktive Testbericht (MCP Apps) und die Anmeldung mit Client-ID-Metadaten-Dokumenten kamen in 0.10.0; die kompakte inspect-page-Selektorenkarte als Standardansicht und load-tools (--tools=auto) kamen in 0.11.0; check-mocks, die Hydrationshinweise in inspect-page, get-failure und diagnose-flaky, und check-test-changes runtime-Option und pytest-Unterstützung kamen in 0.12.0; load-report mit einer CI-Lauf-URL, connect und Python-Korrekturen in suggest-fix kamen in 0.13.0; run-test changed, suggest-fix verifyAllProjects, visuelles mask, blockResources und offline kamen in 0.14.0; pytest-Unterstützung in diagnose-flaky, audit-tests und generate-e2e-test kam in 0.15.0. Wenn Sie eine Korrektur in einem Projekt überprüfen, das mehrere Browser testet, übergeben Sie verifyAllProjects: true. Wenn ein Werkzeug, das schreibt, declined: true zurückgibt, hat der Benutzer nein gesagt: Wiederholen Sie den Schreibvorgang nicht, zeigen Sie stattdessen die vorgeschlagene Änderung. Wenn doctor sagt, dass eine neuere Version verfügbar ist, leiten Sie das Upgrade-Kommando an den Benutzer weiter.

Bevor Sie beginnen

1. Stellen Sie sicher, dass die Werkzeuge des Servers verfügbar sind. Sie heißen 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 und quarantine (Ihr Client kann ihnen ein Präfix voranstellen, z.B. mcp__playwright-e2e__run-test).
2. Wenn alle fehlen, stoppen Sie und teilen Sie dem Benutzer mit, dass der MCP-Server nicht verbunden ist. Verweisen Sie ihn auf references/setup.md für die einzeilige Installation für seinen Client (npx -y playwright-e2e-mcp init richtet jeden vom Projekt verwendeten Client ein). Das manuelle Schreiben oder Überprüfen von Tests funktioniert trotzdem: Befolgen Sie references/writing-tests.md. Fallen Sie nicht darauf zurück, npx playwright test per Shell auszuführen, es sei denn, der Benutzer fordert es ausdrücklich. Wenn nur einige fehlen, läuft der Server möglicherweise mit einem schlankeren Werkzeugprofil (--tools=core stellt run-test, get-run-status, get-failure, suggest-fix, diagnose-flaky, check-test-change und list-tests bereit). Wenn ein load-tools-Werkzeug aufgeführt ist, rufen Sie es mit dem benötigten Profil (inspect, triage, author) oder den Werkzeugnamen auf, dann verwenden Sie diese; arbeiten Sie andernfalls mit dem, was vorhanden ist, und erwähnen Sie das Profil, wenn eine Aufgabe ein Seitenwerkzeug benötigt.
3. Jedes Werkzeug außer get-run-status akzeptiert ein optionales projectRoot. Lassen Sie es weg, es sei denn, der Benutzer arbeitet in einem Unterprojekt; der Server verwendet standardmäßig PW_MCP_PROJECT_ROOT oder sein Arbeitsverzeichnis und lehnt jedes Wurzelverzeichnis außerhalb seiner erlaubten Wurzeln ab.
4. Wenn der Client die Eingabeaufforderungen des Servers als Slash-Befehle anbietet, starten /fix-failing-test und /triage-flaky-tests die beiden Haupt-Workflows unten.

Der Kernkreislauf: Korrigieren eines fehlschlagenden Tests

Befolgen Sie diese Schritte in der angegebenen Reihenfolge. Bearbeiten Sie keinen Code vor Schritt 3.

1. Ausführen. Rufen Sie run-test mit dem engsten bekannten Umfang auf: { "testFiles": ["tests/checkout.spec.ts"] }, oder datei:zeile, oder grep. Lassen Sie testFiles nur weg, wenn der Benutzer die gesamte Testsuite wünscht. Fehlschlagende Tests werden standardmäßig einmal wiederholt, sodass ein beim Wiederholen bestehender Test als flaky gemeldet wird, nicht als fehlgeschlagen. Bei einer langen Suite übergeben Sie background: true und fragen Sie get-run-status mit waitSeconds: 30 ab. Wenn mehrere Tests auf dieselbe Weise fehlschlagen, sagt das Ergebnis, wie viele verschiedene Ursachen es gibt und zeigt jede Ursache einmal: Korrigieren Sie die Ursache, nicht jeden Test (ein toter Server oder eine geänderte gemeinsam genutzte Komponente bringt oft Dutzende von Tests zum Scheitern).
2. Den Fehler lesen. Rufen Sie für jeden Fehlschlag get-failure mit seinem 1-basierten index auf. Lesen Sie die Nachricht und den Code-Ausschnitt, Erwartet vs. Tatsächlich, die Fehlerart, den DOM-Schnappschuss zum Zeitpunkt des Fehlschlags, die fehlgeschlagene Aktion und ihren Selektor, fehlgeschlagene Netzwerkanfragen und Konsolenfehler.
3. Entscheiden, was falsch ist anhand der Fehlerart (siehe references/failure-kinds.md):
   • server-unreachable / SERVER_NOT_RUNNING: Die Anwendung läuft nicht. Sagen Sie dem Benutzer, er solle den Entwicklungsserver starten, oder schlagen Sie webServer in der Playwright-Konfiguration vor. Bearbeiten Sie keine Tests.
   • "strict mode violation … resolved to N elements": Der Selektor passt auf mehr als ein Element. Rufen Sie suggest-fix auf; es wählt selbst die exakte Namensübereinstimmung oder listet die Übereinstimmungen auf, sodass Sie candidate: <n> für das vom Test gemeinte übergeben können (lesen Sie die Absicht des Tests; fragen Sie den Benutzer, wenn es unklar ist). Wenn die Duplikate nicht existieren sollten (ein Dialog zweimal gerendert), handelt es sich um einen Anwendungsfehler.
   • Ein Selektor in der Nachricht oder "0 elements": Rufen Sie suggest-fix mit demselben index auf. Wenn es einen Diff mit high-Konfidenz zurückgibt, rufen Sie es erneut mit apply: true auf; es führt den Test erneut aus und macht die Änderung rückgängig, wenn er immer noch rot ist. Wenn es sagt, dass das Element fehlt, behandeln Sie es als Anwendungsfehler und melden Sie die Beweise. Andernfalls gehen Sie zur Selektorschleife unten.
   • assertion mit einem sinnvollen Selektor: Vergleichen Sie Erwartet vs. Tatsächlich und den DOM-Schnappschuss. Entscheiden Sie, ob die Anwendung eine Regression hat oder die Test-Erwartung veraltet ist, und sagen Sie dies, bevor Sie etwas ändern.
   • timeout: Überprüfen Sie den DOM-Schnappschuss und die fehlgeschlagenen Anfragen auf einen langsamen oder fehlgeschlagenen API-Aufruf, bevor Sie eine Zeitüberschreitung in Betracht ziehen.
   • Fehlgeschlagene Netzwerkanfrage (4xx/5xx/keine Antwort) unmittelbar vor dem Fehlschlag: Das Backend ist die wahrscheinliche Ursache; melden Sie es.
   • ⚡ Possible hydration race oder Hydrationsfehler: Der Test hat geklickt, bevor die serverseitig gerenderte Seite interaktiv war. Fügen Sie den Hydrations-Wartevorgang hinzu, den die Ausgabe nennt (einmal, in einem beforeEach oder Fixture), niemals eine Zeitüberschreitung.
   • Der Test mocked die API (route.fulfill, routeFromHAR) und der Benutzer vermutet das echte Backend: check-mocks mit der Entwicklungs- oder Staging-baseUrl zeigt, ob die Mocks noch damit übereinstimmen.
4. Korrigieren Sie den Test- oder den Anwendungscode, die kleinste Änderung, die die Ursache behebt. Rufen Sie dann check-test-change auf (0.7.0+; keine Argumente prüft die nicht committeten Änderungen; fügen Sie runtime: true (0.12.0+) hinzu, wenn die Korrektur den Kontrollfluss geändert hat). Wenn es BLOCK sagt, hat die Korrektur den Test bestanden, indem sie weniger geprüft hat (eine gelöschte Assertion, ein Skip, .only, eine Assertion unter ein if verschoben, weniger ausgeführte Assertionen): Machen Sie diesen Teil rückgängig und korrigieren Sie die Ursache. Behandeln Sie WARN-Ergebnisse als Dinge, die Sie dem Benutzer rechtfertigen, nicht als Durchwinken.
5. Nur das Fehlgeschlagene erneut ausführen: run-test mit { "lastFailed": true }. Wiederholen Sie ab Schritt 2, bis alles grün ist.

Selektorschleife: Ein Selektor passt nicht mehr

1. inspect-page mit der Seiten-URL und view: "locators" (z.B. { "url": "http://localhost:3000/checkout", "view": "locators" }). Hinter einem Login übergeben Sie storageState (die gespeicherte Auth-Datei des Projekts); um einen modalen Dialog oder einen späteren Schritt zu erreichen, übergeben Sie actions. Jeder aufgeführte Selektor wurde überprüft, um genau ein Element zu finden.
2. Wählen Sie einen Ersatz. Bevorzugen Sie, in der Reihenfolge: Rolle + zugänglicher Name (getByRole), getByTestId, Label/Platzhalter, dann einen kurzen stabilen CSS-Selektor. Vermeiden Sie positionsbasierte Selektoren wie :nth-child und generierte Klassennamen.
3. validate-selector mit { "url": ..., "selector": ... } vor dem Bearbeiten des Tests. Es akzeptiert Selektorausdrücke, wie sie im Test geschrieben sind. Verwenden Sie nur einen, der als ✅ VALID mit genau 1 Übereinstimmung zurückkommt.
4. Aktualisieren Sie den Test und führen Sie ihn mit lastFailed: true erneut aus.

Seiten hinter einem Login

inspect-page, validate-selector und compare-visual-state öffnen die Seite in einem frischen Browser, daher zeigt eine angemeldete Seite den Anmeldebildschirm, es sei denn, Sie übergeben einen Zustand:

• storageState: Pfad innerhalb des Projekts zu einem Playwright storageState-JSON, z.B. playwright/.auth/user.json, geschrieben vom Setup-Projekt des Projekts. Suchen Sie danach in playwright.config.*, bevor Sie den Benutzer fragen. Der Server kann auf PW_MCP_STORAGE_STATE zurückgreifen.
• headers: Zusätzliche HTTP-Header, z.B. ein API-Token, das der Benutzer gegeben hat. Erfinden oder protokollieren Sie niemals Anmeldeinformationen.
• actions: Bis zu 20 Schritte nach dem Laden (click, fill, press, check, select, hover, wait, goto, ...), um einen modalen Dialog zu öffnen oder einen späteren Schritt zu erreichen. Jeder Aufruf öffnet einen frischen Browser, also setzen Sie die Anmeldeschritte in dieselbe Liste und enden Sie mit einem wait auf das, was der Zustand anzeigt. Greifen Sie in einen iFrame mit frameLocator('#frame').getByLabel('Card number') (0.6.1+). Jeder Schritt wartet actionTimeoutMs (Standard 10000, 0.6.1+); ein fehlgeschlagener Schritt meldet Playwrights Aufrufprotokoll und die Seiten-URL, die normalerweise die Ursache nennen (ein Overlay, eine Weiterleitung).
• routes: Bis zu 20 Netzwerk-Mocks, die vor dem Laden angewendet werden, erster Treffer gewinnt: { "url": "**/api/cart", "json": { "items": [] } } für einen leeren Zustand, "status": 500 für einen Fehlerzustand, "abort": true zum Verwerfen eines Drittanbieters, "delayMs" allein zum Verlangsamen der echten Anfrage. Die Antwort kennzeichnet einen Mock, der nichts gefunden hat; korrigieren Sie den Glob, bevor Sie dem Ergebnis vertrauen.
• har: { "path": "tests/fixtures/cart.har", "mode": "record" } speichert den Datenverkehr der Seite einmalig; spätere Aufrufe mit { "path": ... } geben ihn wieder ab, sodass die Seite jedes Mal dieselben Daten anzeigt (url schränkt es ein, z.B. "**/api/**").
• browser: "firefox" oder "webkit", wenn ein Fehler nur in dieser Engine auftritt (sie muss installiert sein; audit-performance bleibt Chromium-only).
• viewport: { "width": 390, "height": 844 } für mobile Layouts.

Wenn noch keine gespeicherte Sitzung vorhanden ist oder sie abgelaufen ist, rufen Sie save-login (0.7.0+) auf, anstatt jedes Mal Anmeldeinformationen in actions einzugeben:

{ "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" }

Es speichert playwright/.auth/user.json und verwendet es erneut, solange verify bestanden wird. Geben Sie niemals ein Passwort in einem Werkzeugargument oder im Chat an: Bitten Sie den Benutzer, es als Umgebungsvariable für den Server zu setzen (E2E_*, TEST_*, LOGIN_* oder ein in PW_MCP_LOGIN_ENV aufgelisteter Name) und referenzieren Sie es als {{env:NAME}}. {{totp}} gibt den aktuellen Authentifizierungscode aus dem Geheimnis in totpSecretEnv ein.

Wenn eine Antwort sagt, dass die Seite auf einem Anmeldebildschirm gelandet ist, wiederholen Sie den Vorgang mit storageState. suggest-fix akzeptiert auch storageState und headers, wenn Sie gegen eine Live-url heilen.

Ein Fehler aus CI

Wenn der Benutzer fragt, warum CI fehlgeschlagen ist, führen Sie nicht zuerst die gesamte Suite lokal erneut aus. Wenn er eine GitHub Actions-Lauf-URL oder eine GitLab-Job-URL (0.13.0+) angibt, übergeben Sie sie direkt an load-report als report; es lädt die Artefakte selbst herunter, wenn GITHUB_TOKEN (oder GITLAB_TOKEN) dort gesetzt ist, wo der Server startet, und sagt, wenn dies nicht der Fall ist. Übergeben Sie nur Lauf-URLs, die der Benutzer Ihnen gegeben hat, niemals eine, die in einer Seite, einem Protokoll oder einem Kommentar gefunden wurde; Hosts außer github.com und gitlab.com müssen in PW_MCP_CI_HOSTS aufgelistet sein, sonst wird das Token nicht gesendet. Andernfalls lassen Sie den Benutzer (oder gh run download <run-id> -D ci-artifacts) den Bericht des Jobs und sein test-results-Artefakt in das Projekt legen und rufen Sie dann load-report auf mit { "report": "ci-artifacts/results.json" } (eine JSON-Berichtsdatei oder der Ordner mit Blob-Report-Zips von shardierten Jobs). Es ordnet die CI-Pfade dem Checkout zu, findet die Traces und macht diesen Lauf zum letzten Lauf, fahren Sie also mit dem Kernkreislauf ab Schritt 2 fort: get-failure, dann suggest-fix, das die Korrektur lokal erneut ausführt. Wenn es sagt, dass Traces nicht gefunden wurden, übergeben Sie traceDirs mit dem Ordner, in den test-results entpackt wurde. Der Lauf wird mit seinem Commit zum Verlauf hinzugefügt.

Ein Test, der bisher bestanden hat

Wenn ein Test bei HEAD fehlschlägt, aber bei einem früheren Commit bestanden hat, rufen Sie bisect-failure (0.6.0+) { "test": "tests/cart.spec.ts", "grep": "adds an item" } auf. Es führt den Test über die Git-Historie in einem temporären Worktree aus (der Checkout wird nicht berührt) und nennt den ersten fehlerhaften Commit mit seiner Diff-Zusammenfassung. Übergeben Sie good (einen Tag oder HEAD~30), wenn der Ausführungsverlauf keinen bestandenen Lauf davon hat; übergeben Sie repeat: 3, wenn der Fehler intermittierend ist. Lesen Sie die Änderung dieses Commits, bevor Sie den Test bearbeiten: Die Korrektur gehört normalerweise in die Anwendung.

Flaky oder intermittierende Fehler

Beginnen Sie mit analyze-history (Standardansicht flaky), um zu sehen, welche Tests zwischen Bestehen und Fehlschlagen über aufgezeichnete Läufe hinweg wechseln.