PlaywrightEx.Page (PlaywrightEx v0.13.0)

Interact with a Playwright Page.

There is no official documentation, since this is considered Playwright internal.

Reference: https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/page.ts

Summary

Types

add_init_script_opt()

bring_to_front_opt()

close_opt()

expect_download_opt()

expect_screenshot_opt()

expect_url_opt()

mouse_down_opt()

mouse_move_opt()

mouse_up_opt()

reload_opt()

screenshot_opt()

update_subscription_opt()

Functions

add_init_script(context_id, opts \\ [])

Adds a script which would be evaluated in one of the following scenarios

bring_to_front(page_id, opts \\ [])

Brings page to front (activates tab).

close(page_id, opts \\ [])

Closes the page.

expect_screenshot(page_id, opts \\ [])

Asserts that a screenshot of the page matches the provided baseline.

mouse_down(page_id, opts \\ [])

Dispatches a mousedown event at the current mouse position.

mouse_move(page_id, opts \\ [])

Moves the mouse to the specified coordinates.

mouse_up(page_id, opts \\ [])

Dispatches a mouseup event at the current mouse position.

reload(page_id, opts \\ [])

Reloads the page.

screenshot(page_id, opts \\ [])

Returns the screenshot as a base64-encoded binary string.

update_subscription(page_id, opts \\ [])

Updates the subscription for page events.

Client-Composed Functions

await_download(pending)

Consumes the download event captured by expect_download/2.

expect_download(page_id, opts \\ [])

Arms a download listener before the action that triggers it.

expect_url(page_id, opts \\ [])

Expects page URL to match the provided expectation.

Types

add_init_script_opt()

@type add_init_script_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:source, binary()}

bring_to_front_opt()

@type bring_to_front_opt() :: {:connection, GenServer.name()} | {:timeout, timeout()}

close_opt()

@type close_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:reason, binary()}

expect_download_opt()

@type expect_download_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:predicate, (term() -> term())}

expect_screenshot_opt()

@type expect_screenshot_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:is_not, boolean()}
  | {:expected, term()}
  | {:comparator, term()}
  | {:max_diff_pixels, integer()}
  | {:max_diff_pixel_ratio, float()}
  | {:threshold, float()}
  | {:full_page, boolean()}
  | {:locator, map()}
  | {:clip, map()}
  | {:omit_background, boolean()}
  | {:caret, term()}
  | {:animations, term()}
  | {:scale, term()}
  | {:mask, term()}
  | {:mask_color, binary()}
  | {:style, binary()}

expect_url_opt()

@type expect_url_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:url, binary() | struct() | (term() -> term())}
  | {:is_not, boolean()}
  | {:ignore_case, boolean()}

mouse_down_opt()

@type mouse_down_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:button, term()}

mouse_move_opt()

@type mouse_move_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:x, integer() | float()}
  | {:y, integer() | float()}

mouse_up_opt()

@type mouse_up_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:button, term()}

reload_opt()

@type reload_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:wait_until, term()}

screenshot_opt()

@type screenshot_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:full_page, boolean()}
  | {:omit_background, boolean()}

update_subscription_opt()

@type update_subscription_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:event, term()}
  | {:enabled, boolean()}

Functions

add_init_script(context_id, opts \\ [])

