Playwright.Locator (playwright v1.18.0-alpha.1) View Source

Playwright.Locator represents a view to the element(s) on the page. It captures the logic sufficient to retrieve the element at any given moment. Locator can be created with the Playwright.Locator.new/2 function.

See also Playwright.Page.locator/2.

Example

locator = Playwright.Locator.new(page, "a#exists")
Playwright.Locator.click(locator)

The difference between the Playwright.Locator and Playwright.ElementHandle is that the latter points to a particular element, while Playwright.Locator captures the logic of how to retrieve that element.

ElementHandle Example

In the example below, handle points to a particular DOM element on page. If that element changes text or is used by React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to unexpected behaviors.

handle = Page.query_selector(page, "text=Submit")
ElementHandle.hover(handle)
ElementHandle.click(handle)

Locator Example

With the locator, every time the element is used, up-to-date DOM element is located in the page using the selector. So in the snippet below, underlying DOM element is going to be located twice.

locator = Playwright.Locator.new(page, "a#exists")
:ok = Playwright.Locator.hover(locator)
:ok = Playwright.Locator.click(locator)

Strictness

Locators are strict. This means that all operations on locators that imply some target DOM element will throw if more than one element matches given selector.

alias Playwright.Locator
locator = Locator.new(page, "button")

# Throws if there are several buttons in DOM:
Locator.click(locator)

# Works because we explicitly tell locator to pick the first element:
Locator.first(locator) |> Locator.click()

# Works because count knows what to do with multiple matches:
Locator.count(locator)

Link to this section Summary

Functions

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

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

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

Checks the (checkmark) element by performing the following steps

Clicks the element by performing the following steps

Returns the number of elements matching given selector.

Double clicks the element.

Dispatches the param: type event on the element.

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

Resolves given locator to all matching DOM elements.

Returns the result of executing param: expression.

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

Fills a form field or contenteditable element with text.

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

Calls focus on the element.

Returns element attribute value.

Hovers over the element.

Returns the element.innerHTML.

Returns the element.innerText.

Returns the input.value.

Returns whether the element is checked.

Returns whether the element is disabled.

Returns whether the element is editable.

Returns whether the element is enabled.

Returns whether the element is hidden.

Returns whether the element is visible.

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

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

Returns a %Playwright.Locator{}.

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

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

Returns a buffer with the captured screenshot data.

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

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

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

Checks or unchecks an element.

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

Returns a string representation of the Playwright.Locator.

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

Returns the node.textContent.

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

Unchecks the (checkmark) element by performing the following steps

Returns when element specified by locator satisfies option: state.

Link to this section Types

Specs

options() :: %{optional(:timeout) => non_neg_integer()}

Specs

options_click() :: %{
  optional(:button) => param_input_button(),
  optional(:click_count) => number(),
  optional(:delay) => number(),
  optional(:force) => boolean(),
  optional(:modifiers) => [:alt | :control | :meta | :shift],
  optional(:no_wait_after) => boolean(),
  optional(:position) => options_position(),
  optional(:timeout) => number(),
  optional(:trial) => boolean()
}

Specs

options_keyboard() :: %{
  optional(:delay) => non_neg_integer(),
  optional(:no_wait_after) => boolean(),
  optional(:timeout) => non_neg_integer()
}

Specs

options_position() :: %{optional(:x) => number(), optional(:y) => number()}

Specs

param_input_button() :: :left | :right | :middle

Specs

selector() :: binary()

Specs

serializable() :: any()

Specs

t() :: %Playwright.Locator{frame: Playwright.Frame.t(), selector: selector()}

Link to this section Functions

Link to this function

all_inner_texts(locator)

View Source

Specs

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

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

Returns

  • [binary()]
Link to this function

all_text_contents(locator)

View Source

Specs

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

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

Returns

  • [binary()]
Link to this function

bounding_box(locator, options \\ %{})

View Source

Specs

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

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2. (default: 30 seconds)
Link to this function

check(locator, options \\ %{})

View Source

Specs

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

key/nametypedescription
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:positionoption%{x: x, y: y}A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2. (default: 30 seconds)
:trialoptionboolean()When set, this call only performs the actionability checks and skips the action. Useful to wait until the element is ready for the action without performing it. (default: false)
Link to this function

click(locator, options \\ %{})

View Source

Specs

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.Channel.Error.t(). Passing 0 timeout disables this.

