DEV Community: Yang

FlowBinding 1.0

Yang — Thu, 24 Dec 2020 07:48:18 +0000

It's been over a year since the initial release of FlowBinding.

Over the last year we've added 4 new artifacts for AndroidX libraries, dropped our minimum SDK all the way back to API 14, introduced a new InitialValueFlow API for widgets that emit state changes, and new API docs.

Today I'm excited share the 1.0 stable release of FlowBinding!

What's new

While the majority of the APIs have remained the same since the first public release (original blogpost) last year, we've made a decent amount of improvements to the library over the last 14 months.

New artifacts

Our focus has been on providing bindings for flowbinding-material which is where most of the new UI widgets are being developed, but we also added 4 new artifacts for AndroidX libraries:

flowbinding-activity - provides binding on OnBackPressedDispatcher from AndroidX Activity
flowbinding-lifecycle - turns lifecycle change events from AndroidX Lifecycle into Flow<Lifecycle.Event>
flowbinding-preference - provides bindings for Preference and EditTextPreference from AndroidX Preference (Settings)
flowbinding-viewpager - backports bindings from flowbinding-viewpager2 for the legacy androidx.viewpager.widget.ViewPager artifact.

Min SDK 14

Originally the minSdkVersion FlowBinding required was API 21. While this is reasonable for most users, support for lower API levels remains essential for users who are developing for emerging markets (see this tweet for more context).

We've now dropped our minSdkVersion to API 14.

Initial value

For UI widgets that hold a state internally such as the current value of a Slider (a recently added Material Component), our bindings used to provide an optional emitImmediately: Boolean to indicate whether the current value should be emitted immediately when collected:

@CheckResult
@UseExperimental(ExperimentalCoroutinesApi::class)
fun Slider.valueChanges(emitImmediately: Boolean = false): Flow<Float> = callbackFlow {
...
}

The default value of emitImmediately was false which not everyone agrees.

After discussions within the community we've decided to introduce a new InitialValueFlow for the bindings that emit state changes (many thanks to Sven Jacobs for the idea).

An InitialValueFlow emits the current value (state) of the widget immediately upon collection of the Flow.

This effectively changed the previous default value of emitImmediately from false to true, but communicates the behavior more clearly in the type itself.

To skip the initial emission of the current value, call the skipInitialValue() function on the InitialValueFlow:

slider.valueChanges()
    .skipInitialValue()
    .onEach { value ->
        // handle value
    }
    .launchIn(uiScope) // current value won't be emitted immediately

This is also consistent with RxBinding's InitialValueObservable.

New API Docs

FlowBinding has many artifacts and APIs. We now have a new project website that documents all transitive AndroidX dependencies and the bindings available in each artifact, along with new API docs powered by Dokka 1.4.

What's next?

Jetpack Compose is clearly the future of UI development for Android, while FlowBinding specifically targets the current generation of UI toolkits, which isn't going away anytime soon. The material-components-android library is still being actively developed with many new view-based components being added or planned.

Therefore we're planning to continue the work on maintaining AndroidX bindings and adding bindings for the new Material Design Components (e.g. TimePicker) as they become available.

Thanks!

I'd like to thank everyone who has used FlowBinding, reported bugs, made feature requests, participated in discussions or sent PRs in the last 14 months, which all contributed to what we've achieved with the library today!

Git-based Android App Versioning with AGP 4.0

Yang — Fri, 11 Sep 2020 11:27:37 +0000

An Android app has 2 pieces of version information:

versionCode - a positive integer used as an internal version number of the app that needs to monotonically increase with each subsequent release.
versionName - a string as a version number shown to users.

To automate the process of generating the versionCode and versionName for an app release, a common approach is to compute these values from Git tags:

android {
  defaultConfig {
    versionCode buildVersionCode()
    versionName buildVersionName()
  }
}

The buildVersionCode() and buildVersionName() need to execute a command-line process to fetch the git information (e.g. latest tag), parse it and generate the versionCode and versionName required:

def buildVersionCode = {
  try {
    def stdout = new ByteArrayOutputStream()
      exec {
        commandLine 'git', 'describe', '--tags'
        standardOutput = code
      }
      // computeVersionCodeFromTag(tag) might use a formula such as MAJOR * 10000 + MINOR * 100 + PATCH for SemVer tags.
      return computeVersionCodeFromTag(stdout.toString().trim())
  } catch (ignored) {
    return -1
  }
}

def buildVersionName = {
  try {
      def stdout = new ByteArrayOutputStream()
      exec {
          commandLine 'git', 'describe', '--tags'
          standardOutput = stdout
      }
      return stdout.toString().trim()
  } catch (ignored) {
    return null
  }
}

The main issue here is that we are doing computation during configuration of the build which is extremely inefficient as buildVersionCode and buildVersionName are executed every time a project is configured (e.g. every Gradle sync from the IDE, or just running ./gradlew help), whereas in practice the versionCode and versionName are only required when assembling an APK or AAB.

While Gradle has been pushing for Lazy Task Configuration and Task Configuration Avoidance for a couple of years now, the Android Gradle Plugin (AGP) had not migrated some of the most important APIs to support Gradle properties and providers until very recently. Thus there wasn't an easy way to avoid computing versionCode and versionName during configuration (here's a workaround provided by the AGP team back at IO 19).

This issue was finally addressed in AGP 4.0 with the introduction of 2 new APIs for configuring the build variants early in the configuration phase: onVariants and onVariantsProperties. Here's the skeleton for generating versionCode and versionName in a Gradle task from the official Android Plugin for Gradle cookbook.

Android App Versioning Gradle Plugin

A few months ago while working on automating the release process at work, I decided to take a closer look at the new onVariantProperties API and move the version info computation logic to a proper Gradle task. The initial prototype was developed in streamlined and had received some interests from the community.

After adding support for customizing versionCode and versionName with a lambda and simplifying the plugin configurations, today I’m happy to share App Versioning - a Gradle Plugin for lazily generating Android app's versionCode & versionName from Git tags.

How it works

Let's start by applying the plugin to the app module:

plugins {
    id("com.android.application")
    id("io.github.reactivecircus.app-versioning") version "x.y.z"
}

Note that the samples in the post are written with Gradle Kotlin DSL but traditional Groovy DSL is also fully supported.

At this point if your repository has a Git tag that follows Semantic Versioning, app-versioning will start generating versionCode and versionName for your APK / AAB!

Let's imagine the latest tag in your current branch is 1.3.1. Assembling the APK with ./gradlew assembleRelease will trigger a generateAppVersionInfoForRelease task which generates both the versionCode and versionName for the assembled APK:

> Task :app:generateAppVersionInfoForRelease
Generated app version code: 10301.
Generated app version name: "1.3.1".

The generated versionCode and versionName are injected into the merged manifest at app/build/intermediates/merged_manifests/release/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="io.github.reactivecircus.streamlined"
    android:versionCode="10301"
    android:versionName="1.3.1" >
...
</manifest>

Default rules

Without providing any configurations, app-versioning will fetch the latest Git tag in the repository, attempt to parse it into a SemVer string, and compute the versionCode following positional notation:

versionCode = MAJOR * 10000 + MINOR * 100 + PATCH

So for the tag 1.3.1, the generated versionCode is 1 * 10000 + 3 * 100 + 1 = 10301.

The versionName generated will just be the name of the latest Git tag (1.3.1 in the example above).

If the default rules described above work for you, you are now ready to enjoy automated version info generation without further configurations! But chances are you might want to tweak the formula used for generating versionCode, or inject additional metadata into the versionCode and/or versionName to fit your existing process and workflow:

Instead of reserving 2 digits for each of the MAJOR, MINOR, and PATCH components, you might want to use a smaller or bigger range.
You might want to add an additional BUILD_NUMBER from CI to the versionCode or versionName.
You might need to include the commit hash in the versionName.

With that in mind, let's now take a look at how these custom rules can be specified with a couple of plugin configurations.

Custom rules

To maximize the supported use cases without introducing too many configurations, app-versioning lets you define how you want to compute the versionCode and versionName by implementing lambdas which are evaluated lazily during execution:

appVersioning {

  overrideVersionCode { gitTag, providers ->
    // TODO generate an Int from the given gitTag and/or providers
  }

  overrideVersionName { gitTag, providers ->
    // TODO generate a String from the given gitTag and/or providers
  }
}

GitTag is a type-safe representation of a tag encapsulating the rawTagName, commitsSinceLatestTag and commitHash, provided by the plugin.

