Synchronous comparison results
Learn Percy’s synchronous visual comparison for immediate result verification.
Percy processes visual comparisons asynchronously by default. This allows you to view the snapshot or comparison results only upon the completion of the build on the Percy dashboard or by polling the snapshot API to determine whether the snapshot has finished processing. This process excels in fast processing and supports maximum parallelization.
If you want to immediately incorporate the visual comparison results into your functional tests upon detecting a visual change, the default asynchronous setup in Percy might be a bit challenging. Not to worry though, Percy’s got a solution with the synchronous comparison results option.
With the synchronous comparison results option, you can wait for each snapshot to be processed individually. This means you get the response in your test script as soon as Percy finishes processing each snapshot. This allows you to actively monitor visual comparison results in real-time, and fulfills the desire to flag visual changes and mark their functional tests as failed.
- Currently, the synchronous comparison results feature is exclusively supported using the Percy SDK on Selenium. If you are looking for support on other frameworks, contact us.
- Percy on Automate supports this feature on both Selenium and Appium.
Prerequisites
Before you start, ensure that you have the following:
- @percy/cli version 1.28.0 and higher
- Project token is set to Full-access
Synchronous comparison results workflow
Set up Percy project and ensure that builds are actively running by utilizing the percyScreenshot() or percySnapshot() method.
Run the test script, and the command will return the object.
Wait for the response to finish, and when it’s done, the object gives you the comparison results of individual snapshots. Use these results to decide if your functional test passes or fails.
Response Structure
Error response
Supported Parameters
Snapshots
| Parameter | Sub Parameter | Description | Use Case |
|---|---|---|---|
| snapshot-name | - | Name of the snapshot. | - |
| status | - | Represents the state of the visual comparison. | Users can check if the visual comparison is successful or not based on the ‘status’ parameter, which might indicate ‘passed’ or ‘failed’. |
| started_processing_at | - | Time at which snapshot processing started. | Users can use this along with finished_processing_at to calculate processing time of the snapshot. |
| finished_processing_at | - | Time at which snapshot processing ended. | Users can use this along with started_processing_at to calculate processing time of the snapshot. |
| dashboard-urls | current-build | Current build URL. | Helps users to reference the specific head build related to the visual comparison. |
| base-build | Base build URL (if exists). | Helps users reference to the specific base build related to the visual comparison. | |
| current-snapshot | Current snapshot URL. | Helps users to reference the specific head snapshot related to the visual comparison. | |
| base-snapshot | Base snapshot URL (if exists). | Helps users to reference the specific base snapshot related to the visual comparison. |
Screenshots
| Parameter | Comparison Level | Sub Parameter | Description | Use Case |
|---|---|---|---|---|
| screenshots | platform-information | browser-info | Retrieve details such as browser name and version. | Use it for test assertions for a particular browser version combination. |
| os-info | Retrieve details such as OS name and version. | Use it for test assertions for a particular OS version combination. | ||
| device-info | Retrieve the device name. | Use it for test assertions for a particular device. Only available for POA and App Percy. | ||
| viewport | width | Viewport width. | Use it for test assertions on a specific width, ensuring that the screenshot dimensions meet certain requirements. | |
| height | Viewport height. | Use it for test assertions on a specific height, ensuring that the screenshot dimensions meet certain requirements. | ||
| resources | current-image | Retrieve the URL of the currently captured image from the system. | Use it to identify and retrieve the specific head screenshot for further analysis. | |
| base-image | Capture the Base Image URL. | Use it to identify and retrieve the specific base screenshot for further analysis. | ||
| diff_image | Retrieve the Diff Image URL generated after the comparison. | Provides users with access to the visual representation of the differences between the snapshots. | ||
| intelli-ignore-diff-image | Use the Intelli Ignore Image URL to display ignored diffs after running Intelli Ignore. | Useful for users to analyze contextual differences between snapshots if available. | ||
| diff-info | diff_ratio | Indicates the percentage of variation in comparison. | Use it to retrieve the diff_ratio from the comparison and subsequently utilise it within the test case, to pass/fail the test case. | |
| diff-coordinates | Diff Coordinates pinpointing specific y-axis locations of differences. | May assist in pinpointing the exact locations of visual differences within screenshots wrt y locations. |
Errors
| Parameter | Sub Parameter | Description | Use Case |
|---|---|---|---|
| errors | [{ message: “error1“ }, { message: “error2“ } ] | It is an array of error objects, with each object containing the error message. | Users can check if the visual comparison is successful or not based on this parameter; it will be null when there is no error. |
Global configuration file support
Synchronous comparison results is supported in the global configuration file as shown:
It does not function alongside the defer-uploads configuration.
SDK Compatibility Matrix
SDK Compatibility Matrix
| Framework | Language | Version |
|---|---|---|
| Selenium | Python | >=v2.0.3 |
| Java | >=v2.0.4 | |
| Dotnet | >=v2.0.2 | |
| Javascript | >=v2.0.4 | |
| Ruby | >=v1.0.2 | |
| Appium | Python | >=v2.0.4 |
| Java | >=v2.1.1 | |
| Dotnet | >=v3.0.3 | |
| Javascript | >=v2.0.4 | |
| Ruby | >=v0.0.4 | |
| Playwright | Javascript | >=v1.0.5 |
WebdriverIO at >= v3.1.1 is supported when using percySnapshot method.
Limitations
- It does not work when using the snapshot command via CLI option.
- It does not work when using the Upload via CLI option.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!