Playwright.Frame (playwright v0.1.17-preview-1) View Source

At any point of time, Playwright.Page exposes its current frame tree via the Playwright.Page.main_frame/1 and Playwright.Frame.child_frames/1 functions.

A Frame instance lifecycle is governed by three events, dispatched on the Playwright.Page resource:

  • Page event: :frame_attached - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
  • Page event: :frame_navigated - fired when the frame commits navigation to a different URL.
  • Page event: :frame_detached - fired when the frame gets detached from the page. A Frame can be detached from the page only once.

Link to this section Summary

Functions

Clicks an element matching param: selector, performing the following steps

Double clicks an element matching selector.

Dispatches the param: type event on the param: selector element.

Returns the return value of expression.

Returns the return value of expression as a Playwright.JSHandle.

Fills a form field or contenteditable element with text.

Fetches an element with param: selector and focuses it.

Returns element attribute value. !!!

Hovers over an element matching param: selector.

Optional callback implementation for Playwright.ChannelOwner.init/2.

param: key can specify the intended keyboardEvent.key value or a single character for which to generate the text.

See Playwright.Frame.query_selector!/3.

Returns the list of Playwright.ElementHandle pointing to the frame elements.

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

Returns

  • :ok

Arguments

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

Returns the page title.

Waits for the required load state to be reached.

Returns when element specified by selector satisfies state option.

Link to this section Types

Specs

evaluation_argument() :: any()

Specs

expression() :: binary()

Specs

load_state() :: atom() | binary()

Specs

options() :: map()

Specs

serializable() :: any()

Specs

t() :: %Playwright.Frame{
  connection: term(),
  guid: term(),
  initializer: term(),
  listeners: term(),
  load_states: term(),
  parent: term(),
  type: term(),
  url: term()
}

%Playwright.Frame{}

Link to this section Functions

Link to this function

click(owner, selector, options \\ %{})

View Source

Specs

click(
  t() | Playwright.Page.t() | {:ok, t() | Playwright.Page.t()},
  binary(),
  options()
) :: :ok

Clicks an element matching param: selector, performing the following steps:

  1. Find an element matching param: selector. If there is none, wait until a matching element is attached to the DOM.
  2. Wait for "actionability (guide)" checks on the matched element, unless option: force option is set. If the element is detached during the checks, the whole action is retried.
  3. Scroll the element into view if needed.
  4. Use Playwright.Page.Mouse to click the center of the element, or the specified option: position.
  5. Wait for initiated navigations to either succeed or fail, unless option: :no_wait_after option is set.

When all steps combined have not finished during the specified option: timeout, /click/3 raises a TimeoutError. Passing zero for option: timeout disables this.

Link to this function

dblclick(frame, selector, options \\ %{})

View Source

Specs

dblclick(t(), binary(), options()) :: :ok

Double clicks an element matching selector.

Performs the following steps:

  1. Find an element matching param: selector. If there is none, wait until a matching element is attached to the DOM.
  2. 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.
  3. Scroll the element into view if needed.
  4. Use Page.Mouse to double click in the center of the element, or the specified option: position.
  5. 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.

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
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.
: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.
:strictoptionboolean()When true, the call requires selector to resolve to a single element. If given selector resolves to more then one element, the call throws an exception.
: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(frame, selector, type, event_init \\ nil, options \\ %{})

View Source

Specs

dispatch_event(t(), binary(), binary(), evaluation_argument(), options()) :: :ok

Dispatches the param: type event on the param: selector 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:

Frame.dispatch_event(frame, "button#submit", :click)

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

data_transfer = Frame.evaluate_handle(frame, "new DataTransfer()")
Frame.dispatch_event(frame, "#source", :dragstart, { "dataTransfer": data_transfer })

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.
typeparamatom() or binary()DOM event type: :click, :dragstart, etc.
event_initparamevaluation_argument()Optional event-specific initialization properties.
:strictoptionboolean()When true, the call requires selector to resolve to a single element. If given selector resolves to more then one element, the call throws an exception.
: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

eval_on_selector(frame, selector, expression, arg \\ nil, options \\ %{})

View Source

Specs

eval_on_selector(t(), binary(), binary(), term(), map()) :: term()

Returns the return value of expression.

!!!

Link to this function

eval_on_selector_all(frame, selector, expression, arg \\ nil)

View Source
Link to this function

evaluate(owner, expression, arg \\ nil)

View Source

Specs

evaluate(
  t() | Playwright.Page.t() | {:ok, t() | Playwright.Page.t()},
  expression(),
  any()
) :: {:ok, serializable()}

