Skip to main content

SmartUI App SDK Integration Guide

SmartUI App SDK enables you to perform visual regression testing on your mobile applications using any cloud testing provider. This guide will help you integrate SmartUI App SDK with your existing mobile app testing framework.

Prerequisites​

  • Basic understanding of mobile app testing and Appium
  • Login to TestMu AI SmartUI with your credentials
  • An active subscription plan with valid screenshots limit

Create a SmartUI Project​

The first step is to create a project that will contain all your builds. To create a SmartUI Project:

  1. Go to Projects page
  2. Click on the new project button
  3. Select the platform as CLI for executing your SDK tests
  4. Add name of the project, approvers for the changes found, and tags for filtering
  5. Click on Submit

Steps to Run Your First Test​

Step 1: Add the SmartUI SDK Dependency​

Add the following dependency to your pom.xml file:

<dependency>
    <groupId>io.github.lambdatest</groupId>
    <artifactId>lambdatest-java-sdk</artifactId>
    <version>1.0.8</version>
</dependency>

Step 2: Configure Your Project Token​

You can configure your project token in one of two ways:

  1. Using Environment Variables:
export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"
  1. Directly in the Configuration: You can pass the project token directly in your test configuration as shown in Step 3.

Step 3: Integrate SmartUI in Your Test Script​

Import the required SmartUI class and add the screenshot capture code where needed:


public class YourTestClass {
    @Test
    public void testMethod() {
        // Initialize SmartUI
        SmartUIAppSnapshot SmartUI = new SmartUIAppSnapshot();

        // Configure screenshot settings
        Map<String, String> ssConfig = new HashMap<>();
        // Either use environment variable
        ssConfig.put("projectToken", "your-project-token-here"); // Use this if you are not setting the project token in environment variable
        // ssConfig.put("buildName", "First Build"); // Optional
        ssConfig.put("deviceName", "iPhone 15"); // Required, you can use the variables that you are setting in the cloud capabilities

        ssConfig.put("platform", "iOS"); // Optional,you can use the variables that you are setting in the cloud capabilities

        try {
            // Start SmartUI session
            SmartUI.start(ssConfig);

            // Your test code here
// Your test code here - Example of native app interactions
            driver.findElement(MobileBy.AccessibilityId("username-input")).sendKeys("[email protected]");
            driver.findElement(MobileBy.AccessibilityId("password-input")).sendKeys("password123");

            // Take screenshot of login form
            SmartUI.smartuiAppSnapshot(driver, "Login Form", ssConfig);

            driver.findElement(MobileBy.AccessibilityId("login-button")).click();

            // Wait for home screen to load
            WebDriverWait wait = new WebDriverWait(driver, 10);
            wait.until(ExpectedConditions.presenceOfElementLocated(MobileBy.AccessibilityId("home-screen")));

            // Take screenshot of home screen
            SmartUI.smartuiAppSnapshot(driver, "Home Screen", ssConfig);

            // More test steps...

        } finally {
            // Stop SmartUI session
            SmartUI.stop();
        }
    }
}

Step 4: Execute the Tests​

Run your tests as you normally would with your cloud provider. SmartUI will automatically capture and process the screenshots for visual regression testing.

mvn test

Configuration Options​

Screenshot Configuration Options​

KeyDescriptionRequired
projectTokenYour SmartUI project tokenYes
deviceNameName of the device being testedYes
buildNameCustom name for your buildNo
platformPlatform being tested (iOS/Android)No

Supported Platforms and Devices​

The deviceName and platform parameters in SmartUI App SDK are used as metadata to ensure consistent screenshot comparison across builds. You can use any device name and platform that matches your cloud provider's capabilities:

ssConfig.put("deviceName", "iPhone 15");
ssConfig.put("platform", "iOS");

Important Notes:​

  • It is advised to use the same deviceName and platform combination across builds to compare screenshots of the same device
  • These parameters are metadata tags and don't affect the actual device selection on your cloud provider