@spec add_init_script(PlaywrightEx.guid(), [
  add_init_script_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}

Adds a script which would be evaluated in one of the following scenarios:

Whenever the page is navigated.
Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.

The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed Math.random.

Reference: https://playwright.dev/docs/api/class-page#page-add-init-script

Script Execution Order Is Not Defined

The order of evaluation of multiple scripts installed via PlaywrightEx.BrowserContext.add_init_script/2 and PlaywrightEx.Page.add_init_script/2 is not defined.

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:source (String.t/0) - Required. Raw JavaScript code to be evaluated in all pages before any scripts run.

bring_to_front(page_id, opts \\ [])

@spec bring_to_front(PlaywrightEx.guid(), [
  bring_to_front_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}

Brings page to front (activates tab).

Reference: https://playwright.dev/docs/api/class-page#page-bring-to-front

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.

close(page_id, opts \\ [])

@spec close(PlaywrightEx.guid(), [close_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}

Closes the page.

Reference: https://playwright.dev/docs/api/class-page#page-close

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:reason (String.t/0) - The reason to be reported to the operations interrupted by the page closure.

expect_screenshot(page_id, opts \\ [])

@spec expect_screenshot(PlaywrightEx.guid(), [
  expect_screenshot_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, binary() | nil} | {:error, {map(), map()}} | {:error, any()}

Asserts that a screenshot of the page matches the provided baseline.

Pass expected: nil (or omit it) for capture-only mode — the server takes a screenshot and returns the PNG bytes without performing any comparison.

Reference: https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:is_not (boolean/0) - The default value is false.
:expected (term/0) - Base64-encoded baseline image. nil = capture-only mode.
:comparator - The default value is "pixelmatch".
:max_diff_pixels (integer/0) - Max absolute pixel count allowed to differ.
:max_diff_pixel_ratio (float/0) - Max ratio (0-1) of differing pixels.
:threshold (float/0) - Per-pixel color distance tolerance (0-1).
:full_page (boolean/0) - Capture the full scrollable page.
:locator (map/0) - Scope the assertion to a sub-element: %{frame: %{guid: frame_guid}, selector: string}.
:clip (map/0) - %{x: float, y: float, width: float, height: float}
:omit_background (boolean/0) - Transparent background (PNG only).
:caret
:animations
:scale
:mask (term/0) - List of %{frame: %{guid: frame_guid}, selector: string}.
:mask_color (String.t/0) - Colour for masked areas.
:style (String.t/0) - CSS to apply before screenshotting.

mouse_down(page_id, opts \\ [])

@spec mouse_down(PlaywrightEx.guid(), [mouse_down_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}

Dispatches a mousedown event at the current mouse position.

Reference: https://playwright.dev/docs/api/class-mouse#mouse-down

Example

# Perform a manual drag operation
{:ok, _} = Page.mouse_move(page_id, x: 100, y: 100, timeout: 5000)
{:ok, _} = Page.mouse_down(page_id, timeout: 5000)
{:ok, _} = Page.mouse_move(page_id, x: 200, y: 100, timeout: 5000)
{:ok, _} = Page.mouse_up(page_id, timeout: 5000)

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:button - Defaults to :left. The default value is :left.

mouse_move(page_id, opts \\ [])

@spec mouse_move(PlaywrightEx.guid(), [mouse_move_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}

Moves the mouse to the specified coordinates.

This method dispatches a mousemove event. Supports fractional coordinates for precise positioning.

Reference: https://playwright.dev/docs/api/class-mouse#mouse-move

Example

# Get element position
{:ok, result} = Frame.evaluate(frame_id,
  expression: "() => {
    const el = document.querySelector('.slider-handle');
    const box = el.getBoundingClientRect();
    return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
  }",
  is_function: true,
  timeout: 5000
)

# Move to element
{:ok, _} = Page.mouse_move(page_id, x: result["x"], y: result["y"], timeout: 5000)

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:x - Required. x coordinate relative to the main frame's viewport in CSS pixels.
:y - Required. y coordinate relative to the main frame's viewport in CSS pixels.

mouse_up(page_id, opts \\ [])

@spec mouse_up(PlaywrightEx.guid(), [mouse_up_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}

Dispatches a mouseup event at the current mouse position.

Reference: https://playwright.dev/docs/api/class-mouse#mouse-up

Example

# Right-click at current position
{:ok, _} = Page.mouse_down(page_id, button: :right, timeout: 5000)
{:ok, _} = Page.mouse_up(page_id, button: :right, timeout: 5000)

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:button - Defaults to :left. The default value is :left.

reload(page_id, opts \\ [])

@spec reload(PlaywrightEx.guid(), [reload_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}

Reloads the page.

Reference: https://playwright.dev/docs/api/class-page#page-reload

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:wait_until - When to consider operation succeeded, defaults to load.

screenshot(page_id, opts \\ [])

@spec screenshot(PlaywrightEx.guid(), [screenshot_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, binary()} | {:error, any()}

Returns the screenshot as a base64-encoded binary string.

Reference: https://playwright.dev/docs/api/class-page#page-screenshot

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:full_page (boolean/0) - When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to false.
:omit_background (boolean/0) - Hides default white background and allows capturing screenshots with transparency. Defaults to false. Not applicable to jpeg images.

update_subscription(page_id, opts \\ [])

@spec update_subscription(PlaywrightEx.guid(), [
  update_subscription_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}

Updates the subscription for page events.

Explicit enabling keeps the subscription active until explicitly disabled. Disabling releases that explicit subscription; active PlaywrightEx.EventWaiter listeners keep their subscription until they finish or are canceled.

Reference: https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/page.ts

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:event - Required.
:enabled (boolean/0) - The default value is true.

Client-Composed Functions

Helpers composed in this client from multiple channel operations/events, primarily to keep API parity with other Playwright clients where no single server method maps directly.

await_download(pending)

@spec await_download(PlaywrightEx.EventWaiter.t()) ::
  {:ok, PlaywrightEx.Download.t()} | {:error, PlaywrightEx.EventWaiter.error()}

Consumes the download event captured by expect_download/2.

Returns metadata as soon as downloading starts. Use Download.save_as/3 to wait for completion and copy the contents. The original event deadline is retained even if awaiting begins after the action finishes. Like Task.await/2, call this once, from the process that called expect_download/2.

expect_download(page_id, opts \\ [])

@spec expect_download(PlaywrightEx.guid(), [expect_download_opt()]) ::
  {:ok, PlaywrightEx.EventWaiter.t()}
  | {:error, PlaywrightEx.EventWaiter.error()}

Arms a download listener before the action that triggers it.

Accepts only :timeout, :connection, and :predicate.

Returns a handle for await_download/1. Pass a required :timeout in milliseconds (0 means no waiting; :infinity disables the timeout) and an optional :connection. The deadline bounds event capture, not file transfer. Await once, from the process that armed the listener. Cancel with PlaywrightEx.EventWaiter.cancel/1 if you abandon the action.

An optional :predicate receives a PlaywrightEx.Download and accepts the first download for which it returns a truthy value, for example predicate: &(&1.suggested_filename == "report.csv"). It runs in the task; keep it quick and nonblocking. Rejected downloads do not restart the timeout.

{:ok, pending} = Page.expect_download(page_id, timeout: 1_000)
try do
  {:ok, _} = Frame.click(frame_id, selector: "a#export", timeout: 1_000)
  {:ok, download} = Page.await_download(pending)
  :ok = Download.save_as(download, "report.csv", timeout: 5_000)
after
  PlaywrightEx.EventWaiter.cancel(pending)
end

expect_url(page_id, opts \\ [])

@spec expect_url(PlaywrightEx.guid(), [expect_url_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, boolean()} | {:error, any()}

Expects page URL to match the provided expectation.

This library exposes URL assertions as Page.expect_url/2.

In the official Playwright JavaScript API, URL assertions are written as await expect(page).toHaveURL(...). That matcher API is not exposed here.

Matching strategy:

String/Regex: delegates to PlaywrightEx.Frame.expect/2 with expression "to.have.url", which uses server-side assertion polling (is_not is passed through for retry semantics).
Predicate function: delegates to PlaywrightEx.Frame.wait_for_url/2, which is navigation-event based (waits on :navigated + lifecycle events rather than polling page JavaScript).

Returns true when the expectation is satisfied and false otherwise.

Reference: https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-url

Options

:connection (term/0) - The Connection process name. Defaults to PlaywrightEx.Supervisor.Connection. The default value is PlaywrightEx.Supervisor.Connection.
:timeout (timeout/0) - Required. Operation timeout in milliseconds. 0 means no waiting; :infinity disables the timeout.
:url - Required. Expected URL as a string, Regex, or predicate function fn URI.t() -> boolean end.
:is_not (boolean/0) - Whether to negate the expectation. The default value is false.
:ignore_case (boolean/0) - Whether URL comparison should ignore case. The default value is false.