How to Set Up Playwright with GitHub Actions: Step-by-Step

What you'll need

This guide assumes you have a Playwright project set up. If you don't, run npm init playwright@latest in your project and follow the prompts. You'll also need a GitHub repository with Actions enabled.

Step 1: Install Playwright as a dev dependency

If Playwright isn't already a dev dependency in your package.json, add it:

npm install --save-dev @playwright/test

Step 2: Create the GitHub Actions workflow file

Create .github/workflows/playwright.yml in your repository:

name: Playwright Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        run: npx playwright test

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Step 3: Configure parallel execution

Playwright supports running tests in parallel. In your playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  workers: process.env.CI ? 2 : undefined,
  retries: process.env.CI ? 2 : 0,
  reporter: [['html'], ['github']],
  use: {
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

Step 4: Run only on affected browsers in CI

Running all three browsers (Chromium, Firefox, WebKit) on every PR can be slow. For PRs, run only Chromium and save the full suite for main branch pushes:

- name: Run Playwright tests
  run: npx playwright test --project=chromium
  if: github.event_name == 'pull_request'

- name: Run all browsers on main
  run: npx playwright test
  if: github.ref == 'refs/heads/main'

Step 5: View test results

After the workflow runs, go to your GitHub Actions run → Artifacts → download playwright-report. Open index.html to see the full HTML report with screenshots, traces, and step-by-step logs for every failed test.

Tips for faster CI runs

• Cache the Playwright browser binaries with actions/cache, this saves 30–60 seconds per run
• Use --shard flag for very large suites: split tests across multiple jobs
• Set retries: 2 in CI to reduce flaky-test noise without hiding real failures

Need help setting up your Playwright CI pipeline? Get in touch with RedQA. We have implemented this across enterprise environments including BBC and Bupa.