Wallaby.Browser (wallaby v0.28.0) View Source

The Browser module is the entrypoint for interacting with a real browser.

By default, action only work with elements that are visible to a real user.

Actions

Actions are used to interact with form elements. All actions work with the query interface:

<label for="first_name">
  First Name
</label>
<input id="user_first_name" type="text" name="first_name">
fill_in(page, Query.text_field("First Name"), with: "Grace")
fill_in(page, Query.text_field("first_name"), with: "Grace")
fill_in(page, Query.text_field("user_first_name"), with: "Grace")

These queries work with any of the available actions.

fill_in(page, Query.text_field("First Name"), with: "Chris")
clear(page, Query.text_field("user_email"))
click(page, Query.radio_button("Radio Button 1"))
click(page, Query.checkbox("Checkbox"))
click(page, Query.checkbox("Checkbox"))
click(page, Query.option("Option 1"))
click(page, Query.button("Some Button"))
attach_file(page, Query.file_field("Avatar"), path: "test/fixtures/avatar.jpg")

Actions return their parent element so that they can be chained together:

page
|> find(Query.css(".signup-form"), fn(form) ->
  form
  |> fill_in(Query.text_field("Name"), with: "Grace Hopper")
  |> fill_in(Query.text_field("Email"), with: "grace@hopper.com")
  |> click(Query.button("Submit"))
end)

Scoping

Finders provide scoping like so:

session
|> visit("/page.html")
|> find(Query.css(".users"))
|> find(Query.css(".user", count: 3))
|> List.first
|> find(Query.css(".user-name"))

If a callback is passed to find then the scoping will only apply to the callback and the parent will be passed to the next action in the chain:

page
|> find(Query.css(".todo-form"), fn(form) ->
  form
  |> fill_in(Query.text_field("What needs doing?"), with: "Write Wallaby Documentation")
  |> click(Query.button("Save"))
end)
|> find(Query.css(".success-notification"), fn(notification) ->
  assert notification
  |> has_text?("Todo created successfully!")
end)

This allows you to create a test that is logically grouped together in a single pipeline. It also means that its easy to create re-usable helper functions without having to worry about chaining. You could re-write the above example like this:

def create_todo(page, todo) do
  find(Query.css(".todo-form"), & fill_in_and_save_todo(&1, todo))
end

def fill_in_and_save_todo(form, todo) do
  form
  |> fill_in(Query.text_field("What needs doing?"), with: todo)
  |> click(Query.button("Save"))
end

def todo_was_created?(page) do
  find Query.css(page, ".success-notification"), fn(notification) ->
    assert notification
    |> has_text?("Todo created successfully!")
  end
end

assert page
|> create_todo("Write Wallaby Documentation")
|> todo_was_created?

Link to this section Summary

Functions

Accepts one alert dialog, which must be triggered within the specified fun. Returns the message that was presented to the user. For example

Accepts one confirmation dialog, which must be triggered within the specified fun. Returns the message that was presented to the user. For example

Accepts one prompt, which must be triggered within the specified fun. The [with: value] option allows to simulate user input for the prompt. If no value is provided, the default value that was passed to window.prompt will be used instead. Returns the message that was presented to the user. For example

Finds all of the DOM elements that match the CSS selector. If no elements are found then an empty list is immediately returned. This is equivalent to calling find(session, css("element", count: nil, minimum: 0)).

Checks if query is present within parent and raises if not found.

Matches the Element's content with the provided text and raises if not found.

Attaches a file to a file input. Input elements are looked up by id, label text, or name.

Gets the value of the elements attribute.

Clicks and holds the given mouse button at the current mouse coordinates.

Releases given previously held mouse button.

Clicks the mouse on the element returned by the query or at the current mouse cursor position.

Closes the currently focused window.

Gets the current path of the session

Gets the current url of the session

Dismisses one confirmation dialog, which must be triggered within the specified fun. Returns the message that was presented to the user. For example

Dismisses one prompt, which must be triggered within the specified fun. Returns the message that was presented to the user. For example

Double-clicks left mouse button at the current mouse coordinates.

Executes JavaScript synchronously, taking as arguments the script to execute, an optional list of arguments available in the script via arguments, and an optional callback function with the result of script execution as a parameter.

