PlaywrightPHP

GitHub Actions Setup

One workflow step that installs the Playwright runtime and browser binaries on CI runners.

The playwright-php/setup-playwright action installs the Playwright npm runtime, selected browser binaries, and Linux browser dependencies. PHP, Composer dependencies, application setup, caching, and the test command remain explicit steps.

Minimal workflow

yaml
# .github/workflows/test.yml
name: PHP Tests
on: [push]
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.62.1'
          browsers: chromium

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

Options

Set browsers explicitly on every action use. Version 1 still falls back to Google Chrome when the input is omitted, but that compatibility behavior is deprecated and will be rejected in version 2.

Several browsers at once:

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

Install Playwright's complete managed set:

yaml
- uses: playwright-php/setup-playwright@v1
  with:
    browsers: all

Managed targets are chromium, firefox, and webkit. Branded targets are chrome, chrome-beta, msedge, and msedge-beta. Chrome and Edge install globally and should be selected only when the job specifically tests that distribution.

Reuse cached downloads:

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

- uses: playwright-php/setup-playwright@v1
  with:
    playwright-version: '1.62.1'
    browsers: chromium
    browsers-path: ~/.cache/ms-playwright

Pin the Playwright version, skip the OS packages:

yaml
- uses: playwright-php/setup-playwright@v1
  with:
    playwright-version: '1.62.1'
    browsers: webkit
    with-deps: false

Manual alternative

Without the action, install Node, run composer install, then use vendor/bin/playwright-install --with-deps chromium or select the target required by the job. Caching remains a separate actions/cache step in both approaches. The Continuous integration guide shows the full manual workflow; the Install & CI cheatsheet has both on one sheet.

Recommended path

Use the action for the browser/runtime setup, then keep application setup visible in separate workflow steps. A readable job usually looks like this:

  1. checkout;
  2. prepare Playwright PHP runtime;
  3. install Composer dependencies;
  4. prepare the application;
  5. start or expose the app;
  6. run the browser tests;
  7. upload artifacts on failure.

This makes CI failures easier to classify. If the action fails, the runner is not ready. If the app setup fails, the browser is not the problem. If tests fail, artifacts should explain the product failure.

Operational notes

Cache browser binaries when runs are frequent. Keep cache keys simple and invalidate them when dependency versions change.

Do not run headed browsers in CI unless the runner is explicitly prepared for it. Headless plus trace artifacts is the normal path.

Adoption checklist

Before standardizing on the action, confirm:

  • the project runs on GitHub Actions;
  • the browser suite has a clear PHPUnit group or command;
  • Composer install remains visible;
  • application startup is a separate step;
  • artifacts are uploaded on failure;
  • the cache path is restored before browser installation.

The action should make the workflow shorter, not opaque. A maintainer reading the YAML should still see where dependencies install, where the app starts, where tests run, and where failure evidence is kept.

What this integration is not

It is not a cross-CI abstraction. It is also not an application bootstrapper. Keep database setup, Symfony cache warmup, server startup, migrations, and test data in project-owned workflow steps.

Troubleshooting

  • Browser install fails: check runner image, OS dependencies, disk space, and proxy variables.
  • Tests cannot reach the app: verify the server step and whether the browser process can resolve the host.
  • Browser downloads every run: restore the cache before the install step.
  • Failure has no evidence: add trace/screenshot upload, not more setup logging.

FAQ

Does this action replace composer install?

No. It prepares the Playwright runtime and browsers. Your project still owns PHP dependencies.

Should every workflow use the action?

Only GitHub Actions workflows. Other CI systems should use the manual setup pattern from the Guide.

See also