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

Installs and locates the Playwright driver: a pinned `playwright-core` npm package plus
the pinned Node.js binary for the host platform. No Node.js is needed beforehand.

Mirrors playwright-python (`scripts/build_driver.py`, `_impl/_driver.py`), except that
Python assembles the bundle at wheel-build time and we do it lazily on the user's machine.

Layout (same as Python's `playwright/driver/`):

    <cache_dir>/<driver_version>/<platform>/
      node | node.exe   Node.js binary
      LICENSE           Node.js license
      package/          playwright-core npm package (package/cli.js is the entry point)

`cache_dir` defaults to `:filename.basedir(:user_cache, "playwright")`, overridable with
the `:cache_dir` option.

Overrides (no download happens when one is set):

  * `executable: path` - an npm-managed `playwright` CLI (e.g. `node_modules/.bin/playwright`),
    run as `path run-driver`.
  * `node: path` - like Python: use this Node binary with the cached `package/cli.js` (the
    package is still installed if missing).

## Configuration

The options default to `config :playwright, :driver`, which `Playwright.Supervisor` and
`mix playwright.install` both read:

    config :playwright, :driver, cache_dir: "/cache"

Put it in `config/config.exs`, not in a file imported only for one environment (such as
`config/test.exs`: `mix playwright.install` usually runs in `:dev`) or in `config/runtime.exs`
(`mix playwright.install` doesn't compile the project, so it doesn't read it). Mix evaluates
`config/config.exs` on every run, so an environment variable read there takes effect each time,
locally and in CI. No option has an environment variable: the library reads only those
upstream's client and reporters read (such as `PWDEBUG`, `PWDEBUGIMPL`, `GITHUB_WORKSPACE`),
`HTTPS_PROXY` (or `https_proxy`) for the driver download and, on Windows,
`PROCESSOR_ARCHITECTURE` for its platform; the Playwright CLI reads its own, such as
`PLAYWRIGHT_BROWSERS_PATH`. To take an option from one of your choice (an empty one counts as
unset):

    if dir = System.get_env("PLAYWRIGHT_CACHE_DIR") do
      config :playwright, :driver, cache_dir: dir
    end

A release evaluates `config/config.exs` when it's built, so a release that sets these at boot
reads them in `config/runtime.exs`, which `Playwright.Supervisor` sees.

# `option`

```elixir
@type option() ::
  {:executable, Path.t()}
  | {:node, Path.t()}
  | {:cache_dir, Path.t()}
  | {:platform, String.t()}
```

An option, overriding `config :playwright, :driver` (see the module docs). `:platform` (nodejs.org
naming, `"linux-x64"`) installs or locates the driver of another platform than the host's.

# `cache_dir`

```elixir
@spec cache_dir([option()]) :: String.t()
```

The cache directory: the `:cache_dir` option (or config), else the user cache
directory (`:filename.basedir(:user_cache, "playwright")`).

# `ensure_installed`

```elixir
@spec ensure_installed([option()]) :: {String.t(), [String.t()]}
```

Installs the driver unless it is installed or an override is set (`install/1`), then returns
`executable/1`. `Playwright.Supervisor` calls it when it starts.

# `executable`

```elixir
@spec executable([option()]) :: {String.t(), [String.t()]}
```

The driver command: `{program, args_prefix}`, to which `run-driver`, `install ...` etc. are
appended. Doesn't install, see `ensure_installed/1`.

# `install`

```elixir
@spec install([option() | {:force, boolean()}]) :: :ok
```

Downloads, verifies and extracts the driver. Idempotent; atomic (everything happens in a
temp dir next to the target, which is renamed into place only after all checks passed).

Options: `:cache_dir`, `:platform`, `force: true` to reinstall. Raises if a download or a
checksum fails.

# `install_browsers`

```elixir
@spec install_browsers([String.t()], [option()]) :: :ok
```

Installs browsers with the driver's own Node, like `python -m playwright install ...`
(which forwards its argv to `node cli.js`). No args installs its default browsers, as
`npx playwright install`. Browsers land in Playwright's usual
location (`PLAYWRIGHT_BROWSERS_PATH`, default `~/Library/Caches/ms-playwright` etc). The
output goes to stdout. Raises if the CLI exits with a non-zero status, as `install/1` raises.

# `install_dir`

```elixir
@spec install_dir([option()]) :: String.t()
```

Where the pinned driver is (or will be) installed: `<cache_dir>/<version>/<platform>`.

# `installed?`

```elixir
@spec installed?([option()]) :: boolean()
```

Whether the pinned driver is installed in `install_dir/1`.

# `node_version`

```elixir
@spec node_version() :: String.t()
```

The pinned Node.js version the driver runs on (unless `:node` or `:executable` is set).

# `version`

```elixir
@spec version() :: String.t()
```

The pinned Playwright version (`playwright-core` on npm), which the driver runs.

---

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