Integration

Requirements

• Android SDK: API 21

Gradle

AppeliumTests SDK can be found in the Appelium Maven repository. Add this line to your build.gradle file to access the Maven repository:

repositories {
    maven { 
        url 'https://maven.appelium.com/release' 
    }
}

To use the AppeliumTests SDK, add this line to your build.gradle file:

androidTestImplementation("com.appelium:appelium-tests:<appelium-tests-version>")

If you use Gradle Version Catalog, the equivalent is:

androidTestImplementation(libs.appelium.tests)

Do not use a release classifier (for example :release@aar or artifact { classifier = 'release' }).

Note

If your app also integrates Firebase and you get duplicate com.google.protobuf classes, apply a scoped exclusion on this dependency:

androidTestImplementation("com.appelium:appelium-tests:<appelium-tests-version>") {
    exclude group: "com.google.protobuf", module: "protobuf-javalite"
}

Version Catalog equivalent:

androidTestImplementation(libs.appelium.tests) {
    exclude group: "com.google.protobuf", module: "protobuf-javalite"
}

For full context and guidance for the feedback and okhttp-v4 dependencies, see Troubleshooting.

Usage

Since the UI Tests on Android are not a self-contained app, they don't have such an obvious entry point for doing initialization as using an Application class.

To workaround this limitation, you can create a base test class and initialize AppeliumTests in init.

Info

The AppeliumTests is built to accept only the first initialization call will, therefore it is safe to have multiple subclasses of BaseTest without worrying about creating many instances of AppeliumTests.

open class BaseTest {

    @Rule
    @JvmField
    val appeliumTestWatcher = AppeliumTestWatcher()

    init {
        AppeliumTests.Builder(apiKey = <#api key#>).build()

        // Optionally set the name and/or the version of the backend environment
        AppeliumTests.setTestExecutionEnvironment(name = "STAGING", version = "2.4.0")

        // Optionally set the name of the test plan (for example: Complete, Smokes, PR etc.)
        AppeliumTests.testPlanName = "Complete"
    }

}

You can create a new app token or find an existing one here.

Tests execution on multiple devices in parallel or using Test Orchestrator

Info

If you are running your UI tests in parallel on a single device or not using Test Orchestrator, you can skip this part - there is nothing more you need to set up.

If you are running tests on multiple devices or if each test is part of its own test execution, you would need to pass a UUID into your tests and then forward it to AppeliumTests.Builder. The UUID will then be used for grouping all tests together into one execution. The UUID can be generated in your Gradle scripts and then passed into your test as build config.

AppeliumTests.Builder(apiKey = <#api key#>)
    .setTestExecutionUuid(uuid = BuildConfig.getTestExecutionUuid())
    .build()

Direct Links to Test Execution

You can leverage the UUID described above for generating direct URLs to your test executions.

Using the uuid variable from the code snippet above, and WORKSPACE_NAME which you can find by navigating to your home page on Dashboard (the path component after https://dashboard.appelium.com ), you can construct the following URL:

https://dashboard.appelium.com/${WORKSPACE_NAME}/resolve?testsCorrelationUuid=${UUID}