Snippets alias Playwright.{Browser, BrowserType, ...}.
Installation
Add the dependency to mix.exs as shown in the Overview. Its name
is the app's, :playwright, and hex: :playwright_ex is required: the Hex package is
playwright_ex, as playwright on Hex is another library. If you only use it in tests, prefer
only: [:dev, :test] to only: :test: its mix tasks, and mix usage_rules.sync for its
usage rules, then work in :dev, where it starts no driver. Fetch it and install the
driver and the browsers:
mix deps.get
mix playwright.install
The driver is Node.js plus the playwright-core package, both pinned and checksum-verified, so
no Node.js or npm is needed beforehand. It goes to the user cache directory
(config :playwright, :driver, cache_dir: ... overrides it, see Playwright.Driver; to take it
from an environment variable, locally or in CI, read that in config/config.exs) and installs itself on first
start if missing. Browsers
go to Playwright's browser cache.
Arguments are playwright install's:
mix playwright.install chromium # one browser
mix playwright.install chromium --with-deps # and its system packages (Linux CI)
In CI, run it in the tests' env, as Debugging and CI shows.
To run a browser you already have, such as a system or Nix Chrome, install only the driver and
launch the browser with :executable_path or :channel:
mix playwright.install --no-browsers
playwright = Playwright.instance()
BrowserType.launch!(Playwright.chromium(playwright), executable_path: "/path/to/chrome")The library needs Elixir 1.18 or later. The browsers run where Playwright's do: Windows 11+, macOS 14+, Debian 12 and 13, Ubuntu 22.04, 24.04 and 26.04 (system requirements).
Starting the driver
Playwright.Supervisor runs one driver and its connection. Add it to your supervision tree:
children = [
{Playwright.Supervisor, name: MyApp.PlaywrightDriver}
]and get the root Playwright object by that name:
playwright = Playwright.instance(MyApp.PlaywrightDriver)Without :name, the supervisor registers as Playwright, which Playwright.instance/0
uses. Tests don't need it: Playwright.Case gives each test a browser from drivers the runner
starts and stops (Testing with ExUnit).
To use an npm-managed Playwright instead of the pinned driver, pass
executable: "assets/node_modules/.bin/playwright"; Playwright.Driver lists the other
options.
First script
Navigate to a page, print its title and take a screenshot:
alias Playwright.{Browser, BrowserType, Page}
{:ok, _} = Playwright.Supervisor.start_link()
browser = Playwright.instance() |> Playwright.chromium() |> BrowserType.launch!()
page = Browser.new_page!(browser)
Page.goto!(page, "https://playwright.dev/")
IO.puts(Page.title!(page))
Page.screenshot!(page, path: "example.png")
Browser.close!(browser)
Supervisor.stop(Playwright)Save it as example.exs and run mix run example.exs. mix run halts the VM without stopping
the supervisor; Supervisor.stop/1 waits for the driver to exit, which could otherwise reset the
terminal afterwards. If your application already starts the supervisor, drop the start_link/1
and Supervisor.stop/1 lines, pass its name to Playwright.instance/1, and end the script
with Application.stop(:my_app) instead (your app restarts a supervisor stopped on its own).
Browser.new_page!/1 opens a page in a context of its own. A
context is an isolated browser session (cookies,
storage, options such as base_url) and is cheap to create, so use one per test or per user:
context = Browser.new_context!(browser, base_url: "http://localhost:4000")
page = BrowserContext.new_page!(context)
Page.goto!(page, "/")
BrowserContext.close!(context)Playwright.firefox/1 and
Playwright.webkit/1 launch the other browsers. Browsers run
headless by default; Watching it run shows how to launch
one headed.
Finding elements
Find elements the way a user does: get_by_role with name: for interactive elements,
get_by_label for form fields, get_by_text for non-interactive text, and get_by_test_id
when nothing user-facing identifies the element. Use
Page.locator/3 with CSS or XPath only as a last resort, never
by CSS classes or DOM structure.
Page.get_by_role(page, :button, name: "Save") |> Locator.click!()
Page.get_by_role(page, :listitem)
|> Locator.filter(has_text: "Apple")
|> Locator.get_by_role(:button, name: "Buy")
|> Locator.click!()Locators are lazy and strict: nothing is looked up until an action, and an action on a locator that
matches several elements fails. Narrow it with
Locator.filter/2,
Locator.first/1,
Locator.last/1 or
Locator.nth/2. Act directly, as actions wait for their element, so
don't check is_visible first. Avoid
Page.wait_for_timeout/2, which is for debugging: wait
for what the user sees. More: locators.
Timeouts
Actions and navigations time out after 30 seconds (in a Playwright.Test test, as in
Playwright Test, only the test's timeout bounds them, see
Testing with ExUnit). Set defaults per context (or page)
instead of a timeout: per call:
BrowserContext.set_default_timeout(context, 5_000)
BrowserContext.set_default_navigation_timeout(context, 10_000)For no timeout, pass timeout: :infinity; 0 also means no timeout, unlike Elixir's convention (details).
A call's timeout: option wins. Assertions (Playwright.Expect) retry for 5 seconds by
default:
# config/test.exs
config :playwright, :expect, timeout: 10_000Logging
Each API call logs at :debug, as DEBUG=pw:api does in JS. To silence it:
Logger.put_application_level(:playwright, :info)Upgrading
To upgrade, bump the dependency and run mix playwright.install again for the new driver and
browsers. Read the changelog and Playwright's release
notes.
Usage rules for coding agents
The package ships usage rules for coding agents. Sync them with
usage_rules as a skill:
# mix.exs
def project do
[
# ...
usage_rules: [
skills: [
build: [
playwright: [
description: "Use when writing browser automation or tests with Playwright.",
usage_rules: [:playwright]
]
]
]
]
]
endRun mix usage_rules.sync after upgrading.
Next
From playwright.dev to Elixir shows how a JS call reads in Elixir, and the Cheatsheet lists frequent calls.