Percy integration basics in Cypress - Deep Dive

Overview - Percy integration basics

What is it?

Percy is a tool that helps you check how your website looks by taking pictures during tests. It works with Cypress, a testing tool, to capture snapshots of your web pages automatically. These snapshots are compared over time to find any visual changes or bugs. This helps catch design mistakes before users see them.

Why it matters

Without Percy, visual bugs can go unnoticed because manual checking is slow and error-prone. Percy automates visual testing, saving time and catching problems early. This means websites look right on all devices and updates don’t break the design. It improves user experience and reduces costly fixes after release.

Where it fits

Before using Percy, you should know basic Cypress testing and how to write automated tests. After learning Percy integration, you can explore advanced visual testing techniques and combining Percy with other CI/CD tools for full automation.

Mental Model

Core Idea

Percy takes pictures of your app during tests and compares them to catch visual changes automatically.

Think of it like...

Imagine Percy as a photographer who takes snapshots of your website every time you make changes, then compares the photos to spot any differences, like a friend noticing if your room looks messy after you rearranged it.

┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│ Cypress Tests │─────▶│ Percy Snapshot│─────▶│ Visual Diff   │
│ run on app    │      │ captures page │      │ compares old  │
│               │      │ images        │      │ and new images│
└───────────────┘      └───────────────┘      └───────────────┘

Build-Up - 6 Steps

1

Foundation

What is Percy and Visual Testing

Concept: Introduce Percy as a visual testing tool and explain visual testing basics.

Visual testing means checking how a website looks, not just how it works. Percy helps by taking screenshots during tests and comparing them to find visual bugs. This is different from checking if buttons work; it checks if buttons look right.

Result

You understand Percy’s role in catching visual bugs automatically.

Knowing that visual bugs are different from functional bugs helps you see why Percy is important alongside regular tests.

2

Foundation

Setting Up Cypress with Percy

Concept: Explain how to add Percy to a Cypress project.

To use Percy with Cypress, install the Percy Cypress package using npm. Then, add Percy commands to your Cypress tests to take snapshots. Finally, configure your Percy project with an access token to connect your tests to Percy’s service.

Result

Your Cypress tests can now take visual snapshots with Percy.

Understanding the setup process shows how Percy integrates smoothly into existing Cypress tests.

3

Intermediate

Writing Tests with Percy Snapshots

🤔Before reading on: do you think Percy snapshots capture the whole page or just visible parts? Commit to your answer.

Concept: Learn how to add Percy snapshot commands inside Cypress tests to capture pages or components.

Inside your Cypress test, use cy.percySnapshot('name') to take a snapshot at any point. You can capture full pages or specific states after interactions. Naming snapshots clearly helps track changes over time.

Result

Tests now include visual checkpoints that Percy compares on each run.

Knowing when and what to snapshot helps catch visual bugs exactly where they happen.

4

Intermediate

Understanding Visual Diffs and Baselines

🤔Before reading on: do you think Percy compares snapshots to the first run or the last run? Commit to your answer.

Concept: Explain how Percy compares new snapshots to a baseline and shows differences.

Percy stores a baseline snapshot from the first test run. On later runs, it compares new snapshots to this baseline. If differences appear, Percy highlights them in a visual diff. You can approve changes to update the baseline or reject if they are bugs.

Result

You understand how Percy detects visual changes and manages baselines.

Understanding baselines and diffs is key to trusting Percy’s visual feedback and managing changes.

5

Advanced

Integrating Percy in CI/CD Pipelines

🤔Before reading on: do you think Percy runs only locally or can run automatically in CI? Commit to your answer.

Concept: Learn how to run Percy visual tests automatically in continuous integration pipelines.

You can configure your CI system (like GitHub Actions) to run Cypress tests with Percy. This means every code change triggers visual tests and reports results automatically. You need to set environment variables for Percy tokens and add Percy commands in your CI scripts.

Result

Visual testing becomes part of your automated deployment process.

Knowing how to automate Percy tests in CI ensures visual bugs are caught before code reaches users.

6

Expert

Handling Dynamic Content and Flaky Visuals

🤔Before reading on: do you think Percy can handle pages with changing ads or animations without false positives? Commit to your answer.

Concept: Explore strategies to reduce false positives caused by dynamic content in Percy snapshots.

Dynamic content like ads or animations can cause Percy to report differences that are not bugs. To handle this, you can mask or hide dynamic areas before snapshots, use CSS to freeze animations, or configure Percy to ignore certain regions. This keeps visual diffs meaningful.

Result

Your visual tests become stable and reliable despite dynamic page elements.

Understanding how to manage dynamic content prevents wasted time chasing false visual bugs.

Under the Hood

Percy works by capturing screenshots of your web pages during Cypress test runs. It uploads these images to Percy’s cloud service, where they are stored as baseline snapshots. On subsequent runs, Percy compares new screenshots pixel-by-pixel against the baseline to detect visual differences. It uses smart algorithms to highlight meaningful changes and ignore minor noise. The comparison results are shown in a web dashboard for review and approval.

