Persistente Debug-Session

Lass die AUT nach einem Lauf offen und verbinde dich beim nächsten Mal wieder mit genau dieser laufenden Instanz — ohne den Test-Runner zu blockieren.

← Zurück zur Übersicht · 🇬🇧 English · ← Ausführen und Debuggen · Self-Healing aktivieren →

Was es tut

Standardmäßig startet jeder Lauf einen frischen Browser (oder eine frische Electron-App) und schließt ihn am Ende wieder. Eine persistente Debug-Session ändert das fürs lokale Debuggen: Die AUT bleibt nach dem Lauf offen, und der nächste Lauf verbindet sich mit genau dieser laufenden Instanz, statt sie neu zu starten — genau in dem Zustand, in dem der vorherige Lauf sie zurückgelassen hat (gleiche Seite, gleicher Login, gleicher Formular-Zustand).

Der erste Lauf mit aktiviertem Feature startet die AUT als eigenständigen, unabhängigen Prozess und beendet sich danach normal — dein Terminal bekommt sofort seinen Prompt zurück, nichts blockiert. Jeder folgende Lauf erkennt die noch offene Instanz und verbindet sich über das Chrome DevTools Protocol (CDP) mit ihr, statt eine neue zu starten.

💡 Warum das nützlich ist. Das Iterieren an einem flakigen oder halbfertigen TestCase bedeutet meist: Test laufen lassen, Fehlschlag beobachten, Locator anpassen, Test erneut laufen lassen, warten bis die ganze App wieder hochgefahren ist, von Hand zurück zum selben Screen klicken, Test erneut laufen lassen … Eine persistente Debug-Session nimmt diese “App neu hochfahren und zurücknavigieren”-Steuer aus dieser Schleife heraus — die App sitzt schon genau dort, wo der letzte Lauf sie zurückgelassen hat.

Aktivieren

Zwei gleichwertige Wege, nach derselben Prioritäts-Kette wie Self-Healing: Eine Umgebungs-Variable gewinnt, wenn gesetzt, immer gegenüber der Config-Datei, die wiederum gegenüber dem Default (aus) gewinnt.

Umgebungs-Variable — der wörtliche String true aktiviert es; jeder andere Wert, einschließlich des wörtlichen Strings false, deaktiviert es explizit (und überschreibt eine Config-Datei, die es aktiviert):

export CC_DEBUG_SESSION=true

Config-Datei — füge debugSession als zusätzlichen Top-Level-Schlüssel in .cc-testframework.local.json im Root deines Projekts (pm/) hinzu, neben eventuell bereits vorhandenen selfHealing-Einstellungen in derselben Datei:

{
  "schemaVersion": 1,
  "debugSession": true
}

Für diesen Schlüssel gibt es keinen eigenen CLI-Setter (anders als npx cc-testframework config self-healing enable) — bearbeite die Datei direkt. Sie enthält keine Geheimnisse, ist aber eine persönliche, lokale Laufzeit-Einstellung — trag sie in dein .gitignore ein, falls noch nicht geschehen (das mitgelieferte Template tut das bereits für dich).

Standardmäßig aus: Ist weder die Umgebungs-Variable noch der Config-Schlüssel gesetzt, verhält sich jeder Lauf exakt wie heute — ein verwalteter Browser (oder eine verwaltete Electron-App), der frisch startet und am Ende des Laufs schließt.

Lebenszyklus: einmal starten, danach jedes Mal wiederverbinden 

# Lauf 1 — noch keine Session aufgezeichnet: startet die AUT losgelöst und verbindet sich danach mit ihr.
# Der Runner beendet sich normal; die AUT läuft weiter.
CC_DEBUG_SESSION=true npx playwright test 3_Cases/TC_DeinTest.spec.ts --workers=1

# Lauf 2 — eine laufende Session ist aufgezeichnet: verbindet sich wieder, statt neu zu starten.
# Die Seite ist genau so, wie Lauf 1 sie zurückgelassen hat.
CC_DEBUG_SESSION=true npx playwright test 3_Cases/TC_DeinTest.spec.ts --workers=1

Ein Wiederverbinden gibt eine Zeile wie diese auf der Konsole aus, damit du immer weißt, welchen Weg ein Lauf genommen hat:

