@callback add_cookies(transport(), guid(), [map()]) :: :ok | {:error, term()}

Add cookies to a context. Each cookie is a map using Playwright's field names (name, value, and either url or domain+path; optionally expires, httpOnly, secure, sameSite). Used to seed a signed session cookie so tests can start past an auth gate without driving the login UI.

@callback add_init_script(transport(), guid(), String.t(), keyword()) ::
  :ok | {:error, term()}

Add an init script to a context, evaluated before any page scripts on every page/navigation in that context. Targets a context guid, so it must be installed before the page is created.

@callback cdp_send(transport(), guid(), String.t(), map()) ::
  {:ok, term()} | {:error, term()}

Send a CDP command over a session opened with new_cdp_session/2 (e.g. Network.emulateNetworkConditions). Windows transport only.

@callback click(transport(), guid(), String.t(), keyword()) :: :ok | {:error, term()}

Click an element

@callback close_browser(transport(), guid()) :: :ok | {:error, term()}

Close a browser

@callback close_context(transport(), guid()) :: :ok | {:error, term()}

Close a context

@callback close_page(transport(), guid()) :: :ok | {:error, term()}

Close a page

@callback content(transport(), guid()) :: {:ok, String.t()} | {:error, term()}

Get page content

@callback evaluate(transport(), guid(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Evaluate a JavaScript expression in a frame and return the result.

opts may include :is_function (treat the expression as a function body), :arg (an argument passed to the function), and :timeout.

@callback expose_binding(transport(), guid(), String.t(), (list() -> term())) ::
  :ok | {:error, term()}

Expose an Elixir callback to the page as a binding: the page can call window.<name>(...args) and the transport invokes the callback with the argument list, returning its result to the page.

Experimental and :windows-only - it is the one verb that needs the bidirectional event channel. :local/:remote return {:error, :not_supported}. Most harness needs are met by polling with evaluate/4 + wait_for_function/4; prefer those.

@callback fill(transport(), guid(), String.t(), String.t(), keyword()) ::
  :ok | {:error, term()}

Fill an input

@callback goto(transport(), guid(), String.t(), keyword()) :: result()

Navigate to a URL

@callback healthy?(transport()) :: boolean()

Check if transport is healthy

@callback launch_browser(transport(), browser_type(), keyword()) ::
  {:ok, guid()} | {:error, term()}

Launch a browser instance

@callback new_cdp_session(transport(), guid()) :: {:ok, guid()} | {:error, term()}

Open a Chrome DevTools Protocol session for a page. Returns an opaque CDP session id to be used with cdp_send/4.

Only the :windows transport supports CDP; :local returns {:error, :not_supported} (playwright_ex exposes no CDP surface).

@callback new_context(transport(), guid(), keyword()) :: {:ok, guid()} | {:error, term()}

Create a new browser context

@callback new_page(transport(), guid()) :: {:ok, map()} | {:error, term()}

Create a new page in a context

@callback screenshot(transport(), guid(), keyword()) :: {:ok, binary()} | {:error, term()}

Take a screenshot

@callback send_message(transport(), message(), timeout()) :: result()

Send a message to Playwright and wait for response

@callback start_link(keyword()) :: {:ok, pid()} | {:error, term()}

Start the transport connection

@callback stop(transport()) :: :ok

Stop the transport

@callback storage_state(transport(), guid()) :: {:ok, map()} | {:error, term()}

Return the context's storage state (cookies + localStorage snapshot), e.g. to capture it after a UI login and re-seed it (via add_cookies/3) in later runs.

@callback wait_for_function(transport(), guid(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Wait until a JavaScript predicate becomes truthy in a frame.

opts may include :is_function, :arg, :polling (a number of ms or "raf"), and :timeout.