Executes asynchronous JavaScript, taking as arguments the script to execute, an optional list of arguments available in the script via arguments, and an optional callback function with the result of script execution as a parameter.

Fills in an element identified by query with value.

Finds a specific DOM element on the page based on a CSS selector. Blocks until it either finds the element or until the max time is reached. By default only 1 element is expected to match the query. If more elements are present then a count can be specified. Use :any to allow any number of elements to be present. By default only elements that are visible on the page are returned.

Changes the driver focus to the default (top level) frame.

Changes the driver focus to the frame found by query.

Changes the driver focus to the parent frame.

Changes the driver focus to the window identified by the handle.

Validates that the query returns a result. This can be used to define other types of matchers.

Searches for CSS on the page.

Searches for CSS that should not be on the page

Matches the parent's content with the provided text.

Matches the Element's value with the provided value.

Hovers over an element.

Maximizes the currently focused window.

Moves mouse by an offset relative to current cursor position.

Sets the position of the currently focused window.

Retrieves the source of the current page.

Gets the title for the current page

Checks if query is not present within parent and raises if it is found.

Sets the size of the currently focused window.

Attempts to synchronize with the browser. This is most often used to execute queries repeatedly until it either exceeds the time limit or returns a success.

Checks if the element has been selected. Alias for checked?(element)

Sends a list of key strokes to active element. If strings are included then they are sent as individual keys. Special keys should be provided as a list of atoms, which are automatically converted into the corresponding key codes.

Sets the value of an element. The allowed type for the value depends on the type of the element. The value may be

Takes a screenshot of the current window. Screenshots are saved to a "screenshots" directory in the same directory the tests are run in.

Taps the element.

Gets the Element's text value.

Touches the screen at the given position.

Touches and holds the element on its top-left corner plus an optional offset.

Moves the touch pointer (finger, stylus etc.) on the screen to the point determined by the given coordinates.

Scroll on the screen from the given element by the given offset using touch events.

Stops touching the screen.

Checks if the element is visible on the page

Changes the current page to the provided route. Relative paths are appended to the provided base_url. Absolute paths do not use the base_url.

Gets the window handle of the currently focused window.

Gets the window handles of all available windows.

Gets the position of the currently focused window.

Gets the size of the currently focused window.

Link to this section Types

Specs

opts() :: Wallaby.Query.opts()

Specs

parent() :: element() | session()

Specs

queryable()

Specs

sync_result() :: {:ok, any()} | {:error, any()}

Specs

t() :: any()

Specs

take_screenshot_opt() :: {:name, String.t()} | {:log, boolean()}

Link to this section Functions

Link to this function

accept_alert(session, fun)

View Source

Accepts one alert dialog, which must be triggered within the specified fun. Returns the message that was presented to the user. For example:

message = accept_alert session, fn(s) ->
  click(s, Query.link("Trigger alert"))
end
Link to this function

accept_confirm(session, fun)

View Source

Accepts one confirmation dialog, which must be triggered within the specified fun. Returns the message that was presented to the user. For example:

message = accept_confirm session, fn(s) ->
  click(s, Query.link("Trigger confirm"))
end
Link to this function

accept_prompt(session, fun)

View Source

Accepts one prompt, which must be triggered within the specified fun. The [with: value] option allows to simulate user input for the prompt. If no value is provided, the default value that was passed to window.prompt will be used instead. Returns the message that was presented to the user. For example:

message = accept_prompt session, fn(s) ->
  click(s, Query.link("Trigger prompt"))
end

Example providing user input:

message = accept_prompt session, [with: "User input"], fn(s) ->
  click(s, Query.link("Trigger prompt"))
end
Link to this function

accept_prompt(session, list, fun)

View Source

Specs

Finds all of the DOM elements that match the CSS selector. If no elements are found then an empty list is immediately returned. This is equivalent to calling find(session, css("element", count: nil, minimum: 0)).

Link to this macro

assert_has(parent, query)

View Source (macro)

Checks if query is present within parent and raises if not found.

Returns the given parent if the assertion is correct so that it is easily pipeable.

Examples

session
|> visit("/")
|> assert_has(Query.css(".login-button"))
Link to this function

assert_text(parent, text)

View Source

Specs

assert_text(parent(), String.t()) :: parent()
Link to this function

