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_000

Logging

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]
          ]
        ]
      ]
    ]
  ]
end

Run 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.