Returns

  • :ok

Arguments

key/nametypedescription
:buttonoption:left, :right or :middle(default: :left)
:click_countoptionnumber()See MDN: UIEvent.detail (default: 1)
:delayoptionnumber()Time to wait between mousedown and mouseup in milliseconds. (default: 0)
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:modifiersoption[:alt, :control, :meta, :shift]Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:positionoption%{x: x, y: y}A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2. (default: 30 seconds)
:trialoptionboolean()When set, this call only performs the actionability checks and skips the action. Useful to wait until the element is ready for the action without performing it. (default: false)

Specs

count(t()) :: number()

Returns the number of elements matching given selector.

Returns

  • number()
Link to this function

dblclick(locator, options \\ %{})

View Source

Specs

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

key/nametypedescription
:buttonoption:left, :right or :middle(default: :left)
:delayoptionnumber()Time to wait between keydown and keyup in milliseconds. (default: 0)
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:modifiersoption[:alt, :control, :meta, :shift]Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:positionoption%{x: x, y: y}A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
:trialoptionboolean()When set, this call only performs the actionability checks and skips the action. Useful to wait until the element is ready for the action without performing it. (default: false)
Link to this function

dispatch_event(locator, type, event_init \\ nil, options \\ %{})

View Source

Specs

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:

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

key/nametypedescription
typeparamatom() or binary()DOM event type: :click, :dragstart, etc.
event_initparamevaluation_argument()Optional event-specific initialization properties.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

element_handle(locator, options \\ %{})

View Source

Specs

element_handle(t(), options()) ::
  Playwright.ElementHandle.t() | {:error, Playwright.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.Channel.Error.t()}

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

element_handles(locator)

View Source

Specs

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

Resolves given locator to all matching DOM elements.

Returns

  • [Playwright.ElementHandle.t()]
Link to this function

evaluate(locator, expression, arg \\ nil, options \\ %{})

View Source

Specs

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

key/nametypedescription
expressionparambinary()JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted as a function. Otherwise, evaluated as an expression.
argparamany()Argument to pass to expression (optional)
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

evaluate_all(locator, expression, arg \\ nil)

View Source

Specs

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

key/nametypedescription
expressionparambinary()JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted as a function. Otherwise, evaluated as an expression.
argparamany()Argument to pass to expression (optional)
Link to this function

evaluate_handle(locator, expression, arg \\ nil, options \\ %{})

View Source

Specs

evaluate_handle(t(), binary(), any(), options()) ::
  Playwright.ElementHandle.t() | {:error, Playwright.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.Channel.Error.t()}

Arguments

key/nametypedescription
expressionparambinary()JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted as a function. Otherwise, evaluated as an expression.
argparamany()Argument to pass to expression (optional)
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

fill(locator, value, options \\ %{})

View Source

Specs

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

Returns

  • :ok

Arguments

key/nametypedescription
valueparambinary()Value to fill for the <input>, <textarea> or [contenteditable] element
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)

Specs

first(t()) :: t()

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

Link to this function

focus(locator, options \\ %{})

View Source

Specs

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

Calls focus on the element.

Returns

  • :ok

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

get_attribute(locator, name, options \\ %{})

View Source

Specs

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

Returns element attribute value.

Arguments

key/nametypedescription
nameparambinary()Name of the attribute to retrieve.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

hover(locator, options \\ %{})

View Source

Specs

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

key/nametypedescription
selectorparambinary()A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See "working with selectors (guide)" for more details.
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:modifiersoption[:alt, :control, :meta, :shift]Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:positionoption%{x: x, y: y}A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
:trialoptionboolean()When set, this call only performs the actionability checks and skips the action. Useful to wait until the element is ready for the action without performing it. (default: false)
Link to this function

inner_html(locator, options \\ %{})

View Source

Specs

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

Returns the element.innerHTML.

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

inner_text(locator, options \\ %{})

View Source

Specs

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

Returns the element.innerText.

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

input_value(locator, options \\ %{})

View Source

Specs

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

Returns the input.value.

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

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

is_checked(locator, options \\ %{})

View Source

Specs

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

Returns whether the element is checked.

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

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

is_disabled(locator, options \\ %{})

View Source

Specs

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

Returns whether the element is disabled.

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

is_editable(locator, options \\ %{})

View Source

Specs

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

Returns whether the element is editable.

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

is_enabled(locator, options \\ %{})

View Source

