Gradle plugin

Emcee Gradle plugin is a regular jar file that might be downloaded from release page.

Then create libs directory in project's root and put jar file there.

To enable the plugin, add to root build.gradle.kts:

buildscript {
    dependencies {
        classpath(files("libs/emcee-gradle-plugin-<VERSION>-all.jar"))
        // replace <VERSION> by actual Emcee plugin version
        // see latest plugin version here on the release page https://github.com/avito-tech/Emcee/releases
        // example: classpath(files("libs/emcee-gradle-plugin-21.5.0-all.jar"))
    }
}

along with setting plugin's id in build.gradle.kts for Application module:

plugins {
    id("com.android.application")
    id("com.avito.emcee.client")
}

Plugin settings#

The plugin is configured through the properties in project.

Property	Description
`queueBaseUrl`	Address of deployed queue
`testTimeout`	Maximum duration of individual test in seconds. Learn more
`executionTimeout`	Maximum duration of all configurations. Learn more
`artifactory`	Artifactory configuration. Nested properties: user, password, baseUrl, repository, connectionTimeout, readTimeout, writeTimeout. `user` User for Artifactory. Use blank `""` if there is no authorization in Artifactory `password` Password for Artifactory. Use blank `""` if there is no authorization in Artifactory `baseUrl` Address of deployed Artifactory. For instance, `http://<your hostname or ip>:8081/artifactory/`. `repository` Repository to put files in Artifactory `connectionTimeout`, `readTimeout`, `writeTimeout` HTTP client settings for Artifactory.
`job`	A logical unit of work to be processed by a queue. Typically, it is one test run. Nested properties: id, groupId, priority, groupPriority. `id` identifier for job. Use blank `""` to tell Emcee to generate job identifier `groupId` identifier to combine several jobs into groups `priority` priority for the job. The higher this value, the higher the priority of the work being performed. Acceptable values are 0..999 `groupPriority` similarly to `priority` but for group of jobs.
`environment`	A map of environment variables for tests.
`loggerConfiguration`	Logger configuration for plugin. Nested properties: `logLevel` level for logging. Possible values: `verbose`, `debug`, `info`, `warning`, `critical`. `printStackTrace` determines if Emcee should print stack trace, possible values `true` or `false`
`screenRecordConfiguration`	Configuration for screen recording during test execution. `videoRecordStrategy` may be one of `ScreenRecordStrategy.RECORD_ALL, RECORD_NONE, RECORD_ON_FAIL`.
`testRetryConfiguration`	Optional. Configuration to retry failed tests. Nested properties: `mode` to retry (see more below). `retries` count. Available retry modes: `TestRetryMode.RETRY_THROUGH_QUEUE` retries failed tests on other workers `TestRetryMode.RETRY_ON_WORKER` retries failed tests on the same worker By default mode is `TestRetryMode.RETRY_ON_WORKER` with `1` retry
`devices`	A list with devices on which the tests will be run. At least one device should be specified. Find all available api versions and screen resolutions
`testsSplitter`	Strategy to split tests into buckets. Possible values: - `Individual` - the number of buckets will be equal the number of tests - `EquallyDivided` - equal number of tests in each bucket - `TimeWeighted` - equal time of execution for every each bucket - `UnSplit` - all tests will be in one bucket - `fixedBucketSize` - fixed tests count in each bucket
`testRunFeatureTogglesConfiguration`	Enabling additional functional: - `isAllureEnabled` - enables Allure report for tests. Files are searched in default directories, more details about directories look in the documentation Allure Kotlin. Files for the Allure report are created by Allure itself if it is present in the tests - `shouldGenerateJunitReport` - enables Junit report for tests. The report will be in the directory with the rest of other artifacts. By default, all feature toggles are disabled

Take a look on example configuration of the Emcee plugin in Kotlin DSL:

import com.avito.emcee.client.ScreenRecordStrategy
import com.avito.emcee.queue.ScheduleStrategy
import com.avito.emcee.queue.TestRetryMode
import java.time.Duration

plugins {
    id("com.android.application")
    id("com.avito.emcee.client")
}

android {
    //...
}

