PlaywrightEx.Frame (PlaywrightEx v0.2.0)

Navigates a frame to a specified URL and returns the main resource response. In cases of multiple redirects, it resolves with the final redirect's response.

inner_html(frame_id, opts \\ [])

Returns the element.innerHTML property from a matching element.

press(frame_id, opts \\ [])

Focuses a matching element and activates a combination of keys.

select_option(frame_id, opts \\ [])

Selects one or more options from a <select> element matching the provided selector.

set_input_files(frame_id, opts \\ [])

Sets the value of the file input to these file paths or files.

title(frame_id, opts \\ [])

Returns the page title.

type(frame_id, opts \\ []) deprecated

Sends keydown, keypress/input, and keyup events for each character in the text.

uncheck(frame_id, opts \\ [])

Unchecks an element matching a selector by performing several steps: locating an element that matches the given selector, ensuring it's a checkbox or radio input, waiting for actionability checks (unless force is set), scrolling into view if needed, using the mouse to click the center of the element, and verifying the element is now unchecked. The method throws a TimeoutError if all steps don't complete within the specified timeout period.

url(frame_id, opts \\ [])

Returns the frame's URL.

wait_for_selector(frame_id, opts \\ [])

Returns when element specified by selector satisfies state option. Returns nil if waiting for hidden or detached.

Types

blur_opt()

@type blur_opt() :: {:timeout, timeout()} | {:selector, binary()}

check_opt()

@type check_opt() ::
  {:timeout, timeout()} | {:selector, binary()} | {:strict, boolean()}

click_opt()

@type click_opt() ::
  {:timeout, timeout()} | {:selector, binary()} | {:strict, boolean()}

content_opt()

@type content_opt() :: {:timeout, timeout()}

drag_and_drop_opt()

@type drag_and_drop_opt() ::
  {:timeout, timeout()}
  | {:source, binary()}
  | {:target, binary()}
  | {:strict, boolean()}

evaluate_opt()

@type evaluate_opt() ::
  {:timeout, timeout()}
  | {:expression, binary()}
  | {:is_function, boolean()}
  | {:arg, term()}

expect_opt()

@type expect_opt() ::
  {:timeout, timeout()}
  | {:is_not, boolean()}
  | {:expression, binary()}
  | {:selector, binary()}
  | {:expected_text, term()}
  | {:expected_number, term()}

fill_opt()

@type fill_opt() ::
  {:timeout, timeout()}
  | {:selector, binary()}
  | {:value, binary()}
  | {:strict, boolean()}

goto_opt()

@type goto_opt() :: {:timeout, timeout()} | {:url, binary()}

inner_html_opt()

@type inner_html_opt() :: {:timeout, timeout()} | {:selector, binary()}

press_opt()

@type press_opt() ::
  {:timeout, timeout()}
  | {:selector, binary()}
  | {:key, binary()}
  | {:delay, non_neg_integer()}

select_option_opt()

@type select_option_opt() ::
  {:timeout, timeout()}
  | {:selector, binary()}
  | {:options, term()}
  | {:strict, boolean()}

set_input_files_opt()

@type set_input_files_opt() ::
  {:timeout, timeout()}
  | {:selector, binary()}
  | {:local_paths, term()}
  | {:strict, boolean()}

title_opt()

@type title_opt() :: {:timeout, timeout()}

type_opt()

@type type_opt() ::
  {:timeout, timeout()}
  | {:selector, binary()}
  | {:text, binary()}
  | {:delay, non_neg_integer()}

uncheck_opt()

@type uncheck_opt() ::
  {:timeout, timeout()} | {:selector, binary()} | {:strict, boolean()}

url_opt()

@type url_opt() :: {:timeout, timeout()}

wait_for_selector_opt()

@type wait_for_selector_opt() :: {:timeout, timeout()} | {:selector, binary()}

Functions

blur(frame_id, opts \\ [])

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

Calls the native blur function on the matching element, which removes focus from that element.

Reference: https://playwright.dev/docs/api/class-frame#frame-blur

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.

check(frame_id, opts \\ [])

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

Checks a checkbox or radio input element.

This method locates an element matching the given selector and performs a series of automated steps: finding the element, verifying it's a checkbox or radio input, performing actionability checks, scrolling into view if necessary, and using mouse interaction to click the center of the element. The method ensures the element becomes checked after the click.

If the element is already checked, the method returns immediately without further action. Developers can bypass actionability checks using the force option. The method throws an error if the matched element is not a checkbox or radio input. A TimeoutError is thrown if operations don't complete within the specified timeout period. Zero timeout disables timeout restrictions.

