Appium Visual Testing -8(Part-4) : Complete Details On Built-In method — ” .getImagesSimilarity” with SimilarityMatchingOptions- options

“.getImagesSimilarity(File image1,File images2, SimilarityMatchingOptions options)

Watch the video below for your complete step-by-step guide!

In this article, the four in a four-part series, will explore one of Appium’s built-in methods

“.getImagesSimilarity(File image1,File images2, SimilarityMatchingOptions options)

Visual Testing with “.getImagesSimilarity(File image1, File image2, SimilarityMatchingOptions options)"

Introduction

Modern test automation is increasingly moving beyond simple DOM assertions toward visual validation. As UI complexity grows, so does the need to ensure pixel-perfect consistency. For this, image-based comparison APIs are critical. One such API is:

driver.getImagesSimilarity(File image1, File image2, SimilarityMatchingOptions options)

This method provides a flexible and powerful way to visually compare two image files in automated UI testing frameworks like Appium or Selenium enhanced with image comparison plugins.

Method Overview

Signature

SimilarityMatchingResult result = driver.getImagesSimilarity(
    File image1,
    File image2,
    SimilarityMatchingOptions options
);

Parameters

ParameterTypeDescriptionimage1FileThe first image file (typically a screenshot or baseline).image2FileThe second image to compare (e.g., from a current test run).optionsSimilarityMatchingOptionsA configuration object that allows fine-grained control over the comparison (threshold, ignored regions, visualization, etc.).

Return

SimilarityMatchingResult object containing:
score – A floating-point similarity score between 0.0 and 1.0.
status – Pass/fail based on threshold.
visualization – Optional diff image.
rectangles – Coordinates of mismatches (if any).

Step-by-step demonstration of how to use the method “.getImagesSimilarity(File image1, File image2, SimilarityMatchingOptions options)"

Step 1: Capture the Screenshot in file format

//Step 1: Capture the Screenshot in file format
  System.out.println("Step 1: Capture the Screenshot in file format");
  
  FileUtils.copyFile(driver.getScreenshotAs(OutputType.FILE), new File("actual_image"+".png"));
  
  File file1=new File(System.getProperty("user.dir")+"/actual_image.png");
  File file2=new File(System.getProperty("user.dir")+"/Expected_image.png");

Step 2: Create Similarity Options

//Step 2: Create SimilarityMatchingOptions Options
  System.out.println("Step 2: Create SimilarityMatchingOptions Options");
  
  SimilarityMatchingOptions options=new SimilarityMatchingOptions().withEnabledVisualization();

Step 3: Perform the Comparison

//Step 3: Perform the Comparison
  System.out.println("Step 3: Perform the Comparison");
  
  SimilarityMatchingResult result=driver.getImagesSimilarity(file1, file2, options);

Step 4: Calculate the Score & Print the Result

//Step 4: Calculate the Score & Print the Result
  System.out.println("Step 4: Calculate the Score & Print the Result");
  
  System.out.println("Similarity Scrore : "+result.getScore());

Step 5: Generate/Analyze a visual_diff image

//Step 5: Generate/Analyze a visual_diff image
  System.out.println("Step 5: Generate/Analyze a visual_diff image");
  
  if(result.getVisualization()!=null) {
   byte[] vis=Base64.getDecoder().decode(result.getVisualization());
   Files.write(new File("visual_diff.png").toPath(), vis);
  }

Step 6: Run Appium Server with below flags:

The plugin must be explicitly activated when launching the Appium server:

appium - use-plugins=images

“Complete Code: Optimized and Ready to Use”:

package com.appiumguide.appiumvisualTesting;

import org.apache.commons.io.FileUtils;
import org.openqa.selenium.OutputType;
import org.testng.annotations.AfterTest;
import org.testng.annotations.BeforeTest;
import org.testng.annotations.Test;

import io.appium.java_client.android.AndroidDriver;
import io.appium.java_client.android.options.UiAutomator2Options;
import io.appium.java_client.imagecomparison.SimilarityMatchingOptions;
import io.appium.java_client.imagecomparison.SimilarityMatchingResult;
import java.io.File;
import java.io.IOException;
import java.net.*;
import java.nio.file.Files;
import java.time.Duration;
import java.util.Base64;

