Appium Visual Testing -6(Part-2) : Complete Details On Built-In method —” .getImagesSimilarity” with ‘SimilarityMatchingOptions’

.getImagesSimilarity(byte[] base64image1, byte[] base64image2, SimilarityMatchingOptions options)

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

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

.getImagesSimilarity(byte[] base64image1, byte[] base64image2, SimilarityMatchingOptions options)

Deep Dive into ".getImagesSimilarity(byte[ ] base64image1, byte[ ] base64image2, SimilarityMatchingOptions options)"

Introduction

In modern test automation, visual validation is gaining prominence due to the need for pixel-perfect UI verification across different platforms and devices. Tools like Appium support image-based comparison to ensure UI integrity, particularly when DOM-based assertions aren’t sufficient. One such powerful method is:

driver.getImagesSimilarity(byte[] base64image1, byte[] base64image2, SimilarityMatchingOptions options)

This method enables flexible and configurable image comparison by leveraging an additional SimilarityMatchingOptions parameter to fine-tune the matching behavior.

Method Signature Overview

Syntax

SimilarityMatchingResult result = driver.getImagesSimilarity(
    byte[] base64image1,
    byte[] base64image2,
    SimilarityMatchingOptions options
);

Parameters

ParameterTypeDescriptionbase64image1byte[]First image in Base64-encoded byte array form.base64image2byte[]Second image to compare.optionsSimilarityMatchingOptionsObject to specify tolerance, match threshold, and more.

Returns

• SimilarityMatchingResult: Contains detailed results of the image comparison including:
• score: Similarity value (typically between 0.0 and 1.0).
• rectangles: Areas where mismatches were found.
• visualization: Optional diff image for debugging.
• status: Match pass/fail based on the defined threshold.

Step-by-step demonstration of how to use the method .getImagesSimilarity(byte[ ] base64image1, byte[ ] base64image2, SimilarityMatchingOptions options)

Step 1: Capture the Screenshot

Step 2: Covert the file to base64image

Step 3: Create Similarity Options

Step 4: Perform the Comparison

Step 5: Print the Result

Step 6: Visualize the difference

Step 7: 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-2): Complete Details On .getImagesSimilarity(byte[] base64image1, byte[] base64Image2,SimilarityMatchingOptions options)
 * 
 * appium-java-client version: Latest
 * 
 * @author 'Ramesh Kodumuru' for AppiumGuide [appiumguide@gmail.com]
 */


public class GetImagesSimilarity_Demo2 {
 
 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 {
  
  //Launch thw wdiodemo app
  driver.activateApp("com.wdiodemoapp");
  Thread.sleep(5000);
  
  //Step 1: Capture the Screenshot
  System.out.println("Step 1: Capture the Screenshot");
  
  FileUtils.copyFile(driver.getScreenshotAs(OutputType.FILE), new File("actual_image"+".png"));
  Thread.sleep(5000);
  
  //Step 2: Convert the file to base64image
  System.out.println("Step 2: Convert the file to base64image");
  byte[] img1Bytes=Files.readAllBytes(new File(System.getProperty("user.dir")+"/actual_image.png").toPath());
  byte[] img2Bytes=Files.readAllBytes(new File(System.getProperty("user.dir")+"/Expected_image.png").toPath());
  
  byte[] base64Image1=Base64.getEncoder().encode(img1Bytes);
  byte[] base64Image2=Base64.getEncoder().encode(img2Bytes);
  
  //Step 3: Create SimilarityMatchingOptions
  System.out.println("Step 3: Create SimilarityMatchingOptions");
  
  SimilarityMatchingOptions options=new SimilarityMatchingOptions().withEnabledVisualization();
  
  //Step 4: Perform the Comparison
  System.out.println("Step 4: Perform the Comparison");
  
  SimilarityMatchingResult result=driver.getImagesSimilarity(base64Image1, base64Image2, options);
  Thread.sleep(5000);
  
  //Step 5: Print the Result
  System.out.println("Step 5: Print the Result");
  
  System.out.println("Similarity Score - : "+result.getScore());
  
  //Step 6: Visualize the difference 
  System.out.println("Step 6: Visualize the difference");
  
  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");
  }
  
 }

}

Best Practices

• Normalize resolution before comparison.
• Use ROI and ignored regions to reduce false negatives.
• Set a realistic threshold based on your UI consistency expectations.
• Enable visual diff during debugging.

Conclusion

The driver.getImagesSimilarity(byte[] base64image1, byte[] base64image2, SimilarityMatchingOptions options) method is a robust feature for visual validation in test automation frameworks. It allows you to go beyond simple image comparison, giving you control over accuracy, tolerance, and analysis depth. This makes it a vital tool for maintaining visual quality across test runs.

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!

AppiumGuide

📌 Step-by-Step Appium Tutorial for Beginners & Experts with Practical Examples 👍 ✅ Learn Appium from Scratch with…

www.youtube.com