Ausführen und Debuggen

Führe einen TestCase lokal aus, lies, was er produziert hat, und arbeite dich durch einen Fehlschlag — Locator, Timeout oder anderes.

← Zurück zur Übersicht · 🇬🇧 English · ← Deinen TestCase komponieren · Persistente Debug-Session →

Führe einen einzelnen TestCase aus

Alle Befehle auf dieser Seite laufen aus pm/ heraus (siehe Quickstart — Schritt 5):

npx playwright test 3_Cases/TC_DeinTest.spec.ts

Füge --grep "<pattern>" hinzu, um nach Test-Titel zu filtern, oder --repeat-each 3, um denselben TestCase mehrfach laufen zu lassen, während du einem flakigen Fehlschlag nachjagst. Lass den Pfad ganz weg, um jeden TestCase unter testDir auszuführen; füge --last-failed hinzu, um nur die erneut zu laufen, die beim letzten Mal fehlgeschlagen sind.

Führe nur einen Browser / ein Project aus

npx playwright test 3_Cases/TC_DeinTest.spec.ts --project=chromium

--project matcht einen Namen aus dem projects-Array deiner playwright.config.ts — nützlich, sobald dein Projekt auch firefox/webkit fährt, oder ein Desktop-Project neben Web, und du einen Fehlschlag nur auf einem davon reproduzieren willst.

Führe im Headed-Modus aus, um den Test zu beobachten

npx playwright test 3_Cases/TC_DeinTest.spec.ts --headed

--headed überschreibt sowohl use.headless deiner playwright.config.ts als auch das headless-Feld einer Web-AUT in GlobalConfig.apps (siehe Neue App hinzufügen) nur für diesen Lauf — hinterher nichts zurückzustellen.

Run-Mode wählen: sofort abbrechen oder trotz Fehlschlag weiterlaufen (`CC_RUN_MODE`)

Standardmässig bricht ein TestCase beim allerersten fehlgeschlagenen Step ab — failfast, unverändert, kein Setup nötig.

Setze failsafe, damit ein TestCase über eine fehlgeschlagene Assertion hinweg weiterläuft — ein Core.expect(...)/Check.*-Inhaltscheck, der das Element gefunden hat, dessen Inhalt oder Zustand aber nicht passte — statt sofort abzubrechen. Der fehlgeschlagene Check wird weiterhin geloggt ([FAIL] TS_x: ..., dieselbe Zeile wie heute) und der Gesamtlauf endet weiterhin mit Status failed; lediglich die übrigen, unabhängigen Steps im selben TestCase bekommen zusätzlich die Chance zu laufen, statt als Unexecuted gemeldet zu werden. Alles, was KEIN Inhalts-Mismatch ist — ein nicht gefundenes Element, ein Timeout oder ein anderer Ausführungsfehler — bricht den TestCase weiterhin sofort ab, in beiden Modi; nur fehlgeschlagene Assertions sind jemals soft.

CC_RUN_MODE=failsafe npx playwright test 3_Cases/TC_DeinTest.spec.ts

Persistiere einen Default über Shells/Sessions hinweg, statt die Umgebungsvariable jedes Mal neu zu setzen — nach derselben Priority-Chain wie jeder andere Framework-Toggle (siehe Self-Healing — Setup dauerhaft speichern): Die Umgebungsvariable gewinnt, wenn gesetzt, immer über die persistierte Config-Datei, die wiederum über den Default (failfast) gewinnt.

npx cc-testframework set-run-mode failsafe   # Default für dieses Projekt persistieren
npx cc-testframework set-run-mode            # den aufgelösten Wert + seine Quelle anzeigen (env|config|default)
npx cc-testframework set-run-mode failfast   # zurück zum Default (erster Fehlschlag bricht ab)

Lies den HTML-Report

Das baseConfig des Frameworks behält Playwrights Default-['html']-Reporter (siehe API-Referenz — baseConfig), also schreibt jeder Lauf einen Report nach pm/playwright-report/. Öffne ihn mit:

npx playwright show-report

baseConfig schaltet außerdem screenshot: 'on' und video: 'on' für jeden Test ein (nicht nur Fehlschläge) sowie trace: 'on-first-retry' — ein fehlschlagender Step hat also fast immer einen Screenshot und ein Video im Report angehängt, plus einen vollständigen Playwright-Trace, sobald ein Retry stattgefunden hat. Öffne den Trace über den “Trace”-Tab des Reports, oder direkt mit npx playwright show-trace <pfad-zum-trace.zip>, um dich durch den exakten DOM-/Netzwerk-Zustand zum Zeitpunkt des Fehlschlags zu klicken.

Debugge einen fehlschlagenden Locator

Ein Locator, der nichts findet, wirft eine Meldung wie diese, sobald sein Suchfenster abläuft:

search timeout reached. (timeout:20s / timetaken:20.0s). No child element was found by the given locators [...]

Drei Wege nach vorn, grob nach Aufwand geordnet:

