Wallaby Documentation

Wallaby's API is built on two core concepts: Queries and Actions.

• Queries are declarative descriptions of elements you want to interact with (e.g., css(".user", count: 3) or text_field("Name")).
• Actions use these queries to perform operations on the DOM (e.g., click/2, fill_in/3).

Key Behavior: Actions will block until the query is satisfied or the action times out. This built-in blocking helps reduce race conditions when elements are added or removed dynamically by asynchronous JavaScript.

Example of combining queries and actions:

session
|> find(css(".user", count: 3))
|> List.first
|> assert_has(css(".user-name", count: 1, text: "Ada"))

To test Passkeys in Chrome, you must enable the WebAuthn Virtual Authenticator via Chromedriver. This allows Chrome to automatically present a virtual Passkey when create() or get() APIs are called.

{:ok, _result} =
  Wallaby.HTTPClient.request(:post, "#{session.url}/chromium/send_command_and_get_result", %{
    cmd: "WebAuthn.enable",
    params: %
  })

{:ok, result} =
  Wallaby.HTTPClient.request(:post, "#{session.url}/chromium/send_command_and_get_result", %{
    cmd: "WebAuthn.addVirtualAuthenticator",
    params: %{
      options: %{
        protocol: "ctap2",
        transport: "internal",
        hasResidentKey: true,
        hasUserVerification: true,
        isUserVerified: true,
        automaticPresenceSimulation: true
      }
    }
  })

Add wallaby to your mix.exs dependencies. It is recommended to set runtime: false and restrict it to the :test environment.

After adding the dependency, you must configure a driver (Chrome is the default) and ensure the corresponding browser driver (like chromedriver or selenium) is installed on your system. Finally, ensure the :wallaby application is started in your test_helper.exs.

# mix.exs
def deps do
  [
    {:wallaby, "~> 0.30", runtime: false, only: :test}
  ]
end

# config/config.exs
# Chrome (default)
config :wallaby, driver: Wallaby.Chrome

# Selenium
config :wallaby, driver: Wallaby.Selenium

# test/test_helper.exs
{:ok, _} = Application.ensure_all_started(:wallaby)

Wallaby provides a Domain Specific Language (DSL) for locating DOM elements using CSS, XPath, or specialized semantic finders. You can create queries using direct selectors or high-level functions that decouple your tests from presentation details like CSS classes.

Basic Selectors

• Query.css(".selector"): Locate elements via CSS.
• Query.xpath(".//xpath"): Locate elements via XPath.

Semantic Form Finders

These finders allow you to locate form elements by their id, name, placeholder, or the text of their associated <label>:

• Query.text_field(selector)
• Query.checkbox(selector)
• Query.radio_button(selector)
• Query.select(selector)
• Query.file_field(selector)
• Query.button(selector)
• Query.link(selector)
• Query.option(selector)

Query.css(".some-css")
Query.xpath(".//input")
Query.text_field("My Name")

Wallaby captures JavaScript logs and errors. Uncaught JS exceptions are re-thrown as Elixir errors.

• Disable JS errors: Set js_errors: false in the Wallaby config.
• Configure JS logging: Use the :js_logger option to specify an IO device. By default, logs are written to :stdio.

To log to a file:

{:ok, file} = File.open("browser_logs.log", [:write])
Application.put_env(:wallaby, :js_logger, file)

To disable logging entirely, set :js_logger to nil.

The Selenium driver extends send_keys/2 to support file uploads. If the list of keys passed to send_keys contains a path to a local file, Wallaby will automatically:

1. Zip the local file.
2. Base64 encode it.
3. Upload it to the Selenium server via the /file endpoint.
4. Set the remote file path as the input's value.

This allows you to interact with <input type="file"> elements by passing the local file path in the keys list.

The Wallaby.Element module provides functions to interact with elements found on a page. These functions are typically used within a find/2 block to perform actions on a specific element.

Important: Retrying and Stale Elements

Unlike the Browser module, actions in Wallaby.Element do not retry if an element becomes stale. If an element is stale, a Wallaby.StaleReferenceError will be raised immediately.

page
|> find(Query.css(".some-element"), fn(element) -> Element.click(element) end)

Wallaby uses hackney for HTTP requests. You can control request and receive timeouts by providing :hackney_options in your configuration.

config :wallaby,
  hackney_options: [timeout: :infinity, recv_timeout: :infinity]

# Or override a specific value
config :wallaby,
  hackney_options: [timeout: 5_000]

config :wallaby,
  hackney_options: [timeout: :infinity, recv_timeout: :infinity]

# Overriding a value
config :wallaby,
  hackney_options: [timeout: 5_000]