# `Playwright`
[🔗](https://github.com/ftes/playwright_ex/blob/v1.65.0-rc.3/lib/playwright/api/playwright.ex#L7)

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 {: .warning}
>
> 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](getting-started.md) and
[From playwright.dev to Elixir](api-conventions.md) 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:

```elixir
# 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}`).

# `error`

```elixir
@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.

# `t`

```elixir
@type t() :: %Playwright{
  conn: term(),
  guid: term(),
  initializer: term(),
  table: term(),
  type: term()
}
```

A `Playwright` handle. Compare handles with `==`, their fields are internal.

# `chromium`

```elixir
@spec chromium(t()) :: Playwright.BrowserType.t()
```

This object can be used to launch or connect to Chromium, returning instances of [`Browser`](`Playwright.Browser`).

*Since Playwright 1.8.*

# `device`

```elixir
@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"))

# `devices`

```elixir
@spec devices() :: %{optional(String.t()) =&gt; 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"`.

# `devices`

```elixir
@spec devices(t()) :: %{
  optional(String.t()) =&gt; 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`.

```elixir
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.*

# `errors`

```elixir
@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:

```elixir
try do
  Page.locator(page, ".foo") |> Locator.wait_for!()
rescue
  _ in Playwright.TimeoutError ->
    # Do something if this is a timeout.
    nil
end
```

*Since Playwright 1.8.*

# `firefox`

```elixir
@spec firefox(t()) :: Playwright.BrowserType.t()
```

This object can be used to launch or connect to Firefox, returning instances of [`Browser`](`Playwright.Browser`).

*Since Playwright 1.8.*

# `instance`

```elixir
@spec instance(atom()) :: t()
```

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.

# `request`

```elixir
@spec request(t()) :: Playwright.APIRequest.t()
```

Exposes API that can be used for the Web API testing.

*Since Playwright 1.16.*

# `selectors`

```elixir
@spec selectors(t()) :: Playwright.Selectors.t()
```

Selectors can be used to install custom selector engines. See
[extensibility](https://playwright.dev/docs/extensibility) for more information.

*Since Playwright 1.8.*

# `webkit`

```elixir
@spec webkit(t()) :: Playwright.BrowserType.t()
```

This object can be used to launch or connect to WebKit, returning instances of [`Browser`](`Playwright.Browser`).

*Since Playwright 1.8.*

---

*Consult [api-reference.md](api-reference.md) for complete listing*
