# `Playwright.Test.BrowserPool`
[🔗](https://github.com/ftes/playwright_ex/blob/v1.65.0-rc.3/lib/playwright/test/browser_pool.ex#L1)

Browsers for tests, on drivers the pool starts and stops after the suite: Playwright Test's
worker-scoped `browser` and `playwright` fixtures, and its worker model. Contexts and pages
come from the plain API (`Playwright.Browser.new_context!/2`,
`Playwright.BrowserContext.new_page!/1`), and a test of `use Playwright.Test` records the
contexts it creates on a pooled browser and gives them Playwright Test's defaults.

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

    setup %{browser: browser} do
      context = Browser.new_context!(browser)
      %{context: context, page: BrowserContext.new_page!(context)}
    end

`browser/1` takes these options, merged over `config :playwright, :test` (`launch_options`
and `driver` one level deep). In a module of `use Playwright.Test`, the module's
`browser_name`, `headless`, `channel`, `launch_options` and `connect_options` (its `use` options and its project's,
see "Browser" in `Playwright.Test`) are between the two, each replacing the config's as a
whole (`launch_options` too, as upstream's fixture); the call's `launch_options` merge over
them one key at a time:

  * `:browser_name` - `:chromium` (default), `:firefox` or `:webkit` (or its string); without one anywhere,
    that of the module's device.
  * `:headless`, `:channel` - Playwright Test's options of their own, set over the launch
    options' when given; unset (`nil`, default), the launch options' (`headless` `true` when
    they have none).
  * `:launch_options` - for `Playwright.BrowserType.launch/2`, with `headless` and `channel`
    over them (upstream's `_browserOptions`).
  * `:connect_options` - Playwright Test's `connectOptions`: `:ws_endpoint` (required) and
    the options of `Playwright.BrowserType.connect/3` (`:headers`, `:expose_network`,
    `:timeout`, `:slow_mo`). The browser is then connected to that Playwright server instead
    of launched, with the launch options (`headless` and `channel` over them) sent in the
    `x-playwright-launch-options` header (the
    call's `headers` win). `nil` (default) launches.
  * `:driver` - `[env: _]`, the driver's environment (`Playwright.Supervisor`'s `:env`). The
    driver itself is `config :playwright, :driver`'s, as `mix playwright.install` installs it.
  * `:on_start` - a function of the Playwright (`Playwright`) or `{m, f, args}`
    (called with the Playwright first), run once on each new driver before its browser
    launches: `&MyApp.Selectors.register/1`. Part of the worker's key, so pass a capture, not
    a closure. The worker's `headless` and `channel` are passed to the launch explicitly, over
    any default launch options an `on_start` sets.

A worker is one driver and one browser, keyed by all of the options, as upstream's worker hash
covers its project's options. A connected browser runs on the server, its driver here:
`on_start` runs on the driver before the connect, and its contexts get the defaults and are
recorded, as a launched browser's. Unknown options and bad values raise `ArgumentError`.

## Workers

A worker is a process that runs one driver and its browser at a time, of one set of options,
held by the scope that calls `browser/1`. Called in `setup_all`, the
module holds it until it ends, as upstream runs a file in one worker; a test's own calls then
go to its module's hold. In `setup` or a test of a module that holds none (or a `Task` of the
test, through `$callers`), the test holds it until it ends. The scope's further calls with the
same options return the same browser; other options take another worker. At the end of the scope
(the last step of a registered test's `on_exit`; for another scope, an `on_exit` its first call
registers), its workers go back, their drivers warm for the next caller of the options, unless it
failed: then the drivers stop, as upstream replaces a worker after a failure. A module fails
when its `setup_all` failed (raised, past its timeout, killed or taken down by a linked process;
only with `use Playwright.Test`, which registers and wraps it: a plain ExUnit module's
`setup_all` counts as passed, as an unregistered test does), when a test of it failed, or when a
test's artifacts took longer than their half of its timeout (its contexts may be left open). An
`on_exit` of `setup_all` that fails doesn't reset them, where upstream stops a worker whose
`afterAll` failed. Only registered tests have results: register tests with `use Playwright.Test`
to get Playwright Test's discard-after-failure; a scope with no known result (no registered
test, a doctest) counts as passed. A lost browser is launched (or connected) again by the scope's
next call.

At most `workers` workers are held at once (config, default half the schedulers, as Playwright
Test's `workers`); other scopes wait, first come first served, within ExUnit's test timeout
(not counted in `setup_all`'s). A scope that waits costs nothing, so ExUnit's `max_cases` can stay
above `workers`. A scope that holds a worker takes its further options over `workers`, so it
never waits while others wait for it; those workers stop at its end. A scope gets an idle
worker of its options, else a new one, else the longest idle worker of other options, whose
driver its `browser/1` restarts, as upstream restarts a worker of another hash: in a run that mixes
options, each switch costs a driver start (about 110 ms) and a browser launch.

The test id attribute of `get_by_test_id` is global to the VM (upstream's to the worker
process), so only a suite-wide one is safe: config `test_id_attribute`, which each pooled
driver gets.

With `connect_options`, each driver connects once, and the server launches a browser per
connection, so each worker has a browser of its own, as each Playwright Test worker does.

A driver you start yourself (`start_supervised!({Playwright.Supervisor, name: MyDriver})`,
then `Playwright.chromium/1` and `Playwright.BrowserType.launch!/2` or
`connect!/3`) has no cap, no reuse, no context defaults and no recording.

# `browser`

```elixir
@spec browser(keyword()) :: Playwright.Browser.t()
```

The browser of `opts` held by the calling scope (see the moduledoc): a registered test (the
caller or a process in its `$callers`; its module's, if the module holds one), else the
calling process, a `setup_all`'s. Raises outside ExUnit's processes. A call before `use
Playwright.Test` registered its test or `setup_all` (a case template's own `setup`) gets none of
the module's options, so the registration raises.

# `playwright`

```elixir
@spec playwright(Playwright.Browser.t()) :: Playwright.t()
```

The Playwright (`Playwright`) of a pooled browser's driver: its `selectors`,
`request` and other browser types. Raises for a browser the pool didn't launch.

---

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