providers is a ProviderFactory instance which is a Gradle API that can be useful for reading environment variables and system properties lazily.

SemVer-based version code

As mentioned earlier the plugin by default reserves 2 digits for each of the MAJOR, MINOR and PATCH components in a SemVer tag.

To allocate 3 digits per component instead (i.e. each version component can go up to 999):

import io.github.reactivecircus.appversioning.toSemVer
appVersioning {
  overrideVersionCode { gitTag, providers ->
    val semVer = gitTag.toSemVer()
    semVer.major * 1000000 + semVer.minor * 1000 + semVer.patch
  }
}

toSemVer() is an extension function (or SemVer.fromGitTag(gitTag) if you use Groovy) provided by the plugin to help create a type-safe SemVer object from the GitTag by parsing its rawTagName field.

If a Git tag is not fully SemVer compliant (e.g. 1.2), calling gitTag.toSemVer() will throw an exception. In that case we'll need to find another way to compute the versionCode.

Using timestamp for version code

Since the key characteristic for versionCode is that it must monotonically increase with each app release, a common approach is to use the Epoch / Unix timestamp for versionCode:

import java.time.Instant
appVersioning {
  overrideVersionCode { _, _ ->
    Instant.now().epochSecond.toInt()
  }
}

This will generate a monotonically increasing version code every time the generateAppVersionInfoFor<BuildVariant> task is run:

Generated app version code: 1599750437.

Using environment variable

Another common practice when computing version code is to add a BUILD_NUMBER environment variable provided by CI to the formula. To do this, we can use the providers lambda parameter to create a provider that's only queried during execution:

import io.github.reactivecircus.appversioning.toSemVer
appVersioning {
  overrideVersionCode { gitTag, providers ->
    val buildNumber = providers
        .environmentVariable("BUILD_NUMBER")
        .getOrElse("0").toInt()
    val semVer = gitTag.toSemVer()
    semVer.major * 10000 + semVer.minor * 100 + semVer.patch + buildNumber
  }
}

versionName can be customized with the same approach:

import io.github.reactivecircus.appversioning.toSemVer
appVersioning {
  overrideVersionName { gitTag, providers ->
    // a custom versionName combining the tag name, commitHash and an environment variable
    val buildNumber = providers
        .environmentVariable("BUILD_NUMBER")
        .getOrElse("0").toInt()
    "${gitTag.rawTagName} - #$buildNumber (${gitTag.commitHash})"
  }
}

Custom version name generated:

Generated app version name: "1.3.1 - #345 (f0b6056)".

App versioning on CI

Release APKs are usually built on CI, where the build configurations and host environment are likely to be different from a local dev environment. There are a couple of things worth noting when using the app-versioning plugin on CI.

Enable the plugin only when necessary

For performance reason many CI providers only fetch a single commit by default when checking out the repository. For app-versioning to work we need to make sure Git tags are also fetched. Here's an example for doing this with GutHub Actions:

- uses: actions/checkout@v2
  with:
    fetch-depth: 0

CI jobs such as unit tests and Lint usually do not require a versionCode to be present in the merged AndroidManifest to complete. If these CI jobs are sharded such that they run in separate VMs in parallel, we can disable the app-versioning plugin and not worry about telling the CI to fetch those additional Git tags when checking out.

To do this we can define an environment variable ENABLE_APP_VERSIONING and set it to false to indicate that no versionCode or versionName need to be generated by the app-versioning plugin for this job:

unit-tests:
  name: Unit tests
  runs-on: ubuntu-latest
  env:
    ENABLE_APP_VERSIONING: false

We can then enable / disable the plugin based on the value of the environment variable:

val enableAppVersioning = providers
  .environmentVariable("ENABLE_APP_VERSIONING")
  .forUseAtConfigurationTime()
  .getOrElse("true").toString().toBoolean()

appVersioning {
  enabled.set(enableAppVersioning)
  ...
}

Note that we need to use the experimental forUseAtConfigurationTime() API to create a configuration time provider.

Retrieving the generated version code and version name

There are cases where you may need to retrieve the versionCode and versionName of a generated APK / AAB:

including the version code and version name in a Slack message sent from CI after a successful build
communicating with a 3rd party service where version code and version name need to be included in the request (e.g. uploading R8 mapping file to a crashing reporting service)

Both the versionCode and versionName generated by app-versioning are in the build output directory:

app/build/outputs/app_versioning/<buildVariant>/version_code.txt
app/build/outputs/app_versioning/<buildVariant>/version_name.txt

We can cat the output of these files into variables:

VERSION_CODE=$(cat app/build/outputs/app_versioning/<buildVariant>/version_code.txt)
VERSION_NAME=$(cat app/build/outputs/app_versioning/<buildVariant>/version_name.txt)

Note that if you need to query these files in a different VM than where the APK (and its version info) was originally generated, you need to make sure these files are "carried over" from the original VM. Otherwise you'll need to run the generateAppVersionInfoFor<BuildVariant> task again to generate these files, but the generated version info might not be the same as what's actually used for the APK (e.g. if you use the Epoch timestamp for versionCode).

Here's an example with GitHub Actions that does the following:

in the Assemble job, build the App Bundle and archive / upload the build outputs directory which include the AAB and its R8 mapping file, along with the version_code.txt and version_name.txt files generated by app-versioning.
later in the Publish to Play Store job, download the previously archived build outputs directory, cat the content of version_code.txt and version_name.txt into variables, upload the R8 mapping file to Bugsnag API with curl and passing the retrieved $VERSION_CODE and $VERSION_NAME as parameters, and finally upload the AAB to Play Store (without building the AAB or generating the app version info again).

Lazy, incremental, cacheable

By moving version info generation to a Gradle task, we're finally able to avoid doing computation during Gradle's task configuration phase.

We can take this further by making the generateAppInfoFor<BuildVariant> task incremental and cacheable.

To do this the plugin tracks the .git/refs directory as a task input, so the task only becomes "dirty" and re-runs when there are changes to the Git references in the repository e.g. adding new commits or tags.

Task is executed with the first run:

./gradlew generateAppVersionInfoForProdRelease
...
BUILD SUCCESSFUL in 3s
1 actionable task: 1 executed

Task is up-to-date with the subsequent run:

./gradlew generateAppVersionInfoForProdRelease
...
BUILD SUCCESSFUL in 1s
1 actionable task: 1 up-to-date

Task output is loaded from build cache (Gradle build cache needs to be enabled) after cleaning the project level build directory and running the task again:

./gradlew clean
./gradlew generateAppVersionInfoForProdRelease
...
BUILD SUCCESSFUL in 1s
1 actionable task: 1 from cache

What's next

Customizing version code and version name has become easier and faster thanks to the new APIs introduced in Android Gradle Plugin 4.x. The Android App Versioning Gradle Plugin builds on top of these APIs to specifically improve the experience for app versioning use cases based on Git.

Instructions for installing, configuring and using the plugin are available on GitHub.

Please give it a try and share your feedback as we work towards the stable release!

References:

Testing Kotlin Lambda Invocations without Mocking

Yang — Fri, 07 Feb 2020 09:38:49 +0000

In this post I want to share a simple technique for verifying the invocation of a Kotlin lambda function without mocking it.

Let's imagine we have a class for loading data:

class DataLoader {
    ....

    fun load(query: String, fetcher: (String) -> Data): Data {
        return findCachedData(query) ?: fetcher(query).also { fetchedData ->
            cacheData(query, fetchedData)
        }
    }
}


data class Data(val result: String)

fun findCachedData(query: String): Data? {....}
fun cacheData(query: String, data: Data) {....}

When consumer calls the load function, Data from the cache will be returned immediately if cached entry can be found for the given query, otherwise the fetcher function provided by the user will be invoked with its result being cached.

val data1 = dataLoader.load("a") { query ->
    // this should be invoked the first time
    api.fetchDataByQuery(query)
}

val data2 = dataLoader.load("a") { query ->
    // this should NOT be invoked the second time as cached Data is available
    api.fetchDataByQuery(query)
}

Since the execution of the fetcher might be expensive, we want to make sure it's only invoked when no Data is available in the cache for the given query.

How do we test this behavior?

Mocks

Mocking is a common way to help verify that the code under test has (or has not) interacted with a dependency.

We can mock the (String) -> Data lambda expression as if it's an interface, and verify whether the invoke(...) function has been invoked.

Here's how our test might look like with mockito-kotlin:

private val dataLoader = DataLoader(...)

private val testData = Data("result")