/**
 * Script Details - Appium-Visual Testing (Part-4): Complete Details On Appium Built-in method "getImagesSimilarity(File image1, File image2, SimilarityMatchingOptions options)"
 * 
 * appium-java-client version: Latest
 * 
 * @author 'Ramesh Kodumuru' for AppiumGuide [appiumguide@gmail.com]
 */

public class GetimagesSimilarity_Demo4 {
 
 private AndroidDriver driver;
 File screenshot;
        
 @BeforeTest
 public void setup() throws MalformedURLException {
  UiAutomator2Options cap=new UiAutomator2Options();
  cap.setPlatformName("android");
  cap.setAutomationName("uiautomator2");
  cap.setDeviceName("Pixel9");  
     
  driver = new AndroidDriver(new URL("http://127.0.0.1:4723"), cap);
  driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(100));
  
 }
 
 @Test
 public void test() throws InterruptedException, IOException {
  
  driver.activateApp("com.wdiodemoapp");
  Thread.sleep(5000);
  
  //Step 1: Capture the Screenshot in file format
  System.out.println("Step 1: Capture the Screenshot in file format");
  
  FileUtils.copyFile(driver.getScreenshotAs(OutputType.FILE), new File("actual_image"+".png"));
  
  File file1=new File(System.getProperty("user.dir")+"/actual_image.png");
  File file2=new File(System.getProperty("user.dir")+"/Expected_image.png");
  
  //Step 2: Create SimilarityMatchingOptions Options
  System.out.println("Step 2: Create SimilarityMatchingOptions Options");
  
  SimilarityMatchingOptions options=new SimilarityMatchingOptions().withEnabledVisualization();
  
  //Step 3: Perform the Comparison
  System.out.println("Step 3: Perform the Comparison");
  
  SimilarityMatchingResult result=driver.getImagesSimilarity(file1, file2, options);
  
  //Step 4: Calculate the Score & Print the Result
  System.out.println("Step 4: Calculate the Score & Print the Result");
  
  System.out.println("Similarity Scrore : "+result.getScore());
  
  //Step 5: Generate/Analyze a visual_diff image
  System.out.println("Step 5: Generate/Analyze a visual_diff image");
  
  if(result.getVisualization()!=null) {
   byte[] vis=Base64.getDecoder().decode(result.getVisualization());
   Files.write(new File("visual_diff.png").toPath(), vis);
  }
  
 }
 
    
  
 @AfterTest
 public void teardown() {
  
  if(driver!=null) {
   driver.quit();
   System.out.println("Test Completed");
  }
  
 }

}

Benefits of File-Based Image Comparison

No need to convert images to Base64.
Simpler integration with screenshot utilities.
Easier storage and retrieval from file system or test artifacts.
Ideal for CI/CD workflows where images are saved per test run.

Limitations

Sensitive to resolution or device pixel ratio differences.
May fail if content changes subtly but acceptably (like font hinting).
Requires consistent capture conditions for reliable results.

Best Practices

Standardize screenshot resolution across test runs.
Use ignored regions to minimize noise.
Set similarity threshold based on real-world tolerances.
Store baseline images in version control or a dedicated artifact repository.
Enable visual diff for easier triage of failures.

Conclusion

The driver.getImagesSimilarity(File image1, File image2, SimilarityMatchingOptions options) method empowers test automation engineers with fine-grained visual validation tools. Whether used for regression testing, cross-platform comparison, or pixel-level verification, it provides a flexible and developer-friendly way to ensure UI fidelity with confidence.

GitHub Link:

GitHub — AppiumGuide/AppiumGuide

Contribute to AppiumGuide/AppiumGuide development by creating an account on GitHub.

github.com

🎬 Explore More! Watch My Latest Videos on YouTube!

One Stop Destination for Endless Appium Knowledge - All in one Place

buttons

Pages