Prompt
How do I add visual regression testing to pull requests?
Latest observation
To add visual regression testing to pull requests, the usual pattern is:
- Capture screenshots of key UI states from a base branch
- Compare them against screenshots from the PR branch
- Fail or comment on the PR if differences exceed a threshold
Here’s a practical setup.
1) Pick a visual testing approach
You have two common options:
A. Self-hosted/open-source
Good if you want full control and lower cost.
Popular tools:
- Chromatic (for Storybook)
- Playwright + image snapshots
- Cypress + screenshot diffing
- Percy (hosted, but easy integration)
B. Hosted visual testing
Best for convenience and PR annotations.
Examples:
- Percy
- Chromatic
- Applitools
2) Decide what you’ll test
Pick a few stable pages/components:
- Home page
- Login form
- Nav/header
- Important modals
- Component library stories
Avoid pages with:
- random ads
- timestamps
- live data changes
- animations
- unstable fonts/rendering
3) Set up deterministic screenshots
Visual tests are flaky unless the UI is stable.
Do this:
- Use fixed viewport sizes
- Mock API responses
- Freeze time/date
- Disable animations
- Use consistent fonts
- Seed test data
- Wait for network idle or specific selectors
4) Example using Playwright in CI
Playwright can take screenshots and compare them to stored baselines.
Install
npm i -D @playwright/test
npx playwright install
Example test
import { test, expect } from '@playwright/test';
test('homepage visual regression', async ({ page }) => {
await page.goto('http://localhost:3000');
await page.setViewportSize({ width: 1280, height: 720 });
await expect(page).toHaveScreenshot('homepage.png');
});
First run to create baselines
npx playwright test --update-snapshots
Run in CI
npx playwright test
If the screenshot differs, the test fails.
5) Add it to pull request checks
Use your CI provider to run visual tests on every PR:
- GitHub Actions
- GitLab CI
- CircleCI
- Jenkins
- Bitbucket Pipelines
Typical flow:
- On PR: run tests against preview build
- Compare screenshots to baseline from
main - Upload diffs as artifacts or PR comments
- Mark check as failed if differences are significant
6) GitHub Actions example
name: visual-tests
on:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npx playwright install --with-deps
- run: npm run build
- run: npm run start &
- name: Run visual tests
run: npx playwright test
- name: Upload screenshots on failure
if: failure()
uses: actions/upload-artifact@v4
with:
name: playwright-diffs
path: test-results/
7) If using Percy or Chromatic
These tools make PR integration easier.
Percy
- Take snapshots in tests
- Percy uploads screenshots
- It comments on the PR with diffs
- You can approve or reject changes in the UI
Chromatic
Best for Storybook-driven component testing:
- Build Storybook
- Upload stories to Chromatic
- It compares each story across commits
- PR comments show visual changes
Example:
npx chromatic --project-token=$CHROMATIC_PROJECT_TOKEN
8) Recommended PR workflow
A good pull request flow looks like this:
- Developer opens PR
- CI builds app
- Visual tests run against preview
- Diff results are posted to PR
- Reviewer checks diffs
- If expected, approve/update baseline
- If unexpected, fix UI or test
9) Tips to reduce flaky failures
- Test components in isolation when possible
- Use
data-testidor stable selectors - Hide dynamic content
- Set consistent browser/OS versions
- Keep screenshots small and focused
- Review diff thresholds carefully
- Rebaseline only when UI changes are intentional
10) Best practice recommendation
If you already use Storybook, start with Chromatic.
If you want a more general E2E approach, use Playwright with screenshot assertions.
Simple rule:
- Storybook components → Chromatic
- Full pages / app flows → Playwright or Percy
If you want, I can give you:
- a GitHub Actions + Playwright setup,
- a Storybook + Chromatic setup, or
- a Percy/Cypress setup.