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.
You can use synchronous comparison results option using PercySDK with Percy Web or Percy with Automate. Choose Percy if you want to perform visual tests solely on the newest browsers; choose Automate if you want to run visual tests on a range of desktop, mobile, and browser combinations.
To establish this integration, choose the appropriate option and refer to the following section accordingly:
- 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 percySnapshot() method.
Enable synchronous comparison results during screenshot capture by setting the sync parameter to true.
response = await percySnapshot(driver, name, { sync: 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
{
"snapshot-name": "Percy Synchronous CLI",
"status": "success",
"started-processing-at": "2024-01-30T17:44:40.000Z",
"finished-processing-at": "2024-01-30T17:45:00.000Z",
"dashboard-urls": {
"current-build": "https://percy.io/test/project_slug/builds/2",
"base-build": "https://percy.io/test/project_slug/builds/1",
"current-snapshot": "https://percy.io/test/project_slug/snapshot/3xxx/default-comparison",
"base-snapshot": "https://percy.io/test/project_slug/snapshot/1xxx/default-comparison"
},
"screenshots": [
{
"platform-information": {
"browser-info": {
"name": "Safari",
"version": "16.5"
},
"os-info": {
"name": "macOS",
"version": "13.4.1"
}
},
"viewport": {
"width": 375,
"height": 1024
},
"resources": {
"current-image": "https://images.percy.io/3xxx",
"base-image": "https://images.percy.io/1xxx",
"diff-image": "https://images.percy.io/1xxx_diff",
"intelli-ignore-diff-image": "https://images.percy.io/1xxx_intelli_ignore_diff"
},
"diff-info": {
"diff-ratio": 0.0448868,
"diff-coordinates": {
"y_coords": [[74,98]],
"intelli_ignore_y_coords": [[92,100]]
}
},
"started-processing-at": "2024-01-30T17:44:40.000Z",
"finished-processing-at": "2024-01-30T17:45:13.000Z"
},
{
"platform-information": {
"browser-info": {
"name": "Safari",
"version": "16.5"
},
"os-info": {
"name": "macOS",
"version": "13.4.1"
}
},
"viewport": {
"width": 1280,
"height": 1024
},
"resources": {
"current-image": "https://images.percy.io/1xx",
"base-image": null,
"diff-image": null,
"intelli-ignore-diff-image": null
},
"diff-info": {
"diff-ratio": null,
"diff-coordinates": null
},
"started-processing-at": "2024-01-30T17:44:40.000Z",
"finished-processing-at": "2024-01-30T17:45:19.000Z"
},
{
"platform-information": {
"browser-info": {
"name": "Chrome",
"version": "115.0.5790.102"
},
"os-info": {
"name": "Linux",
"version": ""
}
},
"viewport": {
"width": 375,
"height": 1024
},
"resources": {
"current-image": "https://images.percy.io/2xxx",
"base-image": null,
"diff-image": null,
"intelli-ignore-diff-image": null
},
"diff-info": {
"diff-ratio": null,
"diff-coordinates": null
},
"started-processing-at": "2024-01-30T17:44:40.000Z",
"finished-processing-at": "2024-01-30T17:44:58.000Z"
},
{
"platform-information": {
"browser-info": {
"name": "Chrome",
"version": "115.0.5790.102"
},
"os-info": {
"name": "Linux",
"version": ""
}
},
"viewport": {
"width": 1280,
"height": 1024
},
"resources": {
"current-image": "https://images.percy.io/1xxxx",
"base-image": null,
"diff-image": null,
"intelli-ignore-diff-image": null
},
"diff-info": {
"diff-ratio": null,
"diff-coordinates": null
},
"started-processing-at": "2024-01-30T17:44:40.000Z",
"finished-processing-at": "2024-01-30T17:45:00.000Z"
}
]
}Error response
{
"snapshot-name": "Percy Synchronous CLI",
"status": "failure",
"started-processing-at": "2024-01-30T17:47:30.000Z",
"errors": [
{
"message": "Snapshot failed to process"
}
]
}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. |
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:
version: 2
snapshot:
sync: true/falseIt 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 | |
| CSharp | >=v2.0.2 | |
| Javascript | >=v2.0.4 | |
| Ruby | >=v1.0.2 | |
| Appium | Python | >=v2.0.4 |
| Java | >=v2.1.1 | |
| CSharp | >=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!