# `PlaywrightEx.Frame`
[🔗](https://github.com/probably-not/playwright_ex/blob/v0.5.0-fork.2/lib/playwright_ex/channels/frame.ex#L1)

Interact with a Playwright `Frame` (usually the "main" frame of a browser 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/frame.ts

# `blur_opt`

```elixir
@type blur_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
```

# `check_opt`

```elixir
@type check_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `click_opt`

```elixir
@type click_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `content_opt`

```elixir
@type content_opt() :: {:connection, GenServer.name()} | {:timeout, timeout()}
```

# `dispatch_event_opt`

```elixir
@type dispatch_event_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:type, binary()}
  | {:event_init, term()}
  | {:strict, boolean()}
```

# `drag_and_drop_opt`

```elixir
@type drag_and_drop_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:source, binary()}
  | {:target, binary()}
  | {:strict, boolean()}
```

# `evaluate_opt`

```elixir
@type evaluate_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:expression, binary()}
  | {:is_function, boolean()}
  | {:arg, term()}
```

# `expect_opt`

```elixir
@type expect_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:is_not, boolean()}
  | {:expression, binary()}
  | {:selector, binary()}
  | {:expected_text, term()}
  | {:expected_number, term()}
  | {:expression_arg, term()}
```

# `fill_opt`

```elixir
@type fill_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:value, binary()}
  | {:strict, boolean()}
```

# `focus_opt`

```elixir
@type focus_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `get_attribute_opt`

```elixir
@type get_attribute_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:name, binary()}
  | {:strict, boolean()}
```

# `goto_opt`

```elixir
@type goto_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:url, binary()}
```

# `hover_opt`

```elixir
@type hover_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `inner_html_opt`

```elixir
@type inner_html_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
```

# `inner_text_opt`

```elixir
@type inner_text_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `input_value_opt`

```elixir
@type input_value_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `is_checked_opt`

```elixir
@type is_checked_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `is_disabled_opt`

```elixir
@type is_disabled_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `is_editable_opt`

```elixir
@type is_editable_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `is_enabled_opt`

```elixir
@type is_enabled_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `is_visible_opt`

```elixir
@type is_visible_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `press_opt`

```elixir
@type press_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:key, binary()}
  | {:delay, non_neg_integer()}
```

# `select_option_opt`

```elixir
@type select_option_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:options, term()}
  | {:strict, boolean()}
```

# `set_input_files_opt`

```elixir
@type set_input_files_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:local_paths, term()}
  | {:strict, boolean()}
```

# `text_content_opt`

```elixir
@type text_content_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `title_opt`

```elixir
@type title_opt() :: {:connection, GenServer.name()} | {:timeout, timeout()}
```

# `type_opt`

```elixir
@type type_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:text, binary()}
  | {:delay, non_neg_integer()}
```

# `uncheck_opt`

```elixir
@type uncheck_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:strict, boolean()}
```

# `url_opt`

```elixir
@type url_opt() :: {:connection, GenServer.name()} | {:timeout, timeout()}
```

# `wait_for_function_opt`

```elixir
@type wait_for_function_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:expression, binary()}
  | {:is_function, boolean()}
  | {:arg, term()}
  | {:polling, pos_integer() | binary()}
```

# `wait_for_load_state_opt`

```elixir
@type wait_for_load_state_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:state, term()}
```

# `wait_for_selector_opt`

```elixir
@type wait_for_selector_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector, binary()}
  | {:state, term()}
  | {:strict, boolean()}
```

# `wait_for_url_opt`

```elixir
@type wait_for_url_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:url, binary() | struct() | (term() -> term())}
  | {:wait_until, term()}
```

# `blur`

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

Calls the native [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) function on the matching element, which removes focus from that element.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

# `check`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `click`

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

Clicks an element matching selector by performing the following steps:

1. Locates an element matching the provided selector, waiting if necessary for it to appear in the DOM
2. Performs actionability checks unless the force option is enabled; retries if the element detaches during checks
3. Scrolls the element into view as needed
4. Uses the mouse to click at the element's center or a specified position
5. 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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `content`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