assert_text(parent, query, text)

View Source

Specs

assert_text(parent(), Wallaby.Query.t(), String.t()) :: parent()

Matches the Element's content with the provided text and raises if not found.

Returns the given parent if the assertion is correct so that it is easily pipeable.

Examples

session
|> visit("/")
|> assert_text("Login")

Example providing query:

session
|> visit("/")
|> assert_text(Query.css(".login-button"), "Login")
Link to this function

attach_file(parent, query, list)

View Source

Specs

attach_file(parent(), Wallaby.Query.t(), [{:path, String.t()}]) :: parent()

Attaches a file to a file input. Input elements are looked up by id, label text, or name.

When dealing with Selenium server (especially a remote instance), the file must be uploaded to Selenium via send_keys recognizing a local file, else attaching a file fails.

Link to this function

attr(parent, query, name)

View Source

Specs

attr(parent(), Wallaby.Query.t(), String.t()) :: String.t() | nil

Gets the value of the elements attribute.

Link to this function

button_down(parent, button \\ :left)

View Source

Specs

button_down(parent(), atom()) :: parent()

Clicks and holds the given mouse button at the current mouse coordinates.

Link to this function

button_up(parent, button \\ :left)

View Source

Specs

button_up(parent(), atom()) :: parent()

Releases given previously held mouse button.

Specs

clear(parent(), Wallaby.Query.t()) :: parent()

Specs

click(parent(), :left | :middle | :right) :: parent()
click(parent(), Wallaby.Query.t()) :: parent()

Clicks the mouse on the element returned by the query or at the current mouse cursor position.

Specs

close_window(parent()) :: parent()

Closes the currently focused window.

Specs

current_path(parent()) :: String.t()

Gets the current path of the session

Specs

current_url(parent()) :: String.t()

Gets the current url of the session

Link to this function

dismiss_confirm(session, fun)

View Source

Dismisses one confirmation dialog, which must be triggered within the specified fun. Returns the message that was presented to the user. For example:

message = dismiss_confirm session, fn(s) ->
  click(s, Query.link("Trigger confirm"))
end
Link to this function

dismiss_prompt(session, fun)

View Source

Dismisses one prompt, which must be triggered within the specified fun. Returns the message that was presented to the user. For example:

message = dismiss_prompt session, fn(s) ->
  click(s, Query.link("Trigger prompt"))
end

Specs

double_click(parent()) :: parent()

Double-clicks left mouse button at the current mouse coordinates.

Link to this function

execute_query(parent, query)

View Source
Link to this function

execute_script(session, script)

View Source

Specs

execute_script(parent(), String.t()) :: parent()

Executes JavaScript synchronously, taking as arguments the script to execute, an optional list of arguments available in the script via arguments, and an optional callback function with the result of script execution as a parameter.

Link to this function

execute_script(session, script, arguments)

View Source

Specs

execute_script(parent(), String.t(), list()) :: parent()
execute_script(parent(), String.t(), (binary() -> any())) :: parent()
Link to this function

execute_script(parent, script, arguments, callback)

View Source

Specs

execute_script(parent(), String.t(), list(), (binary() -> any())) :: parent()
Link to this function

execute_script_async(session, script)

View Source

Specs

execute_script_async(parent(), String.t()) :: parent()

Executes asynchronous JavaScript, taking as arguments the script to execute, an optional list of arguments available in the script via arguments, and an optional callback function with the result of script execution as a parameter.

Link to this function

execute_script_async(session, script, arguments)

View Source

Specs

execute_script_async(parent(), String.t(), list()) :: parent()
execute_script_async(parent(), String.t(), (binary() -> any())) :: parent()
Link to this function

execute_script_async(parent, script, arguments, callback)

View Source

Specs

execute_script_async(parent(), String.t(), list(), (binary() -> any())) ::
  parent()
Link to this function

fill_in(parent, query, list)

View Source

Specs

fill_in(parent(), Wallaby.Query.t(), [{:with, String.t()}]) :: parent()

Fills in an element identified by query with value.

All inputs previously present in the input field will be overridden.

Examples

page
|> fill_in(Query.text_field("name"), with: "Chris")
|> fill_in(Query.css("#password_field"), with: "secret42")

Note

