> Full documentation index: [llms.txt](https://docs.qualitymax.io/llms.txt)

# 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

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

```bash
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:

```ts
// 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.

## 2. Add the workflow

Create `.github/workflows/playwright.yml`:

```yaml
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](/guides/test-nextjs-app/) has a complete example.

## 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

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](/quickstart-web-app/) or ask your coding
  agent through the [MCP quickstart](/quickstart-mcp/).
- **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:

  ```yaml
  - 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](/self-healing/).

For a pull-request pipeline that also reviews the diff and tests the preview deployment, see
[Code Review & Gates](/code-review-gates/) and
[Run Playwright tests against a Vercel preview deployment](/guides/test-vercel-preview-deployments/).

## Moving from another tool

- [Cypress to Playwright](/migrate-cypress-to-playwright/)
- [Selenium to Playwright](/migrate-selenium-to-playwright/)