Den Control von Hand fixen — die UI hat wahrscheinlich ihre Form geändert; siehe Controls hinzufügen für Locator-Style und wo die Datei liegt.
Self-Healing automatisch reparieren lassen — binde einmal einen Referenz-Screenshot, und ein künftiger Lauf kann einen kaputten Locator selbst heilen; siehe Self-Healing Locators fürs Setup.
Den Authoring-Agenten einen Fix schreiben lassen — npx cc-testframework author --test 3_Cases/TC_DeinTest.spec.ts führt den fehlschlagenden TestCase erneut aus und dispatched einen Fix für Fehlerklassen, die er erkennt; siehe Custom Steps — Der Agent als Kommandozeilen-Befehl.

Debugge einen hängenden Test

Ein Test, der nie fertig wird, fällt meist in eine dieser Kategorien:

Die App wurde nie erreichbar. Playwrights eigenes Navigations-Timeout feuert (page.goto: Timeout ... exceeded) — siehe Neue App hinzufügen für die üblichen Ursachen.
Eine Core.expect(...)-Assertion retried immer weiter. Core.expect ist Playwrights eigenes expect — web-first Matcher wie .toBeVisible() retryen automatisch, bis sie bestehen oder Playwrights Test-Timeout abläuft, statt beim ersten Check zu scheitern. Eine lang hängende Assertion hier retried meist gegen ein Element, das nie erscheinen wird, nicht gegen einen Framework-Bug:

// Retried intern bis zu Playwrights Test-Timeout — kein sofortiges Pass/Fail
await Core.expect(page.getByText('Success')).toBeVisible();

Ein blockierender Dialog oder Overlay. Ein nativer Browser-Dialog (alert/confirm) oder ein App-Level-Modal, das Playwright nicht selbst schließen kann, blockiert jede weitere Locator-Suche, bis etwas ihn behandelt — prüfe, ob im Flow ein TS_Dialog_*/TS_Message_*-Step fehlt (siehe TestSteps bauen).

Core.Constant.searchTimeout (standardmäßig 20 Sekunden) begrenzt, wie lange ein einzelner Core.findLocators-Aufruf wartet, bevor er aufgibt — erhöhe oder senke es pro Aufruf über den searchTimeout-Parameter eines Controls statt global, wenn ein bestimmter Screen ungewöhnlich langsam ist.

Iteriere schneller mit dem Inspector

await Core.Inspector.pause();

Setze diese Zeile in einen TestStep- oder TestCase-Body, und der laufende Test pausiert, spawnt die Inspector-Web-UI (npm install @meintest/cc-testframework-inspector-ui innerhalb von pm/, falls noch nicht installiert) und öffnet sie in deinem System-Browser gegen den lebenden App-Zustand — inspiziere das aktuelle DOM, probiere Locators aus und nimm einen Referenz-Screenshot für Self-Healing auf, klicke dann “Resume Test”, um genau dort weiterzumachen, wo du aufgehört hast. Eine eigene Deep-Dive-Seite ist geplant; das hier ist die Kurzversion, die dich heute entblockt.

Übergib Optionen, wenn die Default-Auto-Erkennung einen Hinweis braucht — z.B. mehr als eine registrierte App und keine aktuell gebunden, oder eine harte Obergrenze, wie lange die Pause einen CI-Job blockieren darf:

await Core.Inspector.pause({ appId: 'DeineApp', timeoutMs: 120_000 });

Häufige Fehlermuster und ihre Fixes

Fehler	Wahrscheinliche Ursache	Fix
`defineExecutionStep: unknown appName 'DeineApp'`	Tippfehler, oder fehlender `GlobalConfig.apps`-Eintrag	Siehe Neue App hinzufügen
`search timeout reached ... No child element was found`	Locator matcht die aktuelle UI nicht mehr	Siehe Debugge einen fehlschlagenden Locator oben
`page.goto: Timeout ... exceeded`	App von der Testmaschine aus nicht erreichbar	Siehe Neue App hinzufügen
`browser executable not found`	Playwright-Browser nicht installiert	`npx playwright install` — siehe FAQ
Custom Step wirft `not yet automated`	Ein `@custom`-getaggter Step hat noch keine Implementierung	Siehe Custom Steps
Test läuft lokal grün, scheitert nur in CI	Fehlender Env-Var/Credential, oder ein CI-spezifischer Timing-Unterschied	Prüfe, ob `SELF_HEALING_WRITEBACK` und ein KI-API-Key (`AI_API_KEY`, `set-ai-key`, oder `ANTHROPIC_API_KEY`) gesetzt sind, falls der Lauf darauf angewiesen ist; siehe Self-Healing — Kosten und BYOK und Credential Management

Wo es weitergeht

Persistente Debug-Session — lass die AUT zwischen Läufen offen, während du an einem fehlschlagenden TestCase iterierst
CI-Integration — denselben TestCase in einer Pipeline ausführen, mit CC_RUN_MODE und dem Rest als CI-Secrets gesetzt
Self-Healing Locators — hör auf, denselben Locator jedes Mal von Hand zu fixen, wenn sich die UI ändert
Custom Steps — schreibe (oder generiere) eine Implementierung für einen Step, der noch nicht automatisiert ist
Controls hinzufügen — fixe oder erweitere einen Control direkt
FAQ — Troubleshooting für Setup-Probleme, die schon vor dem ersten Testlauf auftauchen

📧 Fragen? Kontakt: jens.szelag@itsbusiness.ch

itsbusiness AG · Bern · Schweiz