Setup Playwright (for PHP)

Install the Playwright npm package and browser binaries for a Playwright PHP GitHub Actions workflow.

This action does not install PHP, Composer dependencies, or Playwright PHP. Configure those separately in your workflow.

Quick start

# .github/workflows/test.yml
name: PHP Tests

on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'

      - uses: playwright-php/setup-playwright@v1
        with:
          playwright-version: '1.58.2'
          browsers: chromium

      - run: composer install
      - run: vendor/bin/phpunit

Pin playwright-version to the version expected by Playwright PHP so CI does not change when Playwright publishes a new release.

Examples

Install multiple browsers

- uses: playwright-php/setup-playwright@v1
  with:
    browsers: '["chromium","firefox"]'

Use chromium for Playwright's bundled open-source browser. Use chrome when the workflow specifically needs the Google Chrome channel.

Reuse cached browser downloads

- name: Choose Playwright version
  run: echo "PLAYWRIGHT_VERSION=1.58.2" >> "$GITHUB_ENV"

- uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: playwright-${{ runner.os }}-${{ env.PLAYWRIGHT_VERSION }}-chromium

- uses: playwright-php/setup-playwright@v1
  with:
    playwright-version: ${{ env.PLAYWRIGHT_VERSION }}
    browsers: chromium
    browsers-path: ~/.cache/ms-playwright

Include the runner OS, Playwright version, and browser selection in the cache key. Browser binaries are tied to their Playwright release.

Use the action outputs

- id: playwright
  uses: playwright-php/setup-playwright@v1
  with:
    playwright-version: '1.58.2'
    browsers: '["chromium","firefox"]'

- name: Show installed runtime
  run: |
    echo "Playwright ${{ steps.playwright.outputs.playwright-version }}"
    echo '${{ steps.playwright.outputs.installed-browsers }}'

Control operating-system dependencies

- uses: playwright-php/setup-playwright@v1
  with:
    browsers: webkit
    with-deps: false

with-deps: auto installs browser system dependencies on Linux and skips that step on macOS and Windows. Use true or false to override this behavior.

Outputs

The action exposes two outputs:

• playwright-version: the installed Playwright CLI version
• installed-browsers: a JSON list of the browsers that were installed

Configuration

Option	Default	Allowed values	Notes
browsers	chrome	chrome, chromium, firefox, webkit, msedge, all	msedge only on Windows runners
playwright-version	latest	Any valid npm specifier (for the playwright package)	Pin an exact version for reproducible CI. Use latest only when intentionally testing new upstream releases.
with-deps	auto	true, false, auto	auto appends Playwright's --with-deps flag on Linux runners.
browsers-path		Directory path	Exports PLAYWRIGHT_BROWSERS_PATH so downloads land in your cache. Leave blank for Playwright defaults (~/.cache/ms-playwright, %LOCALAPPDATA%\ms-playwright, etc.)

Action version

Reference playwright-php/setup-playwright@v1 to receive backward-compatible fixes within the current major version. Pin a complete tag such as @v1.0.0 when the workflow must use an immutable action revision.

The action version and the playwright-version input are independent: the first selects the action code, the second selects the npm package and browser binaries the action installs.

Testing the action

1. Trigger .github/workflows/test.yml via workflow_dispatch to exercise the action on hosted runners.
2. Run the same workflow with act to catch issues locally before pushing.
3. In a scratch repo, reference the action with uses: ./ so every commit is validated before tagging a Marketplace release.

License

This package is released by the Playwright PHP project under the MIT License. See the LICENSE file for details.