How to Set a Visual Testing Baseline and Overwrite Screenshot Results

A visual testing baseline is an accepted reference screenshot that later test captures are compared against. In Playwright Test, create or update screenshot references with npx playwright test --update-snapshots. Run that command only after an intentional UI change, inspect every updated image, and commit approved references alongside the code change. The command writes references; it does not decide whether a difference is acceptable.

What a visual testing baseline does

A baseline is the known-good image for a particular page or UI checkpoint. A visual test captures the current page and compares it with that reference. Differences can reveal regressions, but may also reflect an intended design change or a changed rendering environment. Treat the baseline as reviewed test data, not as an automatic record of whatever the application rendered most recently.

Playwright stores reference screenshots in the project and compares later screenshots against them. Its documentation recommends reviewing snapshot changes and running tests in the environment used to generate the references. Playwright screenshot assertions and snapshots.

Set up and update Playwright screenshot baselines

1. Write a screenshot assertion. Add an assertion at a stable point in the page flow. For example, save the following as tests/homepage.spec.ts in a Playwright Test project:

import { test, expect } from '@playwright/test';

test('homepage matches its visual baseline', async ({ page }) => {
  await page.goto('http://localhost:3000');
  await expect(page).toHaveScreenshot('homepage.png', {
    fullPage: true,
  });
});

The test assumes the application is available at http://localhost:3000 and Playwright Test is configured in the project. If your app uses another address, replace the URL. The assertion can capture the page or, when appropriate, a locator for a smaller component.

2. Generate the initial reference. Run the test. When a reference is missing, Playwright writes the actual screenshot as the new reference. Review the created image before treating it as the intended appearance.
3. Make the planned UI change. Keep the implementation change and its expected visual effect clear. Avoid updating snapshots as a routine response to a failing test.
4. Update references explicitly. Run this from the project root:

npx playwright test --update-snapshots

To update only a particular test file, pass its path before the flag:

npx playwright test tests/homepage.spec.ts --update-snapshots

5. Review every changed image. Inspect the image files in the code review. Confirm each difference matches the intended change and that unrelated pages or components did not shift.
6. Commit approved references. Commit the changed baseline files with the UI or test change. This ensures future runs compare against the reviewed version.

For exact assertion options and update behavior, consult the Playwright documentation. Keep the installed Playwright version in mind if your project’s behavior differs from the documented command.

Review changes without masking regressions

Updating a reference is an approval action in your repository workflow. A safe review asks whether the image change is expected, limited to the intended feature, and consistent across the affected states. If a change is surprising, investigate the application or test before accepting a new reference.

• Inspect the changed images, not only the test output saying snapshots were updated.
• Check whether the difference appears on pages that were not part of the change.
• Verify that the capture ran in the same environment as the reference generation.
• Keep the baseline change in the same review as the corresponding UI change.
• If the difference is unexpected, revert the reference update and fix the cause.

Do not use --update-snapshots to make a failing visual test pass without understanding the diff. The command replaces references; the team still needs to decide whether the new appearance is correct.

Hosted visual review and other baseline workflows

Hosted visual-review tools generally capture checkpoints, compare them to stored baselines, and provide a review step. In Applitools’ described workflow, accepting a difference saves the new checkpoint as the baseline; rejecting it retains the previous baseline. Baseline modification may require an approved, authenticated user. See Applitools’ Playwright documentation and its baseline review documentation.

Percy’s Playwright repository describes a deliberate setup command for establishing baselines in an existing project: npx percy playwright:setup-baseline. Its repository says ordinary runs on an existing project do not automatically re-baseline it. Check the current package version and integration instructions before relying on that command: Percy Playwright repository.

Decision point	Local Playwright snapshots	Hosted visual review
Where references live	Screenshot files in the test repository.	References managed by the service, depending on integration.
How differences are reviewed	Image diffs in local tooling or code review.	A visual report with service review actions.
Who approves changes	People with repository review and merge access.	Service permissions may limit who can accept or reject.
What to verify	Consistent runner environment and committed snapshot files.	Current integration behavior, authentication, and approval rules.

These workflows solve related review problems, but their commands and approval mechanics are product-specific. The cited documentation does not establish a universal rule for every visual testing framework.

Keep screenshot comparisons consistent

Rendering differences can create noisy image changes even when application code is unchanged. Playwright recommends generating and comparing screenshots in the same environment. Keep the browser and operating system, installed fonts, viewport, device scale factor, locale, timezone, test data, and page state consistent where they affect rendering.

• Wait for the page content and fonts your assertion depends on before capturing.
• Use stable test data and predictable page state.
• Choose a consistent viewport and browser configuration.
• When a baseline changes unexpectedly in CI, compare the CI environment with the environment that generated the reference.
• For animated or time-sensitive content, make the test state deterministic before updating references.

Playwright’s guidance is to use the same environment as the one where the baseline screenshots were generated; see its snapshot documentation.

Troubleshooting

Symptom	Likely cause	What to do
The test reports a missing reference.	This is the first run for that screenshot, or the reference file is absent.	Run the test to generate the reference, inspect it, then commit it if it is the intended appearance.
Many unrelated snapshots change.	The rendering environment, browser, fonts, viewport, data, or application state changed.	Compare the current setup with the baseline-generation environment. Revert bulk updates until the source of the difference is understood.
The update command succeeds, but an unwanted appearance is now accepted.	The command updates references without judging whether the differences are correct.	Review the image diff. Restore the old reference or correct the UI, then rerun and review.
A local update does not match CI.	Local and CI rendering environments differ.	Generate and compare references in a consistent environment, and check browser and operating-system dependencies.
A hosted review user cannot accept a difference.	The user may not be authenticated or authorized to edit baselines.	Sign in and use an account with the required approval permission, following the service’s access rules.
Percy setup behavior differs from an example.	The integration or package version may have changed, or the project is not following the described existing-project setup path.	Check the current Percy Playwright repository and the installed package’s instructions before running setup.

Performance, reliability, and cost considerations

Baseline maintenance adds work to test review and version control: screenshots must be generated, inspected, and kept aligned with their tests. A full-page capture can produce more image data and cover more content than a component capture, so use the smallest capture scope that verifies the behavior you care about. Stable test data and a repeatable rendering environment reduce needless baseline churn.

Local Playwright snapshots are files in your project, so their storage and review are part of your repository workflow. A hosted service adds its own account, integration, access-control, and pricing considerations. The sources cited here do not establish current prices or a controlled performance comparison, so check the relevant vendor’s current plan details when evaluating hosted services.

Or skip the browser setup

If you need clean screenshots for documentation, review, or other capture workflows without configuring browser automation, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. It is a capture service, not a replacement for Playwright’s baseline assertions or visual regression review.

Cookie and consent banners are accepted and removed before capture, along with 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation. Example using cURL:

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}`);

ScreenshotNeo includes full-page capture, CSS-selector element capture, viewport and device presets, dark mode, retina scale, custom CSS and JavaScript, waits, request blocking, custom headers and cookies, PDF options, caching, signed links, async jobs, bulk capture, and a usage API. All features are on every plan. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Details are at ScreenshotNeo.

Start with 1,000 free screenshots a month, no card required.

FAQ

Does updating a baseline prove the visual change is correct?

No. It updates the reference image. Review the difference and verify it matches the intended UI change.

Should every screenshot assertion cover the full page?

No. Capture the full page when page-wide layout matters; use a locator screenshot when the behavior under test is confined to a component.

Can a screenshot API replace a visual regression test?

A capture API can return screenshots, but the baseline comparison and approval workflow still need to be provided by your test code or review system.