Percy Enterprise Visual Testing Features

Percy Enterprise is a visual testing platform that automates the detection of unintended visual changes in web applications. You provide it with a base set of screenshots (or it captures them for you), and it compares future builds against that baseline, highlighting any pixel-level differences so your team can review and approve them before release. This article documents the features that are officially described in Percy’s public documentation, organized for easy reference.

What Percy Enterprise Is Built On

Percy is a visual regression testing tool that integrates into your CI/CD pipeline. It was originally a standalone service, and after being acquired by BrowserStack, it now offers both a cloud-hosted (SaaS) version and an Enterprise tier. The Enterprise plan adds features aimed at larger organizations: single sign-on (SSO), audit logs, dedicated support, and in some cases, on-premise or private cloud deployment. The core visual testing workflow—snapshot, render, compare, approve—is identical across plans, but Enterprise adds administrative and security controls that the standard plan lacks.

Core Visual Testing Workflow

The heart of Percy is the “snapshot” process. Your tests (using a Percy SDK like @percy/cli or a framework-specific SDK) capture the DOM and CSS of a page at a given moment. Percy then renders that snapshot in a headless browser at the widths and devices you specify. The rendered image is stored as the baseline for that commit. On the next run, it renders the new snapshot and compares it pixel-by-pixel against the baseline.

• Snapshot capture: SDKs for JavaScript, Python, Ruby, Java, and others, plus a CLI that can wrap any test runner.
• Parallel testing: You can upload snapshots from multiple machines concurrently; Percy groups them by build.
• Cross-browser rendering: Choose from a list of browsers and viewports (e.g., Chrome, Firefox, Safari, Edge) to render each snapshot.
• Diff visualization: The UI shows a side-by-side or overlaid comparison, with changed regions highlighted in color.

Approval and Review Features

Once a build is created, it goes through a review process. Percy Enterprise adds a few collaboration features that are not in the free tier.

• Manual approval: A team member can approve or reject a build. If rejected, you can add a comment explaining why.
• Auto-approval: You can configure the system to auto-approve builds that have zero changes, or that match a certain pattern (e.g., from a dependabot branch).
• Per-change approval: Instead of approving the whole build, you can approve each individual snapshot diff. This is useful when a build contains both intentional and unintentional changes.
• Review comments: You can leave comments on a specific diff, which is helpful for team communication.

In the Enterprise UI, the build summary page lists all snapshots, their status (unchanged, changed, new), and who reviewed them. The audit log records every approval and rejection, which is critical for compliance.

Integration with CI/CD and Version Control

Percy is designed to fit into your existing pipeline. The typical flow is: push code → CI runs your test suite → Percy SDK uploads snapshots → Percy compares and returns a status (success if no changes, or if changes are approved).

• GitHub, GitLab, Bitbucket: Percy posts a status check on the commit, and you can see the build link directly from the PR.
• CI providers: Works with Jenkins, CircleCI, Travis CI, GitHub Actions, GitLab CI, and others. You just set two environment variables (PERCY_TOKEN and PERCY_BRANCH).
• API: The REST API lets you programmatically create builds, upload snapshots, and retrieve results.
• Webhooks: You can configure webhooks to notify your chat tool (e.g., Slack) when a build is ready for review.

Enterprise-specific integration features include SAML SSO for authentication and SCIM for user provisioning, which are common requirements for large teams.

Managing Baselines and Branches

A common misconception is that Percy only compares against the last commit. In reality, it uses a “base build” concept. For each branch, Percy finds the most recent build that was approved (or that had no changes) and uses that as the baseline. This means you can have multiple feature branches running in parallel without them interfering with each other.

• Branch detection: Percy automatically detects the branch name from the CI environment. If you need to override it, you can set PERCY_BRANCH manually.
• Base build selection: By default, it uses the last approved build on the same branch. You can also specify a different branch to compare against (e.g., compare a feature branch against master).
• Cross-branch comparison: The UI lets you switch the baseline to any other build, which is useful when you want to see how a branch diverged.

Enterprise Administration and Security

The Enterprise plan adds a layer of administrative control that is not present in the standard plan. These features are documented in the Percy Enterprise admin guide.

• Single Sign-On (SSO): Support for SAML 2.0, which allows your team to log in with your corporate identity provider (Okta, Azure AD, etc.).
• Audit logs: A record of every action taken in the organization, including who approved a build, who changed settings, and when.
• User management: Admins can invite/remove users, assign roles (admin, member, read-only), and manage teams.
• Private cloud / on-premise: For organizations that cannot send screenshots to a third-party cloud, Percy Enterprise offers a self-hosted option. This is deployed in your own infrastructure, and the documentation includes Docker images and Kubernetes manifests.
• Data retention: You can set how long build history is kept. The default is unlimited, but you can configure a retention policy to comply with data protection regulations.

Common Problems and How to Avoid Them

Even with a solid tool, teams run into issues. The most frequent ones are:

• Flaky tests due to dynamic content: Animations, timers, or random data cause diffs. Solution: use Percy’s freeze and clip options in the SDK to stabilize the snapshot.
• Missing baseline: If a branch is new and has no prior approved build, Percy will mark all snapshots as “new” and require approval. This is expected, but teams sometimes mistake it for a regression.
• False positives from anti-aliasing: Text rendering can vary slightly between browsers. Percy’s diff algorithm is designed to ignore sub-pixel differences, but if you see persistent false positives, you can adjust the diffThreshold (the minimum percentage of pixels that must change to count as a diff).
• Slow builds: Rendering many snapshots takes time. Use parallelization and only snapshot the pages that matter.

Frequently Asked Questions

Does Percy Enterprise support on-premise deployment?

Yes. The Enterprise plan includes an option for self-hosting Percy in your own environment. BrowserStack provides Docker images and a Helm chart for Kubernetes. You are responsible for the infrastructure, but the feature set is identical to the cloud version.

Can I use Percy with my existing test framework (e.g., Cypress, Playwright)?

Yes. Percy offers SDKs for Cypress, Playwright, Puppeteer, Selenium, and WebdriverIO, among others. You add a few lines of code to your tests to capture snapshots. The SDKs are open-source and documented on the Percy website.

How does Percy handle dynamic content like dates or user avatars?

You can use the SDK’s freeze option to replace dynamic values with static ones before capturing the snapshot. For example, you can freeze the system time or mock network requests. Percy also has a feature called “ignored regions” where you can specify areas of the page to exclude from comparison.

What is the difference between Percy and BrowserStack’s other visual testing tools?

BrowserStack also offers a visual testing tool called “BrowserStack Visual” which is a separate product. Percy is the older, more established tool that BrowserStack acquired. The two have similar features, but Percy has a larger ecosystem of SDKs and a more mature API. BrowserStack is gradually integrating Percy into its platform, but they are still separate products.

Can I automatically approve changes that are expected?

Yes. You can configure auto-approval rules in the project settings. For example, you can auto-approve builds that have no changes, or builds from a specific branch (like dependabot). You can also use the API to approve builds programmatically from your CI script.

Does Percy support visual testing for mobile apps?

Percy primarily targets web applications. For mobile apps, you can use Percy’s ability to render web views, but for native mobile screenshots, you would need a different tool. BrowserStack offers a separate product for native app visual testing.

Related

• Threads Edit Button & Voice Notes: No Subscription?
• Recruitment Chatbot Data: What’s Collected & How to Protect It
• Stable Phone Case: How to Choose One That Won’t Rock