Native Mobile Library

Introduction

The Applitools Native Mobile Library (NML) uses advanced algorithms to generate full-page screenshots of native mobile applications for validation by Eyes SDKs.

NML is embedded within the application code and captures screenshots directly from inside the application. It automatically handles scrolling when needed, ensuring an accurate screenshot without stitching issues. Additionally, system elements like the system clock or battery indicator are excluded from the image.

To use NML, you must link it with the application code. This can be done statically if you have direct access to the source code or dynamically if the application is already compiled.

Benefits of Native Mobile Library

When taking images of an application on a mobile device, NML has the following benefits:

• Runs inside the app – Since NML is integrated into the application itself, it can capture what’s on the screen without interference from system UI elements like the clock or battery indicator.

• Handles scrolling automatically – When a screen is longer than the viewport, NML scrolls and captures the full content seamlessly, avoiding common issues with stitching multiple images together.

• Efficient and accurate – Because NML operates from within the app, it avoids distortions or inconsistencies that might arise from taking screenshots externally (e.g., from a test automation framework).

NML supports UIKit & SwiftUI for iOS and AndroidX for Android compiled applications.

Setting up NML

To work with NML, you need to do the following:

1. Instrument your application – There is a separate process for iOS and Android devices. There are two ways to instrument the application:

   • Static – Inside the application before it is compiled
   • Dynamic – After the application has been compiled.

2. Set Eyes SDK in the Test Code Environment – For details see the Quickstart section of the relevant SDK.

3. Configure the SDK to use NML in your test code – This is done with the setMobileCapabilities method inside your test code. See Configure the SDK to use NML in your Test Code

Instrument your application on iOS

If you are testing with an SDK that supports iOS (Appium or XCUI) you can instrument the application using one of the following methods:

• Static - If you have access to the code before the application is compiled, you can statically instrument the application before it is compiled. There are two ways to instrument the application statically:

  • Using Swift Package Manager (SwiftPM)
  • Using a manual process

• Dynamic - If you do not have access to the application before it is compiled.

Static - Using Swift Package Manager

1. In Xcode, select File > Add Packages...

2. Enter the following URL:
   https://github.com/applitools/ios-applitools-framework-swift-package.git

3. Click Add Package, then click Add Package in the Choose Package dialog box.

   

4. Build and run the app.

5. Verify in the console that Applitools_iOS <version> loaded appears at launch.

6. The Applitools iOS framework is always used in conjunction with the Applitools Eyes SDK for visual and UI testing. As of Xcode 16, Swift Package Manager does not support conditionally adding package dependencies for specific configurations. To exclude this framework from production builds (e.g., App Store release builds):

   info

   This is important to make sure the package is only used for testing purposes and not in the production build.

   1. In Xcode, select your application target then click the Build Settings tab.

   2. Under Build Options > Excluded Source File Names, select your production configuration (e.g. "Release"), then click the +.

   3. Type Applitools* then press ENTER.

   4. Build and run your iOS application for a Release configuration.

   5. Verify that Applitools_iOS <version> loaded does not appear in the Console log.

Static - Manually Adding the Framework

1. Download the Applitools Native Mobile Library

2. In the Xcode Project Navigator, add the file Applitools_iOS.xcframework.

3. In the Xcode target settings, under Frameworks, Libraries, and Embedded Content, click + and select Applitools_iOS.xcframework. Make sure that the configuration does not target an App Store release.

4. Set the framework to Embed & Sign.

5. Build and run the app.

6. Verify in the console that Applitools_iOS <version> loaded appears at launch.

Dynamic

Use this option if you need to add the library to an already compiled app. Each time you run this option, the latest version of the library is installed.

1. Download the required applitoolsify instrumentation:

   • applitoolsify-ios-Linux-x86_64
   • applitoolsify-ios-macos-arm64
   • applitoolsify-ios-macos-x86_64
   • applitoolsify-ios-win-x86_64.exe

2. If running on macOS or Linux, add execution permissions to applitoolsify:

   chmod +x <downloaded_file_name>

   On macOS, if you have permission issues, run the following:

   xattr -d com.apple.quarantine <applitooslfiy_path>

