Options, devices and projects

Copy Markdown View Source

Playwright Test's use options are options at five levels here, each over the one before per option: the config, a project, the module, a describe block and the test. A call's own options win over all of them. The rules (which level takes which option, nil, how the layers merge) are in Playwright.Test's Context defaults and Browser; this guide shows each level. Snippets alias Playwright.{Browser, BrowserContext, Page, Test} and Playwright.Test.BrowserPool.

Playwright TestHere
use: { locale: 'de-DE' } in the configconfig :playwright, :test, locale: "de-DE"
a project's useparameterize: [Playwright.Test.parameters(locale: "de-DE")]
test.use({ locale: 'de-DE' }) at a file's topuse Playwright.Case, locale: "de-DE"
test.use({ ... }) in a test.describe@describetag Test.use(locale: "de-DE")
(a describe around one test)@tag Test.use(locale: "de-DE")
...devices['iPhone 13']Playwright.device("iPhone 13") as the options

The context options are options of their own, with Playwright.Browser.new_context/2's names (locale, viewport, color_scheme, timezone_id, base_url, storage_state, ...), and context_options is Playwright Test's contextOptions, for any other option of new_context (record_har, strict_selectors). The values are known at compile time, not functions. The config's, the project's and the module's options reach every context the module creates, setup_all's included (goto("/") works there with base_url); a describe's and a test's reach that test's contexts, as ExUnit runs setup_all without them.

A library that passes options in a call merges into the test's resolved ones, Playwright.Test.info().use, as the call's replace them as a whole (extra_http_headers too): Browser.new_context!(browser, extra_http_headers: Map.merge(Test.info().use[:extra_http_headers] || %{}, headers)).

Devices

Playwright Test's devices['iPhone 13'] is Playwright.device("iPhone 13"): the device's context options as a keyword list, static data of the pinned Playwright version, so it needs no driver and works at compile time. An unknown name raises, naming the closest; Playwright.devices/0 is the map of all of them, and its docs list the names. Browser.new_context!/2 takes a device as it is or with more. Playwright Test's { ...devices['iPhone 13'], locale: 'de-DE' } is ++, where a later key wins, as in JS's spread:

test "on a phone" do
  browser = BrowserPool.browser(browser_name: :webkit)
  iphone = Playwright.device("iPhone 13")
  page = BrowserContext.new_page!(Browser.new_context!(browser, iphone ++ [locale: "de-DE"]))
  # ...
end

The device's options are the call's, so they win over Playwright Test's defaults (its viewport over the 1280x720 one), and its default_browser_type ("webkit") names its browser, which new_context ignores.

For a module, Playwright Test's test.use({ ...devices['iPhone 13'] }) at a file's top, give the device to a use Playwright.Test (a module's uses add up; in one use, it is use Playwright.Case, [async: true] ++ Playwright.device("iPhone 13"), where a later key wins):

defmodule MyApp.PhoneTest do
  use Playwright.Case, async: true
  use Playwright.Test, Playwright.device("iPhone 13")

  test "on a phone", %{page: page} do
    # ...
  end
end

As in Playwright Test, the device also picks the browser: without a browser_name in the module's use, its project or the config, BrowserPool.browser/1 (so Playwright.Case's browser) launches the device's default_browser_type, WebKit here. A browser_name set in any of those wins (use Playwright.Case, browser_name: :chromium). Playwright.Case puts the browser's name in the context, %{browser_name: :webkit} here.

For the whole suite (one project), the device goes in the config. config/config.exs and config/test.exs are evaluated before the dependencies are compiled, so Playwright.device/1 can't be called there: write the options out, or set them in config/runtime.exs, which runs after the compilation (the runner reads the config at run time). Guard it with config_env(): the dependency is only: [:dev, :test], so Playwright.device/1 fails in every other env:

# config/runtime.exs
if config_env() == :test do
  config :playwright, :test, Playwright.device("Desktop Chrome")
end

Describe blocks and tests

For a describe block, Playwright Test's test.use in a test.describe, tag it with Playwright.Test.use/1, which takes the options a describe may set: the context options, context_options, action_timeout, navigation_timeout, trace, screenshot and video:

describe "in Berlin" do
  @describetag Test.use(timezone_id: "Europe/Berlin", locale: "de-DE")

  test "shows local time", %{page: page} do
    # ...
  end
end

For one test, @tag it. Playwright Test has no test.use for a single test, and nests a describe around it instead; ExUnit's describe blocks can't nest:

@tag Test.use(color_scheme: :dark, trace: :on)
test "is readable in the dark", %{page: page} do
  # ...
end

The browser is the module's, as in Playwright Test, which rejects a browser option in a describe because it forces a new worker: a @describetag or @tag with browser_name, headless, channel, launch_options, connect_options or default_browser_type raises when the module compiles a test under it, so does one with a device (@tag Test.use(Playwright.device("Pixel 7"))). The module takes them, in its use or its @moduletag Test.use(...)s (merged, the later winning per option), for all its tests. For a device's emulation alone in a describe, drop its browser: Test.use(Keyword.delete(Playwright.device("Pixel 7"), :default_browser_type)). To run a module once per device, make each device a project (Projects), as Playwright Test's projects: [{ name, use: { ...devices[name] } }]:

use Playwright.Case,
  parameterize: for(name <- ["iPhone 13", "Pixel 7"], do: Playwright.Test.parameters([name: name] ++ Playwright.device(name)))