@Test
fun `fetcher is not executed when data associated with the query exists in cache`() {
    val mockFetcher = mock<(String) -> Data> {
        on { invoke(any()) }.doReturn(testData)
    }

    dataLoader.load("query", mockFetcher)

    // fetcher should be invoked the first time
    verify(mockFetcher, times(1)).invoke(any())

    clearInvocations(mockFetcher)

    dataLoader.load("query", mockFetcher)

    // fetcher should NOT be invoked for the same query the second time
    verify(mockFetcher, times(0)).invoke(any())
}

Here's what we've done to test the behavior mentioned earlier:

Create a mock of the type (String) -> Data.
Stub the invoke(query: String): Data function and return a testData (the actual value is not important in this test).
Call dataLoader.load("query", mockFetcher) for the first time.
Verify that the invoke(query: String): Data function on the mockFetcher was invoked exactly 1 time, as no existing data associated with query exists in the cache yet.
Clear any previous recorded invocations on the mockFetcher to avoid stubbing again.
Call dataLoader.load("query", mockFetcher) for the second time.
Verify that the invoke(query: String): Data function on the mockFetcher was NOT invoked this time as cached Data for the query exists.

The same test looks similar with MockK:

private val dataLoader = DataLoader(...)

private val testData = Data("result")

@Test
fun `fetcher is not executed when data associated with the query exists in cache`() {
    val mockFetcher = mockk<(String) -> Data>()
    every { mockFetcher.invoke(any()) } returns testData

    dataLoader.load("query", mockFetcher)

    // fetcher should be invoked the first time
    verify(exactly = 1) { mockFetcher(any()) }

    clearMocks(mockFetcher)

    dataLoader.load("query", mockFetcher)

    // fetcher should NOT be invoked for the same query the second time
    verify(exactly = 1) { mockFetcher(any()) }
}

Fakes

The approach above seems reasonable, but having to use mocks in unit tests is usually a code smell.

The necessity to use mocks in unit tests is often caused by tight coupling between the unit under test and its dependencies. For example, when a class directly depends on a type from a third-party library or something that does IO operation, unit testing the class without mocking means the tests will likely be indeterministic and slow - the opposite of what we want with unit tests.

However, mocking comes with costs:

Mocking adds noise and cognitive load, especially when there are multiple / nested mocks that need to be stubbed in subtle ways to setup the specific test scenarios.
Mocking can make refactoring harder as tests with mocks verify both the external behavior and the internal workings of the class under test, coupling test code and production code.
Relying on a mocking framework for testing discourages developers from following good design principles such as dependency inversion.

As such we generally want to avoid using mocks in unit tests and only use them sparingly in higher-level integration tests when necessary.

Now if we look at the fetcher lambda again, there's nothing complex or indeterministic about its implementation that requires mocking. In fact, the implementation is always provided by the call-side as a trailing lambda:

dataLoader.load("a") {
    // perform any side-effects...
    ....
    // return data
    Data("result")
}

Mocking the fetcher here provides no benefit aside from being able to verify the invocation using the mocking framework.

We can easily achieve the same with a Fake implementation of the lambda:

private val dataLoader = DataLoader(...)

private val testData = Data("result")

@Test
fun `fetcher is not executed when data associated with the query exists in cache`() {
    var invokeCount = 0
    val testFetcher = { _: String ->
        invokeCount++
        testData
    }

    dataLoader.load("query", testFetcher)

    assertThat(invokeCount).isEqualTo(1)

    dataLoader.load("query", testFetcher)

    // invokeCount should NOT increment
    assertThat(invokeCount).isEqualTo(1)
}

Instead of mocking the fetcher: (String) -> Data lambda, we track the number of invocations with a invokeCount variable that gets incremented whenever the fetcher lambda is invoked. Now we're able to verify the lambda invocations with regular assertions.

The testFetcher implementation records the number of invocations on the lambda and returns a Data. This looks like something we want to reuse in multiple tests.

We need a TestFetcher class with a var for tracking the invocation count, but since the fetcher parameter is a Kotlin function type rather than a regular interface with a fun fetch(query: String): Data, what super type should this class implement?

It turns out that a class can implement a function type just like a regular interface:

class TestFetcher(val expectedData: Data) : (String) -> Data {
    var invokeCount = 0

    override fun invoke(query: String): Data {
        invokeCount++
        return expectedData
    }
}

With this fake fetcher implementation in place, our test has now become:

private val dataLoader = DataLoader(...)

private val testData = Data("result")

@Test
fun `fetcher is not executed when data associated with the query exists in cache`() {
    val testFetcher = TestFetcher(expectedData = testData)

    dataLoader.load("query", testFetcher)

    assertThat(testFetcher.invokeCount).isEqualTo(1)

    dataLoader.load("query", testFetcher)

    // invokeCount should NOT increment
    assertThat(testFetcher.invokeCount).isEqualTo(1)
}

We can also implement a different Fetcher that throws an exception:

class FailedTestFetcher(val expectedException: Exception) : (String) -> Data {
    var invokeCount = 0

    override fun invoke(query: String): Data {
        invokeCount++
        throw expectedException
    }
}

Now we can test that an exception thrown by the fetcher is propagated to the call-side:

private val dataLoader = DataLoader(...)

@Test
fun `fetcher exception is propagated`() {
    val testFetcher = FailedTestFetcher(expectedException = IOException())

    assertThrows(IOException::class.java) {
        dataLoader.load("query", testFetcher)
    }

    assertThat(testFetcher.invokeCount).isEqualTo(1)
}

Note that currently suspend function is not allowed as super types but this will be supported in the upcoming Kotlin 1.4.

// doesn't compile
class Fetcher : suspend (String) -> Data { 
    override suspend fun invoke(query: String): Data = ....
}

A real-world example

I recently wrote a new in-memory caching library for dropbox/store. One of the supported features is cache loader which is an API for getting cached value by key and using the provided loader: () -> Value lambda to compute and cache the value automatically if none exists.

interface Cache<in Key : Any, Value : Any> {
....
    /**
     * Returns the value associated with [key] in this cache if exists,
     * otherwise gets the value by invoking [loader], associates the value with [key] in the cache,
     * and returns the cached value.
     *
     * Note that [loader] is executed on the caller's thread. When called from multiple threads
     * concurrently, if an unexpired value for the [key] is present by the time the [loader] returns
     * the new value, the existing value won't be replaced by the new value.
     * Instead the existing value will be returned.
     *
     * Any exceptions thrown by the [loader] will be propagated to the caller of this function.
     */
    fun get(key: Key, loader: () -> Value): Value
....
}

This is similar to our DataLoader example above. We can verify the loader lambda invocations with the same approach:

@Test
fun `get(key, loader) returns existing value when an unexpired entry with the associated key exists before executing the loader`() {
    val cache = Cache.Builder.newBuilder()
        .expireAfterAccess(expiryDuration, TimeUnit.NANOSECONDS)
        .build<Long, String>()

    cache.put(1, "dog")

    // create a new `() -> Value` lambda
    val loader = createLoader("cat")

    val value = cache.get(1, loader)

    // loader should not have been invoked as "dog" is already in the cache.
    assertThat(loader.invokeCount)
        .isEqualTo(0)

    assertThat(value)
        .isEqualTo("dog")
}

To support adding different variants of fake Loader implementation for some of the more complex concurrency tests, we have a TestLoader class that takes val block: () -> Value as a constructor parameter, and a bunch of top-level functions for creating different Loader implementations for different needs.

private class TestLoader<Value>(private val block: () -> Value) : () -> Value {
    var invokeCount = 0
    override operator fun invoke(): Value {
        invokeCount++
        return block()
    }
}

// a regular loader that returns computed value immediately
private fun <Value> createLoader(computedValue: Value) =
    TestLoader { computedValue }

// a loader that throws an exception immediately
private fun createFailingLoader(exception: Exception) =
    TestLoader { throw exception }

// a loader that takes certain duration (virtual) to execute and return the computed value
private fun <Value> createSlowLoader(
    computedValue: Value,
    executionTime: Long
) = TestLoader {
    runBlocking { delay(executionTime) }
    computedValue
}

The complete test suite can be found here.

Summary

I hope you find this technique useful! Here's the TLDR:

You don't need help from a mocking framework for testing Kotlin lambda invocations - it's easy to track the invocation count in the lambda implementation provided
You don't need to wrap a function inside an interface to be able to provide a fake implementation in tests - a class can implement a function type directly just like implementing a regular interface.

Thanks to Eyal Guthmann for suggesting the use of invocation counter in my cache rewrite PR which inspired me to write this article.

