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.
1. Add Playwright to the repository
Section titled “1. Add Playwright to the repository”If the repository has no Playwright tests yet, initialize them from the repository root:
npm init playwright@latestAccept 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:
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.
2. Add the workflow
Section titled “2. Add the workflow”Create .github/workflows/playwright.yml:
name: Playwrighton: 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: 14If 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.
3. Make it a required check
Section titled “3. Make it a required check”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.
4. Add QualityMax to the same gate
Section titled “4. Add QualityMax to the same gate”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 secretQUALITYMAX_CREDENTIAL, and add:- uses: Quality-Max/qualitymax-github-action@v1with:api-key: ${{ secrets.QUALITYMAX_CREDENTIAL }}project-id: 'your-project-id'test-suite: smokeNever 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.