Snippets alias Playwright.{Page, BrowserContext, Tracing, ...}.
Errors and call logs
A failed call says what it waited for. The message of a Playwright.TimeoutError ends with
the call log, the steps the driver took; error.log has them as a list:
locator.click: Timeout 1000ms exceeded.
Call log:
- waiting for getByRole('button', { name: 'Save' })A failed Expect.* bang raises Playwright.ExpectError with the expected and received values and
the same log. Most failures are clear from that alone.
Traces
A trace records every action with DOM snapshots, screenshots, network and console, and is the best tool for a failure you can't reproduce locally:
tracing = BrowserContext.tracing(context)
Tracing.start!(tracing, screenshots: true, snapshots: true, sources: true)
# ... the test
Tracing.stop!(tracing, path: "tmp/trace.zip")Open it in the trace viewer (it opens a browser window):
mix playwright.cli show-trace tmp/trace.zip
or drop the file on trace.playwright.dev.
Tracing.group!/3 and
Tracing.group_end!/1 name a group of steps. In tests,
Playwright.Test traces failing tests, on a rerun or retained on failure (Testing with
ExUnit).
Screenshots and videos
Page.screenshot!(page, path: "tmp/page.png", full_page: true)
Page.get_by_role(page, :dialog) |> Locator.screenshot!(path: "tmp/dialog.png")Without path:, screenshot! returns the PNG as a binary. For videos, record a context; each
page's video is written when its context closes:
context = Browser.new_context!(browser, record_video: %{dir: "tmp/videos"})
page = BrowserContext.new_page!(context)
# ... the test
BrowserContext.close!(context)
Page.video(page) |> Video.path!()Console and page errors
Forward the page's console and uncaught errors to the test process or the log:
require Logger
BrowserContext.on(context, :console, &Logger.info("console.#{ConsoleMessage.type(&1)}: #{ConsoleMessage.text(&1)}"))
BrowserContext.on(context, :web_error, &Logger.error(Exception.message(WebError.error(&1))))Page.on(page, :page_error, fun) gets one page's errors as exceptions. A test can also fail on
them: send them to the test process and refute_received at the end.
Watching it run
Headless is the default. Locally, run a headed browser slowed down, and
Page.pause!/1 to stop in the Playwright Inspector:
Playwright.instance() |> Playwright.chromium() |> BrowserType.launch!(headless: false, slow_mo: 500)PWDEBUG=1 opens the Playwright Inspector, as in Playwright Test. Run one test with
--trace:
PWDEBUG=1 mix test --trace test/my_app/sign_up_test.exs:12
--trace removes ExUnit's timeout and runs one test at a time, as Playwright Test's --debug
sets no timeout and one worker. Without it, ExUnit's timeout ends the test mid-inspection, and its
contexts close.
The driver's own logs go to stderr with DEBUG=pw:api in its environment:
{Playwright.Supervisor, env: [{"DEBUG", "pw:api"}]}GitHub Actions
Install the browsers with their system packages (--with-deps runs apt-get). Set MIX_ENV
for the whole job, so every task shares the test build: the install in :dev would compile the
dev deps too.
env:
MIX_ENV: test
steps:
# ... checkout, erlef/setup-beam
- run: mix deps.get
- run: mix playwright.install chromium --with-deps
- run: mix test
- uses: actions/upload-artifact@v7
if: ${{ !cancelled() }}
with:
name: test-results
path: test-resultsUpload unless cancelled, not only on failure(): when failures are rerun (see
Annotations), a job the rerun turned green still has the first run's files.
Cache neither the driver nor the browsers. On ubuntu-latest (26.04) a cold driver download
takes about 2 s and Chromium about 8 s, while restoring a cache of both takes about 3 s: it saves
roughly 6 s per job and churns the cache on every Playwright bump. For Chromium, with the system
libraries already on the image, --with-deps installs only 9 font packages (21 MB), and caching
them (cache-apt-pkgs-action, or the .deb files) didn't speed up the roughly 14 s step, which
apt-get update and dpkg dominate. WebKit's system packages are about 140 MB, and the runner's
apt mirror has stalled for whole attempts, so this library's CI caches the .deb files and
bounds each attempt. Upstream
advises the same: restoring a browser cache takes about as
long as downloading, and operating system dependencies aren't cacheable. For reference, if your
network is slow or you run offline: the driver goes to ~/.cache/playwright
(~/Library/Caches/playwright on macOS; the :cache_dir option moves it), the browsers to
~/.cache/ms-playwright (~/Library/Caches/ms-playwright on macOS, or
PLAYWRIGHT_BROWSERS_PATH).
In Playwright's image
Or run the job in Playwright's image, which has every browser (at PLAYWRIGHT_BROWSERS_PATH)
and its system packages, so only the driver is installed. Its tag is the pinned driver's
version, not this package's: mix playwright.cli --version prints it (Version 1.65.1, or
with executable: that CLI's version, the tag then), and the README names it. Install with
--no-browsers there: an image that lacks the driver's browsers then fails at launch with
Playwright's "Please update docker image as well", instead of mix playwright.install
downloading them on every run.
erlef/setup-beam needs unzip, ImageOS and HOME there. It pays off with WebKit or many
browser jobs. The image is about 2 GB, pulled per job on hosted runners, and it is Ubuntu 24.04:
a _build (with NIFs) or a cached OTP from a job on ubuntu-latest may not run in it, so build
in the image too. Services are reached by name, not localhost.
runs-on: ubuntu-24.04
container:
image: mcr.microsoft.com/playwright:v1.65.1-noble
env:
MIX_ENV: test
ImageOS: ubuntu22
HOME: /root
steps:
- uses: actions/checkout@v6
- run: apt-get update && apt-get -y install unzip
- uses: erlef/setup-beam@v1
with:
elixir-version: "1.20"
otp-version: "29"
- run: mix deps.get
- run: mix playwright.install --no-browsers
- run: mix testAnnotations
Playwright.Test.GitHubFormatter is Playwright Test's github reporter: annotations for the
failed tests (at their line), failed setup_alls and slow files, and a summary. It prints
only those, so name ExUnit.CLIFormatter next to it (--formatter replaces the configured
formatters). When failures are rerun, pass it to the rerun too: as upstream annotates every
attempt, a test failing twice gets an error per run (the rerun's under Retry #1), and one
passing on the rerun counts as flaky in the rerun's summary (so does one that a failed
setup_all kept from running in the first run, where upstream counts it as passed). As it
takes a mix test --failed run for retry 1, a local --failed rerun after a fix lists every
fixed test as flaky: the formatter is meant for CI. Rerun
only on exit status 2 (tests failed): any other failure, such as a crash or a missed coverage
threshold, would otherwise go green on an empty --failed run.
On Elixir 1.20 and earlier, --failed loses some failures: see
Retries.
erlef/setup-beam's problem matchers annotate each failure again, at the test's line, so turn
them off:
- uses: erlef/setup-beam@v1
with:
elixir-version: "1.20"
otp-version: "29"
disable_problem_matchers: true
- run: |
f="--formatter ExUnit.CLIFormatter --formatter Playwright.Test.GitHubFormatter"
mix test $f || { [ $? -eq 2 ] && mix test --failed $f; }With --partitions, rerun without it. The failures manifest holds only this partition's
failures, and mix test deals the files to the partitions round-robin, so --partitions would
deal them again: a partition reruns only some of its failures, possibly none, and can exit 0.
- env:
MIX_TEST_PARTITION: ${{ matrix.partition }}
run: mix test --partitions 4 || { [ $? -eq 2 ] && mix test --failed; }Docker
Browsers need system libraries, so install them in the image:
FROM elixir:1.20
ENV MIX_ENV=test
WORKDIR /app
COPY mix.exs mix.lock ./
RUN mix local.hex --force && mix deps.get && mix deps.compile
RUN mix playwright.install chromium --with-deps
COPY . .
CMD ["mix", "test"]Remote browsers
When the tests can't run in Playwright's image (local development on macOS, or an app's own
image), run only the browsers there and connect to them. The image's version must match the
driver's (Playwright.Driver.version/0):
docker run -p 3000:3000 --rm --init -it mcr.microsoft.com/playwright:v1.65.1-noble \
npx -y playwright@1.65.1 run-server --port 3000 --host 0.0.0.0
browser =
Playwright.instance()
|> Playwright.chromium()
|> BrowserType.connect!("ws://localhost:3000/", expose_network: "<loopback>")The local driver still runs; only the browser is remote. expose_network: "<loopback>" lets the
remote browser reach localhost on your machine, where the app under test runs. For the pooled
browsers of Playwright.Test, set connect_options
(Remote browsers).
More: trace viewer, debugging, CI, Docker.