Featured in Kotlin Weekly #185 and Android Weekly #401.

Exploring Cirrus CI for Android

Yang — Mon, 23 Dec 2019 13:05:06 +0000

I recently wrote about my experience using various cloud-based CI services for running Android instrumented tests on CI for opensource projects, and how I landed on a solution using a custom GitHub Action.

As mentioned in that article, most cloud-based CI providers today don't have KVM enabled in the host VMs which is required for running hardware-accelerated x86 / x86_64 emulators in a docker environment.

I recently came across Cirrus CI, a less-known cloud-based CI provider with native KVM support and it's completely free for opensource projects. Despite having a positive experience with GitHub Workflow using my custom android-emulator-runner action that runs on macOS VMs, I was keen to try out KVM-enabled containers provided by Cirrus CI as I'd still be more comfortable with a solution based on a standard Linux/docker environment which Google has been putting more effort into recently.

In this article I'm going to share some of my experiences with Cirrus CI - specifically, how I migrated FlowBinding's instrumented tests from GitHub Action to Cirrus CI task, along with some of the features provided by Cirrus CI you might find useful for Android in general.

Cirrus CI Overview

Cirrus CI doesn't have a fancy product / marketing website like some of the other providers such as CircleCI. The main entry point is cirrus-ci.org which covers feature descriptions, pricing information, examples, and comprehensive documentations.

Features

A list of features can be found here. For Android (and opensource projects in particular) some of the more interesting ones are:

Free for opensource projects (public repositories on GitHub)
Provides Linux, Windows, macOS and FreeBSD containers
Provides KVM-enabled containers
Containers on community clusters (free plans) can use a maximum of 8.0 CPUs and up to 24 GB of memory
Supports local and remote build cache
Supports build matrix

Here's a comparison with other CI services found on Cirrus CI's website:

Pricing

Cirrus CI's pricing models can be found here.

As mentioned before, Cirrus CI is free for public repositories. There is a per-user concurrency limit of 8 Linux VMs, but this is quite generous for a free plan and should be more than enough for most projects.

Commercial plans for private repositories are available at $10/seat/month which is again quite affordable compared to some of the other more popular services, but for my projects I haven't needed to upgrade.

Installation

Cirrus CI currently only supports repositories hosted on GitHub. To get started, go to the Cirrus CI Application on GitHub Marketplace and setup a plan for your account or organization.

That's basically all you need to do to setup Cirrus CI for a project. Everything else (except a couple of security options) is configured in a .cirrus.yml file in your project's root directory.

Writing CI Tasks

Task(s) are the building block of a .cirrus.yml configuration file. A task defines a sequence of instructions to run and the environment to execute these instructions in. The equivalent concepts of tasks and instructions in GitHub Actions are jobs and steps respectively. Here's a simple task that assembles a debug APK:

assemble_task:
  container:
    image: reactivecircus/android-sdk:latest
  assemble_script:
    ./gradlew assembleDebug

Tasks in .cirrus.yml have the task suffix. In this case assemble_task is the only task we define in the config.

Script is one of the supported instructions. Similarly scripts need to have the script suffix e.g. assemble_script.

container is a field where we can define the docker image used for the task. reactivecircus/android-sdk is a docker image with the minimum Android SDK components required for building Android projects.

A comprehensive guide for writing tasks can be found here.

It's worth noting that code completion support from IntelliJ IDEA / Android Studio is available when writing .cirrus.yml, thanks to the YMAL plugin bundled in the IDE and the supported schema store.

Dashboard

Cirrus CI's build dashboard is hosted at cirrus-ci.com. Once logged in with your GitHub account you'll see a list of builds for all your projects using Cirrus CI. Individual tasks and build results are available for each build.

While the UIs don't look as pretty as some of the more popular products, overall I found them effective and responsive.

Running Instrumented Tests

Now let's look at how we can write a task that runs Android instrumented tests on hardware-accelerated emulators.

We'll start by converting the following GitHub workflow that uses the android-emulator-runner action for running instrumented tests on macOS:

jobs:
  test:
    runs-on: macOS-latest
    steps:
    - name: checkout
      uses: actions/checkout@v2

    - name: run tests
      uses: reactivecircus/android-emulator-runner@v2
      with:
        api-level: 28
        arch: x86_64
        target: default
        emulator-options: -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim
        script: ./gradlew connectedDebugAndroidTest

Converted task in .cirrus.yml:

connected_check_task:
  name: Run Android instrumented tests
  only_if: $CIRRUS_BRANCH == "master" || CIRRUS_PR != ""
  env:
    API_LEVEL: 28
    TARGET: default
    ARCH: x86_64
  container:
    image: reactivecircus/android-emulator-28:latest
    kvm: true
    cpu: 8
    memory: 24G
  create_device_script:
    echo no | avdmanager create avd --force --name "api-${API_LEVEL}" --abi "${TARGET}/${ARCH}" --package "system-images;android-${API_LEVEL};${TARGET};${ARCH}"
  start_emulator_background_script:
    $ANDROID_HOME/emulator/emulator -avd "api-${API_LEVEL}" -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim -camera-back none
  wait_for_emulator_script:
    adb wait-for-device shell 'while [[ -z $(getprop sys.boot_completed) ]]; do sleep 3; done; input keyevent 82'
  disable_animations_script: |
    adb shell settings put global window_animation_scale 0.0
    adb shell settings put global transition_animation_scale 0.0
    adb shell settings put global animator_duration_scale 0.0
  run_instrumented_tests_script:
    ./gradlew connectedDebugAndroidTest

name is a field where we can define a custom name for the task.

only_if is a keyword that controls whether the task should be executed. $CIRRUS_BRANCH == "master" || CIRRUS_PR != "" here means we only want to run this task on commits on the master branch or any pull request.

Environment variables can be specified in the env block. Here we are only specifying the configurations of the system image used for creating the emulator. Other common environment variables such as JAVA_TOOL_OPTIONS or GRADLE_OPTS can also be specified here.

container defines the host VM used for running the task and its configurations. We use reactivecircus/android-emulator-28 as the docker image which has the minimum SDK components for running hardware-accelerated emulator on API 28.

The most interesting bit here is kvm: true where we enable KVM for the container to take advantage of native virtualization when running the modern x86 / x86_64 emulators.

We've also given the container the maximum amount of CPU (8) and memory (24G) as the container will be running an Android Emulator instance as well as Gradle commands, both of which are known to be processor and memory intensive.

create_device_script and wait_for_emulator_script create a new AVD instance, launch an Emulator, and wait until it's fully booted and ready for use. These are not needed in the GitHub workflow as they are taken care of by the android-emulator-runner Github Action.

We then add the disable_animations_script to disable the global animations on the emulator. This is again run by default when using the android-emulator-runner GitHub Action.

Finally in the run_instrumented_script we define the Gradle task for running all Android tests in all modules.

Here's the build summary for FlowBinding which has 160 tests across 10 modules:

The build took ~20 mins which is almost identical to the GitHub Actions equivalence. Note that there's an extra 1-2 mins of scheduling period for KVM-enabled containers due to the additional virtualization layer.

Build matrix

With GitHub Actions we can leverage build matrix to run the tests across multiple API levels:

jobs:
  test:
    runs-on: macOS-latest
    strategy:
      matrix:
        api-level: [21, 22, 23, 24, 25, 26, 27, 28]
    steps:
    - name: checkout
      uses: actions/checkout@v2

    - name: run tests
      uses: reactivecircus/android-emulator-runner@v2
      with:
        api-level: ${{ matrix.api-level }}
        script: ./gradlew connectedDebugAndroidTest

We can do the same with Cirrus CI using matrix modification:

connected_check_task:
  name: Run Android instrumented tests (API $API_LEVEL)
  only_if: $CIRRUS_BRANCH == "master" || CIRRUS_PR != ""
  env:
    matrix:
      - API_LEVEL: 21
      - API_LEVEL: 22
      - API_LEVEL: 23
      - API_LEVEL: 24
      - API_LEVEL: 25
      - API_LEVEL: 26
      - API_LEVEL: 27
      - API_LEVEL: 28
  container:
    image: reactivecircus/android-emulator-${API_LEVEL}:latest
    kvm: true
    cpu: 8
    memory: 24G
...

We've defined a matrix of API_LEVEL values so the same connected_check_task will be executed for each of these values. Note that we are able to specify the name of the docker image dynamically because these images are named in the same reactivecircus/android-emulator-${API_LEVEL} pattern. The repository for these images can be found here (all x86 images for API 21 and above are available).