Returns the return value of expression.

!!!

Link to this function

evaluate_handle(owner, expression, arg \\ nil)

View Source

Specs

evaluate_handle(
  t() | Playwright.Page.t() | {:ok, t() | Playwright.Page.t()},
  expression(),
  any()
) :: {:ok, serializable()}

Returns the return value of expression as a Playwright.JSHandle.

!!!

Link to this function

fill(frame, selector, value, options \\ %{})

View Source

Specs

fill(t() | Playwright.Page.t(), binary(), 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.Frame.type/4.

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.
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)
:strictoptionboolean()When true, the call requires selector to resolve to a single element. If given selector resolves to more then one element, the call throws an exception.
: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

focus(frame, selector, options \\ %{})

View Source

Specs

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

Fetches an element with param: selector and focuses it.

If no element matches the selector, waits until a matching element appears in the DOM.

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.
:strictoptionboolean()When true, the call requires selector to resolve to a single element. If given selector resolves to more then one element, the call throws an exception.
: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(owner, selector, name, options \\ %{})

View Source

Specs

get_attribute(
  t() | Playwright.Page.t() | {:ok, t() | Playwright.Page.t()},
  binary(),
  binary(),
  map()
) :: {:ok, binary() | nil}

Returns element attribute value. !!!

Link to this function

goto(owner, url, params \\ %{})

View Source

Specs

goto(
  t() | Playwright.Page.t() | {:ok, t() | Playwright.Page.t()},
  binary(),
  map()
) :: {:ok, Playwright.Response.t()} | {:error, term()}

!!!

Link to this function

hover(frame, selector, options \\ %{})

View Source

Specs

hover(t(), binary(), options()) :: :ok

Hovers over an element matching param: selector.

Performs the following steps:

  1. Find an element matching param: selector. If there is none, wait until a matching element is attached to the DOM.
  2. 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.
  3. Scroll the element into view if needed.
  4. Use Page.Mouse to hover over the center of the element, or the specified option: position.
  5. 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.
:strictoptionboolean()When true, the call requires selector to resolve to a single element. If given selector resolves to more then one element, the call throws an exception.
: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

init(owner, initializer)

View Source

Specs

init(struct(), map()) :: {atom(), struct()}

Optional callback implementation for Playwright.ChannelOwner.init/2.

If implemented, the callback will receive:

  1. The newly created "channel owner" struct.
  2. The :initializer received from the Playwright browser server.

The implementation has the option of "patching" the struct as stored in the catalog, and/or binding event handlers.

Example

def init(owner, _initializer) do
  Channel.bind(owner, :close, fn event ->
    Logger.warn("Closing #{inspect(event.target)}")
  end)

  {:ok, %{owner | version: "1.2.3"}}
end

Returns

  • {:ok, %{}}

Arguments

key / nametypedescription
ownerparamstruct()The newly created channel owner (resource).
initializerparamstruct()The initializer received from with the channel owner instance was derived.
Link to this function

inner_html(frame, selector, options \\ %{})

View Source

Specs

inner_html(t(), binary(), options()) :: {:ok, binary()}
Link to this function

inner_text(frame, selector, options \\ %{})

View Source

Specs

inner_text(t(), binary(), options()) :: {:ok, binary()}
Link to this function

input_value(frame, selector, options \\ %{})

View Source

Specs

input_value(t(), binary(), options()) :: {:ok, binary()}
Link to this function

is_checked(frame, selector, options \\ %{})

View Source

Specs

is_checked(t(), binary(), options()) :: {:ok, boolean()}
Link to this function

is_disabled(frame, selector, options \\ %{})

View Source

Specs

is_disabled(t(), binary(), options()) :: {:ok, boolean()}
Link to this function

is_editable(frame, selector, options \\ %{})

View Source

Specs

is_editable(t(), binary(), options()) :: {:ok, boolean()}
Link to this function

is_enabled(frame, selector, options \\ %{})

View Source

Specs

is_enabled(t(), binary(), options()) :: {:ok, boolean()}
Link to this function

is_hidden(frame, selector, options \\ %{})

View Source

Specs

is_hidden(t(), binary(), options()) :: {:ok, boolean()}
Link to this function

is_visible(frame, selector, options \\ %{})

View Source

Specs

is_visible(t(), binary(), options()) :: {:ok, boolean()}
Link to this function

press(owner, selector, key, options \\ %{})

View Source

Specs

press(t() | Playwright.Page.t(), binary(), binary(), options()) :: :ok

