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

Runs one Playwright driver and its connection.

    children = [{Playwright.Supervisor, name: MyApp.PlaywrightDriver}]
    playwright = Playwright.instance(MyApp.PlaywrightDriver)

Options:

  * `:name` - defaults to `Playwright`.
  * `:executable`, `:node`, `:cache_dir` - see `Playwright.Driver`; by default
    `config :playwright, :driver`.
  * `:env` - extra environment variables for the driver process.

Child: the driver connection (the driver's pipe and the connection process), the OTP form of
JS's `outofprocess.start()`. The child id is the `:name`, so drivers of different names can
share a supervision tree.

## Lifetimes

When the driver exits, its connection is closed and the supervisor starts a new driver, with a
new root object.

As `Playwright.BrowserType.connect/3` does when its connection is lost, every page and context
emits `close`, then every browser `disconnected` (also when the supervisor stops), and waits on
them fail with `Playwright.TargetClosedError`: a lost driver is noticed by `disconnected`.

Handles of the old driver keep reading their last state (`Playwright.Page.is_closed/1` is
true, `Playwright.Page.url/1` the last URL) until the processes that created or closed its
browsers and contexts have exited, or the supervisor stops. Calls and other writes on them fail
with `Playwright.TargetClosedError`; closing a page, context or browser returns `:ok`, as it
does for anything closed.

Get the root again with `Playwright.instance/1`: it waits for the new driver (in a
`disconnected` listener too).

The loss is logged as an error, with the driver's exit status (137: killed, often for lack of
memory), its version, the supervisor's name and how many browsers and contexts it closed.

Browsers and contexts are not closed when the process that created them exits; only the data
the library keeps for closed ones is freed then. So close what you open, as tests close their
contexts in `on_exit`.

Starting installs the driver first if it is missing
(`Playwright.Driver.ensure_installed/1`): a download that blocks `start_link/1`.

# `option`

```elixir
@type option() ::
  {:name, atom()}
  | {:executable, Path.t()}
  | {:node, Path.t()}
  | {:cache_dir, Path.t()}
  | {:env, Enumerable.t({String.t(), String.t()})}
```

An option of `start_link/1`, see the module docs.

# `child_spec`

```elixir
@spec child_spec([option()]) :: Supervisor.child_spec()
```

A child spec whose id is the `:name` (`Playwright` by default).

# `start_link`

```elixir
@spec start_link([option()]) :: Supervisor.on_start()
```

Starts the driver and its connection under a supervisor registered as `:name`. Returns once
the root object is ready (`Playwright.instance/1`), after installing the driver if needed.

---

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