Plain tags named like options (@tag trace: :on) set nothing: only Test.use/1's keys are read.

Projects

Playwright Test's projects: [{ use: { ...devices['Desktop Chrome'] } }, ...], one run per browser and device, are ExUnit's parameterize: with a Playwright.Test.parameters/1 map per project. It takes Test.use/1's options, the worker's (browser_name, headless, channel, launch_options, connect_options) and the project's name:

defmodule MyApp.Projects do
  # `PROJECTS="Desktop Firefox" mix test` runs one.
  def all do
    names = String.split(System.get_env("PROJECTS", "Desktop Chrome,Desktop Firefox,Desktop Safari"), ",")
    for name <- names, do: Playwright.Test.parameters([name: name] ++ Playwright.device(name))
  end
end

defmodule MyApp.SignUpTest do
  use Playwright.Case, async: true, parameterize: MyApp.Projects.all()

  test "signs up", %{page: page} do
    # ...
  end
end

The project's options are over the config's and under the module's use, for every context of the module's run, setup_all's included, and its device picks the browser as above: Chromium, Firefox and WebKit here (not with a browser_name in the config, which wins over a device: give the projects one, Test.parameters(browser_name: :firefox)). A module adds its own options over the project's (use Playwright.Case, parameterize: MyApp.Projects.all(), locale: "de-DE"), and parameters of your own go next to them: Map.put(Test.parameters(...), :role, :admin). The name is upstream's project.name: a failure prints it as ExUnit's parameters (Parameters: %{"playwright.project": #Playwright.Test.Project<"de">}), the GitHub annotations of Playwright.Test.GitHubFormatter start with it ([de] › ...), and it fills a snapshot template's {projectName}. Without one ("" is none), the annotations have no [...] › prefix and {projectName} is empty, as upstream; ExUnit's Parameters: line of a failure prints the project's options (Playwright.Test.Project's Inspect). Name every project of a module that has more than one, as Test.parameters([name: "de", locale: "de-DE"] ++ Playwright.device("Desktop Chrome")). ExUnit's filters don't see parameterize: values, so to run one project, read an env var where the list is built, as above. On Elixir 1.20 and earlier, mix test --failed loses a failure in a parameterize: module when another parameter set passes the same test: run one project per mix test, which removes the project dimension only (Retries).

Your own case template

To add setup after the page's, use Playwright.Case in your template's using and put the setup after it there; a template's own setup runs before the ones its using brings in:

# test/support/browser_case.ex
defmodule MyApp.BrowserCase do
  use ExUnit.CaseTemplate

  using do
    quote do
      use Playwright.Case

      setup %{context: context} do
        Playwright.BrowserContext.set_default_timeout(context, 5_000)
        :ok
      end
    end
  end
end

A template forwards its options from using opts as they are: a module's uses merge per key, the later winning, and ExUnit.Case's keys are ignored. So its own use Playwright.Test, ... lines come before the forwarded options, which go last; else the template's options (a device's viewport, say) override the test module's, the reverse of Playwright Test, where the file's test.use beats the project's device. Options of the template's own are unknown to use Playwright.Test and raise: pop them before forwarding the rest.

using opts do
  {sandbox, opts} = Keyword.pop(opts, :sandbox, true)

  quote do
    use Playwright.Test, Playwright.device("iPhone 13")
    use Playwright.Case, unquote(opts)
    @moduletag sandbox: unquote(sandbox)
  end
end

To change a piece, say another browser, write the template from the pieces. Its own setup runs before those of its using, so make use Playwright.Test the first line of its body: the test is then registered before the template's setup creates a context (a context created before the registration makes it raise, saying so). That use takes no options: they go in using.

defmodule MyApp.BrowserCase do
  use ExUnit.CaseTemplate
  use Playwright.Test

  alias Playwright.{Browser, BrowserContext}
  alias Playwright.Test.BrowserPool

  using do
    quote do
      use Playwright.Test
      alias Playwright.{Browser, BrowserContext, Expect, Locator, Page, Test}
    end
  end

  setup_all do
    %{browser: BrowserPool.browser()}
  end

  # `@tag Test.use(locale: "de-DE")` on a test sets its options.
  setup %{browser: browser} do
    context = Browser.new_context!(browser)
    %{context: context, page: BrowserContext.new_page!(context)}
  end
end

The running test

Playwright.Test.info/0 is Playwright Test's test.info(): the running test's test_pid, file, test_name, output_dir, retry (0, or 1 under mix test --failed), timeout, deadline and its resolved options, use, in the test's process and in processes with it in $callers (a Task, a route handler). deadline is monotonic milliseconds (compare with System.monotonic_time(:millisecond)) by which the test must be done: after it, the test's contexts are closed and Playwright calls fail; :infinity without a test timeout. A library that waits or retries on its own stops by it. A library that owns resources per test (an Ecto sandbox owner, a session) finds the test from a Task with it: Playwright.Test.info().test_pid. In the module's setup_all, info/0 returns the module's fields (file, timeout, use); elsewhere it raises, also in on_exit callbacks, where Playwright.Test.info(test_pid) has the test's result. A library that also runs outside them reads the config there:

use = if Test.in_registered_scope?(), do: Test.info().use, else: Test.config()
use[:base_url]

The config has another shape (see Playwright.Test.info/0), so read the keys both have with Access: use[:base_url] is nil when unset, where use.base_url raises.