Running Playwright Tests in GitHub Actions

Run Playwright e2e tests in CI with browsers installed and traces saved on failure.

Playwright needs its browser binaries and OS dependencies installed before tests run. The npx playwright install --with-deps step handles that. Sharding splits the suite across runners, and uploading the HTML report plus traces makes failures debuggable.

What you need

• Playwright installed (@playwright/test) with a playwright.config.
• The npx playwright install --with-deps step for browsers.
• actions/upload-artifact to keep the report and traces.

The workflow

Install browsers, run tests, and upload the report on failure.

- uses: actions/setup-node@v4
  with:
    node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
- uses: actions/upload-artifact@v4
  if: ${{ !cancelled() }}
  with:
    name: playwright-report
    path: playwright-report/

Sharding

Split the suite across runners with the --shard flag and a matrix.

strategy:
  matrix:
    shard: [1, 2, 3]
steps:
  - run: npx playwright test --shard=${{ matrix.shard }}/3

Common gotchas

• Skipping --with-deps causes "missing library" browser launch failures.
• Enable trace: on-first-retry so failures upload a viewable trace.
• E2E suites are slow and minute-hungry; sharding on fast managed runners (Latchkey) keeps wall-clock and cost down.

Key takeaways

• Install browsers with npx playwright install --with-deps.
• Shard the suite across a matrix to cut wall-clock time.
• Upload the HTML report and traces for debugging failures.

Related guides