Guide · Next.js and Vercel
How to test a Next.js app on Vercel preview deployments
A Vercel preview deployment is a live copy of your branch, which makes it the right place to test before merging. It also comes with behaviour that catches teams out: generated URLs, protection that blocks test runners, and environment variables that differ from production. This guide sticks to what the Next.js and Vercel documentation say, and says where Sybqa, which we make, does and does not fit.
Facts checked
What a preview deployment is
Vercel’s documentation says it creates a preview deployment when you push a commit to a branch that is not your production branch, open a pull request on GitHub, GitLab or Bitbucket, or deploy from the CLI without the --prod flag. The first deployment of a new project is always a production deployment, so the preview rules apply only after that exists.
Each deployment gets a generated URL. There are two kinds: a branch-specific URL that always points at the latest changes on that branch, and a commit-specific URL that points at the exact deployment of one commit. Use the commit URL when you need a result you can tie to a revision.
Every environment can define its own environment variables, such as database connection details or API keys. A preview can therefore behave differently from production for reasons that have nothing to do with your code, so a clean preview run is not proof that production will behave the same.
Why your test runner may see a login page
Generated URLs are publicly accessible by default, but Vercel’s Deployment Protection can restrict them. Its Standard Protection scope protects all deployments except production domains and is available on all plans, and the methods include Vercel Authentication, Password Protection and, on Enterprise plans, Passport and Trusted IPs. A test runner that is not a signed-in team member receives the protection challenge, not your app.
For automation, Vercel documents Protection Bypass for Automation, available on all plans. You send the project’s secret in a header named x-vercel-protection-bypass; Vercel exposes it to your deployment as the VERCEL_AUTOMATION_BYPASS_SECRET system environment variable. Adding x-vercel-set-bypass-cookie: true sets a cookie so follow-up in-browser requests are covered. The documentation notes the bypass does not override active DDoS mitigations, rate limits during attacks or attack-time challenges.
What the Next.js docs recommend
The Next.js testing guide lists unit, component, integration, end-to-end and snapshot testing, with Cypress, Jest, Playwright and Vitest set-up guides. It notes that some tools do not yet fully support async Server Components and recommends end-to-end testing over unit testing for them.
For Playwright, the Next.js guide recommends running tests against your production code to more closely resemble how the application will behave: run npm run build and npm run start, then run npx playwright test. Running the same suite against a preview URL follows the same idea, with the deployed build as the target.
Which check answers which question
| Check | Answers | Does not establish |
|---|---|---|
| Unit and component tests (Jest, Vitest) | That a function or component behaves as written, quickly and in isolation | That an async Server Component, routing or the deployed build works end to end |
| Playwright end-to-end suite against the preview | That the journeys you scripted pass on the deployed build, using the bypass header if the preview is protected | Anything you did not script, or how the page looks at widths you did not set |
| Sybqa run against a reachable preview | What a real browser finds on the page at desktop, phone and narrow widths, with evidence | Database rules, server logic, a deployed revision match, or behaviour behind a protection challenge it cannot pass |
| Production smoke check after promotion | That production configuration and variables work | Anything about the preview |
Where Sybqa fits, and where it does not
Sybqa opens a URL in a real browser, so it fits a preview that a browser can reach: an unprotected preview URL, or a staging domain you have chosen to leave open. The GitHub Actions guide shows a saved plan started from a deployment event. For how to keep the reachability, login and assertion layers separate, see authenticated preview deployment testing.
- It is not a substitute for the Next.js test tools: it does not run unit or component tests or look inside Server Components.
- Our public guides do not describe sending a Vercel bypass secret from the hosted service. Do not assume a protected preview can be tested; run your own Playwright suite with the header, or test a domain you have deliberately left open.
- It cannot show that preview environment variables match production, or that a database or API accepts the right requests.
A checklist before you merge
- Open the commit-specific preview URL for the revision you are about to merge, not only the branch URL.
- Confirm the preview is actually serving the app: if you see a Vercel login or password page, protection is active and the test saw the challenge, not your site.
- Run your Playwright journeys against the preview, with the bypass header held in a secret.
- Run a browser-level check at phone width for layout, console errors and accessibility rules.
- List the preview environment variables that differ from production and decide which of them change behaviour.
- After promotion, run a short smoke check on the production domain.
Common questions
Are Vercel preview deployments public?
Generated URLs are publicly accessible by default, according to Vercel’s documentation, and can be restricted with Deployment Protection. Standard Protection, available on all plans, covers everything except production domains.
How do I run Playwright against a protected Vercel preview?
Vercel documents sending the project’s bypass secret in an x-vercel-protection-bypass header, for example through Playwright’s extraHTTPHeaders setting, with the secret read from VERCEL_AUTOMATION_BYPASS_SECRET or your CI secrets.
Should end-to-end tests run against the dev server?
The Next.js documentation recommends running Playwright against your production build, using npm run build and npm run start, because it more closely resembles how the application behaves.
Sources
- Vercel: Environments (checked October 10, 2026)
- Vercel: Accessing deployments through generated URLs (checked October 10, 2026)
- Vercel: Deployment Protection (checked October 10, 2026)
- Vercel: Protection Bypass for Automation (checked October 10, 2026)
- Next.js: Testing (checked October 10, 2026)
- Next.js: How to set up Playwright (checked October 10, 2026)
Related
Try Sybqa on your site
Paste a link, review the plan, and read the evidence report. The free plan gives 10 runs a month without AI review after you sign up. See pricing.