Setup

Requires Elixir 1.19+, OTP 28+, and Chrome (or Chromium). Use mix wallabidi.install to download a pinned Chrome for Testing build, or set WALLABIDI_CHROME_PATH to your existing Chrome binary.

Installation

def deps do
  [{:wallabidi, "~> 0.4.0-rc", runtime: false, only: :test}]
end

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

How Chrome is managed

Wallabidi launches Chrome directly — no chromedriver, Selenium server, or Docker container in the loop. There are two modes:

1. Local Chrome (default)

If Chrome is on your PATH or has been installed by mix wallabidi.install, Wallabidi launches it directly via CDP.

$ MIX_ENV=test mix wallabidi.install   # downloads Chrome for Testing into .browsers/
$ mix test

MIX_ENV=test is required when wallabidi is in your deps as only: :test (the typical setup) — Mix only loads the task module in environments where wallabidi compiles. Plain mix wallabidi.install raises task could not be found.

Override the binary path with WALLABIDI_CHROME_PATH if Chrome lives somewhere unusual:

WALLABIDI_CHROME_PATH=/usr/bin/google-chrome-stable mix test

2. Remote Chrome (CI / Docker)

When Chrome runs as a service in your Docker Compose stack, point Wallabidi at it:

# .env or CI config — just the host:port, wallabidi handles the rest
WALLABIDI_CHROME_URL=chrome:9222

Wallabidi auto-discovers the WebSocket URL via /json/version. Full ws:// URLs also work for backward compat.

CI (GitHub Actions)

steps:
- uses: actions/checkout@v6
- uses: erlef/setup-beam@v1
  with:
    otp-version: 28.x
    elixir-version: 1.19.x
- uses: actions/setup-node@v4
  with:
    node-version: 20

- run: mix deps.get
- run: MIX_ENV=test mix wallabidi.install   # downloads Chrome for Testing
- run: mix test

mix wallabidi.install uses npx @puppeteer/browsers install to download a pinned Chrome for Testing binary into .browsers/. Cache this directory for faster subsequent runs:

- uses: actions/cache@v5
  with:
    path: .browsers
    key: ${{ runner.os }}-browsers-${{ hashFiles('.browsers/PATHS') }}
    restore-keys: ${{ runner.os }}-browsers-

Environment variable overrides

For Docker-based CI or remote browsers:

If you have Chrome pre-installed on the runner (e.g. GitHub Actions' built-in Chrome), set WALLABIDI_CHROME_PATH and skip mix wallabidi.install:

- run: mix test
  env:
    WALLABIDI_CHROME_PATH: /usr/bin/google-chrome-stable

Phoenix

# config/test.exs
config :your_app, YourAppWeb.Endpoint, server: true

# test/test_helper.exs
Application.put_env(:wallabidi, :base_url, YourAppWeb.Endpoint.url)

Test isolation

Browser tests need sandbox access propagated to every server-side process the browser triggers (Ecto, Mimic, Mox, Cachex, FunWithFlags). See the Test Isolation guide for the full sandbox_case / sandbox_shim setup.