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:

Percy Web
Percy with Automate

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.

Copy

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

```shell
{
    "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"
        }
    ]
}
```

Copy

Error response

Copy

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:

Copy

It does not function alongside the defer-uploads configuration.

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.

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() method.

Enable synchronous comparison results during screenshot capture by setting the sync parameter to true.

Copy

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

Copy

Error response

Copy

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:

Copy

It does not function alongside the defer-uploads configuration.

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.

Did this page help you?

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!