This method is discouraged in favor of using the locator-based locator.check() approach, which aligns with modern Playwright testing practices focusing on locators rather than direct selector-based actions.

Reference: https://playwright.dev/docs/api/class-frame#frame-check

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.
:strict (boolean/0) - When true, the call requires selector to resolve to a single element. The default value is true.

click(frame_id, opts \\ [])

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

Clicks an element matching selector by performing the following steps:

Locates an element matching the provided selector, waiting if necessary for it to appear in the DOM
Performs actionability checks unless the force option is enabled; retries if the element detaches during checks
Scrolls the element into view as needed
Uses the mouse to click at the element's center or a specified position
Waits for any initiated navigations to complete, unless noWaitAfter is set

The method throws a TimeoutError if all steps don't complete within the specified timeout period. This deprecated method is discouraged in favor of using locator-based locator.click() instead.

Reference: https://playwright.dev/docs/api/class-frame#frame-click

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.
:strict (boolean/0) - When true, the call requires selector to resolve to a single element. The default value is true.

content(frame_id, opts \\ [])

@spec content(PlaywrightEx.guid(), [content_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, String.t()} | {:error, any()}

Gets the full HTML contents of the frame, including the doctype.

Reference: https://playwright.dev/docs/api/class-frame#frame-content

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).

drag_and_drop(frame_id, opts \\ [])

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

Performs a drag-and-drop operation between two elements.

This method takes a source selector (the element to drag) and a target selector (the element to drop onto), then simulates dragging from the source element to the target element.

The method supports customization through optional parameters including:

Position specification: Define custom drag start and drop end points relative to element padding boxes
Actionability control: Bypass standard actionability checks if needed
Strict mode: Ensure selectors resolve to exactly one element
Timeout configuration: Set maximum operation duration
Trial mode: Perform actionability checks without executing the actual drag-and-drop action

Reference: https://playwright.dev/docs/api/class-frame#frame-drag-and-drop

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:source (String.t/0) - Required. A selector to search for the source element to drag.
:target (String.t/0) - Required. A selector to search for the target element to drop onto.
:strict (boolean/0) - When true, the call requires selector to resolve to a single element. The default value is true.

evaluate(frame_id, opts \\ [])

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

Executes JavaScript code within a frame's context and returns the result.

Returns the return value of the expression. If the function passed to evaluate/2 returns a Promise, then evaluate/2 would wait for the promise to resolve and return its value.

If the function passed to evaluate/2 returns a non-Serializable value, then evaluate/2 returns undefined. Playwright also supports transferring some additional values that are not serializable by JSON: -0, NaN, Infinity, -Infinity.

Reference: https://playwright.dev/docs/api/class-frame#frame-evaluate

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:expression (String.t/0) - Required. The JavaScript code to execute.
:is_function (boolean/0) - Whether the expression is a function. The default value is false.
:arg (term/0) - Optional argument to pass to the function. The default value is nil.

expect(frame_id, opts \\ [])

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

Internal method for setting up expectations on the frame.

This is an internal Playwright method used for implementing expectations and assertions on frame state.

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

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:is_not (boolean/0) - Whether to negate the expectation. The default value is false.
:expression (String.t/0) - Required.
:selector (String.t/0)
:expected_text (term/0)
:expected_number (term/0)

fill(frame_id, opts \\ [])

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

Waits for an element matching selector, waits for actionability checks, focuses the element, fills it and triggers an input event after filling.

You can pass an empty string to clear an input field. The method works with <input>, <textarea>, or [contenteditable] elements. If the target element is inside a <label> with an associated control, that control will be filled instead. The method throws an error if the element doesn't match the supported input types.

For more granular keyboard control, the documentation recommends using locator.pressSequentially() as an alternative.

Reference: https://playwright.dev/docs/api/class-frame#frame-fill

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.
:value (String.t/0) - Required. Value to fill for the <input>, <textarea>, or [contenteditable] element.
:strict (boolean/0) - When true, the call requires selector to resolve to a single element. The default value is true.

goto(frame_id, opts \\ [])

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

Navigates a frame to a specified URL and returns the main resource response. In cases of multiple redirects, it resolves with the final redirect's response.

The method throws an error in these scenarios:

SSL errors occur (e.g., self-signed certificates)
The target URL is invalid
Navigation timeout is exceeded
Remote server is unresponsive or unreachable
Main resource fails to load