[DebugSession] Reconnected to existing session (pid 41822, endpoint http://127.0.0.1:9222).

Schließt du das Fenster selbst (oder stirbt der Prozess anderweitig) zwischen zwei Läufen, erkennt der nächste Lauf, dass die aufgezeichnete Session nicht mehr erreichbar ist, verwirft sie und startet eine frische — für diesen Fall musst du selbst nichts von Hand aufräumen.

💡 Eine Instanz, ein Worker. Es wird immer nur eine persistente Session gleichzeitig verfolgt. Zwei debug-session-aktivierte Playwright-Worker parallel laufen zu lassen — oder eine zweite, andere App zu debuggen, während die Session der ersten noch lebt — wird noch nicht unterstützt; der zweite Lauf verbindet sich dann mit der Instanz der ersten App, statt eine eigene zu starten. Übergib --workers=1, solange eine Debug-Session aktiviert ist.

Die Session per CLI verwalten 

npx cc-testframework session status
npx cc-testframework session close

status meldet, ob eine Session aufgezeichnet ist und ob sie noch erreichbar ist:

$ npx cc-testframework session status
Debug session: LIVE
  kind:      web
  endpoint:  http://127.0.0.1:9222
  pid:       41822
  startedAt: 2026-08-12T09:14:03.000Z
STATUS=live ENDPOINT=http://127.0.0.1:9222 PID=41822 KIND=web

Die letzte Zeile ist eine einzelne, maschinell auswertbare Zusammenfassung neben dem menschenlesbaren Block darüber — für ein Script oder ein anderes Tool, das prüfen will, ohne den formatierten Text zu parsen.

close stoppt die persistente AUT und löscht die aufgezeichnete Session — der nächste debug-session-aktivierte Lauf startet dann wieder frisch:

$ npx cc-testframework session close
Closed the persistent debug session (pid 41822, endpoint http://127.0.0.1:9222).
STATUS=closed

Beide Befehle sind sicher, wenn keine Session aufgezeichnet ist, und sicher, zweimal hintereinander ausgeführt zu werden.

Explizites Close in einer Debug-Session

Solange eine Debug-Session aktiv ist, beendet ein expliziter TS_Execution_Close-Step innerhalb eines TestCase sie tatsächlich — sowohl bei einer Web-App als auch bei einer Electron-App, da beide denselben schlichten Step-Namen verwenden (siehe Neue App hinzufügen — Registriere eine Electron-App): Er tötet den losgelösten AUT-Prozess und löscht die aufgezeichnete Session — genau wie npx cc-testframework session close (siehe oben), tatsächlich ist es intern derselbe Teardown. Ein TestCase, der mit einem Close-Step endet, bleibt nicht erhalten; der nächste Lauf startet eine frische Instanz, statt sich wieder zu verbinden.

Das ist das Gegenteil davon, wie ein normales (Nicht-Debug-Session-)close() sich verhält — normalerweise ist es ein sanftes, logisches Schließen (Web: Navigation zu about:blank; der zugrunde liegende Browser bleibt für den Rest des Laufs offen). Im Debug-Session-Modus wird daraus stattdessen ein echter, expliziter Teardown, weil “ich habe Close aufgerufen” das eindeutigste Signal ist, das ein Tester geben kann, dass er mit dem Debuggen fertig ist.

Um den Wiederverbindungs-Workflow über mehrere Läufe hinweg fortzusetzen, lasse den Close-Step weg — genau so ist das Feature für den Alltag gedacht: laufen lassen, prüfen, anpassen, erneut laufen lassen, und erst einen Close-Step hinzufügen (oder npx cc-testframework session close im Terminal aufrufen), wenn du wirklich fertig bist und willst, dass die AUT verschwindet.

Web und Electron

Sowohl Web-Apps (Chromium) als auch Electron-Apps unterstützen eine persistente Debug-Session — siehe Neue App hinzufügen — Registriere eine Electron-App dafür, wie eine Electron-App überhaupt registriert wird.

⚠ Electron-Besonderheit. Eine wiederverbundene Electron-Session wird komplett über CDP gesteuert, genau wie eine wiederverbundene Web-Session — jeder Control und TestStep, der auf dem Renderer-DOM operiert, funktioniert unverändert. Playwrights separate Electron-Main-Process-API (electronApp.evaluate(...) und Ähnliches) steht auf einer wiederverbundenen Instanz nicht zur Verfügung, da diese API das ursprüngliche, In-Process-_electron.launch()-Handle braucht. Braucht ein TestStep Main-Process-Zugriff, benötigt er einen verwalteten (Nicht-Debug-Session-)Lauf.

Niemals in CI aktivieren

Eine persistente Debug-Session ist eine lokale Debugging-Hilfe, keine CI-Einstellung. Sie in CI zu aktivieren lässt einen losgelösten AUT-Prozess auf dem CI-Runner laufen, nachdem der Job fertig ist — nichts räumt ihn automatisch auf, da genau das für den lokalen Einsatz der Sinn des Features ist. Halte CC_DEBUG_SESSION in CI ungesetzt (oder explizit auf false), und checke keine debugSession: true-Config-Datei in ein geteiltes Repo ein, ohne zu bestätigen, dass CI sie nicht aufgreift.

Wo der Zustand liegt

  • .cc-testframework-session.local.json, im Root deines Projekts (pm/) — die aufgezeichnete Session (Endpoint, Prozess-ID, Art, Startzeit). Vom mitgelieferten Template git-ignoriert.
  • .cc-testframework/, ebenfalls im Root deines Projekts — das persistente Browser-Profil (Cookies, Local Storage) für eine losgelöste Web-Session, sodass auch der Login-Zustand über Läufe hinweg erhalten bleibt. Ebenfalls git-ignoriert.

Keine der beiden Dateien muss committet oder geteilt werden — sie beschreiben einen einzelnen lokalen Prozess auf deiner eigenen Maschine.

Wo es weitergeht

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

itsbusiness AG · Bern · Schweiz