Synchronous comparison results
Learn App Percy’s synchronous visual comparison for immediate result verification.
App 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 Appium. If you are looking for support on other frameworks, contact us.
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() method.
Enable synchronous comparison results during screenshot capture by setting the sync parameter to true.
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
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 |
|---|---|---|
| Appium | Python | >=v2.0.4 |
| Java | >=v2.1.1 | |
| CSharp | >=v3.0.3 | |
| Javascript | >=v2.0.4 | |
| Ruby | >=v0.0.4 |
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!