However, it does not throw for valid HTTP status codes, including 404 or 500 responses—these can be retrieved via response.status().

Navigation to about:blank or same-URL hash changes return null rather than throwing. Headless mode cannot navigate to PDF documents.

Reference: https://playwright.dev/docs/api/class-frame#frame-goto

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:url (String.t/0) - Required. The destination URL, including scheme (e.g., https://) or a relative path (base_url was passed to PlaywrightEx.Browser.new_context/2).

inner_html(frame_id, opts \\ [])

@spec inner_html(PlaywrightEx.guid(), [inner_html_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, String.t()} | {:error, any()}

Returns the element.innerHTML property from a matching element.

This method returns the HTML content nested within the element, including all child elements and their markup.

Reference: https://playwright.dev/docs/api/class-frame#frame-inner-html

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.

press(frame_id, opts \\ [])

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

Focuses a matching element and activates a combination of keys.

Reference: https://playwright.dev/docs/api/class-frame#frame-press

This method waits for actionability checks, focuses the element, presses the specified key combination, and triggers keyboard events. If the element is detached during the action or exceeds the timeout, an error is thrown.

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.
:key (String.t/0) - Required. Name of the key to press or a character to generate, such as ArrowLeft or a.
:delay (non_neg_integer/0) - Time in milliseconds to wait between keydown and keyup. Defaults to 0. The default value is 0.

select_option(frame_id, opts \\ [])

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

Selects one or more options from a <select> element matching the provided selector.

This method waits for an element matching the selector, waits for actionability checks, waits until all specified options are present in the <select> element and selects these options. It triggers change and input events once all the provided options have been selected.

The method accepts options via value, label, index, or element reference and returns an array of the option values that were successfully selected. It throws an error if the target element is not a <select> element. However, if the element is inside a <label> element that has an associated control, the control will be used instead.

Reference: https://playwright.dev/docs/api/class-frame#frame-select-option

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.
:options (term/0) - Required. Option to select. Can be a single value, label, index, or element reference, or an array of these.
:strict (boolean/0) - When true, the call requires selector to resolve to a single element. The default value is true.

set_input_files(frame_id, opts \\ [])

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

Sets the value of the file input to these file paths or files.

This method expects selector to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead. If some of the file paths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

Note: This method is discouraged. Use locator-based locator.setInputFiles() instead.

Reference: https://playwright.dev/docs/api/class-frame#frame-set-input-files

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.
:local_paths (term/0) - Required. File path(s) to set. Can be a string or a list of strings. Relative paths are resolved relative to the current working directory.
:strict (boolean/0) - When true, the call requires selector to resolve to a single element. The default value is true.

title(frame_id, opts \\ [])

@spec title(PlaywrightEx.guid(), [title_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, String.t()} | {:error, any()}

Returns the page title.

Reference: https://playwright.dev/docs/api/class-frame#frame-title

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).

type(frame_id, opts \\ [])

This function is deprecated. Use `fill/2` or `press/2` instead.

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

Sends keydown, keypress/input, and keyup events for each character in the text.

Reference: https://playwright.dev/docs/api/class-frame#frame-type

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.
:text (String.t/0) - Required. Text to type into the element.
:delay (non_neg_integer/0) - Time to wait between key presses in milliseconds. Defaults to 0. The default value is 0.

uncheck(frame_id, opts \\ [])

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

Reference: https://playwright.dev/docs/api/class-frame#frame-uncheck

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required. A selector to search for an element.
:strict (boolean/0) - When true, the call requires selector to resolve to a single element. The default value is true.

url(frame_id, opts \\ [])

@spec url(PlaywrightEx.guid(), [url_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, String.t()} | {:error, any()}

Returns the frame's URL.

Reference: https://playwright.dev/docs/api/class-frame#frame-url

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).

wait_for_selector(frame_id, opts \\ [])

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

Returns when element specified by selector satisfies state option. Returns nil if waiting for hidden or detached.

This method waits for an element matching the selector to appear in the DOM, become visible, become hidden, or be detached, depending on the state option provided. If the selector already satisfies the condition at the time of calling, the method returns immediately. If the selector doesn't satisfy the condition within the timeout period, the function will throw an error.

The method works across navigations and will continue waiting for the element even if the page navigates to a different URL.

Reference: https://playwright.dev/docs/api/class-frame#frame-wait-for-selector

Options

:timeout (timeout/0) - Required. Maximum time for the operation (milliseconds).
:selector (String.t/0) - Required.