Running Percy on Pull Requests: Catch Visual Regressions Early

The Problem: Visual Regressions Slip Through Traditional CI

Modern front‑end teams ship changes quickly, but a small CSS tweak can break the look of a component in one browser and not another. Unit tests rarely catch pixel‑level differences and manual visual checks are slow and error‑prone. Visual regression tools like BrowserStack Percy aim to fill that gap by rendering pages in real browsers and comparing the result to an approved baseline.

Percy Snapshot Workflow Overview

Percy works by taking a rendered snapshot of a page or component and storing it in the cloud. When a new snapshot is created, Percy calculates a pixel‑by‑pixel diff against the baseline. The diff is shown in a web UI where a reviewer can approve or reject the change. Approved snapshots replace the baseline for future runs.

Key points to remember:

• Snapshots are rendered on BrowserStack’s infrastructure, so you get cross‑browser coverage without maintaining your own farm.
• Animations are frozen automatically, but truly dynamic content (timestamps, random ads) still needs to be mocked or hidden.
• Snapshots are captured via SDKs that integrate with popular test frameworks (Cypress, Playwright, Selenium, Storybook). The SDK call is usually a single line of code.
• Because Percy is a commercial product, snapshot volume and parallelization affect cost.

Practical Decision: Run Percy on Pull Requests, Not Only Release Branches

Many teams add Percy to their release or main branch pipeline, assuming that visual changes are only relevant for a full release. However, running Percy on every pull request (PR) has several advantages:

• Smaller Diff Size – The changes are usually limited to a single component or page, making the diff easier to review.
• Attribution – The reviewer knows exactly which PR introduced the change, speeding up triage and rollback if needed.
• Early Detection – Visual bugs are caught before they merge into the main branch, preventing them from propagating to production.

Running Percy on PRs does increase snapshot volume, so teams should verify the current pricing plan and consider throttling or limiting snapshots to critical components.

Worked Example: Adding Percy to a Cypress Test

Below is a minimal example that demonstrates how to add a Percy snapshot to an existing Cypress test. The example assumes you already have a Percy account and the @percy/cypress SDK installed.

/// <reference types="cypress" />
/// <reference types="@percy/cypress" />

// cypress/integration/percy_demo.spec.js

describe('Home page visual test', () => {
  it('captures the main banner', () => {
    // Visit the page
    cy.visit('https://example.com');

    // Wait for the banner to load
    cy.get('#main-banner').should('be.visible');

    // Capture a Percy snapshot
    cy.percySnapshot('Home – Main Banner', {
      // Optional: capture at two widths
      widths: [375, 1024],
      // Optional: ignore dynamic content
      ignore: ['#timestamp', '.ad-banner']
    });
  });
});

**Where to run** – This test is executed as part of your normal Cypress run inside the CI pipeline. The cy.percySnapshot call will contact Percy’s API to upload the rendered image. The snapshot is then available in the Percy dashboard for review.

**Permissions** – The CI job must have the PERCY_TOKEN environment variable set (readonly access is sufficient for uploads). The job also needs network access to api.percy.io and the BrowserStack infrastructure.

**Checks** – After the run, check that the Percy job appears in the CI console output. In the Percy UI, verify that the snapshot has a diff status (e.g., New or Updated). If the diff is acceptable, approve it to make it the new baseline.

Trade‑offs & Limitations

• Human Review Bottleneck – Every new snapshot requires a manual approval. If the team does not own the approval process, PRs may stall.
• Dynamic Content Noise – Elements that change on every load (ads, timestamps) can generate noisy diffs. Use the ignore option or mock data to keep diffs meaningful.
• Cost Implications – Percy charges per snapshot and per parallel run. Running on PRs increases snapshot count, so review your plan and consider snapshot limits or selective snapshotting.
• Version Sensitivity – SDK APIs and supported browser lists change. Verify that your test framework version (Cypress 12/13, Playwright 1.35, etc.) is supported by the Percy SDK you are using.

Actionable Next Steps

1. Audit your CI pipeline to identify where visual tests should live (e.g., PR step).
2. Add the Percy SDK to your test framework and create a single snapshot per feature change.
3. Configure ignore rules for dynamic elements and freeze animations if needed.
4. Set up a review cadence: assign a reviewer or a rotating team to approve snapshots within a set time window.
5. Monitor snapshot volume and cost; adjust the plan or snapshot strategy if necessary.
6. Document the process so new contributors know how to add Percy snapshots to their tests.

By integrating Percy into the PR workflow, teams can catch visual regressions early, keep baselines up‑to‑date, and maintain a high‑quality front‑end without sacrificing speed.