# `dispatch_event`

```elixir
@spec dispatch_event(PlaywrightEx.guid(), [
  dispatch_event_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Dispatches a DOM event on the matching element.

The event is composed from the given `type` and optional `event_init` properties. Events are composed,
not triggered, meaning event listeners are dispatched and any default actions can be prevented.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:type` (`t:String.t/0`) - Required. DOM event type: `"click"`, `"mousedown"`, etc.

* `:event_init` (`t:term/0`) - Optional event-specific initialization properties. The default value is `nil`.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `drag_and_drop`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:source` (`t:String.t/0`) - Required. A selector to search for the source element to drag.

* `:target` (`t:String.t/0`) - Required. A selector to search for the target element to drop onto.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `evaluate`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:expression` (`t:String.t/0`) - Required. The JavaScript code to execute.

* `:is_function` (`t:boolean/0`) - Whether the expression is a function. The default value is `false`.

* `:arg` (`t:term/0`) - Optional argument to pass to the function. The default value is `nil`.

# `expect`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:is_not` (`t:boolean/0`) - Whether to negate the expectation. The default value is `false`.

* `:expression` (`t:String.t/0`) - Required.

* `:selector` (`t:String.t/0`)

* `:expected_text` (`t:term/0`)

* `:expected_number` (`t:term/0`)

* `:expression_arg` (`t:term/0`)

# `fill`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:value` (`t:String.t/0`) - Required. Value to fill for the `<input>`, `<textarea>`, or `[contenteditable]` element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `focus`

```elixir
@spec focus(PlaywrightEx.guid(), [focus_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}
```

Focuses the matching element.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `get_attribute`

```elixir
@spec get_attribute(PlaywrightEx.guid(), [
  get_attribute_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, String.t() | nil} | {:error, any()}
```

Returns the element attribute value for the matching element.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:name` (`t:String.t/0`) - Required. Attribute name to get the value for.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `goto`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:url` (`t: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`).

# `hover`

```elixir
@spec hover(PlaywrightEx.guid(), [hover_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}
```

Hovers over an element matching selector.

This method is discouraged in favor of using locator-based `locator.hover()` instead.

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

## Example

    # Hover before manual drag (see https://playwright.dev/docs/input#dragging-manually)
    {:ok, _} = Frame.hover(frame_id, selector: "#item-to-be-dragged", timeout: 5000)

    # Get element position
    {:ok, box} = Frame.evaluate(frame_id,
      expression: "() => {
        const el = document.querySelector('#item-to-be-dragged');
        const box = el.getBoundingClientRect();
        return { x: box.x, y: box.y };
      }",
      is_function: true,
      timeout: 5000
    )

    # Drag 200px to the right
    {:ok, _} = Page.mouse_down(page_id, timeout: 5000)
    {:ok, _} = Page.mouse_move(page_id, x: box["x"] + 200, y: box["y"], timeout: 5000)
    {:ok, _} = Page.mouse_up(page_id, timeout: 5000)

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `inner_html`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

# `inner_text`

```elixir
@spec inner_text(PlaywrightEx.guid(), [inner_text_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, String.t()} | {:error, any()}
```

Returns `element.innerText` for the matching element.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `input_value`

```elixir
@spec input_value(PlaywrightEx.guid(), [
  input_value_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, String.t()} | {:error, any()}
```

Returns the value for the matching `<input>`, `<textarea>`, or `<select>` element.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `is_checked`

```elixir
@spec is_checked(PlaywrightEx.guid(), [is_checked_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, boolean()} | {:error, any()}
```

Returns whether the checkbox or radio element matching the selector is checked.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `is_disabled`

```elixir
@spec is_disabled(PlaywrightEx.guid(), [
  is_disabled_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, boolean()} | {:error, any()}
```

Returns whether the element matching the selector is disabled.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `is_editable`

