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

@spec all(parent(), Wallabidi.Query.t()) :: [Wallabidi.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"))

@spec assert_text(parent(), Wallabidi.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")

@spec attach_file(parent(), Wallabidi.Query.t(), [{:path, String.t()}]) :: parent()

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

@spec attr(parent(), Wallabidi.Query.t(), String.t()) :: String.t() | nil

Gets the value of the elements attribute.

@spec await_patch(
  session(),
  keyword()
) :: session()

Waits for the next LiveView DOM patch.

Installed automatically via JavaScript — no app.js changes needed.

click/2 and fill_in/3 call this automatically. Use await_patch explicitly for patches triggered by something other than a direct interaction (e.g. PubSub broadcast, timer).

Options

• :timeout — max wait in ms (default: 5_000)

Examples

# Wait for a PubSub-triggered update
Phoenix.PubSub.broadcast(MyApp.PubSub, "updates", :refresh)
session
|> await_patch()
|> assert_has(Query.css(".updated"))

@spec button_down(parent(), atom()) :: parent()

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

@spec button_up(parent(), atom()) :: parent()

Releases given previously held mouse button.

@spec click(parent(), :left | :middle | :right) :: parent()

@spec click(parent(), Wallabidi.Query.t()) :: parent()

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

Options

• :await — controls the LiveView patch-await behaviour for clicks on phx-bound elements.
  • :auto (default) — wait for the resulting patch / page-ready signal before returning. This is what you want for ordinary tests.
  • :defer — fire the click, stash a pre-click pageId, and return immediately. Pair with Wallabidi.LiveView.await_patch/2 to consume the deferred wait. Use this when you need to assert on the optimistic-UI DOM between the click and the server reply. Outside a Wallabidi.LiveView.with_latency/3 block, the optimistic window is usually too short to observe reliably.

Non-LiveView clicks ignore :await — there's nothing to wait for.

@spec close_window(session :: Wallabidi.Session.t()) :: Wallabidi.Session.t()

Closes the current window.

The window is either an instance of a browser tab or another operating system window.

Usage

feature "closing a window focuses the previously focused window", %{session: session} do
  original_handle =
    session
    |> visit("/home")
    |> window_handle()

  new_handle =
    session
    # click a link that takes you to a new tab
    |> click(Query.link("External Page"))
    |> close_window()
    |> window_handle()

  assert original_handle == new_handle
end

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

Gets the current path of the session

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

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

@spec double_click(parent()) :: parent()

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

@spec 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.

@spec 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.

@spec fill_in(parent(), Wallabidi.Query.t(), [{:with, String.t()}]) :: parent()

@spec fill_in(parent(), Wallabidi.Query.t(), with: String.t(), await: atom()) ::
  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, Chrome only supports BMP Unicode characters via the WebDriver send_keys action. Emojis are SMP characters and will be ignored.

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

@spec find(parent(), Wallabidi.Query.t()) ::
  Wallabidi.Element.t() | [Wallabidi.Element.t()]

Finds and returns one or more DOM element(s) on the page based on the given query.

The query is scoped by the first argument, which is either the %Session{} or an %Element{}.

Example

session
|> find(Query.css("#login-button"))
|> assert_text("Login")

buttons =
  session
  |> find(Query.css(".login-button", count: 2, text: "Login"))

Notes

• Blocks until it finds the element(s) or 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 count: :any to allow any number of elements to be present.
• By default only elements that would be visible to a real user on the page are returned.

@spec find(parent(), Wallabidi.Query.t(), (Wallabidi.Element.t() -> any())) ::
  parent()

Same as find/2, but takes a callback to enact side effects on the found element(s).

Example

session
|> find(Query.css("#login-button"), fn button ->
  assert_text(button, "Login")
end)

session
|> find(Query.css(".login-button", count: 2, text: "Login"), fn buttons ->
  assert 2 == length(buttons)
end)

Notes

• Returns the first argument to make the function pipe-able.

@spec focus_default_frame(parent()) :: parent()

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

@spec focus_frame(parent(), Wallabidi.Query.t()) :: parent()

Changes the driver focus to the frame found by query.

@spec focus_parent_frame(parent()) :: parent()

Changes the driver focus to the parent frame.

@spec focus_window(session :: Wallabidi.Session.t(), window_handle :: String.t()) ::
  parent()

Focuses the window identified by the given handle.

The window is either an instance of a browser tab or another operating system window.

Usage

feature "can switch between different tabs", %{session: session} do
  handle =
    session
    |> visit("/home")
    |> window_handle()

  path =
    session
    # click a link that takes you to a new tab
    |> click(Query.link("External Page"))
    |> assert_text("Some text")
    |> focus_window(handle)
    |> current_path()

  assert "/home" == path
end

@spec has?(parent(), Wallabidi.Query.t()) :: boolean()

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

@spec has_css?(parent(), Wallabidi.Query.t(), String.t()) :: boolean()

Searches for CSS on the page.

@spec has_no_css?(parent(), Wallabidi.Query.t(), String.t()) :: boolean()

Searches for CSS that should not be on the page

@spec has_text?(parent(), Wallabidi.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")

@spec has_value?(parent(), Wallabidi.Query.t(), any()) :: boolean()

Matches the Element's value with the provided value.

@spec hover(parent(), Wallabidi.Query.t()) :: parent()

Hovers over an element.

@spec maximize_window(session :: Wallabidi.Session.t()) :: Wallabidi.Session.t()

Maximizes the current window.

The window is either an instance of a browser tab or another operating system window.

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

Usage

feature "maximizes the window to the full size of the display", %{session: session} do
  %{"width" => width, "height" => height} =
    session
    |> visit("/home")
    |> maximize_window()
    |> window_size()

  assert width == 1920
  assert height == 1080
end

@spec move_mouse_by(parent(), integer(), integer()) :: parent()

Moves mouse by an offset relative to current cursor position.

@spec move_window(
  session :: Wallabidi.Session.t(),
  x :: pos_integer(),
  y :: pos_integer()
) ::
  Wallabidi.Session.t()

Sets the position of the current window.

The window is either an instance of a browser tab or another operating system window.

Usage

feature "gets the current display position of the window", %{session: session} do
  %{"x" => x, "y" => y} =
    session
    |> visit("/home")
    |> move_window(500, 500)
    |> window_position()

  assert x == 500
  assert y == 500
end

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

Retrieves the source of the current page.

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

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"))

@spec resize_window(
  session :: Wallabidi.Session.t(),
  width :: pos_integer(),
  height :: pos_integer()
) ::
  Wallabidi.Session.t()

Sets the size of the current window.

The window is either an instance of a browser tab or another operating system window.

Usage

feature "sets the size of the window to mobile dimensions", %{session: session} do
  %{"width" => width, "height" => height} =
    session
    |> visit("/home")
    |> resize_window(375, 667)
    |> window_size()

  assert width == 375
  assert height == 667
end

@spec retry((-> sync_result()), non_neg_integer()) :: 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 wallabidi to loop forever (or until the test is killed by exunit).

@spec selected?(parent(), Wallabidi.Query.t()) :: boolean()

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

@spec send_keys(parent(), Wallabidi.Query.t(), Wallabidi.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 Wallabidi.Helpers.KeyCodes.

Example

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

Note

Currently, Chrome only supports BMP Unicode characters via the WebDriver send_keys action. Emojis are SMP characters and will be ignored.

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

@spec set_value(parent(), Wallabidi.Query.t(), Wallabidi.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

@spec 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.

@spec tap(parent(), Wallabidi.Query.t()) :: session()

Taps the element.

@spec text(parent(), Wallabidi.Query.t()) :: String.t()

Gets the Element's text value.

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

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

Touches the screen at the given position.

@spec touch_down(parent(), Wallabidi.Query.t(), integer(), integer()) :: session()

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

@spec 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.

@spec touch_scroll(parent(), Wallabidi.Query.t(), integer(), integer()) :: parent()

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

@spec touch_up(parent()) :: parent()

Stops touching the screen.

@spec visible?(parent(), Wallabidi.Query.t()) :: boolean()

Checks if the element is visible on the page

@spec 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.

@spec window_handle(session :: Wallabidi.Session.t()) :: String.t()

Gets the window handle of the current window.

The window is either an instance of a browser tab or another operating system window. Getting the current window handle makes it easy to return to the window in case you need to switch between them.

Usage

feature "can open a new tab and switch back to the original tab", %{session: session} do
  handle =
    session
    |> visit("/home")
    |> window_handle()

  path =
    session
    # click a link that takes you to a new tab
    |> click(Query.link("External Page"))
    |> assert_text("Some text")
    |> focus_window(handle)
    |> current_path()

  assert "/home" == path
end

@spec window_handles(session :: Wallabidi.Session.t()) :: [String.t()]

Gets the window handles of all available windows.

The window is either an instance of a browser tab or another operating system window.

Usage

feature "can open new tabs for external links", %{session: session} do
  handles =
    session
    |> visit("/home")
    |> click(Query.link("External Page"))
    |> click(Query.link("Another External Page"))
    |> window_handles()

  assert 3 == length(path)
end

@spec window_position(session :: Wallabidi.Session.t()) :: %{
  required(String.t()) => pos_integer(),
  required(String.t()) => pos_integer()
}

Gets the position of the current window.

The window is either an instance of a browser tab or another operating system window.

Usage

feature "gets the current display position of the window", %{session: session} do
  %{"x" => x, "y" => y} =
    session
    |> visit("/home")
    |> window_position()

  assert x == 200
  assert y == 200
end

@spec window_size(session :: Wallabidi.Session.t()) :: %{
  required(String.t()) => pos_integer(),
  required(String.t()) => pos_integer()
}

Gets the size of the current window.

The window is either an instance of a browser tab or another operating system window.

This is useful for debugging responsive designs where the layout changes as the window size changes. The default window size is 1280x800.

Usage

feature "gets the size of the current window", %{session: session} do
  %{"width" => width, "height" => height} =
    session
    |> visit("/home")
    |> window_size()

  assert width == 1280
  assert height == 800
end