wallaby v0.16.1 Wallaby.Browser
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?
Summary
Functions
Finds all of the DOM elements that match the css selector. If no elements are found then an empty list is immediately returned
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
Checks a checkbox based on id, label text, or name
Checks if the element has been selected
Chooses a radio button based on id, label text, or name
Clicks a element
Clicks the matching button. Buttons can be found based on id, name, or button text
Clicks the matching link. Links can be found based on id, name, or link text
Gets the current path of the session
Gets the current url of the session
Executes javascript synchoronously, taking as arguments the script to execute,
and optionally a list of arguments available in the script via arguments
Fills in a “fillable” element with text. Input elements are looked up by id, label text, or name
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. 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
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
Selects an option from a select box. The select box can be found by id, label text, or name. The option can be found by its text
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
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
Unchecks a checkbox based on id, label text, or name
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
Types
Functions
all(parent, locator) :: [Wallaby.Element.t]
all(parent, Wallaby.Query.t) :: [Wallaby.Element.t]
Finds all of the DOM elements that match the css selector. If no elements are found then an empty list is immediately returned.
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.
Checks a checkbox based on id, label text, or name.
Checks if the element has been selected.
Chooses a radio button based on id, label text, or name.
Clicks a element.
Clicks the matching button. Buttons can be found based on id, name, or button text.
Clicks the matching link. Links can be found based on id, name, or link text.
Executes javascript synchoronously, taking as arguments the script to execute,
and optionally a list of arguments available in the script via arguments
Fills in a “fillable” element with text. Input elements are looked up by id, label text, or name.
find(parent, Wallaby.Query.t) :: Wallaby.Element.t | [Wallaby.Element.t]
find(parent, locator) :: Wallaby.Element.t | [Wallaby.Element.t]
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. 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.
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.
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.
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).
Selects an option from a select box. The select box can be found by id, label text, or name. The option can be found by its text.
select(parent, Wallaby.Query.t, [{:from, Wallaby.Query.t}]) :: parent
select(parent, locator, opts) :: parent
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])
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.
Unchecks a checkbox based on id, label text, or name.
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.