Browser Evaluate CDP Refactor: Schluss mit blockierten Queues

Kennst du das? Du führst ein Skript im Browser aus und plötzlich geht gar nichts mehr. Ein einziger Befehl hängt fest, und weil alles in einer Schlange steht, werden auch alle nachfolgenden Klicks oder Eingaben blockiert. Dein ganzer Tab wirkt wie eingefroren, nur weil ein evaluate länger dauert als geplant.

Das Problem liegt oft an der Serialisierung von Befehlen. Wenn Playwright auf eine Antwort wartet, die nicht kommt, staut sich die gesamte Queue auf. Wir haben uns entschieden, dieses Problem grundlegend zu lösen, indem wir die Ausführung von JavaScript vom restlichen Browser-Traffic isolieren.

Voraussetzungen

• Zugriff auf den Browser Control Service
• Playwright (für die Basis-Aktionen)
• Aktiviertes browser.evaluateEnabled Gate

Schnellstart

In fünf Schritten stellst du auf die neue Architektur um, die CDP direkt nutzt:

1. Budget-Helper integrieren: Nutze eine zentrale Logik für Timeouts und Aborts, damit alle Schichten dasselbe Zeitlimit kennen.
2. CDP-Engine aufsetzen: Erstelle ein Modul, das eine eigene WebSocket-Verbindung und CDP-Session via Target.attachToTarget öffnet.
3. Ref Metadata erweitern: Ergänze deine Role Refs um die backendDOMNodeId.
4. IDs beim Snapshot mappen: Rufe den AX Tree via Accessibility.getFullAXTree ab, um die IDs deinen Refs zuzuordnen.
5. Routing anpassen: Leite act:evaluate primär über die neue CDP-Engine und behalte Playwright nur als Fallback.

Die neue Architektur

Wir empfehlen, die Ausführung von JavaScript komplett von der Playwright-Queue zu trennen. Der Kernpunkt ist, dass die Ausführung über einen separaten Transportweg läuft.

1. Einheitliche Budgets

Statt überall eigene Timeouts zu berechnen, nutzen wir einen Helper. Dieser stellt sicher, dass die verbleibende Zeit (remainingMs) korrekt an alle Unteroperationen weitergegeben wird.

// Beispiel für die Budget-Struktur
const budget = createBudget({
  timeoutMs: 30000,
  signal: upstreamSignal
});

// Zugriff auf das verknüpfte Signal und die Restzeit
console.log(budget.remainingMs());

2. Die CDP-Evaluate Engine

Anstatt page.evaluate zu nutzen, verbindet sich die neue Engine direkt mit dem Browser-Level Socket. Durch eine eigene sessionId können wir Befehle wie Runtime.evaluate senden, ohne die Playwright-Queue zu beeinflussen. Wenn ein Timeout eintritt, schließen wir einfach die Session und den WebSocket.

3. Element Targeting mit Refs

Damit du weiterhin Elemente gezielt ansprechen kannst, erweitern wir die Metadaten. So sieht die neue Struktur für Refs aus:

{
  role: "button",
  name: "Absenden",
  nth: 0,
  backendDOMNodeId: 12345 // Optionale CDP-ID für direktes Targeting
}

Beim Erstellen eines Snapshots wird der AX Tree via CDP abgerufen. Wir mappen die (Role, Name, Nth)-Kombination auf die backendDOMNodeId. Wenn das Mapping funktioniert, nutzt act:evaluate den schnellen CDP-Pfad. Falls nicht, greift automatisch das bewährte Safety Net von Playwright.

Fehlerbehebung

• Mapping-Fehler: Falls eine ref keine backendDOMNodeId hat, wird automatisch der Playwright-Pfad genutzt. Das Feature ist “best-effort” ausgelegt und beeinträchtigt die Stabilität nicht.
• Nebenwirkungen bei Abbruch: Das Senden von Runtime.terminateExecution kann Seiteneffekte im Page-State haben. Wir setzen dies nur ein, wenn ein Timeout oder ein manueller Abort vorliegt.
• CDP-Verbindung blockiert: In Umgebungen, in denen CDP-Attach eingeschränkt ist, bleibt der bisherige Playwright-Weg als Fallback aktiv.

Hast du Fragen zur Implementierung oder brauchst Hilfe beim Setup? Der AI Setup Assistant unterstützt dich dabei.

Nächste Schritte

• Playwright Locator Dokumentation
• CDP Runtime API Referenz
• Browser Snapshot Guide
• Handling Timeouts in Node.js