How to Run Playwright on Vercel

For most teams, “run Playwright on Vercel” means run end-to-end tests in CI against a Vercel deployment after it succeeds. Pass the deployment’s own URL to Playwright so tests cover the revision that was just deployed. The test runner usually runs in your CI provider, not inside a Vercel Function. If your application needs to automate a browser at runtime, that is a different setup; Vercel documents a hosted-browser integration for that case.

This guide uses GitHub Actions and GitHub deployment status as one complete example. Vercel’s guidance also describes triggering GitHub Actions with a repository dispatch event or using a webhook with another CI provider. The essential steps are the same: wait for deployment success, check out the deployed revision, install matching browsers, set the base URL from the event, and run the tests. Vercel’s deployment testing guide and Playwright’s CI guide describe this pattern.

1. Add Playwright to the project

Install Playwright Test and create its starter configuration and example tests:

npm init playwright@latest

Commit the generated configuration, tests, and package lockfile. Choose the browsers your test suite needs. Playwright’s browser binaries are version-specific, so install browsers in CI using the Playwright version pinned by the lockfile.

A minimal configuration can take the target URL from an environment variable. It can also attach Vercel’s automation bypass header if the deployment is protected:

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

const baseURL = process.env.PLAYWRIGHT_TEST_BASE_URL;
if (!baseURL) {
  throw new Error('Set PLAYWRIGHT_TEST_BASE_URL to the deployed Vercel URL');
}

const bypass = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;

export default defineConfig({
  testDir: './tests',
  use: {
    baseURL,
    extraHTTPHeaders: bypass
      ? { 'x-vercel-protection-bypass': bypass }
      : {},
  },
});

The bypass header is only needed when Deployment Protection blocks the test runner. Keep the secret in your CI provider’s secret store. Do not put it in the repository, print it in logs, or pass it to tests that do not need it. Vercel documents an optional x-vercel-set-bypass-cookie header with values such as true or samesitenone for cases where subsequent browser requests need a bypass cookie. See Vercel’s Protection Bypass for Automation documentation.

2. Run tests after a successful GitHub deployment

The workflow below listens for a successful GitHub deployment status, uses the deployment’s target URL and commit SHA, installs dependencies and compatible browser binaries, then runs Playwright. Add VERCEL_AUTOMATION_BYPASS_SECRET to the repository’s Actions secrets only if the target deployment is protected.

# .github/workflows/playwright-after-vercel.yml
name: Playwright after Vercel deployment

on:
  deployment_status:

jobs:
  e2e:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Check out the deployed commit
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.deployment.sha }}

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install project dependencies
        run: npm ci

      - name: Install Playwright browsers and system dependencies
        run: npx playwright install --with-deps

      - name: Run end-to-end tests against this deployment
        run: npx playwright test
        env:
          PLAYWRIGHT_TEST_BASE_URL: ${{ github.event.deployment_status.target_url }}
          VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}

This uses GitHub’s deployment status event payload. Confirm that your deployment integration emits a successful deployment status with a valid target_url and the deployed commit SHA. If your Vercel integration instead sends a repository dispatch event, use that event’s payload fields consistently: do not mix its URL or SHA paths with the deployment-status paths above.

Preview versus Production

Vercel’s default environments are Local, Preview, and Production. Preview deployments are a natural target for pull request validation because they let a change be tested before it affects production. Each deployment has its own URL, so take the URL from the event associated with the deployment being checked instead of hard-coding a Preview URL that can change. Production smoke tests can use the same approach, but should be an intentional separate workflow. Vercel documents its deployment environments and Preview deployments.

3. Handle Deployment Protection

A protected Preview URL can return an authentication or protection page to CI instead of the application. Configure Vercel Protection Bypass for Automation, store its secret as a CI secret, and send it as x-vercel-protection-bypass in Playwright’s extraHTTPHeaders, as shown in the configuration above.

Vercel describes this feature as a way to run automated tests, CI/CD pipelines, and monitoring tools against protected deployments without triggering authentication challenges or security blocks. The bypass applies to documented Deployment Protection checks such as Password Protection, Vercel Authentication, and Trusted IPs, and some system mitigations and bot challenges. It does not override active DDoS mitigations, attack-related rate limits, or every security challenge. Treat a remaining block as a signal to check the deployment’s current protection state rather than assuming the header grants unconditional access.

4. Write tests that use the configured base URL

Use relative paths with baseURL, so the same tests can run locally against a local server or in CI against the deployment URL:

// tests/home.spec.ts
import { test, expect } from '@playwright/test';

test('home page loads', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveTitle(/.+/);
});

Run the test suite locally with a URL, for example:

PLAYWRIGHT_TEST_BASE_URL=https://your-preview-url.vercel.app npx playwright test

For local development when you do not need a deployed target, Playwright’s webServer configuration can start your app before the tests. For post-deployment validation, point the tests at the event-provided deployment URL instead. Playwright’s web server configuration covers the local-server option.

5. Browser setup, reports, and repeatability

