How to Approve Visual Changes in Percy Builds

To approve visual changes in a Percy build, open the build, inspect each snapshot’s diff, and approve only snapshots whose new appearance is intentional. Approval accepts that snapshot’s current appearance as the baseline for future comparisons. Investigate and fix unexpected differences instead of approving them to clear a check. Percy documents approval at the snapshot level, so you can accept selected snapshots without approving the whole build.

1. Generate a Percy build

Run your project’s configured Percy visual test integration. The exact command depends on the framework and project setup; Percy’s Cypress example is:

npx percy exec -- cypress run

This is an example, not a universal command. Use the command and configuration already set up for your test runner. When the run completes, open the resulting build in Percy.

2. Review the build and its snapshot diffs

Percy compares captured snapshots with their existing baselines. In the build, inspect the visual comparisons and highlighted changes. For each changed snapshot, check that you are looking at the expected UI state and viewport, and compare the difference with the intended code or design change.

Identify the page, component, state, and viewport represented by the snapshot.
Inspect the changed regions in the visual diff. Look for both the intended change and any nearby layout, styling, or content regressions.
Check whether the difference is explained by the change under review. If it is not, investigate before deciding.
Repeat for every changed snapshot. A build can contain both expected and unexpected changes.

Visual comparison answers whether captured appearance changed. It does not establish that interactions, accessibility, or application behavior work correctly; keep the relevant functional checks in your review.

3. Approve only intentional changes

When a snapshot’s new appearance is correct, approve that snapshot in Percy. Its current capture becomes the reference baseline used for future comparisons. If the change is an unintended regression, fix the UI and run the visual test again; accepting the diff would make the unwanted appearance the reference.

You do not have to approve every snapshot in a build together. Percy’s changelog documents snapshot-level approval: selected snapshots can become baselines without approving the complete build. This is useful when some changes are ready while other diffs still need investigation.

4. Understand what carries into later builds

Percy’s changelog documents that previously approved snapshots carry forward between builds for the life of a branch. It also documents that a snapshot marked “changes requested” is reflected in build status and carries forward to future builds on that branch. These are dated feature notes, not a guarantee about every current project’s permissions or CI rules. If build status is a release gate, verify the behavior in your current Percy project and integration.

Keep visual reviews stable

Consistent captures make it easier to distinguish product changes from noise. Percy recommends a controlled server environment, fixed viewports, stable configuration, careful baseline review, and masking or excluding dynamic content when needed.

Control the environment: use a predictable server and test data so the same route represents the same state.
Fix viewport settings: keep viewport dimensions consistent between the baseline and the build being reviewed.
Handle dynamic regions deliberately: mask or exclude content that changes independently of the UI under test, when appropriate.
Review baseline changes: treat a new baseline as an intentional decision because later comparisons use it as the reference.
Keep functional coverage: visual snapshots complement behavior tests; they do not replace them.

Common problems and fixes

Symptom	Likely cause	What to do
A diff appears unrelated to the code change	The captured state, test data, environment, or dynamic content differs.	Confirm the route and UI state, stabilize the environment and data, and mask or exclude genuinely dynamic regions where suitable. Rerun before approving.
A snapshot still shows a difference after one change was approved	The build contains multiple snapshots, and approval can be snapshot-specific.	Review each changed snapshot separately. Approve only the ones whose appearance is intentional.
You are unsure whether approving one snapshot approves the whole build	Snapshot-level approval and complete-build approval are distinct actions.	Percy documents approving selected snapshots without approving the complete build. Check the current interface and project permissions before relying on a particular control.
CI remains blocked or build status is unexpected	Project-specific integration or status rules may determine how review states affect CI.	Inspect the current Percy project settings and integration behavior. Historical changelog notes describe carry-forward behavior but do not establish every current CI rule.
The diff looks right, but the feature is broken	A visual comparison checks appearance, not application behavior.	Run the relevant functional and interaction tests before merging or releasing.

Or skip the browser setup

If you need a screenshot for a review, report, or debugging step without setting up browser capture, ScreenshotNeo returns an image from one API request. It is a screenshot API and MCP server from Yorker Media; it is separate from Percy’s baseline review workflow. 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

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted before capture and more than 60 known consent platforms, newsletter popups, and chat widgets are removed; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, with the page verdict and billing status in response headers. An MCP server lets AI agents use the take_screenshot, get_page_info, and capture_pdf tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Can I approve just one Percy snapshot?

Yes. Percy’s changelog documents snapshot-level approval, which lets selected snapshots become baselines without approving the whole build.

Does approving a snapshot prove the change is safe?

No. It records the appearance as the comparison baseline. Review the diff and use functional checks to assess behavior.

Should I approve a diff I cannot explain?

No. First check the captured state, viewport, environment, and dynamic content. Fix or stabilize the cause, then generate and review a new build.

Do approved snapshots carry over to later builds?

Percy’s changelog documents approved snapshots carrying forward for the life of a branch. Confirm current project behavior if branch status or CI depends on it.

Sources

Percy documentation for build review and visual comparisons.
Percy changelog for documented snapshot approval and branch carry-forward behavior.
Percy visual testing best practices for stable capture and review guidance.