emcee {
    queueBaseUrl.set("http://<your hostname or ip>:41000/")
    testTimeout.set(Duration.ofMinutes(1))
    artifactory {
        user.set("Set to empty or set username if auth is enabled in Artifactory")
        password.set("Set to empty or set password if auth is enabled in Artifactory")
        baseUrl.set("http://<your hostname or ip>:8081/artifactory/")
        repository.set("emcee-transport")
        connectionTimeout.set(Duration.ofMinutes(1))
        readTimeout.set(Duration.ofMinutes(1))
        writeTimeout.set(Duration.ofMinutes(1))
    }
    job {
        groupId.set("Emcee Android Sample")
        groupPriority.set(1)
        id.set("Set me to empty for auto generation or set your id")
        priority.set(1)
    }
    environment.set(mapOf("ENV_NAME" to "ENV_VALUE"))
    loggerConfiguration {
        logLevel.set("info")
        printStackTrace.set(false)
    }
    screenRecordConfiguration {
        videoRecordStrategy.set(ScreenRecordStrategy.RECORD_ON_FAIL)
    }
    testRetryConfiguration {
        mode.set(TestRetryMode.RETRY_THROUGH_QUEUE)
        retries.set(1)
    }
    testsSplitterStrategy.set(ScheduleStrategy.TestsSplitter.TimeWeighted(60))
    devices {
        addDevice(31)
    }
    testRunFeatureTogglesConfiguration {
        isAllureEnabled.set(true)
        shouldGenerateJunitReport.set(true)
    }
}

Tests filtering#

You can apply filtering to send only necessary tests to the queue.

To do this, you need to register a filter group, give it a name and specify the required filters.

Since Emcee version 21.6.0 the filters have been changed.

For instance, filters before Emcee version 21.6.0:

import com.avito.emcee.client.internal.test_filter.TestFilter.AnnotationFilter
import com.avito.emcee.client.internal.test_filter.TestFilter.ClassNameFilter

emcee {
    // ...
    testsFilters {
        registerFilterGroup(
            name = "group1",
            filters = listOf(
                AnnotationFilter("FlakyTest"),
                AnnotationFilter("LargeTest"),
            )
        )
        registerFilterGroup(
            name = "group2",
            filters = listOf(
                ClassNameFilter("TestClassName")
            )
        )
    }
}

Filters since Emcee version 21.6.0:

import com.avito.emcee.client.internal.test_filter.FilterType
import com.avito.emcee.client.internal.test_filter.TestFilter
import com.avito.emcee.client.internal.test_filter.TestFilters

emcee {
    // ...
    registerFilterGroup(
        name = "group1",
        filters = TestFilters(
            include = listOf(
                TestFilter(type = FilterType.ANNOTATION, values = setOf("FlakyTest", "LargeTest"))
            ),
            // You can exclude tests by filters
            // If you combine with include filters then the result list will contain `include tests' minus 'exclude tests'
            exclude = listOf(
                TestFilter(type = FilterType.ANNOTATION, values = setOf("SkipThisAnnotation"))
            )
        )
    )
    registerFilterGroup(
        name = "group2",
        filters = TestFilters(
            include = listOf(
                TestFilter(FilterType.CLASS, setOf("TestClassName"))
            )
        )
    )
}

You can register several filter groups at once, in which you can combine filters of different types.

To apply filtering add an argument indicating the group name to command:

./gradlew emceeTestDebug --filterGroupName group1

Available filter types#

Before Emcee version 21.6.0:

Filter	Description
`AnnotationFilter`	Filter by tests annotation name. For instance, `Flaky` or `LargeTest`.
`PackageNameFilter`	Filter by package name. For instance, `com.example.specialtest`.
`ClassNameFilter`	Filter by tests class name. For instance, `ExampleInstrumentedTest`.

Since Emcee version 21.6.0:

Filter	Description
`FilterType.ANNOTATION`	Filter by tests annotation name. For instance, `Flaky` or `LargeTest`.
`FilterType.PACKAGE`	Filter by package name. For instance, `com.example.specialtest`.
`FilterType.CLASS`	Filter by tests class name. For instance, `ExampleInstrumentedTest`.
`FilterType.TEST_METHOD`	Filter by tests test name. For instance, `test_name`.

Launching tests using Gradle plugin#

After applying the plugin Gradle will create tasks like emceeTest<BuildVariant>. For example, emceeTestDebug.

To send tests to the queue run the command following way:

./gradlew emceeTestDebug

Instead of Debug there could be your build variant.