With GitHub Actions you can exclude some of the configurations generated by the build matrix. This is not currently supported by Cirrus CI.

Build cache (local)

Many Gradle tasks are incremental and cacheable, which can significantly improve build times.

The local Gradle build cache is located at ~/.gradle/cache and we are able to get fast incremental builds on CI when tasks outputs are available in this directory.

With CircleCI saving and restoring the local Gradle cache directory is easy:

jobs:
  build:
    executor: android
    steps:
      - checkout
      - restore_cache:
          key: gradle-{{ checksum "buildSrc/dependencies.gradle" }}-{{ checksum "gradle/wrapper/gradle-wrapper.properties" }}
      - run:
          name: Assemble
          command: ./gradlew assemble
      - save_cache:
          key: gradle-{{ checksum "buildSrc/dependencies.gradle" }}-{{ checksum "gradle/wrapper/gradle-wrapper.properties" }}
          paths:
            - ~/.gradle/cache

The cache will only be invalidated when buildSrc/dependencies.gradle or gradle/wrapper/gradle-wrapper.properties changes which is usually when we update our library dependencies or Gradle version. By doing this we can avoid re-downloading all the dependencies on each build on CI.

Cirrus CI also provides a similar cache instruction that works similarly:

connected_check_task:
  name: Run Android instrumented tests
  only_if: $CIRRUS_BRANCH == "master" || CIRRUS_PR != ""
  env:
    API_LEVEL: 28
    TARGET: default
    ARCH: x86_64
  container:
    image: reactivecircus/android-emulator-28:latest
    kvm: true
    cpu: 8
    memory: 24G
  gradle_cache:
    folder: ~/.gradle/caches
    fingerprint_script: cat buildSrc/dependencies.gradle && cat gradle/wrapper/gradle-wrapper.properties
  ...
  cleanup_script:
    - rm -rf ~/.gradle/caches/[0-9].*
    - rm -rf ~/.gradle/caches/transforms-1
    - rm -rf ~/.gradle/caches/journal-1
    - rm -rf ~/.gradle/caches/jars-3/*/buildSrc.jar
    - find ~/.gradle/caches/ -name "*.lock" -type f -delete

The Cirrus CI doc recommends using a technique for avoiding re-upload of the cache when the build outputs are unchanged - adding a cleanup_script that removes the non-deterministic files generated on each build at the end of the task. This improvement is based on the expectation that re-generating these non-deterministic files and always executing a few tasks on every build has much less impact than uploading hundred of Mb of the cache files on every build.

But there's one area where CircleCI performs significantly better - the time taken for downloading and uploading these cache archives.

For roughly 500Mb of cache archive, with CircleCI it only takes about 15 seconds to download (restore) it, and 25 seconds to upload it.

With Cirrus CI, downloading ~500Mb of cache archive takes nearly 1 minute while uploading takes over 1 minute.

Build cache (remote)

Gradle also has built-in support for HTTP remote build cache which works similarly as a local build cache except the build outputs come from a remote server rather than the local ~/.gradle/cache directory.

Cirrus CI is the first CI service I've used that provides native support for Gradle's remote HTTP build cache. This can be configured by adding the following to your settings.gradle file:

ext.isCiServer = System.getenv().containsKey("CIRRUS_CI")
ext.isMasterBranch = System.getenv()["CIRRUS_BRANCH"] == "master"
ext.buildCacheHost = System.getenv().getOrDefault("CIRRUS_HTTP_CACHE_HOST", "localhost:12321")

buildCache {
  local {
    enabled = !isCiServer
  }
  remote(HttpBuildCache) {
    url = "http://${buildCacheHost}/"
    enabled = isCiServer
    push = isMasterBranch
  }
}

Note that if your project uses the buildSrc directory, the build cache configuration should also be applied to buildSrc/settings.gradle. This can be done by putting the build cache configuration above into a separate gradle/buildCacheSettings.gradle file and applying it to both settings.gradle and buildSrc/settings.gradle.

Optimizing script execution order

Before looking at the final build time improvement, let's take a look at a technique for optimizing your CI pipeline when running instrumented tests on an Emulator.

Here's a visualization of our current connected_check_task:

We create a new AVD instance, launch an Emulator in the background, wait until the Emulator is fully booted, and finally run the ./gradlew connectedDebugAndroidTest task.

Is there anything else we could be doing while waiting for the Emulator to come online (usually takes about 1 minute)?

As mentioned earlier many Gradle tasks are incremental, this means that once a task has been executed, its outputs will be stored in the build directory within the sub-project (module) and running the same task again (without changing its inputs) won't actually execute the task itself. Instead the outputs of the task will be immediately loaded from the build directory.

The assemble<BuildVariant>AndroidTest task that generates the test APKs is incremental.

Let's first run it locally with no build cache:

./gradlew clean assembleDebugAndroidTest --no-build-cache
...
BUILD SUCCESSFUL in 59s
936 actionable tasks: 934 executed, 2 up-to-date

The build took about 1 minute with 934 out of 936 tasks executed.

If we run it again without cleaning the build directory:

./gradlew assembleDebugAndroidTest
...
BUILD SUCCESSFUL in 3s
914 actionable tasks: 914 up-to-date

The build completes in 3 seconds and no tasks were executed as they are all up-to-date.

Now since the connectedDebugAndroidTest Gradle task we run at the end effectively depends on the assembleDebugAndroidTest task for generating the test APKs, by first running the assembleDebugAndroidTest task explicitly while waiting for the Emulator to boot, the connectedDebugAndroidTest task will be significantly faster as all of its sub-tasks would be up-to-date at that point.

Final result

Here's the final .cirrus.yml file:

connected_check_task:
  name: Run Android instrumented tests (API $API_LEVEL)
  timeout_in: 30m
  only_if: $CIRRUS_BRANCH == "master" || CIRRUS_PR != ""
  env:
    matrix:
      - API_LEVEL: 21
      - API_LEVEL: 22
      - API_LEVEL: 23
      - API_LEVEL: 24
      - API_LEVEL: 25
      - API_LEVEL: 26
      - API_LEVEL: 27
      - API_LEVEL: 28
    JAVA_TOOL_OPTIONS: -Xmx6g
    GRADLE_OPTS: -Dorg.gradle.daemon=false -Dkotlin.incremental=false -Dkotlin.compiler.execution.strategy=in-process
  container:
    image: reactivecircus/android-emulator-${API_LEVEL}:latest
    kvm: true
    cpu: 8
    memory: 24G
  create_device_script:
    echo no | avdmanager create avd --force --name "api-${API_LEVEL}" --abi "${TARGET}/${ARCH}" --package "system-images;android-${API_LEVEL};${TARGET};${ARCH}"
  start_emulator_background_script:
    $ANDROID_HOME/emulator/emulator -avd "api-${API_LEVEL}" -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim -camera-back none
  assemble_instrumented_tests_script:
    ./gradlew assembleDebugAndroidTest
  wait_for_emulator_script:
    adb wait-for-device shell 'while [[ -z $(getprop sys.boot_completed) ]]; do sleep 3; done; input keyevent 82'
  disable_animations_script: |
    adb shell settings put global window_animation_scale 0.0
    adb shell settings put global transition_animation_scale 0.0
    adb shell settings put global animator_duration_scale 0.0
  run_instrumented_tests_script:
    ./gradlew connectedDebugAndroidTest

With remote build cache enabled, I managed to cut the build time to ~15 mins for FlowBinding. This is a significant improvement compared to the ~20 mins build time with GitHub Actions (mostly due to the unlimited build cache provided by Cirrus CI).

Other Features

After having a positive experience migrating the instrumented tests to run on Cirrus CI, I decided to explore some of the other features provided by the service and see how they work in broader Android CI use cases.

Task dependency

By default all tasks defined in .cirrus.yml run in parallel. Task execution dependencies can be configured by using the depends_on keyword. In the following example, the publish_artifacts_task will only be executed after both the assemble_task and connected_check_task have completed successfully.

assemble_task:
  ...

connected_check_task:
  ...

publish_artifacts_task:
  depends_on:
    - assemble
    - connected_check
  deploy_snapshot_script:
    ...

Encrypted secrets

Sometimes a CI task might need access to some secrets. For example, building a release APK may require the encryption key for the release keystore, while publishing a library to Maven Central requires the Sonatype Nexus credentials.

Cirrus CI supports encrypted variables which can be safely added to the .cirrus.yml file.

To use a secret in a CI task, go to the Cirrus CI settings page and follow the instruction to generate the encrypted variable:

Then add the generated ENCRYPTED[xxx] as a regular environment variable in the env block of a task:

publish_artifacts_task:
  depends_on:
    - assemble_and_check
    - connected_check
  env:
    SONATYPE_NEXUS_USERNAME: ENCRYPTED[abcd]
    SONATYPE_NEXUS_PASSWORD: ENCRYPTED[1234]
  container:
    image: reactivecircus/android-sdk:latest
  deploy_snapshot_script:
    ./gradlew clean androidSourcesJar androidJavadocsJar uploadArchives --no-daemon --no-parallel

Artifacts

Cirrus CI supports storing build artifacts and making them available for download from the dashboard via the artifacts instruction. The following example produces the JUnit XML artifacts for the unit_tests_task:

unit_tests_task:
  container:
    image: reactivecircus/android-sdk:latest
    cpu: 8
    memory: 24G
  unit_test_script:
    ./gradlew test
  always:
    junit_artifacts:
      path: "**/test-results/**/*.xml"
      type: text/xml
      format: junit

