Elixir client for Playwright, ported 1:1 from the official JavaScript client.
Start a driver with Playwright.Supervisor, then get the root object:
{:ok, _} = Playwright.Supervisor.start_link()
playwright = Playwright.instance()
{:ok, browser} = Playwright.BrowserType.launch(Playwright.chromium(playwright))
:ok = Playwright.Browser.close(browser)timeout: 0 means no timeout
As in Playwright JS, timeout: 0 waits forever instead of failing at once. :infinity is
the same and reads better in Elixir.
The public API (Playwright, Playwright.BrowserType, ...) is generated from
upstream's docs, so the docs at playwright.dev apply; the
Getting started and
From playwright.dev to Elixir guides show how.
The Playwright object
Playwright module provides a method to launch a browser instance. The following is a typical example of using Playwright to drive automation:
# Or Playwright.firefox/1 or Playwright.webkit/1.
browser = BrowserType.launch!(Playwright.chromium(playwright))
page = Browser.new_page!(browser)
Page.goto!(page, "http://example.com")
# other actions...
Browser.close!(browser)Since Playwright 1.8.
The examples alias the modules they use (alias Playwright.{Locator, Page}).
Summary
Types
An error a call fails with: the tuple forms return {:error, error}, the bang forms raise it.
These are what a JS call rejects with: Playwright's errors (Playwright.PlaywrightError for
JS Error, Playwright.TimeoutError, Playwright.TargetClosedError,
Playwright.AbortError, the matchers' Playwright.ExpectError), and what the client
throws itself: RuntimeError for a JS new Error(message) ("Route is already handled!"), the
protocol's ValidationError for an argument of the wrong type, JSON.DecodeError where JS's
JSON.parse fails and File.Error for local files. Anything else (ArgumentError for an
unknown option, a FunctionClauseError) is a bug or a misuse and raises in both forms.
A Playwright handle. Compare handles with ==, their fields are internal.
Functions
This object can be used to launch or connect to Chromium, returning instances of Browser.
The device descriptor of name in devices/0, upstream's devices['iPhone 13']: a keyword
list of options. An unknown name raises ArgumentError, naming the closest ones.
Playwright's device descriptors by name, as static data: upstream's
import { devices } from '@playwright/test'. A descriptor is a keyword list of the options
of Playwright.Browser.new_context/2 for that device (user_agent, viewport,
device_scale_factor, is_mobile, has_touch, and its default_browser_type, which
new_context ignores), the options devices/1 returns from a driver as a map
Returns a dictionary of devices to be used with Playwright.Browser.new_context/2 or Playwright.Browser.new_page/2.
Playwright methods might fail if they are unable to fulfill a request. For example,
Playwright.Locator.wait_for/2 might fail if the selector doesn't match any nodes during the given timeframe.
This object can be used to launch or connect to Firefox, returning instances of Browser.
The root Playwright object of the driver started as name.
Exposes API that can be used for the Web API testing.
Selectors can be used to install custom selector engines. See extensibility for more information.
This object can be used to launch or connect to WebKit, returning instances of Browser.
Types
@type error() :: Playwright.PlaywrightError.t() | Playwright.TimeoutError.t() | Playwright.TargetClosedError.t() | Playwright.AbortError.t() | Playwright.ExpectError.t() | %RuntimeError{__exception__: term(), message: term()} | %Playwright.Protocol.ValidatorPrimitives.ValidationError{ __exception__: term(), message: term() } | %JSON.DecodeError{ __exception__: term(), data: term(), message: term(), offset: term() } | %File.Error{ __exception__: term(), action: term(), path: term(), reason: term() }
An error a call fails with: the tuple forms return {:error, error}, the bang forms raise it.
These are what a JS call rejects with: Playwright's errors (Playwright.PlaywrightError for
JS Error, Playwright.TimeoutError, Playwright.TargetClosedError,
Playwright.AbortError, the matchers' Playwright.ExpectError), and what the client
throws itself: RuntimeError for a JS new Error(message) ("Route is already handled!"), the
protocol's ValidationError for an argument of the wrong type, JSON.DecodeError where JS's
JSON.parse fails and File.Error for local files. Anything else (ArgumentError for an
unknown option, a FunctionClauseError) is a bug or a misuse and raises in both forms.
@type t() :: %Playwright{ conn: term(), guid: term(), initializer: term(), table: term(), type: term() }
A Playwright handle. Compare handles with ==, their fields are internal.
Functions
@spec chromium(t()) :: Playwright.BrowserType.t()
This object can be used to launch or connect to Chromium, returning instances of Browser.
Since Playwright 1.8.
@spec device(String.t()) :: Playwright.Browser.new_context_options()
The device descriptor of name in devices/0, upstream's devices['iPhone 13']: a keyword
list of options. An unknown name raises ArgumentError, naming the closest ones.
use Playwright.Test, Playwright.device("iPhone 13")
# config/runtime.exs
if config_env() == :test, do: config(:playwright, :test, Playwright.device("iPhone 13"))
@spec devices() :: %{optional(String.t()) => Playwright.Browser.new_context_options()}
Playwright's device descriptors by name, as static data: upstream's
import { devices } from '@playwright/test'. A descriptor is a keyword list of the options
of Playwright.Browser.new_context/2 for that device (user_agent, viewport,
device_scale_factor, is_mobile, has_touch, and its default_browser_type, which
new_context ignores), the options devices/1 returns from a driver as a map:
iphone = Playwright.devices()["iPhone 13"]
context = Browser.new_context!(browser, iphone)Upstream's { ...devices['iPhone 13'], viewport: { width: 800, height: 600 } } is
iphone ++ [viewport: %{width: 800, height: 600}]: a later key wins, as in JS's spread.
It needs no driver, so it works at compile time. A name that isn't a device's gives
nil, which context_options: rejects: device/1 raises instead, naming the closest.
The data is that of the pinned Playwright version.
Devices
"BlackBerry Z30", "Blackberry PlayBook", "Desktop Chrome", "Desktop Chrome HiDPI", "Desktop Edge", "Desktop Edge HiDPI", "Desktop Firefox", "Desktop Firefox HiDPI", "Desktop Safari", "Galaxy A55", "Galaxy Note 3", "Galaxy Note II", "Galaxy S III", "Galaxy S24", "Galaxy S5", "Galaxy S8", "Galaxy S9+", "Galaxy Tab S4", "Galaxy Tab S9", "Galaxy Z Flip 6", "Galaxy Z Flip 6 Cover", "Galaxy Z Flip 7", "Galaxy Z Flip 7 Cover", "Galaxy Z Fold 6", "Galaxy Z Fold 6 Cover", "Galaxy Z Fold 7", "Galaxy Z Fold 7 Cover", "Kindle Fire HDX", "LG Optimus L70", "Microsoft Lumia 550", "Microsoft Lumia 950", "Moto G4", "Nexus 10", "Nexus 4", "Nexus 5", "Nexus 5X", "Nexus 6", "Nexus 6P", "Nexus 7", "Nokia Lumia 520", "Nokia N9", "Pixel 10", "Pixel 10 Pro", "Pixel 10 Pro XL", "Pixel 2", "Pixel 2 XL", "Pixel 3", "Pixel 4", "Pixel 4a (5G)", "Pixel 5", "Pixel 6", "Pixel 6 Pro", "Pixel 6a", "Pixel 7", "Pixel 7 Pro", "Pixel 7a", "Pixel 8", "Pixel 8 Pro", "Pixel 8a", "Pixel 9", "Pixel 9 Pro", "Pixel 9 Pro XL", "iPad (gen 11)", "iPad (gen 5)", "iPad (gen 6)", "iPad (gen 7)", "iPad Mini", "iPad Pro 11", "iPhone 11", "iPhone 11 Pro", "iPhone 11 Pro Max", "iPhone 12", "iPhone 12 Mini", "iPhone 12 Pro", "iPhone 12 Pro Max", "iPhone 13", "iPhone 13 Mini", "iPhone 13 Pro", "iPhone 13 Pro Max", "iPhone 14", "iPhone 14 Plus", "iPhone 14 Pro", "iPhone 14 Pro Max", "iPhone 15", "iPhone 15 Plus", "iPhone 15 Pro", "iPhone 15 Pro Max", "iPhone 16", "iPhone 16 Plus", "iPhone 16 Pro", "iPhone 16 Pro Max", "iPhone 16e", "iPhone 17", "iPhone 17 Pro", "iPhone 17 Pro Max", "iPhone 17e", "iPhone 6", "iPhone 6 Plus", "iPhone 7", "iPhone 7 Plus", "iPhone 8", "iPhone 8 Plus", "iPhone Air", "iPhone SE", "iPhone SE (3rd gen)", "iPhone X", "iPhone XR".
Each also has a landscape variant ("iPhone 13 landscape"), but
"Desktop Chrome", "Desktop Chrome HiDPI", "Desktop Edge", "Desktop Edge HiDPI", "Desktop Firefox", "Desktop Firefox HiDPI", "Desktop Safari".
@spec devices(t()) :: %{ optional(String.t()) => Playwright.Browser.new_context_options() }
Returns a dictionary of devices to be used with Playwright.Browser.new_context/2 or Playwright.Browser.new_page/2.
iphone = Playwright.devices(playwright)["iPhone 6"]
browser = BrowserType.launch!(Playwright.webkit(playwright))
context = Browser.new_context!(browser, iphone)
page = BrowserContext.new_page!(context)
Page.goto!(page, "http://example.com")
# other actions...
Browser.close!(browser)In Elixir, a descriptor has the snake_case keys of the options (user_agent:), as in the Python client: Browser.new_context(browser, devices["iPhone 6"]).
Since Playwright 1.8.
@spec errors(t()) :: %{TimeoutError: Playwright.TimeoutError}
Playwright methods might fail if they are unable to fulfill a request. For example,
Playwright.Locator.wait_for/2 might fail if the selector doesn't match any nodes during the given timeframe.
For certain types of errors Playwright uses specific error classes. These classes are available via
Playwright.errors/1.
An example of handling a timeout error:
try do
Page.locator(page, ".foo") |> Locator.wait_for!()
rescue
_ in Playwright.TimeoutError ->
# Do something if this is a timeout.
nil
endSince Playwright 1.8.
@spec firefox(t()) :: Playwright.BrowserType.t()
This object can be used to launch or connect to Firefox, returning instances of Browser.
Since Playwright 1.8.
The root Playwright object of the driver started as name.
While a lost driver is being replaced (see Playwright.Supervisor), this waits for the new
driver and returns its root, also when called from a disconnected listener. It exits if the
supervisor is not running, or not restarting the driver.
@spec request(t()) :: Playwright.APIRequest.t()
Exposes API that can be used for the Web API testing.
Since Playwright 1.16.
@spec selectors(t()) :: Playwright.Selectors.t()
Selectors can be used to install custom selector engines. See extensibility for more information.
Since Playwright 1.8.
@spec webkit(t()) :: Playwright.BrowserType.t()
This object can be used to launch or connect to WebKit, returning instances of Browser.
Since Playwright 1.8.