3. Run one of the following commands, depending on your operating system:

   • ./applitoolsify-ios-Linux-x86_64 <app/ipa file path>
   • ./applitoolsify-ios-macos-arm64 <app/ipa file path>
   • ./applitoolsify-ios-macos-x86_64 <app/ipa file path>
   • ./applitoolsify-ios-win-x86_64.exe <app/ipa file path>

   Optional Flag:

   • --local - If specified, use the local bundled NML library. Default is to fetch the latest NML library from the internet (requires internet connection)

4. If you are running on a local real device, re-sign the app. To do this, you will need a signing certificate and provisioning profile. Re-signing is not required if your target is a simulator or a real device in the cloud.

   1. Download iOS App Signer

   2. Install and open iOS App Signer.

   3. Click Browse and navigate to the app you are testing.

   4. Enter the signing certificate and provisioning profile, then click Start.

Instrument your application on Android

If you are testing with an SDK that supports Android (Appium or Espresso) and have access to the code before the application is compiled, you can statically instrument the application before it is compiled. If you do not have access the application before it is compiled, you can dynamically instrument the application.

Static

Use this option if you have access to the code before it is compiled.

1. In the build.gradle file (app level), add the following dependency:

   implementation 'com.applitools:applitools-android:+'

2. Ensure that Internet Permissions are included in the AndroidManifest.xml.

3. For all launcher activities, add the following import:

   import com.applitools.android.ApplitoolsMobile;

4. Inside the onCreate() function, add the initialization:

   ApplitoolsMobile.init(this);

Dynamic

Use this option if you need to add the library to an already compiled app. Each time you run this option, the latest version of the library is installed.

1. Download the applitoolsify instrumentation tool:

   • applitoolsify-android-Linux-x86_64
   • applitoolsify-android-macos-arm64
   • applitoolsify-android-macos-x86_64
   • applitoolsify-android-win-x86_64.exe

2. If running on macOS or Linux, add execution permissions to applitoolsify:

   chmod +x <downloaded_file_name>

   On macOS, if you have permission issues, run the following:

   xattr -d com.apple.quarantine <applitooslfiy_path>

3. Run one of the following commands, depending on your operating system:

   • ./applitoolsify-android-Linux-x86_64 <apk file path>
   • ./applitoolsify-android-macos-arm64 <apk file path>
   • ./applitoolsify-android-macos-x86_64 <apk file path>
   • ./applitoolsify-android-win-x86_64.exe <apk file path>

   Optional Flag:

   • --local - If specified, use the local bundled NML library. Default is to fetch the latest NML library from the internet (requires internet connection)

4. Install the instrumented app.

   info

   If a previous version of your app has been installed, you need to uninstall it before installing the instrumented app to prevent an INSTALL_FAILED_UPDATE_INCOMPATIBLE error.

Configure the SDK to use NML in your Test Code

Once NML has been instrumented in the application code, you need to import the SDK into the test code. The Applitools library must be loaded when the app starts; it cannot be loaded into an already running app.

info

Before launching the app, you must configure the Applitools Native Mobile Library in your test suite before creating a driver.

If you use the public cloud, ignore the serverUrl parameter.

Running a Test with NML

Once you have instrumented NML in your application code, and imported the SDK into the Test code, you can run a test with NML using eyes.check

Taking a System Screenshot​

If you need to take a system screenshot which includes elements outside the application window, for example a system permissions alert, you can take the screenshot outside the regular NML functionality using the useSystemScreenshot method.

If the test flow occurs outside the application context, for example the Applitools Native Mobile Library cannot capture a full-page screenshot. To address this, use the useSystemScreenshot method to have the SDK take the screenshot instead:

Adding Multi-Devices

The multi-device testing feature lets you capture multiple checkpoints across different devices originating from a single checkpoint. This makes visually testing your application much easier and faster by expanding your test coverage more efficiently.

The multi-device target feature is a premium feature that needs to be enabled on your account. Please contact your sales or customer success representative to learn more.

info

This feature is available for iOS applications built with UIKit. SwiftUI and AndroidX capabilities are coming soon!

The devices you configure in your test must have the same iOS version as the device or simulator executing your tests. All devices supported in the Ultrafast Grid are supported. For a list of supported devices, see Ultrafast Grid - Supported Browsers and Devices

Use the configuration setting below to configure the devices you want to use for your testing.