Conditionally skipping builds

Sometimes you may want to skip a CI task if the there's no change in the source code (e.g. changing the README.md file). For example we might want to only run the connected_check_task if there are changes to the Kotlin, XML or Gradle sources in the commit or pull request. This can be implemented with the skip keyword and the changesInclude function:

connected_check_task:
  only_if: $CIRRUS_BRANCH == "master" || CIRRUS_PR != ""
  skip: "!changesInclude('.cirrus.yml', '*.gradle', '*.gradle.kts', '**/*.gradle', '**/*.gradle.kts', '*.properties', '**/*.properties', '**/*.kt', '**/*.xml')"
  ...

Note that this is also supported by GitHub Actions via the path filters.

Manual trigger

A task can also be triggered manually from the Cirrus CI dashboard or the GitHub Checks page. This is often useful in deployment (e.g. publishing a new APK) where we need to be able to control when to trigger the task.

Manual task can be configured by adding trigger_type: manual to the task:

publish_artifacts_task:
  trigger_type: manual
  depends_on:
    - assemble_and_check
    - connected_check
  ...

Delayed execution - Required PR Labels

Tasks such as instrumented tests require special execution environment and have a longer feedback cycle, which make them more expensive to run. Therefore when a new PR is created we might want to run the fast checks (assemble and unit tests) immediately, and only trigger the expensive checks after an initial review.

Cirrus CI provides a feature called Required PR Labels. Tasks can specify a list of required_pr_labels to only get triggered once these labels have been added to the pull request.

In the following example the connected_check_task will only be run after the initial-review label has been added to the pull request.

connected_check_task:
  required_pr_labels: initial-review
  only_if: $CIRRUS_BRANCH == "master" || CIRRUS_PR != ""
  ...

On the GitHub Checks page, tasks which are waiting for PR labels are considered "neutral":

To trigger these tasks, apply the required initial-review label to the PR:

The connected_check_task will now be triggered.

Build notification

A major feature missing from Cirrus CI is notification. When a build fails, the status will be reflected on the GitHub Checks page, but Cirrus CI doesn't have built-in mechanism for sending an Email notification.

This can be worked around by adding a GitHub Action that sends emails when a GitHub Check Suite completes, but you'll need to provide your own SMTP server information.

Cirrus CI Android Templates

If you've made it this far, chances are you want to try out Cirrus CI for your own projects. To help you get started, I've created some cirrusci-android-templates for common use cases such as building APKs, running instrumented tests, and publishing library artifacts.

Summary

Overall I have been really impressed with Cirrus CI. I was initially attracted by the KVM-enabled containers for running instrumented tests. Not only was I able to migrate FlowBinding to use Cirrus CI for running instrumented tests, it was also a lot of fun discovering and trying a few other cool features along the way.

It's clear that the Cirrus CI Team understands the unique challenges when it comes to doing CI for Android. Having used quite a few CI solutions for Android including Jenkins, Buddybuild, Buildkite, CircleCI, Bitrise, and GitHub Actions, I'd like to highlight some of the key competitive advantages Cirrus CI brings to the table and why you might want to consider using it for Android:

Excellent documentations and examples
Completely free for opensource projects with very generous concurrency limit
KVM-enabled containers for running hardware-accelerated Emulators
Powerful VMs - up to 8.0 CPUs and 24 GB of RAM for Linux containers
Built-in support for Gradle build cache (both local and remote)
First-class GitHub integration with features such as Required PR Labels

There are also a few things that could use some improvements:

Being a smaller player in the market means less efforts have been put into marketing, branding, and UX of the product especially the build dashboard
Downloading and uploading cache archives takes noticeably longer than some of the other services
Currently only GitHub is supported, although BitBucket support is planed
There's no built-in support for Email notifications

None of these was a deal breaker for running instrumented tests. But due to the slower download and upload speeds for build cache, I have yet to migrate the rest my CI pipelines from CircleCI.

What's Next

Cirrus Lab (the team behind Cirrus CI) recently announced Cirrus Emulators, a cloud service that provides hardware-accelerated Android Emulators which can be integrated with any CI services using a CLI. I'll share my experience with it once the product is publicly available.

Thanks for reading!

Thanks to Fedor Korotkov for the review.

Running Android Instrumented Tests on CI - from Bitrise.io to GitHub Actions

Yang — Sun, 24 Nov 2019 09:36:00 +0000

It's almost 2020 and it remains a challenge to run Android Instrumented tests on CI, especially for opensource projects and small teams:

Setting up and managing an in-house device farm is expensive and requires long-term investment and on-going infrastructure support - not a viable option for most teams.
Cloud-based device farms such as Firebase Test Lab are a much more cost-effective solution for most teams as they take care of managing the infrastructure while offering simple APIs for integrating with existing CI pipelines. However, for opensource projects with a large amount of tests, free plans offered by these services likely won't cover the needs, while paying for such service is usually hard to justify for an opensource effort.
For small teams who are not quite ready to invest in a fully-fledged cloud-based testing service, running tests on the Android Emulator within a docker container has been the most viable and common approach. But today most cloud-based CI services are still lacking hardware acceleration support from the host VM, which is the no.1 blocker for running tests on modern Android Emulators (especially on recent API levels) on CI.

I recently released FlowBinding which has over 160 instrumented tests across 10 library modules. I wanted to be able to run all these tests on each PR / merge into master without worrying about things like usage limits and quotas. So Firebase Test Lab is not an option as the free plan has a daily limit of 10 test runs on virtual devices and 5 test runs on physical devices. Instead I needed something that checks these boxes:

Free for opensource projects.
Supports configuring the Android Emulator system images used - API level, target: (default or google_apis), arch / ABI (x86 or x86_64).
Supports running emulators in headless mode (as of Emulator 29.2.7 Canary this is equivalent to running emulator -no-window).
Supports running modern x86 and x86_64 based emulators with hardware acceleration (KVM) enabled for better performance.
Provides enough RAM for running both Gradle and an instance of Emulator.

In this post I'll share my journey on finding the best solution for running Android Emulators on CI for opensource projects.

Hardware-accelerated Emulators

Out of those requirements mentioned earlier, enabling hardware acceleration support on the host VM has been the most difficult one to meet.

The old ARM-based emulators were slow. But more importantly ARM-based system images are no longer supported by Google, as only x86 and x86_64 images are provided for recent API levels.

The modern Intel Atom (x86 and x86_64) emulators intend to provide much better performance with GPU hardware acceleration. However, installation of special software (HAXM on Mac & Windows, QEMU on Linux) is required for enabling hardware acceleration support. This presents a challenge on CI as to be able to run hardware accelerated emulators within a docker container, KVM must be enabled by the host VM which isn't the case for most cloud-based CI providers due to infrastructural limits.

This means currently we are not able to run hardware-accelerated emulators on some of the most popular cloud-based CI services such as CircleCI and Travis.

Google wants to help

It's worth to note that recently Google has been putting more efforts into offering better support for running Emulators on CI.

Earlier this year the Android Emulator Team added support for running the emulator engine in headless mode to reduce some of the implicit expectations on the host machine running the emulator in a CI environment. This feature has been unified with the -no-window mode in a recent release.
Google recently published a blog post highlighting some of the new tools they've been working on to improve deployability and debuggability of the Emulators on CI. They also opensourced a bunch of scripts for running Emulators in (Docker) containers.
There was a dedicated session titled Emulator in a Continuous Integration (CI) Environment at Android Developer Summit 2019.
There is also Project Nitrogen which is a larger effort on testing introduced back at Google IO 2018, but there hasn't been any public announcement on its progress this year.

