How to Run Automated Visual Tests for Netlify Sites with Percy

Run Percy visual tests against the Netlify Deploy Preview for each pull request. Add the Percy project token as the Netlify environment variable PERCY_TOKEN, then use the Percy integration for your existing test framework to capture snapshots from the preview. Percy compares those snapshots with a baseline so a reviewer can assess visual changes before the change reaches production.

The exact install command and snapshot call depend on your framework. There is no framework-neutral Percy command that is safe to copy for every project; use the current official Percy guide for your stack. This guide covers the Netlify setup shared by those workflows and shows how to connect it without exposing the token.

1. Use the Netlify Deploy Preview as the test target

Netlify can automatically build a Deploy Preview for a pull or merge request. The preview URL represents the proposed change and is separate from the production site. Netlify’s documented URL pattern is deploy-preview-<request-number>--<site-name>.netlify.app; for example, a preview for request 42 might be deploy-preview-42--mysitename.netlify.app. Deploy Preview behavior can be changed in the site’s settings, so confirm previews are enabled for your repository. Netlify Deploy Previews documentation.

Use the preview URL as the base URL for the pages your framework visits. Avoid pointing a pull request’s visual test at production: the preview is the candidate build you want to review, and a successful preview check does not itself publish the change.

Check preview access before capturing pages. Netlify says preview URLs may be accessible to anyone who has the link unless password protection or team-login protection is enabled. If the site or its test data is sensitive, configure access controls and make sure the CI runner can still reach the preview. Netlify Deploy Previews documentation.

2. Add the Percy token to Netlify

Create or select the Percy project that should receive snapshots, and obtain its project token.
In the Netlify site dashboard, open Settings > Build & deploy > Environment > Environment variables.
Add an environment variable named PERCY_TOKEN with the token value from that Percy project.
Check that the variable is available in the deploy-preview context used by the visual-test job. Netlify supports context-specific environment variables, so a value set for another context may not be present in preview builds.
Trigger a fresh preview build or test run after changing the variable, following your project’s CI workflow.

Keep the token secret. Anyone who has it can add builds to that Percy project; do not commit it to a public repository or paste it into a test script. BrowserStack’s Percy and Netlify integration guide documents the variable setup and token warning: Integrate Percy with Netlify. Netlify’s deploy-context reference explains context-specific environment variables: Environment variables and deploy contexts.

3. Connect Percy to your test framework

Install and invoke Percy through the integration for the framework already used by your project, such as Playwright, Cypress, Puppeteer, or Selenium. Follow that integration’s current official Percy instructions for the package, snapshot API or CLI wrapper, and CI command. The available Netlify integration guidance establishes where to set PERCY_TOKEN, but it does not establish one universal installation command or code snippet for all frameworks.

Your workflow needs to do three things:

Wait until the Netlify preview is deployed and its URL is available to the job.
Run the project’s browser tests against that preview URL and capture the intended pages with Percy.
Ensure the Percy process receives PERCY_TOKEN from the Netlify environment or your CI secret configuration, rather than from source code.

Use the actual preview URL provided by your CI or repository integration; do not assume a URL from a branch name. If your test command runs as part of a Netlify build, verify it runs after the site is ready to serve. If it runs in an external CI job, configure that job to wait for the Deploy Preview and pass its URL to the tests. Keep the test command and snapshot API aligned with the current official guide for your selected framework.

4. Review snapshot differences

Percy compares captured snapshots with a baseline and presents visual differences for review. A reviewer can inspect whether a difference is an intended design change or a regression, then approve or reject it through the project’s Percy review workflow. The precise commands and interface depend on the integration; the comparison-and-review description is the general workflow, not a universal CLI recipe. See the conceptual overview in the Percy visual testing guide.

Review changed pages at the same viewport and with stable page state. Dynamic content, timestamps, rotating content, or data that varies between runs can create differences unrelated to the pull request. Where supported by your framework’s Percy integration, stabilize that content or configure the capture to exclude the unstable region, using the current framework documentation.

5. Keep the preview and production boundary clear

Netlify distinguishes Deploy Preview, branch deploy, and production contexts, and environment variables can vary by context. Keep the visual check attached to the preview context when the goal is to review a proposed pull-request change. Treat the preview result as review evidence; production deployment remains a separate release action. Netlify Deploy Previews documentation.

Common problems and fixes

Symptom	Likely cause	What to check
Percy reports a missing token or cannot authenticate	`PERCY_TOKEN` is unset, misspelled, unavailable in the active deploy context, or belongs to a different project.	Confirm the variable name and project token in Netlify’s environment-variable settings. Check the deploy-preview context and trigger a new run after changing configuration. Do not print the token in logs.
The test captures the old site or production	The browser test uses a hard-coded URL instead of the current Deploy Preview URL.	Pass the preview URL produced for this pull request into the test job and verify the browser’s navigation target before capture.
The preview URL returns an error or is unavailable	The preview has not finished deploying, previews are disabled or restricted, or the test runner cannot access the preview.	Check the Netlify deploy status and preview settings. If access controls are enabled, confirm the runner can authenticate or reach the preview under the configured policy.
No Percy snapshots appear	The framework’s Percy integration is not invoked, the test exits before the snapshot call, or the test process lacks its token.	Follow the current Percy setup guide for the framework, confirm the snapshot call is reached, and inspect CI logs for the integration’s error without exposing secrets.
Many differences appear between identical commits	Page content or rendering conditions vary, such as dynamic data, viewport, or load timing.	Make test data and viewport consistent, wait for the relevant page state, and use framework-supported controls for unstable regions. Consult the integration guide for its capture options.
A token appears in repository history or logs	A secret was committed or echoed during debugging.	Revoke or rotate the exposed Percy project token, remove it from the active configuration and logs where possible, and store the replacement only as a secret environment variable.

Performance, reliability, and cost considerations

Run time: Browser startup, page readiness, and the number of pages captured affect the duration of the visual-test job. Keep the capture set focused on important routes and wait for a meaningful ready state instead of relying on arbitrary short delays.
Reliability: Use the preview URL for the same pull request, ensure the preview is deployed before browser navigation, and keep viewport and test data stable. Preview access controls can also affect whether an external runner can load pages.
Secret handling: Limit token access to the CI context that needs it, avoid logging it, and keep it out of source control. A Percy token grants the ability to add builds to its project.
Cost: The supplied sources do not establish current Percy pricing or plan limits. Check Percy’s current account and plan details before estimating cost; do not infer a price from the Netlify setup.
Release safety: A passing visual review helps evaluate a preview. It is not a production deployment and should not be treated as one.

Or skip the browser setup

If you need a screenshot of a page without wiring up a browser capture flow, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF. The API can accept a URL and capture options; see the ScreenshotNeo API documentation.

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

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned ${res.status}`);
await Bun.write('shot.webp', new Uint8Array(await res.arrayBuffer()));

These examples capture a URL directly; they do not replace Percy’s baseline comparison and pull-request review workflow. ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.

FAQ

Does Percy automatically test every Netlify preview?

Netlify can create Deploy Previews automatically, but the visual test still needs to be configured in your framework and CI workflow.

Can I use one Percy command for any framework?

No universal command is established by the Netlify integration instructions. Use the current Percy setup guide for the framework in your project.

Does a passing preview visual test deploy to production?

No. The preview is for testing and review before a separate production release.

Should the Percy token be committed so every build can use it?

No. Store it as a secret environment variable and make it available to the intended test context.