Skip to content

Run Playwright tests on every pull request with GitHub Actions

This guide gets end-to-end tests running on every pull request in GitHub Actions, makes the result block merges, and then shows where QualityMax fits: generating the tests, keeping them healthy, and running a managed suite as a second check.

If the repository has no Playwright tests yet, initialize them from the repository root:

Terminal window
npm init playwright@latest

Accept TypeScript and a tests folder. Use retries only in CI, and keep a trace when a retry happens so a failure is debuggable from the artifact alone:

playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
retries: process.env.CI ? 2 : 0,
reporter: process.env.CI ? [['html', { open: 'never' }], ['github']] : 'list',
use: {
baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
trace: 'on-first-retry',
},
projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
});

Retries make a run tolerant of transient failures; they do not fix a flaky test. Treat a test that only passes on retry as a defect to investigate.

Create .github/workflows/playwright.yml:

name: Playwright
on:
pull_request:
push:
branches: [main]
jobs:
e2e:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx playwright test
- uses: actions/upload-artifact@v4
if: ${{ !cancelled() }}
with:
name: playwright-report
path: playwright-report/
retention-days: 14

If the tests need the app running, start it with Playwright’s webServer option rather than a background shell step, so Playwright waits for it to be ready and stops it afterwards. The Next.js guide has a complete example.

A workflow that fails but does not block is a notification, not a gate. In GitHub, open the repository’s branch protection rule or ruleset for main, enable required status checks, and add the e2e job. Open a pull request with a deliberately failing assertion once to confirm the merge button is blocked, then revert it.

The workflow above runs tests that already exist. QualityMax adds the parts around them:

  • Generate tests from a crawl of your app or from written intent, then review them before they count as coverage. Start with the web app quickstart or ask your coding agent through the MCP quickstart.

  • Bring passing tests into the repository as a pull request with Insert Tests on the repository card, so they run in the workflow you just added.

  • Run a managed suite as its own check. Tag reviewed tests smoke, create an API token under Settings → API Tokens, save it as the repository secret QUALITYMAX_CREDENTIAL, and add:

    - uses: Quality-Max/qualitymax-github-action@v1
    with:
    api-key: ${{ secrets.QUALITYMAX_CREDENTIAL }}
    project-id: 'your-project-id'
    test-suite: smoke

    Never write the token into the workflow file itself. If the action reports that no tests matched, check the tag and project identifier before treating the gate as complete.

  • Repair broken locators when the UI changes, with the original intent and assertions kept. See self-healing.

For a pull-request pipeline that also reviews the diff and tests the preview deployment, see Code Review & Gates and Run Playwright tests against a Vercel preview deployment.