Currently, ChromeDriver only supports BMP Unicode characters. Emojis are SMP characters and will be ignored by ChromeDriver.

Using JavaScript is a known workaround for filling in fields with Emojis and other non-BMP characters.

Specs

Link to this function

find(parent, query, callback)

View Source

Specs

find(parent(), Wallaby.Query.t(), (Wallaby.Element.t() -> any())) :: parent()

Finds a specific DOM element on the page based on a CSS selector. Blocks until it either finds the element or until the max time is reached. By default only 1 element is expected to match the query. If more elements are present then a count can be specified. Use :any to allow any number of elements to be present. By default only elements that are visible on the page are returned.

Selections can be scoped by providing a Element as the locator for the query.

By default finders only work with elements that would be visible to a real user.

Link to this function

focus_default_frame(session)

View Source

Specs

focus_default_frame(parent()) :: parent()

Changes the driver focus to the default (top level) frame.

Link to this function

focus_frame(session, query)

View Source

Specs

focus_frame(parent(), Wallaby.Query.t()) :: parent()

Changes the driver focus to the frame found by query.

Link to this function

focus_parent_frame(session)

View Source

Specs

focus_parent_frame(parent()) :: parent()

Changes the driver focus to the parent frame.

Link to this function

focus_window(session, window_handle)

View Source

Specs

focus_window(parent(), String.t()) :: parent()

Changes the driver focus to the window identified by the handle.

Specs

has?(parent(), Wallaby.Query.t()) :: boolean()

Validates that the query returns a result. This can be used to define other types of matchers.

Specs

has_css?(parent(), String.t()) :: boolean()
Link to this function

has_css?(parent, query, css)

View Source

Specs

has_css?(parent(), Wallaby.Query.t(), String.t()) :: boolean()

Searches for CSS on the page.

Link to this function

has_no_css?(parent, css)

View Source

Specs

has_no_css?(parent(), String.t()) :: boolean()
Link to this function

has_no_css?(parent, query, css)

View Source

Specs

has_no_css?(parent(), Wallaby.Query.t(), String.t()) :: boolean()

Searches for CSS that should not be on the page

Link to this function

has_text?(session, text)

View Source

Specs

has_text?(parent(), String.t()) :: boolean()
Link to this function

has_text?(parent, query, text)

View Source

Specs

has_text?(parent(), Wallaby.Query.t(), String.t()) :: boolean()

Matches the parent's content with the provided text.

Returns a boolean that indicates if the text was found.

Examples

session
|> visit("/")
|> has_text?("Login")

Example providing query:

session
|> visit("/")
|> has_text?(Query.css(".login-button"), "Login")
Link to this function

has_value?(element, value)

View Source

Specs

has_value?(Wallaby.Element.t(), any()) :: boolean()
Link to this function

has_value?(parent, query, value)

View Source

Specs

has_value?(parent(), Wallaby.Query.t(), any()) :: boolean()

Matches the Element's value with the provided value.

Specs

hover(parent(), Wallaby.Query.t()) :: parent()

Hovers over an element.

Link to this function

maximize_window(session)

View Source

Specs

maximize_window(parent()) :: parent()

Maximizes the currently focused window.

For most browsers, this requires a window manager to be running.

Link to this function

move_mouse_by(parent, x_offset, y_offset)

View Source

Specs

move_mouse_by(parent(), integer(), integer()) :: parent()

Moves mouse by an offset relative to current cursor position.

Link to this function

move_window(session, x, y)

View Source

Specs

move_window(parent(), pos_integer(), pos_integer()) :: parent()

Sets the position of the currently focused window.

Specs

page_source(parent()) :: String.t()

Retrieves the source of the current page.

Specs

page_title(parent()) :: String.t()

Gets the title for the current page

Link to this macro

refute_has(parent, query)

View Source (macro)

Checks if query is not present within parent and raises if it is found.

Returns the given parent if the query is not found so that it is easily pipeable.

Examples

session
|> visit("/")
|> refute_has(Query.css(".secret-admin-content"))
Link to this function

resize_window(session, width, height)

View Source

Specs

resize_window(parent(), pos_integer(), pos_integer()) :: parent()

Sets the size of the currently focused window.

Link to this function

retry(f, start_time \\ current_time())

View Source

Specs

