Skip to content

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.

  • 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.
  • A preview environment and test accounts that the browser running the tests can access.

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.

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 shows that configuration.

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.

  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:
Terminal window
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:

Terminal window
npx playwright show-report

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

When a GitHub repository is connected to Vercel, Vercel sends a repository_dispatch event 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:

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 as the merge gate.

Add a QualityMax-managed suite to the same run

Section titled “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:

- 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

Section titled “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 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 setup needs a real, verified deployment event followed by a preview test execution; a successful Ping is not evidence of either.

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. 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:

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.