param: key can specify the intended keyboardEvent.key value or a single character for which to generate the text.

A superset of the param: 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, etc.

The following 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 being held while the subsequent key is being pressed.

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.
keyparambinary()Name of the key to press or a character to generate, such as ArrowLeft or a.
:delayoptionnumber()Time to wait between keydown and keyup 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)
:strictoptionboolean()When true, the call requires selector to resolve to a single element. If given selector resolves to more then one element, the call throws an exception.
: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

q(owner, selector, options \\ %{})

View Source

See Playwright.Frame.query_selector/3.

Link to this function

q!(owner, selector, options \\ %{})

View Source

See Playwright.Frame.query_selector!/3.

Link to this function

qq(owner, selector, options \\ %{})

View Source

See Playwright.Frame.query_selector_all/3.

Link to this function

query_selector(owner, selector, options \\ %{})

View Source

Specs

query_selector(
  t() | Playwright.Page.t() | {:ok, t() | Playwright.Page.t()},
  binary(),
  map()
) :: {:ok, Playwright.ElementHandle.t() | nil}

Returns the Playwright.ElementHandle pointing to the frame element.

The function finds an element matching the specified selector within the frame. See "working with selectors (guide)" for more details. If no elements match the selector, returns nil.

Returns

  • {:ok, Playwright.ElementHandle.t() | nil}

Arguments

key / nametypedescription
selectorparambinary()A selector to query for. See "working with selectors (guide)" for more details.
strictoptionboolean()When true, the call requires selector to resolve to a single element. If the given selector resolves to more then one element, the call raises an error.
Link to this function

query_selector_all(owner, selector, options \\ %{})

View Source

Specs

query_selector_all(
  t() | Playwright.Page.t() | {:ok, t() | Playwright.Page.t()},
  binary(),
  map()
) :: {atom(), [Playwright.ElementHandle.t()]}

Returns the list of Playwright.ElementHandle pointing to the frame elements.

The method finds all elements matching the specified selector within the frame. See "working with selectors (guide)" for more details.

If no elements match the selector, returns an empty List.

Returns

  • {:ok, [Playwright.ElementHandle.t()]}

Arguments

key / nametypedescription
selectorparambinary()A selector to query for. See "working with selectors (guide)" for more details.
Link to this function

select_option(frame, selector, values, options \\ %{})

View Source

Specs

select_option(t(), binary(), any(), options()) :: {:ok, [binary()]}

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

Performs the following steps:

  1. Waits for an element matching param: selector
  2. Waits for actionability checks
  3. Waits until all specified options are present in the <select> element
  4. 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

# single selection matching the value
Frame.select_option(frame, "select#colors", "blue")

# single selection matching both the label
Frame.select_option(frame, "select#colors", %{label: "blue"})

# multiple selection
Frame.select_option(frame, "select#colors", %{value: ["red", "green", "blue"]})

Returns

  • {:ok, [binary()]}

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.
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)
:strictoptionboolean()When true, the call requires selector to resolve to a single element. If given selector resolves to more then one element, the call throws an exception.
: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

set_content(owner, html, options \\ %{})

View Source

Specs

set_content(
  t() | Playwright.Page.t() | {:ok, t() | Playwright.Page.t()},
  binary(),
  options()
) :: :ok

Returns

  • :ok

Arguments

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

text_content(owner, selector, options \\ %{})

View Source

Specs

text_content(t() | Playwright.Page.t(), binary(), map()) ::
  {:ok, binary() | nil}

Returns Playwright.ElementHandle.text_content/1

Returns

  • {:ok, binary() | nil}

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.
:strictoptionboolean()When true, the call requires selector to resolve to a single element. If given selector resolves to more then one element, the call throws an exception.
: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

title(t() | Playwright.Page.t()) :: {:ok, binary()}

Returns the page title.

Returns

  • {:ok, binary()}
Link to this function

wait_for_load_state(frame, state \\ "load", options \\ %{})

View Source

Specs

wait_for_load_state(t(), binary(), options()) :: {:ok, t()}

Waits for the required load state to be reached.

This returns when the frame reaches a required load state, "load" by default. The navigation must have been committed when this method is called. If the current document has already reached the required state, resolves immediately.

Link to this function

wait_for_selector(owner, selector, options \\ %{})

View Source

Specs

wait_for_selector(t() | Playwright.Page.t(), binary(), map()) ::
  {:ok, Playwright.ElementHandle.t() | nil}

Returns when element specified by selector satisfies state option.

Returns nil if waiting for a hidden or detached element.