Specs

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

Returns whether the element is enabled.

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

is_hidden(locator, options \\ %{})

View Source

Specs

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

Returns whether the element is hidden.

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

is_visible(locator, options \\ %{})

View Source

Specs

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

Returns whether the element is visible.

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)

Specs

last(t()) :: t()

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

Link to this function

locator(locator, selector)

View Source

Specs

locator(t(), binary()) :: t()

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

Specs

Returns a %Playwright.Locator{}.

Arguments

key/nametypedescription

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

Specs

nth(t(), term()) :: t()

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

Link to this function

press(locator, key, options \\ %{})

View Source

Specs

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

key/nametypedescription
keyparambinary()Name of the key to press or a character to generate, such as ArrowLeft or a.
:delayoptionnumber()Time to wait between mousedown and mouseup in milliseconds. (default: 0)
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

screenshot(locator, options \\ %{})

View Source

Specs

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

key/nametypedescription
:omit_backgroundoptionboolean()Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. (default: false)
:pathoptionbinary()The file path to which to save the image. The screenshot type will be inferred from file extension. If path is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk.
:qualityoptionnumber()The quality of the image, between 0-100. Not applicable to png images.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
:typeoption:png or :jpegSpecify screenshot type. (default: :png)
Link to this function

scroll_into_view(locator, options \\ %{})

View Source

Specs

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

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

select_option(locator, values, options \\ %{})

View Source

Specs

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

key/nametypedescription
valuesparamany()Options to select.
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)

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).
Link to this function

select_text(locator, options \\ %{})

View Source

Specs

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

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

Arguments

key/nametypedescription
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

set_checked(locator, checked, options \\ %{})

View Source

Specs

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

key/nametypedescription
checkedparamboolean()Whether to check or uncheck the checkbox.
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:positionoption%{x: x, y: y}A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2. (default: 30 seconds)
:trialoptionboolean()When set, this call only performs the actionability checks and skips the action. Useful to wait until the element is ready for the action without performing it. (default: false)
Link to this function

set_input_files(locator, files, options \\ %{})

View Source

Specs

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.

Arguments

key/nametypedescription
filesparamany()...
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)

Specs

string(t()) :: binary()

Returns a string representation of the Playwright.Locator.

Link to this function

tap(locator, options \\ %{})

View Source

Specs

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

key/nametypedescription
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:modifiersoption[:alt, :control, :meta, :shift]Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:positionoption%{x: x, y: y}A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2. (default: 30 seconds)
:trialoptionboolean()When set, this call only performs the actionability checks and skips the action. Useful to wait until the element is ready for the action without performing it. (default: false)
Link to this function

text_content(locator, options \\ %{})

View Source

Specs

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

Returns the node.textContent.

Arguments

key/nametypedescription
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed by using the Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2 functions. (default: 30 seconds)
Link to this function

type(locator, text, options \\ %{})

View Source

Specs

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

key/nametypedescription
textparambinary()Text to type into a focused element.
:delayoptionnumber()Time to wait between mousedown and mouseup in milliseconds. (default: 0)
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2. (default: 30 seconds)
Link to this function

uncheck(locator, options \\ %{})

View Source

Specs

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

key/nametypedescription
:forceoptionboolean()Whether to bypass the actionability checks. (default: false)
:no_wait_afteroptionboolean()Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. (default: false)
:positionoption%{x: x, y: y}A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
:timeoutoptionnumber()Maximum time in milliseconds. Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2 or Playwright.Page.set_default_timeout/2. (default: 30 seconds)
:trialoptionboolean()When set, this call only performs the actionability checks and skips the action. Useful to wait until the element is ready for the action without performing it. (default: false)
Link to this function

wait_for(locator, options \\ %{})

View Source

Specs

wait_for(t(), options()) :: :ok

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.

Options

key/nametypedescription
:stateoptionstate optionDefaults to visible. See "state options" below"
:timeoutoptionfloatMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the browser_context.set_default_timeout(timeout) or page.set_default_timeout(timeout) methods.

State options

valuedescription
'attached'wait for element to be present in DOM.
'detached'wait for element to not be present in DOM.
'visible'wait for element to have non-empty bounding box and no visibility:hidden. Note that element without any content or with display:none has an empty bounding box and is not considered visible.
'hidden'wait for element to be either detached from DOM, or have an empty bounding box or visibility:hidden. This is opposite to the 'visible' option.