Skip to main content

Native Mobile Library

Introduction​

Many mobile test frameworks, such as Appium, XCUI, Espresso, and WebDriver IO, have a number of limitations that prevent them from taking full-page screenshots of native applications. The Applitools Native Mobile Library utilizes sophisticated algorithms to overcome these limitations and produce a full page screenshot of your application to validate it.

Prerequisites​

Before using Native Mobile Library, you need to instrument your application. You can do this dynamically if the application is already compiled, as part of an automatic build process, or statically if you have access to the source code.

iOS​

Dynamically instrument your application with the Applitools Native Mobile Library​

note

This option is recommended and is suitable if you need to add the library to an app that has already been compiled. Every 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. Add execution permissions to applitoolsify:

    chmod +x applitoolsify

  3. Run one of the following commands as suitable for your operating system:

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

  4. If you are running on a local real device, you need to re-sign the app. For details, see Re-signing the App.
    This step is not required if your target is a simulator or a real device in the cloud.

Statically compile the Applitools Native Mobile Library with your application​

  1. Download the Applitools Native Mobile Library: https://sdksstorage.blob.core.windows.net/mobile/ios/nml/framework/release/Applitools_iOS.xcframework.zip

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

  3. In the Xcode target settings, under Frameworks, Libraries, and Embedded Content, tap + and select Applitools_iOS.xcframework.

  4. Embed and sign.

  5. Build and run the app.

  6. In the console, verify that Applitools_iOS loaded appears at launch

Re-signing the App​

If you are running on a local real device, after instrumenting the app you need to re-sign the app. To do this you 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 the IOS App Signer from https://dantheman827.github.io/ios-app-signer/

  2. Install and open IOS App Signer.

    Signer

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

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

Android​

Dynamically instrument your application with the Applitools Native Mobile Library​

  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. Add execution permissions to applitoolsify:
    chmod +x applitoolsify

  3. Run one of the following commands as suitable for your operating system:

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

Statically compile the Applitools Native Mobile Library with your application​

  1. In the build.gradle file (app level), add the following dependency: Implementation 'com.applitools:applitools-android:+'

  2. Make sure you have Internet Permissions in the manifest.xml.

  3. In all Launcher activities add:
    import com.applitools.android.ApplitoolsMobile;

  4. Inside the onCreate() function add:
    ApplitoolsMobile.init(this);

Testing with Applitools Native Mobile Library​

Before the app is launched, in your test suite you need to configure the Applitools Native Mobile Library one time before the driver creation. Use the Eyes.setMobileCapabilities static method and pass your driver capabilities, Applitools apiKey, Applitools ServerUrl, and Proxy as parameters.

The Applitools library must be loaded when the app starts, and cannot be loaded into an already running app. Therefore, when using Appium, do not use the following capabilities, unless you know that the Applitools library was already loaded into the app:

  • autoRelunch=false
  • noReset=true
  • fullReset=false
DesiredCapabilities caps = new DesiredCapabilities();
Eyes.setMobileCapabilities (caps, apiKey, serverUrl = optional, proxy = optional)

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

To take a full page screenshot, use the following code:

eyes.check(Target.Window())

Taking a System Screenshot​

There are some rare cases where the test flow is outside of the application context, and therefore the Applitools Native Mobile Library cannot take a full page screenshot. To overcome this, use the useSystemScreenshot method and the SDK will take the screenshot instead:

eyes.check(Target.Window()).useSystemScreenshot()