PlaywrightPHP

Run Playwright PHP in CI

Install dependencies, install browsers, run PHPUnit, and keep artifacts when tests fail.

A CI job needs PHP dependencies, Node.js, browser binaries, then PHPUnit.

Use the setup action

For GitHub Actions, start with the setup action:

yaml
name: Tests

on: [push, pull_request]

jobs:
  tests:
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - uses: actions/checkout@v4

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

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

      - run: composer install --no-interaction --prefer-dist

      - run: vendor/bin/phpunit --colors=always

Expected result: the workflow installs PHP, the Playwright npm runtime, Chromium, Composer dependencies, and then runs your PHPUnit suite headless.

Run PHPUnit

If you grouped browser tests:

yaml
      - run: vendor/bin/phpunit --group browser --colors=always

For a full suite:

yaml
      - run: vendor/bin/phpunit --colors=always

Keep failure artifacts

Upload screenshots, traces, or logs only when the job fails:

yaml
      - name: Upload browser artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: browser-artifacts
          path: |
            test-failures/
            var/artifacts/
          retention-days: 7

If it fails

  • Browser install fails: check Node.js 20 and rerun with system dependencies if you are not using the setup action.
  • Tests pass locally but fail in CI: compare PHP version, timezone, viewport, and environment variables.
  • The failure only says timeout: capture a trace or screenshot before increasing timeouts.

Next

Start is complete. Continue with Continuous integration to choose a stable browser matrix and artifact policy.

If the setup action does not fit your runner, use the manual CLI commands. For action-specific inputs and limits, see the setup-playwright package.