wallaby v0.19.1 Wallaby.Browser 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 all subsequent JavaScript dialogs in the given session

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 a element

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 all subsequent JavaScript dialogs in the given session

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

Executes javascript synchoronously, 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

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 Element’s content with the provided text

Matches the Element’s value with the provided value

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 sessions 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:

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

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

Gets the Element’s text value

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 size of the session’s window

Link to this section Types

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

Accepts all subsequent JavaScript dialogs in the given session.

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

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
assert_text(Wallaby.Element.t, String.t) :: boolean
Link to this function assert_text(parent, query, text) View Source
assert_text(parent, Wallaby.Query.t, String.t) :: boolean

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

Link to this function attach_file(parent, query, list) View Source
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.

Gets the value of the elements attribute.

Clicks a element.

Link to this function current_path(session) View Source
current_path(parent) :: String.t

Gets the current path of the session

Link to this function current_url(session) View Source
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_dialogs(session) View Source

Dismisses all subsequent JavaScript dialogs in the given session.

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
Link to this function execute_query(parent, query) View Source
Link to this function execute_script(session, script) View Source
execute_script(parent, String.t) :: parent

Executes javascript synchoronously, 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
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
execute_script(parent, String.t, list, (binary -> any)) :: parent
Link to this function fill_in(parent, query, list) View Source
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"))

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 has?(parent, query) View Source
has?(parent, Wallaby.Query.t) :: boolean

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

Link to this function has_css?(parent, css) View Source
has_css?(parent, locator) :: boolean
Link to this function has_css?(parent, query, css) View Source
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
has_no_css?(parent, locator) :: boolean
Link to this function has_no_css?(parent, query, css) View Source
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
has_text?(Wallaby.Element.t, String.t) :: boolean
Link to this function has_text?(parent, query, text) View Source
has_text?(parent, Wallaby.Query.t, String.t) :: boolean

Matches the Element’s content with the provided text

Link to this function has_value?(element, value) View Source
has_value?(Wallaby.Element.t, any) :: boolean
Link to this function has_value?(parent, query, value) View Source
has_value?(parent, Wallaby.Query.t, any) :: boolean

Matches the Element’s value with the provided value.

Link to this function page_source(session) View Source
page_source(parent) :: String.t

Retrieves the source of the current page.

Link to this function page_title(session) View Source
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
resize_window(parent, pos_integer, pos_integer) :: parent

Sets the size of the sessions window.

Link to this function retry(f, start_time \\ current_time()) View Source
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
selected?(parent, Wallaby.Query.t) :: boolean

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.

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])
Link to this function set_cookie(session, key, value) View Source

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) View Source
take_screenshot(parent) :: parent

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

Gets the Element’s text value.

Link to this function visible?(parent, query) View Source
visible?(parent, Wallaby.Query.t) :: boolean

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.

Link to this function window_size(session) View Source
window_size(parent) :: %{optional(String.t) => pos_integer, optional(String.t) => pos_integer}

Gets the size of the session’s window.