Why designed this way?

Percy was designed to automate visual testing because manual visual checks are slow and error-prone. Using cloud storage and comparison offloads heavy image processing from local machines. The pixel-by-pixel comparison ensures precise detection of visual changes. Alternatives like manual screenshots or simple diff tools lacked automation and accuracy, so Percy’s approach balances automation, precision, and usability.

┌───────────────┐      ┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│ Cypress Test  │─────▶│ Screenshot    │─────▶│ Upload to     │─────▶│ Percy Cloud   │
│ runs and calls│      │ captured by   │      │ Percy Service │      │ stores images │
│ cy.percySnap │      │ browser       │      │               │      │ and baseline  │
└───────────────┘      └───────────────┘      └───────────────┘      └───────────────┘
                                                                      │
                                                                      ▼
                                                           ┌───────────────────┐
                                                           │ Visual Comparison │
                                                           │ pixel-by-pixel    │
                                                           └───────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Percy replace functional testing? Commit yes or no before reading on.

Common Belief: Percy replaces all other tests because it checks the whole page visually.

Reality: Percy only checks how things look, not if buttons or logic work correctly. Functional tests are still needed.

Why it matters: Relying only on Percy can miss bugs that break functionality but don’t change appearance.

Quick: Do you think Percy snapshots capture dynamic content perfectly every time? Commit yes or no.

Common Belief: Percy snapshots always capture exactly what users see, even with animations or ads.

Reality: Dynamic content can cause false positives unless masked or handled properly.

Why it matters: Ignoring this leads to noisy test failures and wasted debugging time.

Quick: Does Percy compare snapshots to the last test run or the first approved baseline? Commit your answer.

Common Belief: Percy compares snapshots only to the last test run’s images.

Reality: Percy compares to the first approved baseline snapshot, not just the last run.

Why it matters: Misunderstanding this can cause confusion about when visual changes are detected and approved.

Quick: Can Percy run only locally? Commit yes or no.

Common Belief: Percy is only for local testing and cannot be integrated into CI pipelines.

Reality: Percy is designed to integrate fully with CI/CD pipelines for automated visual testing.

Why it matters: Not using Percy in CI misses the benefit of catching visual bugs early in development.

Expert Zone

1

Percy’s snapshot timing is critical; capturing snapshots too early or late can cause false diffs due to incomplete page rendering.

2

Masking dynamic regions requires careful CSS selectors and can be combined with Percy’s ignore regions feature for precise control.

3

Percy supports parallel test runs by merging snapshots intelligently, which is essential for large test suites to run efficiently.

When NOT to use

Percy is not ideal for testing highly interactive or canvas-based graphics where pixel-perfect comparison is unreliable. In such cases, unit tests or specialized visual regression tools for graphics should be used instead.

Production Patterns

In production, teams integrate Percy snapshots at key user flows and critical pages, run tests in CI on every pull request, and use Percy’s approval workflow to manage visual changes. They combine Percy with functional Cypress tests for full coverage.

Connections

Snapshot Testing

Percy builds on the idea of snapshot testing by applying it visually rather than just to code output.

Understanding snapshot testing in code helps grasp how Percy compares visual snapshots to detect changes.

Continuous Integration (CI)

Percy integrates with CI pipelines to automate visual testing on every code change.

Knowing CI concepts helps you automate Percy tests and catch visual bugs early in development.

Quality Control in Manufacturing

Percy’s visual diff process is like quality inspectors comparing product samples to a standard to find defects.

Seeing Percy as a quality inspector clarifies why consistent baselines and careful comparisons are essential.

Common Pitfalls

#1 Taking Percy snapshots before the page fully loads causes false visual differences.

Wrong approach:

cy.visit('/page')
cy.percySnapshot('Early snapshot')

Correct approach:

cy.visit('/page')
cy.wait(1000) // wait for page to load
cy.percySnapshot('Loaded snapshot')

Root cause:

Not waiting for page elements to render means snapshots capture incomplete or changing states.

#2 Not masking dynamic content leads to flaky visual tests.

Wrong approach:

cy.percySnapshot('Page with ads') // no masking or hiding dynamic ads

Correct approach:

cy.get('.ad-banner').invoke('hide')
cy.percySnapshot('Page without ads')

Root cause:

Dynamic elements change every run, causing Percy to detect false differences.

#3 Using vague snapshot names makes it hard to track visual changes.

Wrong approach:

cy.percySnapshot('Snapshot')

Correct approach:

cy.percySnapshot('Homepage logged-in state')

Root cause:

Unclear names prevent easy identification of what changed in Percy’s dashboard.

Key Takeaways

Percy automates visual testing by capturing and comparing screenshots during Cypress tests.

Visual testing complements functional testing by catching design and layout bugs invisible to code checks.

Proper setup, snapshot timing, and handling dynamic content are essential for reliable Percy tests.

Integrating Percy into CI pipelines ensures visual bugs are caught early and continuously.

Understanding Percy’s baseline and diff process helps manage visual changes confidently.