Playwright.Driver (Playwright v1.65.0-rc.3)

Copy Markdown View Source

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.

Summary

Types

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.

Functions

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

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.

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

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).

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.

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

Whether the pinned driver is installed in install_dir/1.

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

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

Types

option()

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

Functions

cache_dir(opts \\ [])

@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(opts \\ [])

@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(opts \\ [])

@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(opts \\ [])

@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(args \\ [], opts \\ [])

@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(opts \\ [])

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

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

installed?(opts \\ [])

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

Whether the pinned driver is installed in install_dir/1.

node_version()

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

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

version()

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

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