npx playwright test runs the configured test projects headlessly by default, which suits a CI runner without a desktop. Install browser binaries and their operating-system dependencies in the job with npx playwright install --with-deps. If you update Playwright, update the lockfile and browser installation together; a mismatch can make browser launch fail.

For a useful CI failure report, configure Playwright’s built-in reporters in playwright.config.ts, for example reporter: [['list'], ['html', { open: 'never' }]]. Upload playwright-report/ and, if configured, test-results/ as workflow artifacts using your CI provider’s artifact action. This lets a failed run retain its report and any configured traces or screenshots for diagnosis. Avoid putting secrets or sensitive page data in artifacts accessible to a broad audience.

Keep the workflow tied to the deployment commit and URL from the same event. That makes a failure reproducible against the code that actually shipped. Use test retries only as a diagnostic or resilience choice; retries can reveal intermittent failures but should not hide a consistently broken deployment.

Runtime browser automation inside a Vercel application

If your deployed application itself needs to control a browser, that is not the post-deployment CI pattern above. Vercel’s Browserless integration describes hosted headless browser access through Vercel Connect: install @vercel/connect, create a Browserless connector, and request credentials at runtime. This is an architecture for application runtime automation; it is not required just to test a Vercel deployment with Playwright. See Vercel’s Browserless integration details.

For ongoing Playwright monitoring, Vercel’s integration directory also lists Checkly. It is an adjacent monitoring option rather than a required component of the basic CI workflow. See the Checkly integration listing.

Or skip the browser setup

If the task is to capture a page image or PDF rather than interactively test your application, ScreenshotNeo is a website screenshot API and MCP server for developers. It captures PNG, JPEG, WebP, or PDF with one GET request. For example, this cURL call saves a WebP screenshot:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

For options such as full-page capture, element selection, custom CSS and JavaScript, and PDF settings, see the ScreenshotNeo API documentation. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

Troubleshooting

Symptom	Likely cause	Fix
Tests start before the site responds	The workflow is triggered by an event that fires before deployment completes, or it uses a stale URL.	Trigger on successful deployment status and pass that event’s target URL to Playwright.
Tests run against the wrong revision	The workflow checks out the branch head instead of the commit that produced the deployment.	Check out the deployment SHA from the same event that supplies the URL.
Playwright cannot launch a browser in CI	The matching browser binary or system dependencies are missing, or Playwright and installed browsers are out of sync.	Run `npm ci`, then `npx playwright install --with-deps` with the locked Playwright version.
The page is Vercel’s protection or login screen	The deployment is protected and CI did not send a valid automation bypass.	Configure Protection Bypass for Automation and set the secret in CI; use the documented header in Playwright.
First navigation passes, later requests are blocked	Follow-up browser requests may need the bypass cookie behavior.	Review Vercel’s optional `x-vercel-set-bypass-cookie` header and the documented cookie values for the browser context.
The bypass header is present but access is still denied	An active mitigation, attack-related rate limit, or other security challenge may not be bypassable.	Check Vercel’s protection and mitigation state; the automation bypass is not unconditional.
`PLAYWRIGHT_TEST_BASE_URL` is empty or malformed	The chosen event did not provide a target URL, or the workflow uses the wrong payload path.	Inspect the event payload and verify the successful deployment has a target URL before running tests.
Tests work locally but fail only against Preview	The deployed app may depend on environment variables, authentication, or services that differ from local development.	Check the Preview environment configuration and make test setup explicit; do not silently fall back to a production URL.

Performance, reliability, and cost

This workflow adds a CI job after deployment, and its duration depends on dependency installation, browser installation, test count, and the pages under test; the cited guidance does not establish a general runtime benchmark. Use the CI provider’s dependency caching where appropriate, and keep the test suite focused on important user flows. Browser installation can be cached only with care: the cache must match the Playwright version and operating-system environment.

Reliability depends on testing the exact deployment, keeping browser binaries compatible, and handling protection correctly. A successful test run shows that the tested flows passed at that time; it does not establish permanent availability. If a deployment status event is not emitted by your integration, use the webhook or repository-dispatch pattern supported by your setup and pass that event’s URL and revision together.

The Playwright workflow uses CI minutes and any applicable Vercel deployment resources. The official guidance cited here does not state a universal cost per run, so check the current terms for your CI provider and Vercel plan. Runtime hosted-browser automation is a separate service architecture and may have its own provider pricing.

FAQ

Does Playwright run inside a Vercel Function in this workflow?

No. The usual end-to-end setup runs Playwright in CI and points the browser at the deployed Vercel URL.

Can I test a Preview deployment before merging?

Yes. Use the Preview deployment’s event-provided URL after it succeeds, then run the tests against that deployment.

Do I need Browserless to run deployment tests?

No. Browserless is relevant when an application needs hosted browser automation at runtime. It is not required for the CI test workflow.

Will Protection Bypass defeat every Vercel security block?

No. Vercel documents limits, including active DDoS mitigations and attack-related rate limits.