@spec all(t()) :: [t()]

When the locator points to a list of elements, returns a list of locators, each addressing their respective elements.

NOTE

Playwright.Locator.all/1 does not wait for elements to match the locator, and instead immediately returns whatever is present in the page. When the list of elements changes dynamically, Playwright.Locator.all/1 will produce unpredictable and flaky results. When the list of elements is stable, but loaded dynamically, wait for the full list to finish loading before calling `Playwright.Locator.all/1``.

Returns

• [Playwright.Locator]

Example

Retrieve the text for all <p> elements currently on the page:

Playwright.Page.locator(page, "p")
|> Playwright.Locator.all()
|> Enum.map(fn locator -> Playwright.Locator.text_content(locator) end)

@spec all_inner_texts(t()) :: [binary()]

Returns an list of node.innerText values for all matching nodes.

Returns

• [binary()]

Example

Retrieve the text for all <p> elements currently on the page:

Playwright.Page.locator(page, "p")
|> Playwright.Locator.all_inner_texts()

@spec all_text_contents(t()) :: [binary()]

Returns an list of node.textContent values for all matching nodes.

Returns

• [binary()]

Example

Retrieve the text for all <p> elements currently on the page:

Playwright.Page.locator(page, "p")
|> Playwright.Locator.all_text_contents()

@spec bounding_box(t(), options()) :: map() | nil

Returns the bounding box of the element, or nil if the element is not visible.

The bounding box is calculated relative to the main frame viewport which is usually the same as the browser window.

Scrolling affects the returned bounding box, similarly to Element.getBoundingClientRect.

That means x and/or y may be negative.

Elements from child frames return the bounding box relative to the main frame, unlike Element.getBoundingClientRect.

Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following snippet should click the center of the element:options()

box = Locator.bounding_box(locator)
Page.Mouse.click(page, box.x + box.width / 2, box.y + box.height / 2)

Returns

• %{x: x, y: y, width: width, height: height}
• nil

Arguments

@spec check(t(), options()) :: :ok

Checks the (checkmark) element by performing the following steps:

1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
2. Wait for actionability checks on the element, unless force option is set.
3. Scroll the element into view if needed.
4. Use Playwright.Page.Mouse to click in the center of the element.
5. Wait for initiated navigations to either succeed or fail, unless option: no_wait_after is set.
6. Ensure that the element is now checked. If not, this method throws.

If the element is detached from the DOM at any moment during the action, this method throws.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing 0 timeout disables this.

Returns

• :ok

Arguments

@spec clear(t(), options()) :: :ok

Clears the contents of a form input/textarea field.

@spec click(t(), options_click()) :: :ok

Clicks the element by performing the following steps:

1. Wait for actionability checks on the element, unless option: force is set.
2. Scroll the element into view if needed.
3. Use Playwright.Page.Mouse to click in the center of the element, or the specified position.
4. Wait for initiated navigations to either succeed or fail, unless option: no_wait_after is set.

If the element is detached from the DOM at any moment during the action, this method throws.

When all steps combined have not finished during the specified timeout, this method throws a Playwright.SDK.Channel.Error.t(). Passing 0 timeout disables this.

Returns

• :ok

Arguments

@spec count(t()) :: number()

Returns the number of elements matching given selector.

Returns

• number()

@spec dblclick(t(), options()) :: :ok

Double clicks the element.

Performs the following steps:

1. Wait for actionability checks on the matched element, unless option: force is set.
2. Scroll the element into view if needed. 3 Use Page.Mouse to double click in the center of the element, or the specified option: position.
3. Wait for initiated navigations to either succeed or fail, unless option: no_wait_after is set. Note that if the first click of the dblclick/3 triggers a navigation event, the call will throw.

If the element is detached from the DOM at any moment during the action, the call throws.

When all steps combined have not finished during the specified option: timeout, throws a TimeoutError. Passing timeout: 0 disables this.

NOTE

dblclick/3 dispatches two click events and a single dblclick event.

Returns

• :ok

Arguments

@spec dispatch_event(
  t(),
  atom() | binary(),
  Playwright.Frame.evaluation_argument(),
  options()
) :: :ok

Dispatches the param: type event on the element.

Regardless of the visibility state of the element, the event is dispatched.

Under the hood, creates an instance of an event based on the given type, initializes it with the param: event_init properties and dispatches it on the element.

Events are composed, cancelable and bubble by default.

The param: event_init is event-specific. Please refer to the events documentation for the lists of initial properties:

• DragEvent
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• Event

Example

Dispatch a 'click' event on the element. This is equivalent to calling Playwright.ElementHandle.click/2:

Locator.dispatch_event(locator, :click)

Specify a Playwright.JSHandle as the property value to be passed into the event:

data_transfer = Page.evaluate_handle(page, "new DataTransfer()")
Locator.dispatch_event(locator, :dragstart, { "dataTransfer": data_transfer })

Returns

• :ok

Arguments

@spec element_handle(t(), options()) ::
  Playwright.ElementHandle.t() | {:error, Playwright.SDK.Channel.Error.t()}

Resolves the given Playwright.Locator to the first matching DOM element.

If no elements matching the query are visible, waits for them up to a given timeout. If multiple elements match the selector, throws.

Returns

• Playwright.ElementHandle.t()
• {:error, Playwright.SDK.Channel.Error.t()}

Arguments

@spec element_handles(t()) :: [Playwright.ElementHandle.t()]

Resolves given locator to all matching DOM elements.

Returns

• [Playwright.ElementHandle.t()]

@spec evaluate(t(), binary(), any(), options()) :: serializable()

Returns the result of executing param: expression.

Passes the handle as the first argument to the expression.

Returns

• Serializable.t()

Arguments

@spec evaluate_all(t(), binary(), any()) :: serializable()

Finds all elements matching the specified locator and passes the list of matched elements as an argument to param: expression.

Returns the result of expression invocation.

Returns

• Serializable.t()

Arguments

@spec evaluate_handle(t(), binary(), any(), options()) ::
  Playwright.ElementHandle.t() | {:error, Playwright.SDK.Channel.Error.t()}

Returns the result of param: expression as a Playwright.JSHandle.

Passes the handle as the first argument to param: expression.

The only difference between Playwright.Locator.evaluate/4 and Playwright.Locator.evaluate_handle/3 is that evaluate_handle returns JSHandle.

See Playwright.Page.evaluate_handle for more details.

Returns

• Playwright.ElementHandle.t()
• {:error, Playwright.SDK.Channel.Error.t()}

Arguments

@spec fill(t(), binary(), options()) :: :ok

Fills a form field or contenteditable element with text.

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

If the target element is not an <input>, <textarea> or contenteditable element, this function raises an error. However, if the element is inside the <label> element that has an associated control, the control will be filled instead.

NOTE

• Pass an empty string to clear the input field.
• To send fine-grained keyboard events, use Playwright.Locator.type/3.

Returns

• :ok

Arguments

@spec first(t()) :: t()

Returns a new Playwright.Locator scoped to the first matching element.

@spec focus(t(), options()) :: :ok

Calls focus on the element.

Returns

• :ok

Arguments

@spec get_attribute(t(), binary(), options()) :: binary() | nil

Returns element attribute value.

Arguments

@spec get_by_text(t(), binary(), %{optional(:exact) => boolean()}) :: t()

Allows locating elements that contain given text.

Arguments

@spec hover(t(), options()) :: :ok

Hovers over the element.

Performs the following steps:

1. Wait for actionability checks on the matched element, unless option: force option is set. If the element is detached during the checks, the whole action is retried.
2. Scroll the element into view if needed.
3. Use Page.Mouse to hover over the center of the element, or the specified option: position.
4. Wait for initiated navigations to either succeed or fail, unless option: no_wait_after is set.

When all steps combined have not finished during the specified option: timeout, throws a TimeoutError. Passing 0 timeout disables this.

Returns

• :ok

Arguments

@spec inner_html(t(), options()) :: binary()

Returns the element.innerHTML.

Arguments

@spec inner_text(t(), options()) :: binary()

Returns the element.innerText.

Arguments

@spec input_value(t(), options()) :: binary()

Returns the input.value.

Works on <input>, <textarea>, or <select> elements. Throws for non-input elements.

Arguments

@spec is_checked(t(), options()) :: boolean()

Returns whether the element is checked.

Throws if the element is not a checkbox or radio input.

Arguments

@spec is_disabled(t(), options()) :: boolean()

Returns whether the element is disabled.

Arguments

@spec is_editable(t(), options()) :: boolean()

Returns whether the element is editable.

Arguments

@spec is_enabled(t(), options()) :: boolean()

Returns whether the element is enabled.

Arguments

@spec is_hidden(t(), options()) :: boolean()

Returns whether the element is hidden.

Arguments

@spec is_visible(t(), options()) :: boolean()

Returns whether the element is visible.

Arguments

@spec last(t()) :: t()

Returns a new Playwright.Locator scoped to the last matching element.

@spec locator(t(), binary()) :: t()

Returns a new Playwright.Locator scoped to the Locator's subtree.

@spec new(Playwright.Frame.t() | Playwright.Page.t(), selector()) :: t()

Creates a Playwright.Locator.

Returns

• Playwright.Locator

Arguments

| frame or page | param | Frame.t() | Page.t() | | | selector | param | binary() | A Playwright selector. |

@spec nth(t(), term()) :: t()

Returns a new Playwright.Locator scoped to the n-th matching element.

@spec press(t(), binary(), options_keyboard()) :: :ok

Focuses the element, and then uses keyboard.down(key) and keyboard.up(key).

param: key can specify the intended keyboardEvent.key value or a single character. A superset of the key values can be found on MDN.

Examples of the keys are:

• F1 - F12
• Digit0 - Digit9
• KeyA - KeyZ
• Backquote
• Minus
• Equal
• Backslash
• Backspace
• Tab
• Delete
• Escape
• ArrowDown
• End
• Enter
• Home
• Insert
• PageDown
• PageUp
• ArrowRight
• ArrowUp

The fllowing modification shortcuts are also supported:

• Shift
• Control
• Alt
• Meta
• ShiftLeft

Holding down Shift will type the text that corresponds to the param: key in the upper case.

If param: key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

Shortcuts such as key: "Control+o" or key: "Control+Shift+T" are supported as well. When specified with the modifier, modifier is pressed and held while the subsequent key is pressed.

Arguments

@spec screenshot(t(), options()) :: binary()

Returns a buffer with the captured screenshot data.

Waits for the actionability checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, throws an error.

Arguments

@spec scroll_into_view(t(), options()) :: :ok

Waits for actionability checks, then tries to scroll element into view, unless it is completely visible as defined by IntersectionObserver's ratio.

Arguments

@spec select_option(t(), any(), options()) :: [binary()]

Selects one or more options from a <select> element.

Performs the following steps:

1. Waits for actionability checks
2. Waits until all specified options are present in the <select> element
3. Selects those options

If the target element is not a <select> element, raises an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

Returns the list of option values that have been successfully selected.

Triggers a change and input event once all the provided options have been selected.

Example

alias Playwright.Locator
locator = Locator.new(page, "select#colors")

# single selection matching the value
Locator.select_option(locator, "blue")

# single selection matching both the label
Locator.select_option(locator, %{label: "blue"})

# multiple selection
Locator.select_option(locator, %{value: ["red", "green", "blue"]})

Returns

• [binary()]

Arguments

On values

If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected.

String values are equivalent to %{value: "string"}.

Option is considered matching if all specified properties match.

• value <binary> Matches by option.value. (optional).
• label <binary> Matches by option.label. (optional).
• index <number> Matches by the index. (optional).

@spec select_text(t(), options()) :: :ok

Waits for actionability checks, then focuses the element and selects all its text content.

Arguments

@spec set_checked(t(), boolean(), options()) :: :ok

Checks or unchecks an element.

Performs the following steps and checks:

1. Ensure that the matched element is a checkbox or a radio input. If not, the call throws.
2. If the element already has the right checked state, returns immediately.
3. Wait for actionability checks on the matched element, unless option: force is set. If the element is detached during the checks, the whole action is retried.
4. Scroll the element into view if needed.
5. Use Page.Mouse to click in the center of the element.
6. Wait for initiated navigations to either succeed or fail, unless option: no_wait_after is set.
7. Ensure that the element is now checked or unchecked. If not, the call throws.

When all steps combined have not finished during the specified timeout, throws a TimeoutError. Passing 0 timeout disables this.

Arguments

@spec set_input_files(t(), any(), options()) :: :ok

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

If some of the file paths are relative paths, they are resolved relative to the the current working directory. An empty list, clears the selected files.

Expects element (i.e., locator.selector) to point to an input element.

NOTE:

Of payloads, local_paths, and streams playwright-core capabilities,

only local_paths is currently supported by playwright-elixir.

Arguments

@spec string(t()) :: binary()

Returns a string representation of the Playwright.Locator.

@spec tap(t(), options()) :: :ok

Taps the element (i.e., mimicking trackpad input).

Performs the following steps:

1. Wait for actionability checks on the element, unless option: force is set.
2. Scroll the element into view if needed.
3. Use Page.Touchscreen to tap the center of the element, or the specified position.
4. Wait for initiated navigations to either succeed or fail, unless option: no_wait_after is set.

If the element is detached from the DOM at any moment during the action, throws an error.

When all steps combined have not finished during the specified timeout, throws a TimeoutError. Passing 0 timeout disables this.

NOTE:

tap/2 requires that the :has_touch option of the browser context be set to true.

Arguments

@spec text_content(t(), options()) :: binary()

Returns the node.textContent.

Arguments

@spec type(t(), binary(), options_keyboard()) :: :ok

Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.

To press a special key, like Control or ArrowDown, use Playwright.Locator.press/3.

Arguments

@spec uncheck(t(), options()) :: :ok

Unchecks the (checkmark) element by performing the following steps:

1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
2. Wait for actionability checks on the element, unless force option is set.
3. Scroll the element into view if needed.
4. Use Playwright.Page.Mouse to click in the center of the element.
5. Wait for initiated navigations to either succeed or fail, unless option: no_wait_after is set.
6. Ensure that the element is now checked. If not, this method throws.

If the element is detached from the DOM at any moment during the action, this method throws.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing 0 timeout disables this.

Returns

• :ok

Arguments

@spec wait_for(t(), options()) :: t() | {:error, Playwright.SDK.Channel.Error.t()}

Returns when element specified by locator satisfies option: state.

If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to option: timeout milliseconds until the condition is met.

Returns

• Locator.t()

Arguments

Options for :state

Example

...