Guide · Next.js and Vercel
How to test a Next.js app on Vercel preview deployments
On this page
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.
Have a site ready to check? Test my site free. 10 browser runs a month after sign-up, without AI review. Add your URL and review a test plan before starting a run. See a sample report first.
First published · 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.
Copy a preview deployment evidence card
Before a run, copy the unique deployment URL from the provider and confirm its project and source revision. A branch alias can move when a new build finishes. Keep the provider record separate from a revision label you typed into a test plan; the label alone does not prove which build answered.
| Field | What to record |
|---|---|
| Intended target | Project, preview environment, unique deployment URL and provider deployment ID. |
| Source match | Expected commit and the commit shown in the provider record; write unverified if you cannot compare them. |
| Observed destination | Final URL after redirects, check time and the app-specific heading or control you expected to see. |
| Access context | Signed-out or approved synthetic account, and whether a protection challenge blocked the app. Do not copy credentials. |
| Check and result | Reviewed journey and assertion, actual viewport, evidence reference, and passed, failed, blocked or not run. |
| Production follow-up | The separate production URL and smoke check still needed after publication. |
A successful HTTP response or a screenshot of a login page does not establish that the application journey ran. If the browser reaches a protection screen or an unexpected host, record the affected check as blocked and investigate the target or access setup. Do not mark an empty or skipped journey passed.
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 24, 2026)
- Vercel: Accessing deployments through generated URLs (checked October 24, 2026)
- Vercel: Deployment Protection (checked October 24, 2026)
- Vercel: Protection Bypass for Automation (checked October 24, 2026)
- Next.js: Testing (checked October 24, 2026)
- Next.js: How to set up Playwright (checked October 24, 2026)
Related
Try Sybqa on your site
Explore bugs, UI consistency and user journeys from a reviewed plan. Inspect browser evidence and visual review leads in the report. The free plan gives 10 runs a month without AI review after you sign up. See pricing.
Add your site link here and it will be waiting in the console after you create an account. Then describe one journey to check and review the test plan before any run starts.