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

# Run Playwright tests against a Vercel preview deployment

Unit tests and type checks run against the diff. A preview deployment is the first place the change
runs with its real build, environment variables, routing, and hosting platform. This guide runs your
existing Playwright tests against a Vercel preview URL before you merge: once by hand, then on every
successful deployment with GitHub Actions.

## Before you start

- A Vercel project that deploys previews from a GitHub repository.
- A Playwright suite in the repository with at least one reviewed test. For a new suite, follow
  [Add end-to-end tests to a Next.js app](/guides/test-nextjs-app/).
- A preview environment and test accounts that the browser running the tests can access.

## 1. Make your tests base-URL aware

Tests must navigate with relative paths. A test that hard-codes `https://my-app.vercel.app` will
keep testing that environment even when you select a different preview.

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: { baseURL: process.env.BASE_URL ?? 'http://localhost:3000' },
});
```

If your existing config starts a local `webServer`, disable it when `BASE_URL` is set. The
[Next.js guide](/guides/test-nextjs-app/) shows that configuration.

```ts
import { test, expect } from '@playwright/test';

test('home page renders the primary call to action', async ({ page }) => {
  await page.goto('/');
  await expect(page.getByRole('link', { name: 'Get started' })).toBeVisible();
});
```

Keep the preview suite small and safe: a handful of journeys that prove the deployment works, with
no destructive actions, real payments, or emails to real people.

## 2. Run once against a ready preview

1. Open the pull request's Vercel deployment and wait for it to report **Ready**.
2. Confirm its commit matches the change you want to test.
3. Copy that deployment's preview URL, rather than a production URL or an alias that can move to
   another deployment.
4. From the local checkout with dependencies and Playwright browsers installed, replace the example
   URL below and run:

```bash
BASE_URL='https://your-preview.vercel.app' npx playwright test --reporter=html
```

Playwright exits with a nonzero status when tests fail. Open the report to inspect assertions,
screenshots, and traces when captured:

```bash
npx playwright show-report
```

This local run does not update a pull-request check. The next step runs the same suite
automatically.

## 3. Run on every successful deployment

When a GitHub repository is connected to Vercel, Vercel sends a
[`repository_dispatch` event](https://vercel.com/docs/git/vercel-for-github#repository-dispatch-events)
to GitHub as each deployment changes state. The `vercel.deployment.success` event carries the
deployment URL and commit in `github.event.client_payload`, so a workflow can test exactly the
deployment that just became ready. Create `.github/workflows/preview-e2e.yml`:

```yaml
name: Preview E2E
on:
  repository_dispatch:
    types: ['vercel.deployment.success']

jobs:
  e2e:
    # Production deployments send the same event; test previews only.
    if: github.event.client_payload.environment != 'production'
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.client_payload.git.sha }}
      - 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
        env:
          BASE_URL: ${{ github.event.client_payload.url }}
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 14
```

Two GitHub behaviours to know before relying on it:

- `repository_dispatch` only starts workflows that exist on the **default branch**. Merge the
  workflow file first; until then nothing runs.
- The run is attached to the default branch, not to the pull request's commit. It appears under
  **Actions**, but it does not show up as a check on the pull request and cannot be a required
  check there. Treat it as a post-deployment signal, and keep the
  [pull-request workflow](/guides/playwright-tests-github-actions/) as the merge gate.

### Add a QualityMax-managed suite to the same run

To also run reviewed tests managed in QualityMax against the same preview, add the QualityMax
action after the Playwright step. Its `base-url` input replaces the project's default URL for that
run. Store an API token from **Settings → API Tokens** as the repository secret
`QUALITYMAX_CREDENTIAL`, and tag the tests you want to run `smoke`:

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

If the action reports that no tests matched, check the tag and project identifier before treating
the run as coverage.

## QualityMax webhook automation: current limitation

The **Deploy Webhooks → Add Integration → Vercel** setup cannot currently complete the signing-secret
exchange. [Vercel generates its own webhook signing secret](https://vercel.com/docs/webhooks) when you
create a webhook. QualityMax generates a separate secret and currently offers no way to save
Vercel's issued secret in that integration. Deliveries signed with Vercel's secret therefore fail
QualityMax's signature verification. Use the GitHub Actions workflow above until this setup supports
the provider-issued secret.

**Ping** in QualityMax only records a synthetic event on the integration card. It does not contact
Vercel, check a signature, or prove that a deployment can start tests. A working automatic
[Gate Beta](/code-review-gates-beta/) setup needs a real, verified deployment event followed by a
preview test execution; a successful Ping is not evidence of either.

## Protected previews

Vercel Deployment Protection can require sign-in before a preview responds. A test runner that is
not signed in sees the protection page instead of your app, so assertions fail.

For your own Playwright suite, keep protection on and use
[Protection Bypass for Automation](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation).
Generate a bypass secret in the Vercel project settings, store it as a repository secret named
`VERCEL_PROTECTION_BYPASS`, and send it with every request:

```ts
// playwright.config.ts
export default defineConfig({
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    extraHTTPHeaders: process.env.VERCEL_PROTECTION_BYPASS
      ? {
          'x-vercel-protection-bypass': process.env.VERCEL_PROTECTION_BYPASS,
          // Also sets a cookie, so requests the page makes itself are allowed.
          'x-vercel-set-bypass-cookie': 'true',
        }
      : undefined,
  },
});
```

In the workflow, add `VERCEL_PROTECTION_BYPASS: ${{ secrets.VERCEL_PROTECTION_BYPASS }}`
next to `BASE_URL` in the test step's `env`. The secret works on every deployment in the project until
you revoke it, so keep it out of logs and the repository. Playwright sends `extraHTTPHeaders` to every
host the page contacts, including third-party scripts and APIs; if your app loads any, add the header
only to requests for the preview's origin with `page.route()` instead.

The QualityMax action has no input for custom request headers, so a managed run cannot send the
bypass header. Point it only at previews its runner can reach without signing in. Never weaken
protection on deployments that expose real customer data.

## Related

- [Run Playwright tests on every pull request with GitHub Actions](/guides/playwright-tests-github-actions/)
- [Add end-to-end tests to a Next.js app](/guides/test-nextjs-app/)
- [Gate Beta — preview deployment tests](/code-review-gates-beta/)
