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
Section titled “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.
- A preview environment and test accounts that the browser running the tests can access.
1. Make your tests base-URL aware
Section titled “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.
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.
2. Run once against a ready preview
Section titled “2. Run once against a ready preview”- Open the pull request’s Vercel deployment and wait for it to report Ready.
- Confirm its commit matches the change you want to test.
- Copy that deployment’s preview URL, rather than a production URL or an alias that can move to another deployment.
- From the local checkout with dependencies and Playwright browsers installed, replace the example URL below and run:
BASE_URL='https://your-preview.vercel.app' npx playwright test --reporter=htmlPlaywright exits with a nonzero status when tests fail. Open the report to inspect assertions, screenshots, and traces when captured:
npx playwright show-reportThis local run does not update a pull-request check. The next step runs the same suite automatically.
3. Run on every successful deployment
Section titled “3. Run on every successful deployment”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 E2Eon: 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: 14Two GitHub behaviours to know before relying on it:
repository_dispatchonly 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.
Protected previews
Section titled “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.
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:
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.