PlaywrightPHP

Command line

Install browsers, run PHP browser tests, inspect traces, and prepare CI from the shell.

Playwright PHP uses PHP tools for PHP test execution and small vendor binaries for browser setup. It is close to Playwright's command-line workflow, but it is not the Node test runner: there is no npx playwright test equivalent for PHP projects.

Install the package

bash
composer require --dev playwright-php/playwright

The package provides the PHP API and the helper binaries used by the examples in this documentation.

Install browsers

Install only the browser targets the project runs. For the common Chromium path:

bash
vendor/bin/playwright-install chromium

Pass several names when one job needs several browsers:

bash
vendor/bin/playwright-install chromium webkit

Use --browsers to install Playwright's complete managed set: Chromium, Firefox, and WebKit.

bash
vendor/bin/playwright-install --browsers

On Linux CI images, install the system dependencies for the selected targets too:

bash
vendor/bin/playwright-install --with-deps chromium

Preview what would be installed without downloading:

bash
vendor/bin/playwright-install --dry-run --with-deps chromium

Supported targets are chromium, firefox, webkit, chrome, chrome-beta, msedge, and msedge-beta. The --browsers shortcut cannot be combined with target names. See Browsers and contexts before installing Chrome or Edge.

Run a PHP script

Playwright PHP scripts are ordinary PHP files:

bash
php content/examples/visit.php

Use this for small browser automation scripts, local smoke checks, and examples that are not part of a PHPUnit suite.

Run PHPUnit browser tests

Browser tests are slow, so keep them in a PHPUnit group and leave them out of the default run:

bash
# unit tests only, no browser launched
vendor/bin/phpunit --exclude-group integration

# everything, browsers included
vendor/bin/phpunit

Environment variables

The core library does not read PW_* variables automatically. A project can opt in by building its client with PlaywrightConfigBuilder::fromEnv():

php
use Playwright\Configuration\PlaywrightConfigBuilder;
use Playwright\PlaywrightFactory;

$config = PlaywrightConfigBuilder::fromEnv()->build();
$playwright = PlaywrightFactory::create($config);
$browser = $playwright->chromium()->launch();

The selected browser builder receives settings such as:

Variable Effect
PW_HEADLESS=false Shows the browser instead of hiding it
PW_SLOWMO_MS=250 Slows every action down, to watch what happens
PW_TIMEOUT_MS=10000 Changes the default timeout
PW_TRACE=1 Records a trace
PW_TRACE_DIR=var/traces Where traces are written
PW_VIDEOS_DIR=var/videos Where videos are written
PW_PROXY_SERVER=... Routes the browser through a proxy

With that setup, a headed run is:

bash
PW_HEADLESS=false php tests/browser-smoke.php

For PHPUnit, pass the same built config as the customConfig argument to the provided test trait. PW_TRACE is the exception: the trait reads it directly when deciding whether to record failure traces.

Two more are read at install time rather than at run time:

Variable Effect
PLAYWRIGHT_BROWSERS_PATH Where the browser binaries live
PLAYWRIGHT_NODE_PATH Which Node binary drives the server

Integration packages may expose their own environment variables. Do not assume an integration-specific setting changes the core library; check which process reads it.

Open a trace

The trace format is Playwright's own, so its viewer reads it. The viewer ships with the Node package:

bash
npx playwright show-trace trace.zip

The PHP package ships one binary, playwright-install, and no viewer.

CI checklist

  • Install Composer dependencies.
  • Run vendor/bin/playwright-install --with-deps chromium, or select the browser used by that CI job.
  • Run vendor/bin/phpunit.
  • Store screenshots and traces as CI artifacts.
  • Keep browser cache paths stable when the CI platform supports dependency caching.

Difference from the upstream CLI

The upstream Playwright CLI documents commands such as test execution, browser installation, code generation, trace viewing, and report handling for Node projects. In a PHP project, keep those roles separate: run tests with PHPUnit, install browsers with the PHP package helper, and use the upstream CLI only for tools that inspect existing artifacts, such as the trace viewer.

Go next