retry((() -> sync_result()), timeout()) :: sync_result()

Attempts to synchronize with the browser. This is most often used to execute queries repeatedly until it either exceeds the time limit or returns a success.

Note

It is possible that this function never halts. Whenever we experience a stale reference error we retry the query without checking to see if we've run over our time. In practice we should eventually be able to query the DOM in a stable state. However, if this error does continue to occur it will cause wallaby to loop forever (or until the test is killed by exunit).

Link to this function

selected?(parent, query)

View Source

Specs

selected?(parent(), Wallaby.Query.t()) :: boolean()

Checks if the element has been selected. Alias for checked?(element)

Link to this function

send_keys(element, keys)

View Source

Specs

Link to this function

send_keys(parent, query, list)

View Source

Specs

Sends a list of key strokes to active element. If strings are included then they are sent as individual keys. Special keys should be provided as a list of atoms, which are automatically converted into the corresponding key codes.

For a list of available key codes see Wallaby.Helpers.KeyCodes.

Example

iex> Wallaby.Session.send_keys(session, ["Example Text", :enter])
iex> Wallaby.Session.send_keys(session, [:enter])
iex> Wallaby.Session.send_keys(session, [:shift, :enter])

Note

Currently, ChromeDriver only supports BMP Unicode characters. Emojis are SMP characters and will be ignored by ChromeDriver.

Using JavaScript is a known workaround for filling in fields with Emojis and other non-BMP characters.

Link to this function

set_cookie(session, key, value)

View Source
Link to this function

set_value(parent, query, value)

View Source

Specs

Sets the value of an element. The allowed type for the value depends on the type of the element. The value may be:

  • a string of characters for a text element
  • :selected for a radio button, checkbox or select list option
  • :unselected for a checkbox
Link to this function

take_screenshot(screenshotable, opts \\ [])

View Source

Specs

take_screenshot(parent(), [take_screenshot_opt()]) :: parent()

Takes a screenshot of the current window. Screenshots are saved to a "screenshots" directory in the same directory the tests are run in.

Pass [{:name, "some_name"}] to specify the file name. Defaults to a timestamp. Pass [{:log, true}] to log the location of the screenshot to stdout. Defaults to false.

Specs

tap(parent(), Wallaby.Query.t()) :: session()

Taps the element.

Specs

text(parent()) :: String.t()

Specs

text(parent(), Wallaby.Query.t()) :: String.t()

Gets the Element's text value.

If the element is not visible, the return value will be "".

Link to this function

touch_down(parent, x, y)

View Source

Specs

touch_down(parent(), integer(), integer()) :: session()

Touches the screen at the given position.

Link to this function

touch_down(parent, query, x_offset \\ 0, y_offset \\ 0)

View Source

Specs

touch_down(parent(), Wallaby.Query.t(), integer(), integer()) :: session()

Touches and holds the element on its top-left corner plus an optional offset.

Link to this function

touch_move(parent, x, y)

View Source

Specs

touch_move(parent(), non_neg_integer(), non_neg_integer()) :: parent()

Moves the touch pointer (finger, stylus etc.) on the screen to the point determined by the given coordinates.

Link to this function

touch_scroll(parent, query, x, y)

View Source

Specs

touch_scroll(parent(), Wallaby.Query.t(), integer(), integer()) :: parent()

Scroll on the screen from the given element by the given offset using touch events.

Specs

touch_up(parent()) :: parent()

Stops touching the screen.

Specs

visible?(parent(), Wallaby.Query.t()) :: boolean()

Checks if the element is visible on the page

Specs

visit(session(), String.t()) :: session()

Changes the current page to the provided route. Relative paths are appended to the provided base_url. Absolute paths do not use the base_url.

Specs

window_handle(parent()) :: String.t()

Gets the window handle of the currently focused window.

Specs

window_handles(parent()) :: [String.t()]

Gets the window handles of all available windows.

Link to this function

window_position(session)

View Source

Specs

window_position(parent()) :: %{
  required(String.t()) => pos_integer(),
  required(String.t()) => pos_integer()
}

Gets the position of the currently focused window.

Specs

window_size(parent()) :: %{
  required(String.t()) => pos_integer(),
  required(String.t()) => pos_integer()
}

Gets the size of the currently focused window.