Visual analysis

Run Percy visual tests on your web pages and app screens, then compare each snapshot against its baseline and approve it from your IDE.

A visual test captures a snapshot of your page or screen and compares it against the last approved version of that snapshot. Percy marks the snapshot as changed when the two differ. You decide whether the change is intended.

Test Companion runs that loop for you. It captures the snapshots, sends them to BrowserStack Percy, waits for the build to finish, and opens the comparison in the Visual Analysis panel. You approve the build without leaving your IDE.

Prerequisites

Before you start, confirm the following:

• Test Companion is installed in a supported IDE and you are signed in to your BrowserStack account.
• Your BrowserStack account has access to Percy.
• For a web app, you have a public URL, a running local server, or a web project in your workspace.
• For a mobile app, you have an Android .apk or an iOS .ipa build.

How visual analysis works

A visual analysis run moves through these stages:

1. You ask for a visual test, or you fill the guided form in the Visual Analysis panel.
2. Test Companion selects a capture method for your project, then captures the snapshots.
3. Percy renders each snapshot and compares it against the project baseline.
4. The Visual Analysis panel opens on the finished build. You approve the build or fix the code.

Percy needs time to render and compare a build. The panel shows that no review is ready, then refreshes automatically after the results arrive.

Connect Visual Analysis

Open the Visual Analysis panel from the PANELS row at the top of the Test Companion sidebar, next to Test Cases and Failure Analysis.

Before you connect a project, the panel opens on Connect Visual Analysis and shows two paths. Pick the one that matches your project.

Your Percy token is stored on your machine. Test Companion does not send your token anywhere else.

Set up visual testing from scratch

Choose this path when your project has no visual testing yet. Test Companion writes the prompt for you, so you do not need to know how to phrase it.

1. Click Start Visual Analysis.
2. In Paste your Product URL or test folder, enter the URL or the folder to capture.
3. In Type or paste additional details, name the screens to cover, or leave the field empty.

4. Click Add to prompt.

   

5. Press Enter to send the prompt that Test Companion built.

Add an existing Percy project

Choose this path when you already run Percy, for example, in CI, and you want to review its builds in your IDE.

1. Click Add an existing Visual Analysis project (Percy).
2. Paste your Percy full-access project token, then press Enter.

Test Companion imports that project and lists its builds in the panel. You review and approve the builds the same way you review a build you started yourself.

The Visual Analysis panel

After a build completes, the panel shows every snapshot in the build and the comparison for the snapshot you select.

Approve a build

The first build in a project has no baseline, so the panel reports that none exists yet. Percy stores that build as the baseline for the project.

Every later build is compared against the current baseline. When you approve a build, Percy promotes its snapshots, and the next build is compared against them. Approve a build only after you confirm that each change is intended.

When a difference is a real regression, leave the build unapproved. Fix the code, then run the visual test again to produce a new build.

To review the same build in your browser, click Open in Percy. Use this option when you want the full dashboard or a link you can share.

Next steps

• Run visual tests on web apps: Capture web pages and compare them across browsers and widths.
• Run visual tests on mobile apps: Capture app screens and compare them across real devices.
• Percy documentation: Read how Percy builds, snapshots, and baselines work.