wallaby v0.23.0 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 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 an element.
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 Element's content with the provided text
Matches the Element's value with the provided value.
Hovers over an element.
Maximizes the currenty focused window.
Moves mouse by an offset relative to current cursor position.
Sets the position of the currenty 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 currenty 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.
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 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
Link to this section Functions
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
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 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
all(parent, query)
View Sourceall(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. 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.
Returns the given parent
if the assertion is correct so that it is easily
pipeable.
Examples
session
|> visit("/")
|> assert_has(Query.css(".login-button"))
assert_text(parent, text)
View Sourceassert_text(Wallaby.Element.t(), String.t()) :: boolean()
assert_text(parent, query, text)
View Sourceassert_text(parent(), Wallaby.Query.t(), String.t()) :: boolean()
Matches the Element's content with the provided text and raises if not found
attach_file(parent, query, list)
View Sourceattach_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.
attr(parent, query, name)
View Sourceattr(parent(), Wallaby.Query.t(), String.t()) :: String.t() | nil
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.
clear(parent, query)
View Sourceclear(parent(), Wallaby.Query.t()) :: parent()
Clicks an element.
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:
message = dismiss_confirm session, fn(s) ->
click(s, Query.link("Trigger confirm"))
end
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
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.
fill_in(parent, query, list)
View Sourcefill_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.
find(parent, query)
View Sourcefind(parent(), Wallaby.Query.t()) :: Wallaby.Element.t() | [Wallaby.Element.t()]
find(parent(), locator()) :: Wallaby.Element.t() | [Wallaby.Element.t()]
find(parent, query, callback)
View Sourcefind(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.
Changes the driver focus to the default (top level) frame.
focus_frame(session, query)
View Sourcefocus_frame(parent(), Wallaby.Query.t()) :: parent()
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.
has?(parent, query)
View Sourcehas?(parent(), Wallaby.Query.t()) :: boolean()
Validates that the query returns a result. This can be used to define other types of matchers.
has_css?(parent, query, css)
View Sourcehas_css?(parent(), Wallaby.Query.t(), String.t()) :: boolean()
Searches for CSS on the page.
has_no_css?(parent, query, css)
View Sourcehas_no_css?(parent(), Wallaby.Query.t(), String.t()) :: boolean()
Searches for css that should not be on the page
has_text?(session, text)
View Sourcehas_text?(Wallaby.Element.t(), String.t()) :: boolean()
has_text?(parent, query, text)
View Sourcehas_text?(parent(), Wallaby.Query.t(), String.t()) :: boolean()
Matches the Element's content with the provided text
has_value?(element, value)
View Sourcehas_value?(Wallaby.Element.t(), any()) :: boolean()
has_value?(parent, query, value)
View Sourcehas_value?(parent(), Wallaby.Query.t(), any()) :: boolean()
Matches the Element's value with the provided value.
hover(parent, query)
View Sourcehover(parent(), Wallaby.Query.t()) :: parent()
Hovers over an element.
Maximizes the currenty focused window.
For most browsers, this requires a window manager to be running.
Moves mouse by an offset relative to current cursor position.
move_window(session, x, y)
View Sourcemove_window(parent(), pos_integer(), pos_integer()) :: parent()
Sets the position of the currenty 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.
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"))
resize_window(session, width, height)
View Sourceresize_window(parent(), pos_integer(), pos_integer()) :: parent()
Sets the size of the currenty focused window.
retry(f, start_time \\ current_time())
View Sourceretry((() -> 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).
selected?(parent, query)
View Sourceselected?(parent(), Wallaby.Query.t()) :: boolean()
Checks if the element has been selected. Alias for checked?(element)
send_keys(element, keys)
View Sourcesend_keys(parent(), Wallaby.Element.keys_to_send()) :: parent()
send_keys(parent, query, list)
View Sourcesend_keys(parent(), Wallaby.Query.t(), Wallaby.Element.keys_to_send()) :: parent()
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.
set_value(parent, query, value)
View Sourceset_value(parent(), Wallaby.Query.t(), Wallaby.Element.value()) :: parent()
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
take_screenshot(screenshotable, opts \\ [])
View Sourcetake_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.
text(parent, query)
View Sourcetext(parent(), Wallaby.Query.t()) :: String.t()
Gets the Element's text value.
visible?(parent, query)
View Sourcevisible?(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.
Gets the window handle of the currently focused window.
Gets the window handles of all available windows.
window_position(session)
View Sourcewindow_position(parent()) :: %{ optional(String.t()) => pos_integer(), optional(String.t()) => pos_integer() }
Gets the position of the currently focused window.
window_size(session)
View Sourcewindow_size(parent()) :: %{ optional(String.t()) => pos_integer(), optional(String.t()) => pos_integer() }
Gets the size of the currently focused window.