Example configurations for different cloud providers:

// For an iOS test on LambdaTest
ssConfig.put("deviceName", "iPhone 12");
ssConfig.put("platform", "iOS");

// For an Android test on BrowserStack
ssConfig.put("deviceName", "Samsung Galaxy S22");
ssConfig.put("platform", "Android");

// For a custom device on any cloud provider
ssConfig.put("deviceName", "Custom Device Name"); // Use the same name consistently
ssConfig.put("platform", "iOS/Android"); // Use the actual platform
note

The device name and platform you specify here are used only for screenshot organization and comparison. The actual device selection is handled by your cloud provider's capabilities configuration.

Region-Based Ignore/Select Functionality for Dynamic Content​

To handle dynamic content like timestamps, usernames, or ads that cause false positives in visual comparisons, SmartUI App SDK supports region-based ignore and select functionality using XPath locators.

You can either:

  • Ignore specific regions during comparison using ignoreBoxes
  • Compare only specific regions using selectBoxes

This feature requires the Gson library for JSON serialization. Add it to your pom.xml if not already present:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

Usage Examples​

1. Ignoring Regions (Recommended for Dynamic Content)​

SmartUIAppSnapshot smartUI = new SmartUIAppSnapshot();

Map<String, String> config = new HashMap<>();
config.put("projectToken", "your-project-token-here");
config.put("deviceName", "Pixel 6");
config.put("fullPage", "true");

// Define XPaths of elements to ignore
List<String> ignoreXpath = Arrays.asList(
    "//*[@text=\"Backpack\"]",
    "//*[@text=\"Onesie\"]",
    "//*[@text=\"PRODUCTS\"]",
    "//*[@text=\"Terms of Service | Privacy Policy\"]"
);

Map<String, Object> ignoreBoxesMap = new HashMap<>();
ignoreBoxesMap.put("xpath", ignoreXpath);

Gson gson = new Gson();
config.put("ignoreBoxes", gson.toJson(ignoreBoxesMap));

smartUI.start(config);
smartUI.smartuiAppSnapshot(driver, "SmartUIAndroid", config);
smartUI.stop();

2. Selecting Specific Regions for Comparison​

// Replace "ignoreBoxes" with "selectBoxes" to compare only specified regions
Map<String, Object> selectBoxesMap = new HashMap<>();
selectBoxesMap.put("xpath", Arrays.asList("//*[@resource-id='primary-content']"));

config.put("selectBoxes", gson.toJson(selectBoxesMap));

Configuration Keys​

KeyTypeDescriptionRequired
ignoreBoxesJSON StringDefines regions to ignore during visual comparison. Accepts XPath locators.No
selectBoxesJSON StringDefines regions to include in visual comparison. Accepts XPath locators.No
Best Practices
  • Use ignoreBoxes for elements that change frequently (e.g., ads, timestamps, user avatars).
  • Use selectBoxes when you want to focus comparison only on critical UI sections.
  • Avoid using both ignoreBoxes and selectBoxes in the same config — they are mutually exclusive.
  • Ensure XPath expressions are unique and stable across test runs.

View SmartUI Results​

After test execution, visit your SmartUI project dashboard to:

  1. View all captured screenshots
  2. Compare against baseline images
  3. Identify visual regressions
  4. Approve or reject changes
  5. Manage baseline images
SmartUI Results

Best Practices​

Screenshot Naming

  • Use descriptive, consistent names for screenshots
  • Include screen/component name in screenshot names
  • Avoid special characters that might cause issues
  • Use consistent naming conventions across your test suite

Example:

SmartUISnapshot.smartuiSnapshot(driver, HomeScreen-Header");
SmartUISnapshot.smartuiSnapshot(driver, "CheckoutScreen-PaymentForm");
Last updated on

Test across 3000+ combinations of browsers, real devices & OS.

Book Demo

Help and Support

Related Articles

On this page