```elixir
@spec is_editable(PlaywrightEx.guid(), [
  is_editable_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, boolean()} | {:error, any()}
```

Returns whether the element matching the selector is editable.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `is_enabled`

```elixir
@spec is_enabled(PlaywrightEx.guid(), [is_enabled_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, boolean()} | {:error, any()}
```

Returns whether the element matching the selector is enabled.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `is_visible`

```elixir
@spec is_visible(PlaywrightEx.guid(), [is_visible_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, boolean()} | {:error, any()}
```

Returns whether the element matching the selector is visible.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `press`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:key` (`t:String.t/0`) - Required. Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.

* `:delay` (`t:non_neg_integer/0`) - Time in milliseconds to wait between `keydown` and `keyup`. Defaults to 0. The default value is `0`.

# `select_option`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:options` (`t:term/0`) - Required. Option to select. Can be a single value, label, index, or element reference, or an array of these.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `set_input_files`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:local_paths` (`t: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` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `text_content`

```elixir
@spec text_content(PlaywrightEx.guid(), [
  text_content_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, String.t() | nil} | {:error, any()}
```

Returns `element.textContent` for the matching element.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `title`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

# `type`

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

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:text` (`t:String.t/0`) - Required. Text to type into the element.

* `:delay` (`t:non_neg_integer/0`) - Time to wait between key presses in milliseconds. Defaults to 0. The default value is `0`.

# `uncheck`

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

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.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `url`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

# `wait_for_function`

```elixir
@spec wait_for_function(PlaywrightEx.guid(), [
  wait_for_function_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Waits for the provided JavaScript expression to return a truthy value.

Returns a JSHandle for the expression's return value once it becomes truthy. If the expression throws
during evaluation, the method will keep retrying until it either succeeds or the timeout is reached.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:expression` (`t:String.t/0`) - Required. JavaScript expression to evaluate.

* `:is_function` (`t:boolean/0`) - Whether the expression is a function. The default value is `false`.

* `:arg` (`t:term/0`) - Optional argument to pass to the function. The default value is `nil`.

* `:polling` - Polling interval in ms, or `"raf"` for requestAnimationFrame. The default value is `"raf"`.

# `wait_for_selector`

```elixir
@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
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:selector` (`t:String.t/0`) - Required. A selector to search for an element.

* `:state` - State to wait for: "attached", "detached", "visible" (default), or "hidden". The default value is `"visible"`.

* `:strict` (`t:boolean/0`) - When true, the call requires selector to resolve to a single element. The default value is `true`.

# `wait_for_load_state`

```elixir
@spec wait_for_load_state(PlaywrightEx.guid(), [
  wait_for_load_state_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Waits for the frame to reach the requested load state.

This uses a navigation-event model:
- listens for frame/page lifecycle events (`:loadstate`, `:navigated`, close/crash/dispose),
- resolves when `state` is reached for the tracked frame.

This is event-based waiting, not JavaScript polling. It does not repeatedly evaluate
`document.readyState` in page context, so it remains valid across navigations and document changes.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:state` - Load state to wait for: "domcontentloaded", "load" (default), "networkidle", or "commit". The default value is `"load"`.

# `wait_for_url`

```elixir
@spec wait_for_url(PlaywrightEx.guid(), [
  wait_for_url_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Waits for the frame to navigate to a URL matching `url`.

Behavior is event-based:
- If current URL already matches, waits only for `wait_until` load state.
- Otherwise waits for a matching navigation event, then waits for `wait_until`.
- URL and lifecycle state are tracked from protocol navigation/load events.

This does not poll `window.location.href` in page JavaScript. It remains robust when
document/context is replaced during navigation.

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

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

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

* `:url` - Required. URL matcher to wait for. Supports a string (exact or glob `*`/`**`), `Regex`, or a function `fn URI.t() -> boolean end`.

* `:wait_until` - When to consider operation succeeded: "load" (default), "domcontentloaded", "networkidle", or "commit". The default value is `"load"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*