Reliable automation depends heavily on browser lifecycle behavior. Flaky tests and agent failures often trace back to navigation ordering, execution context stability, or teardown races — not selector bugs.
What Koko focuses on
- Navigation ordering — deterministic event sequence from commit through load
- Realm isolation — separate JavaScript realms for iframes and workers
- WindowProxy semantics — correct cross-frame object identity
- Execution context stability — contexts survive microtasks across navigations where spec requires
- Teardown correctness — clean shutdown without hung CDP sessions
- Deterministic event ordering — predictable microtask scheduling
Why it matters for AI agents
Agents issue rapid sequences of navigate → extract → act. If lifecycle events reorder or contexts invalidate mid-flight, extraction returns stale DOM or actions target destroyed nodes. Koko instruments lifecycle explicitly rather than inheriting desktop-browser heuristics.
Testing
The code-check/lifecycle/ suite exercises realm and navigation edge cases. Run lifecycle probes as part of regression before releases.
SDK interaction
waitUntil: "done"— Koko-specific wait: load + network idle + document completepage.armDialog()— pre-arm JS dialogs before evaluation (headless auto-dismiss breaks reactive CDP)page.type()/page.press()— avoidform.submit()context-destroy races
Known gaps
Koko is under active development. Some click paths (LP.clickNode) can hang on buttons that trigger full navigation without predictable CDP lifecycle events — track separately from fill health.