It's encouraging to see Google's interest and commitment to continuously improve the experience of running Emulators on CI, but as of today the KVM dependency is still the main hurdle that prevents most users from being able to leverage these new tools and improvements.

Bitrise.io

bitrise.io is a CI/CD platform dedicated for Mobile. It has its own ecosystem including an online Workflow Editor and an extensive library of workflow steps, which probably appeal to new teams / projects starting out with basic Mobile CI needs.

But what got me excited were the provided steps for running Android UI tests (both physical and virtual devices), and KVM support in the host environment.

Using Bitrise Steps

Bitrise provides the Android Build for UI Testing and Virtual Device Testing for Android steps which use Firebase Test Lab to run tests for the chosen module / build variant with no limit on device hours / no. of test executions. But there are a couple of limitations:

Only 1 build variant from 1 module can be run for each step. This means if you have multiple library modules with instrumented tests, you'll have to manually configure a Android Build for UI Testing or Virtual Device Testing for Android step for each module (or setup parallel workflows for running these in parallel if you wish to pay for additional containers).
Running tests in a library module doesn't work unless an app APK is also present. The workaround is to also run app:assembleDebug for your library module tests.

You could also use the AVD Manager and Wait for Android emulator steps to spin up an Emulator on Bitrise locally and then run all your tests with Gradle, but you don't have full control over the Emulator configs and the specific SDK components needed for your workflow.

Custom workflow

Since Bitrise's host VMs have KVM enabled, we can easily setup a custom Workflow to control exactly what SDK components we want to download / update, how we want to configure and start an Emulator by providing with a custom shell script and running tests with regular Gradle commands.

Here's a repo showing how to setup such custom workflow on Bitrise.

At this point I was finally able to run Android instrumented tests on CI for FlowBinding on every PR!

Getting greedy

Being able to run unlimited instrumented tests for free on CI is not something to be taken for granted. But as more modules and tests were being added to FlowBinding, build time for the Bitrise workflow also significantly increased.

When I first integrated the Bitrise workflow, FlowBinding had 2 library modules with 9 instrumented tests; the entire Bitrise workflow took about 10 mins (this includes running a custom script to configure and spin up an Emulator, and running the tests with ./gradlew connectedCheck).

By the time I was ready to publish the first version of FlowBinding, there were 10 library modules with a total of 160 instrumented tests; the entire Bitrise workflow was taking over 30 mins.

While the number of modules and tests are unlikely to significantly increase for this project, an above 30 mins build time on CI for each PR is still quite an inconvenience.

Besides the long build time, I also wasn't very comfortable with the recommended way of configuring workflows with the online editor and having to rely on those built-in steps provided by Bitrise. Relying on the platform and ecosystem makes it harder to port our pipelines to potentially better alternatives in the future.

Given these concerns and dissatisfactions, I was set out to continue the search for better experience for running instrumented tests on CI.

GitHub Actions

GitHub Actions recently added support for CI/CD, and is free for public repositories. As a result many opensource projects on GitHub are starting to migrate their CI/CD workflows to GitHub Actions which has first-class integration with GitHub itself and strong infrastructure support from Azure.

The first thing I tried was running a hardware-accelerated Emulator within a docker container on a Linux / Ubuntu VM. Unfortunately (and perhaps unsurprisingly) KVM is not enabled on the host machines.

But GitHub Actions also offer free macOS machines for public repositories, and these macOS VMs also have HAXM (Hardware Accelerated Execution Manager) installed. This is promising as we should be able to setup a GitHub workflow that installs the required SDK components and spins up a hardware-accelerated Emulator directly from the host machine, and finally run our tests on the Emulator!

Custom action on macOS

Setting up a workflow that runs on macOS though is not as easy as doing the same with Docker, as our base environment is no longer a docker image with all the tools installed and configured and we'll need to port our scripts to work in the macOS environment. The workflow would need to do the following:

Install / update the required Android SDK components including build-tools, platform-tools, platform (for the required API level), emulator and system-images (for the required API level).
Create a new instance of AVD with various configuration options such as the API level, CPU architecture / ABI, and device profile used.
Launch a new instance of Emulator from the AVD created.
Wait until the Emulator is booted and ready for use.
Finally execute a Gradle command to run the tests - e.g. ./gradlew connectedCheck.

We can package this process into a custom GitHub Action and provide a bunch of configuration options for the consumer.

A workflow that uses the custom action (Android Emulator Runner) to run instrumented tests on API 29 may look something like this:



jobs:
  test:
    runs-on: macOS-latest
    steps:
    - name: checkout
      uses: actions/checkout@v2

    - name: run tests
      uses: reactivecircus/android-emulator-runner@v2
      with:
        api-level: 29
        script: ./gradlew connectedCheck

Outcome

It was time to run the custom GitHub Action with FlowBinding, and the result was promising!

The entire GitHub workflow took around 20 mins, while the test suites can now be run against multiple API-levels in parallel (maximum concurrent macOS jobs for public repo is 5 per user/org).

This is more than 30% improvements over the previous solution with Bitrise.

On paper the specs of the build machines provided by GitHub Actions and Bitrise are similar - 2-core CPU / 7GB RAM. So I'm not really sure what the cause of the improvement is. One possibility is being able to run everything directly on the host VM without the virtualization overhead in a docker-based environment, but that depends on many factors.

Leveraging build matrix

One of my favourite features of GitHub Actions is Build Matrix, which provides an easy way to run the same job across multiple configurations.

For example, to run instrumented tests on API 21, 23, 29 for both x86 and x86_64 ABIs, we can define the values for each configuration option under matrix and reference these values in the inputs of the action:



jobs:
  test:
    runs-on: macOS-latest
    strategy:
      matrix:
        api-level: [21, 23, 29]
        arch: [x86, x86_64]
    steps:
    - name: checkout
      uses: actions/checkout@v2

    - name: run tests
      uses: reactivecircus/android-emulator-runner@v2
      with:
        api-level: ${{ matrix.api-level }}
        arch: ${{ matrix.arch }}
        script: ./gradlew connectedCheck

The workflow will run the job with all 6 configurations:

API 21, x86
API 21, x86_64
API 23, x86
API 23, x86_64
API 29, x86
API 29, x86_64

We can also filter out certain configurations generated by the build matrix. If we only want to run the job with (API 21, x86) and (API 29, x86_64), we can easily define the configurations we don't want with exclude:



jobs:
  test:
    runs-on: macOS-latest
    strategy:
      matrix:
        api-level: [21, 29]
        arch: [x86, x86_64]
        exclude:
          - api-level: 21
            arch: x86_64
          - api-level: 29
            arch: x86
    steps:
    - name: checkout
      uses: actions/checkout@v2

    - name: run tests
      uses: reactivecircus/android-emulator-runner@v2
      with:
        api-level: ${{ matrix.api-level }}
        arch: ${{ matrix.arch }}
        script: ./gradlew connectedCheck

This will only generate 2 jobs:

API 21, x86
API 29, x86_64

