Class BaseBrowserAdapterAbstract

Current URL of the browser page

Whether the browser is launched and connected

Current viewport dimensions

Capture a snapshot of the given origin's client-side storage (localStorage

• IndexedDB) for later restore into a fresh context — the warm-seed that kills the per-test cold-boot metadata refetch. The caller (driver) captures once post-login and reuses the seed across contexts.

Default returns null (nothing to capture) so adapters without a live page don't break — additive and non-throwing. Adapters backed by a real page (e.g. Playwright) override this.

Capture one frame on demand and push it through the active screencast's callback.

Lets callers force an immediate live-view refresh (e.g. the first paint, or right after a navigation settles) on adapters whose screencast only emits frames on a viewport repaint.

Default implementation is a no-op resolve — safe to call when no screencast is running or the adapter has no screencast support. Adapters with a live screencast (e.g. PlaywrightBrowserAdapter) override this to emit a real frame.

Capture a screenshot of the current viewport.

Close the browser and release all resources. Safe to call multiple times — subsequent calls are no-ops.

Execute a single browser action. The action is a discriminated union — implementations should switch on action.Type for exhaustive handling.

Extract the page's interactive elements (buttons/links/inputs/ARIA roles/ click affordances) as a stable indexed list for element-grounded perception. The returned indices are what a subsequent ClickElement/TypeIntoElement action resolves against, so an adapter that implements this MUST cache the result to resolve those actions.

Default returns an empty list so adapters without a live DOM don't break — element grounding then simply has nothing to offer and the engine falls back to coordinate actions. Adapters backed by a real page override this.

Capture the page's accessibility tree for token-efficient, structured perception (a lighter-weight alternative to a screenshot).

Default implementation returns null so adapters that cannot produce an accessibility tree don't break — additive and non-throwing. Adapters backed by a real page (e.g. Playwright) override this.

Retrieve and flush all buffered diagnostic events captured since the last call. Returns an empty array if the adapter doesn't capture diagnostics or if there are no new events.

Read the page's CURRENT text selection (window.getSelection().toString()).

Used by the remote-browser human "copy-out" path — the viewer reads what the human selected on the remote page and writes it to the local clipboard. Default implementation returns an empty string so adapters without a live page don't break — it's a non-throwing, additive default. Adapters backed by a real page (e.g. Playwright) override this to return the live selection.

Capture the current page's title for cheap perception / sync.

Default implementation returns an empty string so adapters without a live page don't break — it's a non-throwing, additive default. Adapters backed by a real page (e.g. Playwright) override this to return the page title.

Read the visible text of the current page for agent perception.

Returns the rendered (visible) text content of the page body — useful for an LLM controller that needs the page's textual state without a screenshot. Adapters backed by a live page (e.g. Playwright) override this to return the real page text.

Default implementation returns an empty string so adapters that cannot read page text don't break — it's a non-throwing, additive default.

Launch the browser with the given configuration. Must be called before any other method.

Navigate to the given URL and wait for the page to load. Respects the NavigationTimeoutMs from BrowserConfig.

Introspect a single element matched by a CSS selector — its existence, visibility, text, and bounding box — without ever throwing on a miss.

Default implementation reports the element as absent so adapters that cannot query the DOM don't break — additive and non-throwing. Adapters backed by a real page (e.g. Playwright) override this.

Reset per-session state for the given origin while preserving auth tokens.

Intended for shared-context adapters: between tests in the same browser context, cached state from the previous test (IndexedDB metadata cache, sessionStorage, service workers, non-auth localStorage entries) can deadlock the next test's app initialization. This method clears that state so the next test starts clean — but preserves Auth0 / OAuth tokens in localStorage so the user stays logged in.

Default implementation is a no-op. Adapters that own a context across test boundaries (e.g., SharedContextBrowserAdapter) override this.

Best-effort: never throws — all errors are swallowed.

Restore a previously-captured ContextSeed into the current context BEFORE the app boots. Best-effort and cold-boot-safe by contract: any failure must leave the context to refetch from the server, never a half-populated (corrupt) cache.

Default is a no-op resolve so adapters that can't seed don't break — additive and non-throwing. Adapters backed by a real page override this.

Add cookies to the browser context. Used by AuthHandler for CookieInjection auth.

Set extra HTTP headers for all requests to a specific domain. Used by AuthHandler for Bearer, APIKey, and Basic auth.

Headers are additive — calling this multiple times for the same domain merges headers. Calling with a different domain adds a new set of domain-scoped headers.

Implementation note: Playwright uses page.route() interception; other adapters may use their own request interception mechanism.

Set localStorage entries for a specific domain. The browser must have already navigated to the domain (or a page on that domain) for this to work.

Used by AuthHandler for LocalStorage auth.

Start capturing the audio playing inside the browser tab, invoking onChunk for each encoded AudioCaptureChunk until StopAudioCapture is called.

Default implementation is a no-op resolve: it starts no capture and emits no chunks. This is the safer additive default — a consumer that opportunistically requests tab audio on an adapter that can't provide one simply receives nothing rather than an exception. Adapters that can tap the page's media elements (e.g. PlaywrightBrowserAdapter) override this to emit real chunks.

Start a live screencast of the browser viewport, invoking onFrame for each captured frame until StopScreencast is called.

Default implementation is a no-op resolve: it starts no feed and emits no frames. This is the safer additive default — a consumer that opportunistically requests a live feed on an adapter that can't provide one (e.g. a non-CDP backend) simply receives nothing rather than an exception that would break an otherwise-working automation loop. Adapters that can drive CDP (e.g. PlaywrightBrowserAdapter) override this to emit real ScreencastFrames.

Begin recording a forensic trace of the session (DOM snapshots + screenshots + network + console) for later offline inspection.

Default implementation is a no-op resolve so adapters that can't produce a trace (or non-CDP backends) don't break — additive and non-throwing. Adapters backed by a real browser context (e.g. Playwright) override this to call context.tracing.start(...). The caller decides whether to capture (and whether to keep the result); the adapter only knows how.

Stop an audio capture previously started via StartAudioCapture and release any associated in-page resources (the MediaRecorder, observers).

Default implementation is a no-op — safe to call even when no capture is active or the adapter never supported one.

Stop a screencast previously started via StartScreencast and release any associated resources (e.g. the CDP session).

Default implementation is a no-op — safe to call even when no screencast is active or the adapter never supported one.

Stop a trace started via StartTracing, writing it to path. Returns true iff a trace file was actually written (so the caller can decide whether there's an artifact to retain or discard). Default implementation returns false — nothing was traced. Never throws.

Wait until the page reaches a given load state.

Useful after a navigation/action to let the page settle before the next perception step. Default implementation is a no-op resolve so adapters that cannot observe load state don't break — additive and non-throwing. Adapters backed by a real page (e.g. Playwright) override this.