AI visual comparison (FR)

Perfecto command

perfecto:ai:visual-comparison

Purpose

Use the perfecto:ai:visual-comparison command in Appium, Selenium, or Quantum tests while running tests on real and virtual Perfecto mobile devices. Tablets and web browsers are not supported.

To learn more about working with AI-powered validations, see the following resources:

To have this functionality set up in your cloud, contact your Perfecto account representative. A separate license is required to access this feature.

Parameters

Name Type Possible Values Description

baselineId

String

A baseline name

Screenshots of a previous, named run are used as the baseline for the comparison with the checkpoints created during later runs. Choose a name for the baseline indicating the screen being compared.

failCriteria

List

device

value

style

missing

addition

moved

error

uncategorized

pixelDifference

 

Select at least one or multiple values to determine which visual differences in the checkpoint fail the test when compared to the baseline. All criteria are analyzed, but only the ones you list in the parameter fail the test.

  • Device - Signal strength, battery level, time of the day

  • Style - Text style, font, text size, color, alignment, borders, shading

  • Value - Text content or numeric values

  • Missing - UI element is absent

  • Moved - UI element is present but in a different position

  • Addition - A new UI element has appeared

  • Error - Error message, UI elements cut off or overlapping

  • Uncategorized - Differences detected but they are not in any of the categories.

  • Pixel difference - No meaningful differences detected, just common anti-aliasing, image compression, or image scaling artifacts
Typically, you do not include device and pixelDifference as failure criteria, because they trigger almost always.

Examples

Copy

JavaScript

const rawResponse = await driver.executeScript(
"perfecto:ai:visual-comparison",
    {
        args: {
            baselineId: "baseline26/3-2",
                failCriteria: [
                "addition",
                "moved",
                "style",
                "error",
                "uncategorized",
                "pixelDifference",
                "missing",
                "value",
                "device"
                ]
        }
    }
);

const response = rawResponse;
const comparisonExecutedSuccessfully = response.success;
const message = response.message;
const differences = response.differences;

let shouldCommandFail = false;
if (differences != null) {
    shouldCommandFail = differences.some(d => d.fail === true);
}

console.log("Command status = " + (shouldCommandFail ? "FAIL" : "PASS"));

 

Copy
Java
Object rawResponse = driver.executeScript(
    "perfecto:ai:visual-comparison",
        Map.of( "args", Map.of(
            "baselineId", 
            "baseline26/3-2",
            "failCriteria", 
            List.of(
                "addition",
                "moved",
                "style",
                "error",
                "uncategorized",
                "pixelDifference",
                "missing",
                "value",
                "device"
            )
        )
    )
);
//response extraction
Map<String, Object> response = (Map<String, Object>) rawResponse; 

boolean comparisonExecutedSuccessfully = (Boolean) response.get("success"); 
String message = (String) response.get("message");
List<Map<String, Object>> differences =
    (List<Map<String, Object>>) response.get("differences");

boolean shouldCommandFail = false;
if (differences != null) {
    shouldCommandFail = differences.stream()
    .anyMatch(d -> Boolean.TRUE.equals(d.get("fail")));
}

System.out.println("Command status = " + (shouldCommandFail ? "FAIL" : "PASS"));

Return value

True or False

Comparison succeeded – Command FAIL

{
	"success": true,
	"message": "Comparison completed successfully",
	"differences": [
		{
			"type": "VALUE",
			"explanation": "Button text changed from 'Pay now' to 'Proceed to payment'",
			"fail": true
		},
		{
			"type": "STYLE",
			"explanation": "Color of header changed slightly",
			"fail": false
		}
	]
}

2) Comparison succeeded – Command PASS

{
	"success": true,
	"message": "Comparison completed successfully",
	"differences": [
		{
			"type": "VALUE",
			"explanation": "Button text changed from 'Pay now' to 'Proceed to payment'",
			"fail": false
		},
		{
			"type": "STYLE",
			"explanation": "Color of header changed slightly",
			"fail": false
		}
	]
}

Comparison failure

{
	"success": false,
	"message": "Comparison failed <for some technical reason>"
}

Test failure

A test fails if a visual difference to the baseline has been detected in at least one chosen category. Use the following statement to determine a failure:

boolean shouldFail = differences.stream().anyMatch(d -> (Boolean) d.get("fail"));

Exceptions

The following message appears when your cloud does not have the consent to use AI:

Failed to execute command ai:visual-comparison: Unexpected error occurred while processing command 'ai:visual-comparison'. Error message: AI commands are disabled. To use these commands, contact your administrator. Status: Forbidden