You can even go nuts (please don't) and run your tests against all combinations of the configurations available, which when executed will generate a total number of 9 API levels (API 21 to 29) x 2 targets (default, google_apis) x 2 CPU / ABI (x86, x86_64) = 36 jobs.

🙃

Fun fact - while playing with build matrix I discovered that there is no system image available for android-27;google_apis;x86_64.

Update - a response from Google re. the missing system image:

For ‘android-27;google_apis;x86_64’, there may not be a good reason for it missing. That was in a transitional period where we just moved to x86_64 kernels with x86 32-bit userspace, and we needed to manage the extra complexity from there and never got around to making the x86_64 userspace version. We should have a x86 64-bit userspace version of it at some point, though, but it's not currently on our list of stuff to do (Sorry).

Build Cache?

One of the things I love the most about CircirCI is its native support for caching. Since we are able to cache the entire ~/.gradle directly to get incredibly fast incremental builds with CircleCI, I wondered if I could do something similar to my Github workflow to make it even faster.

Turned out there is this actions/cache provided by GitHub for caching dependencies and build outputs.

We can cache the ~/.gradle/caches directory by adding the following step to the job:



- uses: actions/cache@v1
  with:
    path: ~/.gradle/caches
    key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties') }}
    restore-keys: ${{ runner.os }}-gradle-

~~Unfortunately this won't work right now as there's a 200 MB limit on the cache size which isn't enough for Gradle, although they are planning to increase the limit to 2GB in the future.~~

Update: per-cache size limit has been increased to 2GB so the caching config above should now work.

Journey never ends

While the custom GitHub Action has been working really well for FlowBinding since the migration, I'm still hoping to find a more generic and future-proof solution where everything runs within a docker container rather than directly on a macOS VM. It's important for me to be able to easily try out / migrate to other CI/CD providers in the future, and using a workflow that runs things directly on a macOS VM instead of a standard Docker environment would likely make it harder to do so.

I recently came across a less-known cloud-based CI provider with native KVM support, and is completely free for opensource projects. In a future article I'll explore and share my experience with this product and compare it with my current CI workflow.

Stay tuned!

Featured in Android Weekly #390.

Binding Android UI with Kotlin Flow

Yang — Tue, 29 Oct 2019 15:23:30 +0000

Modern Android codebases are becoming increasingly reactive. With concepts and patterns such as MVI, Redux, Unidirectional Data Flow, many components of the system are being modelled as streams.

UI events can also be modelled as streams of inputs into the system.

Android’s platform and unbundled UI widgets provide listener / callback style APIs, but with RxBinding they can easily be mapped to RxJava Observable.

findViewById<Button>(R.id.button).clicks().subscribe {
    // handle button clicked
}

Kotlin Flow

kotlinx.coroutines 1.3 introduced Flow, which is an important addition to the library which finally has support for cold streams. It’s (conceptually) a reactive streams implementation based on Kotlin’s suspending functions and channels API.

Binding Android UI with Flow

In this post I’m not going to discuss why you may or may not want to migrate from RxJava to Kotlin Coroutines / Flow. But let’s see how we can implement the same clicks() example above with Flow. The API should look something like this:

scope.launch {
    findViewById<Button>(R.id.button)
        .clicks() // this returns a Flow<Unit>
        .collect {
            // handle button clicked
        }
}

The kotlinx.coroutines library offers many top-level builder functions for creating Flow. One such function is callbackFlow which is specifically designed for converting a multi-shot callback API into a Flow.

fun View.clicks(): Flow<Unit> = callbackFlow 
    val listener = View.OnClickListener {
        offer(Unit)
    }
    setOnClickListener(listener)
    awaitClose { setOnClickListener(null) }
}

The block within awaitClose is run when the consumer of the flow cancels the flow collection so this is the perfect place to remove the listener registered earlier.

offer(…) pushes a new element into the SendChannel which Flow uses internally. But the function might throw an exception if the channel is closed for send. We can create an extension function that catches any cancellation exception:

fun <E> SendChannel<E>.safeOffer(value: E) = !isClosedForSend && try {
    offer(value)
} catch (e: CancellationException) {
    false
}

Here’s the complete implementation:

@CheckResult
@UseExperimental(ExperimentalCoroutinesApi::class)
fun View.clicks(): Flow<Unit> = callbackFlow {
    checkMainThread()
    val listener = View.OnClickListener {
        safeOffer(Unit)
    }
    setOnClickListener(listener)
    awaitClose { setOnClickListener(null) }
}.conflate()

Some UI widgets might hold a state internally such as the current value of a Slider (a recently added Material Component) which you might want to observe with a Flow. In this case it might also be useful if the Flow can emit the current value immediately when collected, so that you can bind the value to some other UI element as soon as the screen is launched without the value of the slider ever being changed by the user.

@CheckResult
@UseExperimental(ExperimentalCoroutinesApi::class)
fun Slider.valueChanges(emitImmediately: Boolean = false): Flow<Float> = callbackFlow {
    checkMainThread()
    val listener = Slider.OnChangeListener { _, value ->
        safeOffer(value)
    }
    setOnChangeListener(listener)
    awaitClose { setOnChangeListener(null) }
}
    .startWithCurrentValue(emitImmediately) { value }
    .conflate()

The optional emitImmediately parameter controls whether to emit the current value immediately on flow collection.

When emitImmediately is true we add onStart { emit(value)} on the original flow which is the equivalent of startWith(value) in RxJava. This behaviour can again be wrapped in an extension function:

fun <T> Flow<T>.startWithCurrentValue(emitImmediately: Boolean, block: () -> T?): Flow<T> {
    return if (emitImmediately) onStart {
        block()?.run { emit(this) }
    } else this
}

As we can see it’s quite easy to implement UI event bindings for Kotlin Flow, thanks to the powerful Coroutines APIs. But there are myriad of other widgets both from the platform and the unbundled libraries (AndroidX), while new components such as MaterialDatePicker and Slider are being added to Material Components Android.

It’d be nice if we have a library of these bindings for Kotlin Flow.

Introducing FlowBinding

In the past few months I’ve been working on FlowBinding which offers a comprehensive set of binding APIs for Android’s platform and unbundled UI widgets, and I’m delighted to share the first public release now that the roadmap for 1.0 is complete.

The library is inspired by Jake’s RxBinding and aims to cover most of the bindings provided by RxBinding, while shifting our focus to supporting more modern AndroidX APIs such as ViewPager2 and the new components in Material Components as they become available.

Bindings are available as independent artifacts:

// Platform bindings
implementation "io.github.reactivecircus.flowbinding:flowbinding-android:${flowbinding_version}"
// AndroidX bindings
implementation "io.github.reactivecircus.flowbinding:flowbinding-appcompat:${flowbinding_version}"
implementation "io.github.reactivecircus.flowbinding:flowbinding-core:${flowbinding_version}"
implementation "io.github.reactivecircus.flowbinding:flowbinding-drawerlayout:${flowbinding_version}"
implementation "io.github.reactivecircus.flowbinding:flowbinding-navigation:${flowbinding_version}"
implementation "io.github.reactivecircus.flowbinding:flowbinding-recyclerview:${flowbinding_version}"
implementation "io.github.reactivecircus.flowbinding:flowbinding-swiperefreshlayout:${flowbinding_version}"
implementation "io.github.reactivecircus.flowbinding:flowbinding-viewpager2:${flowbinding_version}"
// Material Components bindings
implementation "io.github.reactivecircus.flowbinding:flowbinding-material:${flowbinding_version}"

List of specific binding APIs provided is available in each subproject.

Tests

Lots of efforts have been put into testing the library. All binding APIs are covered by Android instrumented tests which are run on CI builds.

Usage

To observe click events on an Android View:

findViewById<Button>(R.id.button)
    .clicks() // binding API available in flowbinding-android
    .onEach {
        // handle button clicked
    }
    .launchIn(uiScope)

Binding Scope

launchIn(scope) is a shorthand for scope.launch { flow.collect() } provided by the kotlinx-coroutines-core library.

The uiScope in the example above is a CoroutineScope that defines the lifecycle of this Flow. The binding implementation will respect this scope by unregistering the callback / listener automatically when the scope is cancelled.

In the context of Android lifecycle this means the uiScope passed in here should be a scope that's bound to the Lifecycle of the view the widget lives in.

androidx.lifecycle:lifecycle-runtime-ktx:2.2.0 introduced an extension property LifecycleOwner.lifecycleScope: LifecycleCoroutineScope which will be cancelled when the Lifecycle is destroyed.

In an Activity it might look something like this:

class ExampleActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_example)
        findViewById<Button>(R.id.button)
            .clicks()
            .onEach {
                // handle button clicked
            }
            .launchIn(lifecycleScope) // provided by lifecycle-runtime-ktx 

    }
}

Note that with FlowBinding you no longer need to unregister / remove listeners or callbacks in onDestroy() as this is done automatically for you.

More Examples

All binding APIs are documented with Example of usage which can be found in the source.

You can also find usages of all bindings from the instrumented tests.

Roadmap

With the initial release we’ve covered most of the bindings available RxBindings and added bindings for Material Components including the new MaterialDatePicker and Slider. While the library is heavily tested with instrumented tests, the APIs are not yet stable. Our plan is to polish the library by adding any missing bindings and fixing bugs as we work towards 1.0.

Your help would be much appreciated! Please feel free to create an issue on GitHub if you think a useful binding is missing or you want a new binding added to the library.

FlowBinding provides a more fluent and consistent API compared to the stock listeners / callbacks.

One added benefit is that we no longer need to unregister / remove listeners in onDestroy method as we can take advantage and Coroutine’s structured concurrency and the lifecycleScope provided by AndroidX Lifecycle.

If your project currently uses RxBinding and you are planning to migrate over to Kotlin Coroutines / Flow, FlowBinding should be a good replacement option.

I hope this can be of use to some of you. Please feel free to leave a comment below or reach out to me on twitter.
😀

Featured in Kotlin Weekly #170.