Review a pull request’s UI by deciding what should change, inspecting the rendered result, and using screenshot comparisons to find unexpected differences—not to decide whether a change is correct. A reliable process combines author-provided previews, human review, and automated checks against accepted screenshots.
How to review visual changes in a pull request
- Identify what users can see. List affected pages, components, and interaction states. Ask the author for screenshots or a preview link when the visual effect is hard to infer from the code.
- Establish the intended change. Read the pull-request description and inspect the proposed design before judging differences. Check layout, text, imagery, responsive behavior, and consistency with the surrounding interface.
- Inspect rendered states. Open the preview at the viewports and in the states affected by the change. Include relevant loading, empty, error, hover, or expanded states; do not assume the default screen represents the whole change.
- Run screenshot checks. Compare the new rendering with the team’s accepted reference images. Treat a diff as a signal to investigate, not as proof of a bug.
- Resolve each difference. Decide whether it is intended, a defect, or noise. Fix defects, reduce avoidable noise, and update references only for changes that the team has reviewed and accepted.
- Complete the merge review. Confirm relevant checks and required reviewers have completed, including design or product approval when the team requires it.
This distinction matters: screenshot tests detect changes in rendered output; a reviewer determines whether those changes are appropriate. Chromatic documents UI Tests and UI Review as separate workflows: tests compare story snapshots with accepted baselines, while review presents changes for people to assess. See Chromatic’s pull-request workflow and branch and baseline documentation.
What to examine in the rendered change
Layout and responsive behavior
- Check alignment, spacing, sizing, wrapping, overflow, and whether content remains usable at relevant viewport widths.
- Look for changes to shared components that may affect other pages, not only the route shown in the pull request.
- Inspect a narrow viewport when the change affects layout or typography; inspect larger screens when the component has a desktop-specific arrangement.
Content and visual states
- Verify that copy, labels, icons, images, and their placement match the intended design.
- Check the states the change touches: for example, an open menu if menu behavior changed, or an empty state if data handling changed.
- Consider theme, locale, and CSS media features when these are relevant to the affected interface. Chromatic documents these, along with browsers and viewports, as UI Test coverage dimensions; see its workflow documentation.
Consistency and unintended effects
- Compare the changed area with nearby screens and established design-system patterns.
- Review unexpected shifts, missing assets, clipped text, or changed styling in components that were not meant to change.
- When a diff looks surprising, reproduce it in the preview and identify whether it comes from the code change, an environment difference, or an unstable rendering condition before approving it.
Run local visual comparisons with Playwright
Playwright Test supports screenshot assertions with toHaveScreenshot() and comparison against reference images. Its documentation covers screenshot capture, snapshot paths, and updating references: Playwright visual comparisons. The following is a minimal TypeScript example for a project that already has Playwright Test configured and serves the app at http://localhost:3000:
import { test, expect } from '@playwright/test';
test('homepage visual appearance', async ({ page }) => {
await page.goto('http://localhost:3000');
await expect(page).toHaveScreenshot('homepage.png', { fullPage: true });
});Run the project’s Playwright test command, commonly npx playwright test. On its first run, the assertion creates a reference image; subsequent runs compare the rendering with that reference. Review the generated image and the diff as part of the pull request process rather than treating a passing or failing assertion as a design verdict.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Update an intentional baseline
If a reviewer accepts a visual change, update the reference deliberately through the team’s normal review process. Playwright documents --update-snapshots for this purpose; for example, npx playwright test --update-snapshots. Inspect the resulting reference-image changes before committing them. Updating snapshots indiscriminately can make unintended changes appear accepted, so limit updates to the relevant tests and confirm each changed image matches the intended UI.
Choose local checks or hosted visual review
There are two useful patterns, and teams can combine them. A local comparison keeps screenshot assertions in an existing test workflow. A hosted workflow can provide a shared interface for visual diffs and review feedback. Compare options against how your team actually builds and approves UI changes:
| Decision point | Local screenshot comparisons | Hosted visual testing and review |
|---|---|---|
| Test-stack fit | Playwright documents screenshot assertions and reference snapshots within Playwright Test. | Chromatic documents UI Tests and a separate UI Review workflow; Percy’s official Playwright example demonstrates uploading snapshots and reviewing visual differences. |
| Baseline ownership | Reference images are part of the snapshot workflow documented by Playwright. | Chromatic documents baselines and branch comparisons; Percy’s example documents uploaded snapshots. The cited pages do not establish every service’s current baseline-storage details. |
| Review experience | Reviewers inspect test output and image diffs through the team’s existing process. | Chromatic documents pull-request review for designers, product managers, and other stakeholders. Percy’s example demonstrates reviewing visual differences in Percy. |
| Coverage to plan | Select the browsers, viewports, themes, locales, media features, and states your app needs; support depends on the team’s test setup. | Chromatic documents browsers, viewports, themes, locales, and CSS media features as UI Test dimensions. Confirm that any other required states fit the chosen workflow. |
| Operational ownership | The team maintains tests and references and investigates noisy diffs. | The team still needs owners for review, baseline decisions, and noisy-diff handling; a hosted interface does not decide whether a change is correct. |
Chromatic describes UI Review as comparing what will change on the base branch when a pull request is merged, while UI Tests verify changes against baselines. That makes the distinction useful when a team needs both automated regression checks and human sign-off; see Chromatic’s branch and baseline guide and review documentation. Percy’s published Playwright example shows an alternative hosted snapshot-and-diff workflow. The cited documentation does not establish current prices or exact feature parity, so evaluate those directly before choosing a service.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Where ScreenshotNeo fits
ScreenshotNeo is a website screenshot API and MCP server, not a replacement for pull-request visual tests or an approval workflow. It can be useful when you need a rendered capture of a URL for review or another developer workflow. It accepts a URL in one GET request and returns an image or PDF. Its advertised distinctions include removing cookie-consent banners, newsletter popups, and chat widgets before capture; billing only clean shots, with response headers identifying the page verdict and billing status; and an MCP server with screenshot and PDF tools for AI agents. See ScreenshotNeo.
Or skip the browser setup
For a one-off capture, call the API directly. Replace the example URL with the page you want to inspect and use your API key:
Quick Recap
Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpFor request options and response details, see the ScreenshotNeo documentation. Cookie banners, popups, and chat widgets are removed 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 per month with no card, and paid plans start at $5 for 3,000. Sign up for free and try 1,000 screenshots a month with no card.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
