Art and science of writing good code

Full Guide to Testing Android Applications in 2022

Max Kim — Fri, 13 May 2022 10:38:29 GMT

Testing is quite a fascinating topic in software development. On the one hand, writing tests takes time, and it might not feel as rewarding - you cannot show a test to a client as you can a new feature. On the other hand, writing tests is an integral part of a project and shouldn't be treated less seriously than the code that makes the wheels turn.

Apart from actually testing the code functionality, there are many other benefits to writing tests. Tests can act as supplementary documentation that explains the expected behavior of the software. Tests can be a safety net and confidence boosters during complicated refactors and rewrites. Moreover, tests - or the inability to write them - can shine a light on architectural flaws, inciting developers to step up their game and write better code.

That said, even though we will talk a bit about theory, the main goal of this article is to see how Android testing works in practice. We will take a small sample project without any tests and, in the end, have a fully tested application.

Since we will be covering all aspects of testing an Android application, this article is not meant to be consumed in one sitting. There is too much information for that, especially for junior developers. The goal of this article is to create a comprehensive guide to Android testing, which can be studied and referred to as needed.

About the sample project

The project for today's purposes will be a sample app named Boredom Buster.

The source code can be found on GitHub.

This app uses the free BoredAPI to fetch a random activity and allows the user to save this activity to a database as a favorite for later browsing.

The app consists of two screens - an activity screen where the user can generate a random activity and save it to a database and a second screen where the user can see a list of all saved activities and delete them if they wish.

I have used the MVVM design pattern for the app with the following tech stack:

Jetpack Compose with Navigation
Jetpack Lifecycle Components
Retrofit with Moshi converter
Room
Hilt

If you would like to follow along with this article, the repository has a branch start, which doesn't have any tests and will be our starting point. The branch finish contains all the tests that we will write in this article.

Note: We will be using the new Coroutines Test API, which was released in kotlinx.coroutines 1.6.0.

Making your code testable

This will be a very practical article, but before we start, I would like to spend a few moments on a topic that can't be ignored when talking about testing software.

In most cases, writing tests should be straightforward. If you cannot find an easy way to test your code, chances are that your code has some structural flaws.

That is where architecture comes in.

Today we will not focus on architecture, but keep in mind that it is an integral part of writing good tests.

If you are not familiar with the Android App architecture, a good place to start is the official guide to app architecture from Google. However, for a more advanced understanding of architecture, I strongly recommend studying Uncle Bob's Clean Architecture approach. His blog post on the topic was so popular that Uncle Bob wrote a whole book on the subject, and I consider it a must-read for any software developer.

The app we will be testing today uses a Clean Architecture approach adapted for Android.

Writing Unit tests

On that note, let's open up our project and start writing some tests.

First, we will tackle Unit tests that test individual small parts of our application - methods, functions, and classes.

Testing ViewModels with StateFlow

In Android, one of the most important parts to test is the ViewModels, and that is where we will start.

Our project has two ViewModels - one for the Activity screen (I don't see any reason why this can be confusing to Android developers, right?) that is responsible for fetching and displaying a random activity, and one for the Favorites screens displaying a list of saved activities.

Let's first open up NewActivityViewModel and look at its structure.

We have two public methods:

loadNewActivity(): Unit - a method that fetches a random activity from the API and updates the UI state;
setIsFavorite(Activity, Boolean): Unit - a method that either saves an activity to the database or deletes it.

We also have a publicly exposed StateFlow, which emits the current UI state for the Activity screen.

Note: We are using a StateFlow in this ViewModel, but for the sake of covering more testing examples, the FavoritesViewModel exposes its UI state via a LiveData.

One important thing to note here is that NewActivityViewModel also calls loadNewActivity() in its init() block to immediately display a random activity to the user.

Test scenarios

Given that, here are the scenarios we would like to test to make sure our ViewModel works correctly:

When creating a NewActivityViewModel, the initial UI state is Loading;
Creating a NewActivityViewModel triggers the emission of a new Success UI state;
Creating a NewActivityViewModel triggers the emission of a new Error UI state in case of error;
If Activity is already saved, the UI state's isFavorite is set to true;
Calling loadNewActivity() successfully reloads the existing UI state with a new activity;
Calling setIsFavorite(activity, true) calls SaveActivity use case;
Calling setIsFavorite(activity, false) calls DeleteActivity use case.

Creating a test

To create a test, you can either create a test file manually or make an Android Studio generate one for you.

To generate a test, you can press Alt + Insert on Windows or Cmd + N on Mac anywhere in the target file to open the Generate popup and select Test.

This will open the Create Test popup:

Projects generated by Android Studio automatically have the necessary dependencies to run tests with JUnit4, so we will use that. JUnit5 is not fully supported for Android and requires some more setting up, so we will ignore it. JUnit4 is more than enough for our testing purposes.

There are some other options that this popup allows us to select, but we will ignore them for now and do everything manually as we see fit.

Clicking OK will prompt us to choose a destination directory:

We have two options where to put our new test:

androidTest - a directory for instrumented Android tests, which run on either a physical or emulated Android device. This directory is for tests that depend on the Android framework to run. Most commonly those are UI tests or database tests.
test - a directory for local unit tests or integrations tests that don't require the Android framework to run.

With that in mind, we will be using the test directory since we don't need anything from the Android framework.

Note: This is one of the main reasons why your ViewModels should not depend on Android Context. But there are also other considerations. Here is a good article for further research.

Clicking OK will generate or new test class, which is quite barebones for now, but we will create a separate test for every scenario outlined above.

In JUnit you create a test by annotating the test method with a @Test annotation.

Also, naming your test methods can be different from naming regular methods, depending on the convention you prefer. It is a good practice to write explicit method names, describing the expected behavior of the test. It also acts as complementary documentation for your code.

In Kotlin, we can use backticks to write method names in “plain text", which I prefer for naming tests.

However, there is a catch. Using this kind of naming is not allowed in Android projects. Therefore, if you want to use the same naming convention in your test and androidTest folders, you should probably stick with the regular naming.

That said, to illustrate that this is also a very popular approach in testing, we will use this naming in our non-Android tests.

With that in mind, let's create a test for the first scenario:

@Test
fun `creating a viewmodel exposes loading ui state`() {

}

The tests usually follow the AAA pattern, which stands for Arrange - Act - Assert.

In this first scenario, we won't have an Act part since we will be testing the initial UI state immediately after creating the NewActivityViewModel.

However, we cannot just create an instance of NewActivityViewModel since it depends on a bunch of use cases. In this test, we are focusing on the NewActivityViewModel class only and don't care about all other parts of the app and how our app interacts with them. We will test that later with integration tests, which, as the name suggests, are meant to test integration between different components.

Fakes vs. Mocks

There are two common ways to solve this problem - by either using fakes or mocks. Fakes are working implementations of dependencies that are written with testing in mind, while mocks are test doubles that can be programmed to behave as you like and require a mocking framework, such as Mockito.

It is always a hot topic which approach is better. However, it is important to highlight that both approaches have pros and cons.

I prefer to use fakes as much as possible. I mainly use mocks when I test the number or order of interactions, which is much easier to do with mocks. In general, being too dependent on mocks can make you miss opportunities to have better integration tests when testing how multiple components work together. Or even highlight flaws in the architecture if your components depend on concrete implementations and it is not possible to create a fake.

Your components should be decoupled for cleaner code and easier testing. In most cases, components should depend on interfaces, not concrete implementations.

Creating fake dependencies

We will discuss how to use both fakes and mocks in this article, but let's start with fakes since they don't require additional dependencies and are also recommended by Google.

We will be reusing our fakes, so let's create a new package eu.maxkim.boredombuster.activity.fake, where we will put all our fakes.

To test our ViewModel we will only need fake use cases, so let’s put all of them together in a new package .fake.usecase.

First we need a fake GetRandomActivity use case, so let's create a new class FakeGetRandomActivity, which implements that interface.

Here is our newly created fake:

class FakeGetRandomActivity : GetRandomActivity {

    override suspend fun invoke(): Result {
        TODO("Not yet implemented")
    }
}

As you can see, since the data comes from the network, our use case returns a wrapper Result, which can either be a Success or Error. Naturally, we would want to test both those scenarios, so let's make sure our fake supports that. The easiest way to implement that is to just pass a Boolean argument in a constructor, which will change the behavior of our fake:

class FakeGetRandomActivity(
    private val isSuccessful: Boolean = true
) : GetRandomActivity {
    ...
}

With that out of the way, we will also need some dummy test objects to play around with in our tests. To make things cleaner, let's create a new TestModels.kt file to store them.

For now let's add two test activities:

//TestModels.kt
val activity1 = Activity(
    name = "Learn to dance",
    type = Activity.Type.Recreational,
    participantCount = 2,
    price = 0.1f,
    accessibility = 0.2f,
    key = "112233",
    link = "www.dance.com"
)

val activity2 = Activity(
    name = "Pet a dog",
    type = Activity.Type.Relaxation,
    participantCount = 1,
    price = 0.0f,
    accessibility = 0.1f,
    key = "223344",
    link = "www.dog.com"
)

Now we can finish our fake:

class FakeGetRandomActivity(
    private val isSuccessful: Boolean = true
) : GetRandomActivity {

    override suspend fun invoke(): Result {
        return if (isSuccessful) {
            Result.Success(activity1)
        } else {
            Result.Error(RuntimeException("Boom..."))
        }
    }
}

Another fake that we will use in the first test scenario is IsActivitySaved use case.

When getting a random activity from API, we use this use case to check whether or not the user has already saved this activity to display its state correctly.

Later on, we will be testing whether or not our ViewModel correctly displays the favorite status, so we will make this fake flexible as well:

class FakeIsActivitySaved(
    private val isActivitySaved: Boolean = false
) : IsActivitySaved {

    override suspend fun invoke(key: String): Boolean {
        return isActivitySaved
    }
}

We won't use the two remaining use cases in the first test scenario, so let's just create them without any logic and return to them when we need them:

class FakeSaveActivity : SaveActivity {

    override suspend fun invoke(activity: Activity) {
        TODO("Not yet implemented")
    }
}

class FakeDeleteActivity : DeleteActivity {

    override suspend fun invoke(activity: Activity) {
        TODO("Not yet implemented")
    }
}

First test scenario

With that out of the way, we can get back to writing our test. Let's create an instance of a NewActivityViewModel using our fakes:

@Test
fun `creating a viewmodel exposes loading ui state`() {
    // Arrange
    val viewModel = NewActivityViewModel(
        FakeGetRandomActivity(),
        FakeSaveActivity(),
        FakeDeleteActivity(),
        FakeIsActivitySaved()
    )
}

Now we want to test that after creating the viewModel the initial value of the uiState is NewActivityUiState.Loading.

Here are a couple of things to keep in mind when writing this first test.

First, StateFlow always has a value or a state (hence the name), so we can access it synchronously with viewModel.uiState.value. We don't need to be inside a coroutine to do that.

Second, people use many different libraries in their tests for assertions, but we will use the standard assertion functions that come with Kotlin and JUnit to make things easier.

With that in mind we can finish our test:

@Test
fun `creating a viewmodel exposes loading ui state`() {
    // Arrange
    val viewModel = NewActivityViewModel(
        FakeGetRandomActivity(),
        FakeSaveActivity(),
        FakeDeleteActivity(),
        FakeIsActivitySaved()
    )

    // Assert
    assert(viewModel.uiState.value is NewActivityUiState.Loading)
}

Now, if we run this test, we will get an error:

Exception in thread "Test worker" java.lang.IllegalStateException: 
Module with the Main dispatcher had failed to initialize. 
For tests Dispatchers.setMain from kotlinx-coroutines-test module can be used

This happens because creating a new instance of NewActivityViewModel immediately calls loadNewActivity() method, which launches a new coroutine in the viewModelScope.

This scope uses the Dispatchers.Main.immediate dispatcher, and since Dispatcher.Main usually comes with the framework responsible for drawing UI and otherwise is not readily available, we will have to supply our own dispatcher.

Luckily, this is very easy to do, and the error message even gives us a hint. We can use Dispatchers.setMain() method from kotlinx-coroutines-test module.

Let's add it to our project:

// project build.gradle
coroutines_test_version = '1.6.1'

// module build.gradle
testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:$coroutines_test_version"

Now we can set the StandartTestDispatcher, which comes from the kotlinx-coroutines-test library, as our Dispatchers.Main. It is a good practice to set and reset the Dispatchers.Main before and after each test, and for that, we can use @Before and @After annotations that come with JUnit.

@ExperimentalCoroutinesApi
class NewActivityViewModelTest {
    private val testDispatcher = StandardTestDispatcher()

    @Before
    fun setUp() {
        Dispatchers.setMain(testDispatcher)
    }

    @After
    fun tearDown() {
        Dispatchers.resetMain()
    }

    ...
}

Note: We also need to add either @ExperimentalCoroutinesApi or @OptIn(ExperimentalCoroutinesApi::class) to the class since most of the stuff inside kotlinx-coroutines-test is experimental.

Since we can set the Dispatchers.Main ourselves in the tests, we can easily test coroutine scopes that use this dispatcher (like viewModelScope or lifecycleScope) without injecting a test scope. However, we must replace the scopes that use other dispatchers with a TestScope. We will look into those scenarios a bit later.

If we run our test now, it finally passes, and we have our first working test!

Creating test rules

It took us a while to get our first test running, but we are still in the process of setting up, so test writing will speed up as we go.

One of the things that we can do to speed it up even more, is to create a Rule that will be responsible for setting and resetting the Dispatchers.Main. This way, we can re-use this logic in other test files.

Let's create a new package eu.maxkim.boredombuster.util with a new class CoroutineRule.

To get the @Before and @After behavior, we can extend an abstract TestWatcher class, which comes with starting and finished methods.

After overriding these methods we get:

@ExperimentalCoroutinesApi
class CoroutineRule(
    val testDispatcher: TestDispatcher = StandardTestDispatcher()
) : TestWatcher() {

    override fun starting(description: Description?) {
        Dispatchers.setMain(testDispatcher)
    }

    override fun finished(description: Description?) {
        Dispatchers.resetMain()
    }
}

With our CoroutineRule ready, let's go back to our test and replace the @Before and @After logic with the rule. For that, we need to add the following to our test class:

@get:Rule
val coroutineRule = CoroutineRule()

@get:Rule annotation comes from JUnit.

With that in place, here is what our test file looks like now:

@ExperimentalCoroutinesApi
class NewActivityViewModelTest {

    @get:Rule
    val coroutineRule = CoroutineRule()

    @Test
    fun `creating a viewmodel exposes loading ui state`() {
        // Arrange
        val viewModel = NewActivityViewModel(
            FakeGetRandomActivity(),
            FakeSaveActivity(),
            FakeDeleteActivity(),
            FakeIsActivitySaved()
        )

        // Assert
        assert(viewModel.uiState.value is NewActivityUiState.Loading)
    }
}

Run the test to make sure that everything works as before.

Understanding test dispatchers after Kotlin Coroutines 1.6

Before we move on to our second test scenario, I would like to talk about why this test works. One might assume that this test should be flaky since creating the NewActivityViewModel loads a new activity immediately and changes the UI state to NewActivityUiState.Success.

However, we confidently check the UI state and expect it always to be NewActivityUiState.Loading.

The secret here is the StandardTestDispatcher(). Coroutines launched on this dispatcher are not executed immediately, which is a big difference compared to how testing coroutines worked before kotlinx.coroutines 1.6.0.

Here is an excerpt from StandardTestDispatcher() documentation:

/**
 * In practice, this means that [launch] or [async] blocks 
 * will not be entered immediately (unless they are
 * parameterized with [CoroutineStart.UNDISPATCHED]), 
 * and one should either call [TestCoroutineScheduler.runCurrent] to
 * run these pending tasks, which will block until there are 
 * no more tasks scheduled at this point in time, or, when
 * inside [runTest], call [yield] to yield the (only) thread 
 * used by [runTest] to the newly-launched coroutines.
 */

This means that the coroutine that we launch inside the loadNewActivity() method is not executed unless we explicitly specify it, which we will do for our next test scenario.

If we need our tests to run blocking as they did in the old testing API, which might be useful during a migration to the new API, we can replace the StandardTestDispatcher() with the UnconfinedTestDispatcher(). Using this dispatcher gives us a much closer behavior to runBlockingTest from the old testing API, since it executes all launched coroutines eagerly.

For learning purposes, you can try replacing the StandardTestDispatcher() in the CoroutineRule with the UnconfinedTestDispatcher(), which will make our test fail. In that case, when we make our assertion, the UI state will already be NewActivityUiState.Success. However, if you do change it, don't forget to change it back!

Remaining test scenarios

Second test scenario

Now that we better understand how testing coroutines work, we can start writing our next test.

We will test that after an instance of NewActivityViewModel is created and all the coroutines have successfully finished, the UI state is NewActivityUiState.Success.

We prepare our viewModel an also an expectedUiState that we should get if everything works correctly:

@Test
fun `creating a viewmodel updates ui state to success after loading`() {
    // Arrange
    val viewModel = NewActivityViewModel(
        FakeGetRandomActivity(),
        FakeSaveActivity(),
        FakeDeleteActivity(),
        FakeIsActivitySaved()
    )

    val expectedUiState = NewActivityUiState.Success(activity1, false)
}

Now we need to execute our coroutine that loads a new activity from the FakeGetRandomActivity use case. There are many ways to achieve that, but for now, we will go with the easiest and most straightforward way to do it, which is calling runCurrent() on a TestCoroutineScheduler used by our TestDispatcher. You can also use advanceUntilIdle() to get the same result. There is a difference between these two functions, but we will discuss this difference and how the scheduler and dispatcher are connected a bit later. We can access the TestDispatcher and the TestCoroutineScheduler from our CoroutineRule.

After that, we can do our assertions and expect the test to pass.

Here is the finished test:

@Test
fun `creating a viewmodel updates ui state to success after loading`() {
    // Arrange
    val viewModel = NewActivityViewModel(
        FakeGetRandomActivity(),
        FakeSaveActivity(),
        FakeDeleteActivity(),
        FakeIsActivitySaved()
    )

    val expectedUiState = NewActivityUiState.Success(activity1, false)

    // Act
    coroutineRule.testDispatcher.scheduler.runCurrent()

    // Assert
    val actualState = viewModel.uiState.value
    assertEquals(actualState, expectedUiState)
}

Third test scenario

We should also test that the UI state correctly updates to NewActivityUiState.Error if something goes wrong. With all the things we have already discussed, writing this test should be a breeze. All we have to do is to make our fake return an error.

Here is the final result:

@Test
fun `creating a viewmodel updates ui state to error in case of failure`() {
    // Arrange
    val viewModel = NewActivityViewModel(
        FakeGetRandomActivity(isSuccessful = false), // our fake will return an error
        FakeSaveActivity(),
        FakeDeleteActivity(),
        FakeIsActivitySaved()
    )

    // Act
    coroutineRule.testDispatcher.scheduler.runCurrent()

    // Assert
    val currentState = viewModel.uiState.value
    assert(currentState is NewActivityUiState.Error)
}

Fourth test scenario

In this scenario, we want to test that, if the activity is already saved, the UI state's isFavorite flag is set to true. Given everything we already know, this shouldn't be that hard.

Here is the final test:

@Test
fun `if activity is already saved, ui state's isFavorite is set to true`() {
    // Arrange
    val viewModel = NewActivityViewModel(
        FakeGetRandomActivity(), // our fake will return an error
        FakeSaveActivity(),
        FakeDeleteActivity(),
        FakeIsActivitySaved(isActivitySaved = true)
    )

    val expectedUiState = NewActivityUiState.Success(activity1, true)

    // Act
    coroutineRule.testDispatcher.scheduler.runCurrent()

    // Assert
    val actualState = viewModel.uiState.value
    assertEquals(actualState, expectedUiState)
}

Fifth test scenario

This scenario is a bit harder since we will be testing whether the new activity loads and replaces the current one when calling loadNewActivity() explicitly.

First of all, let's change our FakeGetRandomActivity to be able to return a new activity when called a second time. The easiest way to do that is to expose a property, which will be returned by the fake if set:

class FakeGetRandomActivity(
    private val isSuccessful: Boolean = true
) : GetRandomActivity {

    var activity: Activity? = null

    override suspend fun invoke(): Result {
        return if (isSuccessful) {
            Result.Success(activity ?: activity1)
        } else {
            Result.Error(RuntimeException("Boom..."))
        }
    }
}

We cannot pass the activity in the constructor since we will need to swap it on the same instance.

With that in place, we can now write a test for this scenario:

@Test
fun `calling loadNewActivity() updates ui state with a new activity`() {
    // Arrange
    val fakeGetRandomActivity = FakeGetRandomActivity()
    val viewModel = NewActivityViewModel(
        fakeGetRandomActivity,
        FakeSaveActivity(),
        FakeDeleteActivity(),
        FakeIsActivitySaved()
    )
    // this can be omitted, but it is nice to not have any pending tasks
    coroutineRule.testDispatcher.scheduler.runCurrent()

    val expectedUiState = NewActivityUiState.Success(activity2, false)
    fakeGetRandomActivity.activity = activity2

    // Act
    viewModel.loadNewActivity()
    coroutineRule.testDispatcher.scheduler.runCurrent()

    // Assert
    val actualState = viewModel.uiState.value
    assertEquals(actualState, expectedUiState)
}

We are not testing the state of our view model after the first call to loadNewActivity() since we already have a dedicated test for that. Therefore, we are only interested in the second call.

Also, in general, Unit tests should be as small as possible, aiming to assert only one scenario. That said, if you want to throw in another assertion and test the UI state before and after, nobody will call the police on you.

Sixth scenario

In this scenario, we will be testing whether or not calling setIsFavorite(activity, true) method interacts with the correct use case, and as I have mentioned before, testing interactions is what mocks are good for.

However, we will have plenty of time to play around with mocks later, so for this ViewModel, let's see how we can test interaction with fakes, so that we have both options.

To do that, we need to introduce a state to our fake, which will change after we invoke it. After that, we will use this state in our assertions.

Here is what our FakeSaveActivity looks like after the changes:

class FakeSaveActivity : SaveActivity {

    var wasCalled = false
        private set

    override suspend fun invoke(activity: Activity) {
        wasCalled = true
    }
}

Note: We are using private set to make sure that the only way to change the state is to call the invoke() method

With that in place, we can write our test as follows:

@Test
fun `calling setIsFavorite(true) triggers SaveActivity use case`() {
    // Arrange
    val fakeSaveActivity = FakeSaveActivity()
    val viewModel = NewActivityViewModel(
        FakeGetRandomActivity(),
        fakeSaveActivity,
        FakeDeleteActivity(),
        FakeIsActivitySaved()
    )

    // Act
    viewModel.setIsFavorite(activity1, true)
    coroutineRule.testDispatcher.scheduler.runCurrent()

    // Assert
    assert(fakeSaveActivity.wasCalled)
}

Seventh scenario

The test for setIsFavorite(activity, false) is exactly the same, so here is the final result:

@Test
fun `calling setIsFavorite(false) triggers DeleteActivity use case`() {
    // Arrange
    val fakeDeleteActivity = FakeDeleteActivity()
    val viewModel = NewActivityViewModel(
        FakeGetRandomActivity(),
        FakeSaveActivity(),
        fakeDeleteActivity,
        FakeIsActivitySaved()
    )

    // Act
    viewModel.setIsFavorite(activity1, false)
    coroutineRule.testDispatcher.scheduler.runCurrent()

    // Assert
    assert(fakeDeleteActivity.wasCalled)
}

Other scenarios

There are still some untested scenarios left in the NewActivityViewModel. For example, testing that calling setIsFavorite() also changes the UI state appropriately. However, these tests are very similar to what we have already discussed and don't provide any educational value to include in this article.

That said, in the finish branch of this project, I will include as many of these tests as possible, so you can reference them if you wish.

Bonus: Testing Flows with Turbine

In the above test scenarios, we had the pleasure of dealing with a StateFlow, which allows us to access its value outside a coroutine. Of course, we could have also used first(), but that is a suspend function, and we would have needed a coroutine for that. That said, when testing Android apps, there will be a lot of scenarios where you will need a coroutine (plenty of those examples later on), and maybe you will want to collect multiple values from a Flow for assertion.

Testing hot flows like StateFlow (they never finish) might be tricky in these scenarios.

And that's where Turbine comes in.

It is a small library that makes testing Flows really easy and intuitive.

To illustrate how it works, let's use Turbine to rewrite the test where we call loadNewActivity() the second time.

Since this is a bonus section, I will not discuss most of the used concepts and will focus on the Turbine library. However, we will cover everything else later in the article, so feel free to return to this section later if something doesn't make sense.

First, we have to add it to the dependencies:

// project build.gradle
turbine_version = '0.8.0'

// module build.gradle
testImplementation "app.cash.turbine:turbine:$turbine_version"

Now we can test our Flows in the following manner:

flowOf("one", "two").test {
    assertEquals("one", awaitItem())
    assertEquals("two", awaitItem())
    awaitComplete()
}

With that in mind, let's test the following scenario again.

We want the initial state of UI to be Loading;
Then, after the first load completes, we expect the state to change to Success with the corresponding activity;
Calling loadNewActivity() again should change the state back to Loading and finish with another Success containing the second activity.

The Turbine's test() function is a suspend function, so we will need to run our test with the runTest coroutine builder (again, if you don't know what it is, please return to this bonus section later).

Also, we will have to collect our flow with the test() function in a separate coroutine so it is not suspending the whole test.

With those details out of the way, here is how we can test this scenario with Turbine:

@Test
fun `calling loadNewActivity() twice goes through expected ui states`() = runTest {
    val fakeGetRandomActivity = FakeGetRandomActivity()
    val viewModel = NewActivityViewModel(
        fakeGetRandomActivity,
        FakeSaveActivity(),
        FakeDeleteActivity(),
        FakeIsActivitySaved()
    )

    assert(viewModel.uiState.value is NewActivityUiState.Loading)

    launch {
        viewModel.uiState.test {
            with(awaitItem()) {
                assert(this is NewActivityUiState.Success)
                assertEquals((this as NewActivityUiState.Success).activity, activity1)
            }

            assert(awaitItem() is NewActivityUiState.Loading)

            with(awaitItem()) {
                assert(this is NewActivityUiState.Success)
                assertEquals((this as NewActivityUiState.Success).activity, activity2)
            }
            // this is not necessary for this specific test
            // but better safe than sorry
            // especially when dealing with hot flows
            cancelAndIgnoreRemainingEvents()
        }
    }

    // runs the initial loading
    runCurrent()

    // prepares and runs the second loading
    fakeGetRandomActivity.activity = activity2
    viewModel.loadNewActivity()
    runCurrent()
}

This is just a brief introduction to Turbine. It has much more to offer when testing different scenarios with Flows. So keep it in mind if you need to write more complex tests.

With that out of the way, let's get back to testing our app!

Testing ViewModels with LiveData

Now let's take a look at how we can test LiveData.

In the app, we have a second ViewModel, which is a good candidate for that - the FavoritesViewModel.

This ViewModel is quite small. There are only three scenarios:

The view model exposes the list of activities from LiveData as a List UI state;
The view model exposes an empty list from LiveData as an Empty UI state;
Calling deleteActivity() triggers interaction with the correct use case.

Create a test file for the FavoritesViewModel, and let's get started.

First scenario and introduction to Mockito

The first thing that we need to consider when testing LiveData is that it also heavily relies on the main UI thread. We already know how to deal with this issue when testing coroutines. We have made a custom CoroutineRule which sets and resets the main thread using the Dispatchers.setMain() and Dispatchers.resetMain() methods.

This time around, we don't have to do anything ourselves since folk at Google kindly provided us with a solution to this problem.

There is a dedicated package for testing Architecture Components, which we can add to our project:

// project build.gradle
arch_testing_version = '2.1.0'

// module build.gradle
testImplementation "androidx.arch.core:core-testing:$arch_testing_version"

The class that we are interested in is InstantTaskExecutorRule, which does exactly what our CoroutineRule does, only for Architecture components.

/**
 * A JUnit Test Rule that swaps the background executor 
 * used by the Architecture Components with a
 * different one which executes each task synchronously.
 * 
 * You can use this rule for your host side tests that 
 * use Architecture Components.
 */
public class InstantTaskExecutorRule extends TestWatcher {
   ...
}

If you look at its implementation, you will find a very familiar pattern. It also overrides starting and finished methods of TestWatcher to change and reset the executor.

Now let's add this rule to our FavoritesViewModelTest:

class FavoritesViewModelTest {

    @get:Rule
    val instantExecutorRule = InstantTaskExecutorRule()
}

One important thing to address is that, unlike StateFlow, LiveData doesn't have a mandatory initial value. Moreover, LiveData is written in Java, and its value doesn't always make sense in Kotlin.

For example, our LiveData type is LiveData, so one would assume that the value is non-nullable. However, that is not the case.

If we create a new instance of FavoritesViewModel and immediately check viewModel.uiStateLiveData.value it will be null.

So to properly test our LiveData, we have to replicate the observer pattern.

There are a couple of ways to do it. There is a way suggested by Google in their codelabs, but for me, honestly, it looks like a hassle. If you want to go that route, that logic can be simplified and made more elegant. That would be just like using fakes with a state. But we already did that, so let's take a different approach and use mocks for this one.

The most popular mock library out there is Mockito, and you will probably use it in your tests one way or another, so let's add it to our project:

// project build.gradle
mockito_kotlin_version = '4.0.0'

// module build.gradle
testImplementation "org.mockito.kotlin:mockito-kotlin:$mockito_kotlin_version"

Note: We are using mockito-kotlin instead of mockito-core to have some cool Kotlin methods.

Now we can start using Mockito in our tests. To create mocks by using Kotlin's mock() function (more on that a bit later) or the equivalent Java's Mockito.mock(), we don't need to do anything else.

However, if we want to use Mockito's annotations to initiate mocks, we need to either run the test with MockitoJUnitRunner:

@RunWith(MockitoJUnitRunner::class)
class MyTest {

    @Mock
    private lateinit var mockComponent: Component
}

or add a Mockito Rule to it:

class MyTest {

    @get:Rule
    val mockitoRule: MockitoRule = MockitoJUnit.rule()

    @Mock
    private lateinit var mockComponent: Component
}

Note: We specify the explicit type MockitoRule because MockitoJUnit.rule() returns a platform type, and we want to make the compiler happy.

The FavoritesViewModelTest has two dependencies. We already have a fake for DeleteActivity, and we can easily make a fake for GetFavoriteActivities. But since we are in the Mockito world right now, let's use mocks this time.

Mockito is quite a flexible library, and it gives us options on how we can approach things, but I find that the easiest way to create mocks in our tests is to use the mock() method from mockito-kotlin library:

/**
 * Creates a mock for [T].
 */
inline fun <reified T : Any> mock(): T

This is a simplified Kotlin way to call Java's:

public static  T mock(Class classToMock, MockSettings mockSettings)

Now that we know how to create a mock, let's add the mocks for our use cases to the test class:

class FavoritesViewModelTest {

    @get:Rule
    val instantExecutorRule = InstantTaskExecutorRule()

    private val mockGetFavoriteActivities: GetFavoriteActivities = mock()
    private val mockDeleteActivity: DeleteActivity = mock()
}

One concern that can arise with mocks is whether or not we should reset our mocks after each test to avoid a dirty state. The answer is - folk at JUnit made sure that this is not an issue. JUnit will create a new test class instance each time it runs a test. You can read about it in this StackOverlow thread. It can also be easily tested by setting the state of a mock in one test and trying to access it from another. Spoiler alert: it will not work.

With those worries out of the way, let's write our test and arrange some data. First, we need a LiveData object that our mock will return and a list we expect to observe.

@Test
fun `the view model maps list of activities to list ui state`() {
    // Arrange
    val liveDataToReturn = MutableLiveData>()
        .apply { value = listOf(activity1, activity2) }

    val expectedList = listOf(activity1, activity2)
}

Note: We should not feed expectedList directly into our LiveData because expected and actual values will be the same reference, which can muddy the test result in some cases.

To set up our mock, we will use Mockito's:

inline fun  whenever(methodCall: T): OngoingStubbing

together with

infix fun  OngoingStubbing.doReturn(t: T): OngoingStubbing

Kotlin's doReturn() method just calls Java's thenReturn() method. Therefore, we can use those two interchangeably.

Here is how it looks in our code:

whenever(mockGetFavoriteActivities.invoke()).doReturn(liveDataToReturn)

Note: We have to set up our mock before creating a ViewModel instance. Otherwise, ViewModel's MediatorLiveData that does the mapping won't have any sources and will crash with a NullPointerException.

With everything set up, we can now create an instance of our ViewModel and the arranging part is done:

@Test
fun `the view model maps list of activities to list ui state`() {
    // Arrange
    val liveDataToReturn = MutableLiveData>()
        .apply { value = listOf(activity1, activity2) }

    val expectedList = listOf(activity1, activity2)

    whenever(mockGetFavoriteActivities.invoke()).doReturn(liveDataToReturn)

    val viewModel = FavoritesViewModel(
        mockGetFavoriteActivities,
        mockDeleteActivity
    )
}

Now we need an Observer to observe our LiveData and something that can capture the observed data and preserve it in a state for us to use in our assertions. This is similar to how Google approaches this problem in the Codelab mentioned above, but we can use an ArgumentCaptor from Mockito to do this for us.

/**
 * Use it to capture argument values for further assertions.
 */
public class ArgumentCaptor<T>

We can create an Observer mock just like we did with the use cases:

private val activityListObserver: Observer = mock()

However, for an ArgumentCaptor, we need a real instance. There are two ways to do it (as far as I know). The first one is mentioned in the documentation and uses a static builder method:

public static  ArgumentCaptor forClass(Class clazz)

Here we need to pass a Class ~~as an argument, and in our case, we would write:~~

ArgumentCaptor.forClass(FavoritesUiState::class.java)

However, the second option is easier and more elegant for my taste.

We can use the @Captor annotation to generate the captor for us:

@Captor private lateinit var activityListCaptor: ArgumentCaptor

Now, since we will be using a Mockito annotation to create this mock, we will need to either run our test with the MockitoJUnitRunner or add a MockitoRule as explained above.

I will go with the MockitoJUnitRunner:

@RunWith(MockitoJUnitRunner::class) class FavoritesViewModelTest { ... }

And here are the new mocks in our file:

private val activityListObserver: Observer = mock() @Captor private lateinit var activityListCaptor: ArgumentCaptor

With that settled, we can now finish our test.

We need to start observing the LiveData with our mock Observer:

// Act viewModel.favoriteActivityLiveData.observeForever(activityListObserver)

Note: We are using observeForever since we don't have a LifecycleOwner.

Assertion part might seem a bit scary at first, but it is really straightforward if you break it down:

// Assert verify(activityListObserver, times(1)).onChanged(activityListCaptor.capture()) assert(activityListCaptor.value is FavoritesUiState.List) val actualList = (activityListCaptor.value as FavoritesUiState.List).activityList assertEquals(actualList, expectedList)

We are verifying that our mock Observer’s onChanged method is called once, and we are using the activityListCaptor to capture the passed value.

After that, we can access the activityListCaptor.value, which is a FavoritesUiState, and compare its activityList to expectedList.

Here is the finished test:

@Test fun `the view model maps list of activities to list ui state`() { // Arrange val liveDataToReturn = MutableLiveData>() .apply { value = listOf(activity1, activity2) } val expectedList = listOf(activity1, activity2) whenever(mockGetFavoriteActivities.invoke()).doReturn(liveDataToReturn) val viewModel = FavoritesViewModel( mockGetFavoriteActivities, mockDeleteActivity ) // Act viewModel.favoriteActivityLiveData.observeForever(activityListObserver) // Assert verify(activityListObserver, times(1)).onChanged(activityListCaptor.capture()) assert(activityListCaptor.value is FavoritesUiState.List) val actualList = (activityListCaptor.value as FavoritesUiState.List).activityList assertEquals(actualList, expectedList) }

Second test scenario

The second scenario is very similar to the first one, but we will be returning an empty list from our mock's LiveData and asserting that the FavoritesUiState is Empty.

There is nothing new here, so here is the finished test:

@Test fun `the view model maps empty list of activities to empty ui state`() { // Arrange val liveDataToReturn = MutableLiveData>() .apply { value = listOf() } whenever(mockGetFavoriteActivities.invoke()).doReturn(liveDataToReturn) val viewModel = FavoritesViewModel( mockGetFavoriteActivities, mockDeleteActivity ) // Act viewModel.uiStateLiveData.observeForever(activityListObserver) // Assert verify(activityListObserver, times(1)).onChanged(activityListCaptor.capture()) assert(activityListCaptor.value is FavoritesUiState.Empty) }

Third test scenario

In this scenario, we will be testing whether calling deleteActivity() interacts with the correct use case. We have already done a similar test, so let's do this one using mocks to have both options.

The Arrange and Act parts in this test are quite straight forward:

@Test fun `calling deleteActivity() interacts with the correct use case`() { // Arrange val viewModel = FavoritesViewModel( mockGetFavoriteActivities, mockDeleteActivity ) // Act viewModel.deleteActivity(activity1) }

The first problem, however, is that deleteActivity() launches a coroutine in the viewModelScope, and we need to set the Dispatcher.Main. But we already know how to fix that.

Let's add our CoroutineRule to this test class:

@get:Rule val coroutineRule = CoroutineRule()

The second problem presents itself if we try to verify that the deleteActivity() method interacted with our mockDeleteActivity. We have seen how to check for the interactions in the previous test, so we would write:

// Assert verify(mockDeleteActivity, times(1)).invoke(activity1)

The problem here is that our use case's invoke() method is suspend, so we need a coroutine.

We have managed to avoid using suspend functions until now, but those are pretty common in Android applications.

Since kotlinx.coroutines 1.6.0 the way to get into the coroutine world in tests is by using runTest coroutine builder. It replaced the runBlockingTest, which is now deprecated.

By wrapping our test with runTest we won't have any more compilation errors, but don't forget to add runCurrent() or advanceUntilIdle() after calling deleteActivity() to make sure the launched coroutine completes its job.

Note: We can also use the yield() suspend function when inside a runTest block to get the same result. But its name is not as explicit as runCurrent() or advanceUntilIdle() and it requires a good understanding of how coroutines work to use comfortably. Therefore, we will not use it in the examples.

Here is the finished test:

@Test fun `calling deleteActivity() interacts with the correct use case`() = runTest { // Arrange val viewModel = FavoritesViewModel( mockGetFavoriteActivities, mockDeleteActivity ) // Act viewModel.deleteActivity(activity1) advanceUntilIdle() // works the same as runCurrent() in this case // Assert verify(mockDeleteActivity, times(1)).invoke(activity1) }

Testing Room database

With ViewModel testing out of the way, the next important area of an app to test is repositories. In our app, the ActivityRepository just delegates data operations to its data sources, so it would make sense to test those.

That said, let's first test the ActivityLocalDataSource and the Room database.

The recommended way to test Room is on an Android device since we need a Context to create a database. Therefore, we will be creating our new test class in the androidTest folder instead of the test one as we did with previous tests.

Let's open up ActivityLocalDataSourceImpl and create a test file for it in the androidTest folder.

First things first, we will be testing the Room database, which is AppDatabase in this app, as well as the ActivityDao. And we will want to create a new database for each test and close() it after we have done testing it. We can use methods annotated with the @Before and @After for that:

class ActivityLocalDataSourceImplTest { private lateinit var activityDao: ActivityDao private lateinit var database: AppDatabase @Before fun createDb() { } @After fun closeDb() { } }

We won't be reusing this logic outside this test class, so there is no need to create a separate Rule.

To create an instance of a Room database, we will need an application Context.

We can get one using:

InstrumentationRegistry.getInstrumentation().targetContext.applicationContext

One thing to mention is that InstrumentationRegistry has this written in its documentation:

/** * It is generally not recommended for direct use by most tests. */

However, it is used in the auto-generated test that Android Studio kindly provides when creating a new project. Those are very conflicting messages from Google if you ask me.

Anyways, there is also another way to do it:

ApplicationProvider.getApplicationContext()

Which uses InstrumentationRegistry under the hood, so its essentially the same thing:

public static T getApplicationContext() { return (T) InstrumentationRegistry.getInstrumentation() .getTargetContext() .getApplicationContext(); }

You can use whichever approach you want.

Now we can use this Context to create an instance of a Room database. That said, we don't want to create a real database every time we run a test - that would be a bit of an overkill. Luckily, Room provides us with inMemoryDatabaseBuilder API, which builds an in-memory version of the database.

This is all we need to set up our createDb() method:

@Before fun createDb() { val context = ApplicationProvider.getApplicationContext() database = Room.inMemoryDatabaseBuilder(context, AppDatabase::class.java) .build() activityDao = database.activityDao() }

And we should close() it after testing:

@After @Throws(IOException::class) fun closeDb() { database.close() }

With our test database all set up, we can start writing our tests.

Test scenarios

There are three scenarios we would like to test here:

We can save an activity to the database;

We can delete an activity from the database;

We can observe the activity list LiveData.

First test scenario

Let's create a first test that checks if we can save an activity to the database and access it.

We will need to use runTest since we will be using suspend functions, but we don't need our CoroutineRule since we are not in the UI layer anymore and won't be using Dispatchers.Main. The TestScope provided by runTest will be enough. We also don't need to call runCurrent() or advanceUntilIdle() since we are not launching any new coroutines, and the TestScope will wait for its direct children to complete.

Also, keep in mind that files and dependencies are not shared between test and androidTest. Therefore, we cannot use the test models we have set up before.

For the sake of not bloating this article even more (can it even be considered an article at this point?) let's just create a new file inside androidTest with our test models:

// TestAndroidModels.kt val androidActivity1 = Activity( name = "Learn to dance", type = Activity.Type.Recreational, participantCount = 2, price = 0.1f, accessibility = 0.2f, key = "112233", link = "www.dance.com" ) val androidActivity2 = Activity( name = "Pet a dog", type = Activity.Type.Relaxation, participantCount = 1, price = 0.0f, accessibility = 0.1f, key = "223344", link = "www.dog.com" )

If you want to reuse the files, which is a good idea, you can take a look at this StackOverflow question.

Also, as we have discussed previously, we will use regular method naming for androidTest tests.

And here is the finished test:

@Test fun canSaveActivityToTheDbAndReadIt() = runTest { // Arrange val activityLocalDataSource = ActivityLocalDataSourceImpl(activityDao) // Act activityLocalDataSource.saveActivity(androidActivity1) // Assert assert(activityLocalDataSource.isActivitySaved(androidActivity1.key)) }

Note: I did say that test and androidTest modules do not share dependencies, but somehow androidTest knows about org.jetbrains.kotlinx:kotlinx-coroutines-test. It comes from androidx.compose.ui:ui-test-junit4, which is automatically added when creating a new Compose project in Android Studio.

Second test scenario

The second scenario is about deleting an activity from the database.

It is a very similar test to the previous one, so let's just get it out of the way:

@Test fun canDeleteActivityFromTheDb() = runTest { // Arrange val activityLocalDataSource = ActivityLocalDataSourceImpl(activityDao) activityLocalDataSource.saveActivity(androidActivity1) // Act activityLocalDataSource.deleteActivity(androidActivity1) // Assert assert(!activityLocalDataSource.isActivitySaved(androidActivity1.key)) }

Note: saveActivity() is a part of Arrange now. We have a separate test to test that functionality.

Third test scenario

This scenario is more complicated, but it should be a breeze given everything we have learned so far.

We will be testing the LiveData coming straight from the database.

We already know what we need to set up to test LiveData, but first, we need to make sure that we have all required dependencies in androidTest module.

We will be using InstantTaskExecutorRule, so let's add:

// module build.gradle androidTestImplementation "androidx.arch.core:core-testing:$arch_testing_version"

We will also need Mockito. However, the regular mockito-kotlin library we used before cannot mock objects when running on an Android VM. So we need a different library to use Mockito in our Android instrumented tests - mockito-android.

Let's add it to our dependencies:

// project build.gradle mockito_android_version = '4.3.1' // module build.gradle androidTestImplementation "org.mockito:mockito-android:$mockito_android_version"

And just to be able to use Kotlin Mockito functions, let's add mockito-kotlin as well:

androidTestImplementation "org.mockito.kotlin:mockito-kotlin:$mockito_kotlin_version"

Now, with all the dependencies sorted out, we can set up our test file, just as we did in the FavoritesViewModel:

@ExperimentalCoroutinesApi @RunWith(MockitoJUnitRunner::class) class ActivityLocalDataSourceImplTest { @get:Rule val instantExecutorRule = InstantTaskExecutorRule() private val activityListObserver: Observer> = mock() @Captor private lateinit var activityListCaptor: ArgumentCaptor> ... }

And we can now test our LiveData scenario:

@Test fun canSaveActivityToTheDbAndObserveTheLiveData() = runTest { // Arrange val activityLocalDataSource = ActivityLocalDataSourceImpl(activityDao) val expectedList = listOf(androidActivity1, androidActivity2) // Act activityLocalDataSource.getActivityListLiveData() .observeForever(activityListObserver) activityLocalDataSource.saveActivity(androidActivity1) activityLocalDataSource.saveActivity(androidActivity2) // Assert verify(activityListObserver, times(3)).onChanged(activityListCaptor.capture()) assertEquals(activityListCaptor.value, expectedList) }

In this test, we start observing the database when there are no entries. Therefore, our first onChanged event will fire with an empty list. We expect our LiveData to be updated after every save, hence onChanged should be triggered three times. And the final list should contain both activities.

Testing Retrofit with MockWebServer

With the local data source out of the way, it is now time to test our ActivityRemoteDataSource.

We won't be testing Retrofit itself since we have no business testing 3rd party libraries in our code. We will, however, test that our ActivityRemoteDataSource correctly returns expected results, depending on the server response.

For that, we need a server. And folk at square have exactly what we need - a MockWebServer library.

Unlike Room tests, these tests will not depend on the Android framework. Therefore, we will be creating them in the test module.

Let's add a MockWebServer dependency to that:

// project build.gradle okhttp_version = '4.9.3' // module build.gradle testImplementation "com.squareup.okhttp3:mockwebserver:$okhttp_version"

Note: MockWebServer is a part of the okhttp3 library.

After that, we can open up ActivityRemoteDataSourceImpl class and create a new test for it in the test module.

Now, let's add some test responses to a new file TestResponses.kt to keep things tidy:

// TestResponses.kt val successfulResponse = """ { "activity": "Go to a music festival with some friends", "type": "social", "participants": 4, "price": 0.4, "link": "", "key": "6482790", "accessibility": 0.2 } """.trimIndent() val errorResponse = "I am not a json :o"

Let's also add a new Activity model to our TestModels.kt file, which corresponds to the successful response:

// TestModels.kt val responseActivity = Activity( name = "Go to a music festival with some friends", type = Activity.Type.Social, participantCount = 4, price = 0.4f, accessibility = 0.2f, key = "6482790", link = "" )

Creating a MockWebServer is very easy. We just call its constructor. But we have to set up a new instance of Retrofit. I assume that you already know how to do that, so we will not dive into that in detail.

Here is our test file after all the preparations:

@ExperimentalCoroutinesApi class ActivityRemoteDataSourceImplTest { private lateinit var mockWebServer: MockWebServer private lateinit var apiClient: ActivityApiClient private val client = OkHttpClient.Builder().build() private val moshi: Moshi = Moshi.Builder() .add(ActivityTypeAdapter()) .build() @Before fun createServer() { mockWebServer = MockWebServer() apiClient = Retrofit.Builder() .baseUrl(mockWebServer.url("/")) // setting a dummy url .client(client) .addConverterFactory(MoshiConverterFactory.create(moshi).asLenient()) .build() .create(ActivityApiClient::class.java) } @After fun shutdownServer() { mockWebServer.shutdown() } }

We can test responses by creating a MockResponse and programming it in any way we like.

After that, we can enqueue() this response on our mockWebServer.

And that is all we need to start testing our ActivityRemoteDataSource.

We will have two testing scenarios:

Successful response returns Result.Success with an activity;

Error response returns Result.Error.

First test scenario

In the first test, we will test that the correct JSON is parsed successfully into an Activity.

We will need to create a MockResponse that will return our prepared json body and enqueue it. Apart from that, the rest of the test should be really familiar at this point:

@Test fun `correct response is parsed into success result`() = runTest { // Arrange val response = MockResponse() .setBody(successfulResponse) .setResponseCode(200) mockWebServer.enqueue(response) val activityRemoteDataSource = ActivityRemoteDataSourceImpl(apiClient) val expectedActivity = responseActivity // Act val result = activityRemoteDataSource.getActivity() // Assert assert(result is Result.Success) assertEquals((result as Result.Success).data, expectedActivity) }

Second test scenario

To be honest, we can even write two tests in this scenario. One when the response is successful, but JSON is malformed. And the other when the response itself has failed.

These tests will be almost identical to the previous test. The difference is a malformed JSON and 400 response code when we want to simulate a faulty response.

Here are these two tests:

@Test fun `malformed response returns json error result`() = runTest { // Arrange val response = MockResponse() .setBody(errorResponse) .setResponseCode(200) mockWebServer.enqueue(response) val activityRemoteDataSource = ActivityRemoteDataSourceImpl(apiClient) // Act val result = activityRemoteDataSource.getActivity() // Assert assert(result is Result.Error) assert((result as Result.Error).error is JsonDataException) }

@Test fun `error response returns http error result`() = runTest { // Arrange val response = MockResponse() .setBody(errorResponse) .setResponseCode(400) mockWebServer.enqueue(response) val activityRemoteDataSource = ActivityRemoteDataSourceImpl(apiClient) // Act val result = activityRemoteDataSource.getActivity() // Assert assert(result is Result.Error) assert((result as Result.Error).error is HttpException) }

And that is our ActivityRemoteDataSource fully tested. The MockWebServer is a really valuable tool for testing these scenarios, so take advantage of that.

Testing components with injected CoroutineScope and CoroutineDispatcher

Another important testing case that often comes up in Android development is when we have a component that uses either a custom CoroutineScope or switches to a different CoroutineDispatcher.

CoroutineScopes in the presentation layer (viewModelScope and lifecycleScope) use Dispatchec.Main, and we can easily set our own main dispatcher with Dispatchers.setMain(). It is enough for testing coroutines that run on those scopes.

However, if we use, for example, an application-scoped CoroutineScope that runs on Dispatchers.Default, we cannot just replace Dispatchers.Default with our own TestDispatcher.

The same applies to switching to a different CoroutineDispatcher with the withContext() function. For example, if we want to do some network calls on Dispatchers.IO or heavy calculations on Dispatchers.Default.

Note: Libraries like Retrofit and Room switch to a correct dispatcher under the hood, so there is no need to explicitly switch dispatchers for those libraries. Moreover, it can slow down the execution of your requests and queries. However, in the sample project's ActivityRepositoryImpl, I do switch a dispatcher so we can have this test scenario.

Now, before we continue, I want to emphasize that, like any other dependency, you should never hardcode your CoroutineScopes and CoroutineDispatchers. The exception can be made for scopes using Dispathers.Main or switching to Dispatchers.Main since it will not hinder testing for the reasons discussed above. Still, even then it is better to keep the code clean and use dependency injection.

With that out of the way, let's open the ActivityRepositoryImpl class. I have altered this repository a bit so it has both CoroutineScope and CoroutineDispatcher as dependencies, and we can see how we can test it.

When testing scenarios with multiple scopes and dispatchers, the most important thing to keep in mind is that during a test all those scopes and dispatchers must share the same instance of a TestCoroutineScheduler.

Here is a quick overview of the dependencies between TestScope, TestDispatcher and TestCoroutineScheduler:

val testScheduler: TestCoroutineScheduler = TestCoroutineScheduler() val testDispatcher: TestDispatcher = StandardTestDispatcher(testScheduler) val testScope: TestScope = TestScope(testDispatcher)

While passing arguments to any of these constructors is optional, the main takeaway here is that you can pass a TestCoroutineScheduler to a TestDispatcher, and you can pass a TestDispatcher to a TestScope.

That said, given the flexibility of the coroutines API, there are many different ways to make all of our test coroutines run on the same TestCoroutineScheduler.

For example, we can create our own set of these objects as we did in the example above and pass them to our components as needed, while also passing either the TestCoroutineScheduler or the TestDispatcher to the runTest coroutine builder (won't work with TestScope since CoroutineScope is not a CoroutineContext.Element) if needed:

@Test fun `my test` = runTest(testDispatcher) { ... }

But in most cases, it is enough to use the TestScope provided by the runTest coroutine builder, with all its underlying elements.

If we look at the ActivityRepositoryImpl constructor, we need both a CoroutineScope and a CoroutineDispatcher.

Getting a TestScope is quite easy, since the receiver of the runTest coroutine builder is a TestScope that is automatically created for us:

@Test fun `my test`() = runTest { val activityRepository = ActivityRepositoryImpl( appScope = this, .... ) }

Passing the CoroutineDispatcher to our repository is a bit trickier since we don't have access to it. However, we do have access to the CoroutineContext. So if you are familiar with how things work in the coroutine world, getting the TestDispatcher is quite straightforward:

@Test fun `my test`() = runTest { val testDispatcher = coroutineContext[ContinuationInterceptor] as TestDispatcher val activityRepository = ActivityRepositoryImpl( appScope = this, ioDispatcher = testDispatcher, .... ) }

If that line hurts your brain and you have no idea how it works, there are two options.

If you are curious and want to understand what that syntax does, I can refer you to my article about the CoroutineContext.

However, if you think that this is ugly and understandably don't want to see such code again, there is another way we can provide a TestDispatcher to our repository.

As you remember, we have mentioned that the most important part of coroutine testing is the TestCoroutineScheduler. Luckily, a TestScope exposes its scheduler for us to use as we please.

That said, we can just create a new StandardTestDispatcher using the provided TestCoroutineScheduler, which will work just as fine:

@Test fun `my test`() = runTest { val activityRepository = ActivityRepositoryImpl( appScope = this, ioDispatcher = StandardTestDispatcher(testScheduler), ... ) }

Note: testScheduler is a property of the TestScope, which is a receiver for runTest.

Test scenarios

Now that we know how to resolve the dependencies, let's write some tests for the following scenarios:

Calling getNewActivity() returns a result after switching the context;

Calling getNewActivityInANewCoroutine calls remote data source in a separate coroutine.

We can go either with fakes or mocks for these tests, but I prefer creating fakes to have them available and not be too dependent on mocks.

Here are the fakes that I will be using:

class FakeActivityLocalDataSource : ActivityLocalDataSource { override suspend fun saveActivity(activity: Activity) { // Save } override suspend fun deleteActivity(activity: Activity) { // Delete } override suspend fun isActivitySaved(key: String): Boolean { return false } override fun getActivityListLiveData(): LiveData> { return MutableLiveData() } }

class FakeActivityRemoteDataSource : ActivityRemoteDataSource { var getActivityWasCalled = false private set override suspend fun getActivity(): Result { getActivityWasCalled = true return Result.Success(activity1) } }

These fakes are nothing special. We have already covered all the concepts.

First test scenario

Now that we have done all the preparations, writing the first test should be really easy:

@Test fun `getNewActivity() returns a result after switching the context`() = runTest { // Arrange val activityRepository = ActivityRepositoryImpl( appScope = this, ioDispatcher = StandardTestDispatcher(testScheduler), remoteDataSource = FakeActivityRemoteDataSource(), localDataSource = FakeActivityLocalDataSource() ) val expectedActivity = activity1 // Act val result = activityRepository.getNewActivity() // Assert assert(result is Result.Success) assertEquals((result as Result.Success).data, expectedActivity) }

Second test scenario

The second scenario is a bit more tricky, but only because I threw in a delay(1000) into the coroutine to illustrate an important concept. Without it, it would be the same test scenario as others where we launch a new coroutine. We would call activityRepository.getNewActivityInANewCoroutine() and either runCurrent() or advanceUntilIdle() immediately after.

However, when we have a delay(), the runCurrent() method will no longer work.

Physically, a runTest block skips all time delays to execute tests immediately in real-time. However, a TestCoroutineScheduler still keeps track of the virtual time, allowing us to test time-sensitive scenarios.

And that is where an important distinction between runCurrent() and advanceUntilIdle() comes in:

/** * Runs the tasks that are scheduled to execute at this moment of virtual time. */ @ExperimentalCoroutinesApi public fun runCurrent()

The runCurrent() function runs all the current tasks without advancing the virtual time.

/** * Runs the enqueued tasks in the specified order, * advancing the virtual time as needed until there are no more * tasks associated with the dispatchers linked to this scheduler. */ @ExperimentalCoroutinesApi public fun advanceUntilIdle() {

While the advanceUntilIdle function, as its name implies, will advance the virtual time until there are no more tasks.

Note: You can use the advanceTimeBy(delayTimeMillis: Long) function to test time-sensitive scenarios.

With that information in mind, we can now finish writing our test:

@Test fun `getNewActivityInANewCoroutine correctly calls remote data source`() = runTest { // Arrange val fakeRemoteRepository = FakeActivityRemoteDataSource() val activityRepository = ActivityRepositoryImpl( appScope = this, ioDispatcher = StandardTestDispatcher(testScheduler), remoteDataSource = fakeRemoteRepository, localDataSource = FakeActivityLocalDataSource() ) // Act activityRepository.getNewActivityInANewCoroutine() advanceUntilIdle() // Assert assert(fakeRemoteRepository.getActivityWasCalled) }

Wrapping up Unit tests

We have covered most of the topics that will allow you to write any Unit test from now on.

There are still some untested components left in this project, but we will not explicitly cover them in this article since they will be very similar and repetitive. That said, I will include as many tests as it makes sense to write in the finish branch of the project. So you can check that out for further reference.

Writing Integration tests

I feel like there is often confusion about what integration tests are. I have seen people confusing them with Android instrumented tests and, if my memory serves me right, it was even mentioned somewhere in Google documentation that integration tests should be run on a real or emulated device.

To clear the air before we move on, integration tests (again, it's in the name!) are testing the integration between two or more components of an application. And that is their main difference from unit tests, which test some local functionality of a component while replacing all dependencies with mocks and fakes. Depending on the test scenario, we can run them either locally or on a device. That said, it can even be argued that if we are testing how our subject under test is interacting with the mocks, it is a small integration test of sorts.

But let's not get bogged down too much with the semantics.

They are not as important as a properly tested application.

Testing how it all works together

The information we have already discussed while writing unit tests is more than enough to write almost any test. So in this section, we will use everything we have learned so far and write a test that will test everything from a view model to a data source.

We will be testing that when the loadNewActivity() method is called, the ActivityApiClient appropriately calls its getActivity() method.

The approach here is the same as with the Unit tests we have been writing all this time. The only difference is that most of our dependencies will be real implementations.

That said, we will mock the ActivityApiClient since we already have dedicated tests with MockWebServer for that.

Let's create a new test for NewActivityViewModel in the test folder and call it NewActivityViewModelIntegrationTest to distinguish it from the other test class.

Next, we will create instances of real implementations all the way from the presentation layer to the framework layer, with mocks for ActivityApiClient and ActivityDao:

@ExperimentalCoroutinesApi class NewActivityViewModelIntegrationTest { private val testScheduler = TestCoroutineScheduler() private val testDispatcher = StandardTestDispatcher(testScheduler) private val testScope = TestScope(testDispatcher) @get:Rule val coroutineRule = CoroutineRule(testDispatcher) private val mockApiClient: ActivityApiClient = mock() private val mockActivityDao: ActivityDao = mock() private val remoteDataSource = ActivityRemoteDataSourceImpl(mockApiClient) private val localDataSource = ActivityLocalDataSourceImpl(mockActivityDao) private val activityRepository = ActivityRepositoryImpl( appScope = testScope, ioDispatcher = testDispatcher, remoteDataSource = remoteDataSource, localDataSource = localDataSource ) private val getRandomActivity = GetRandomActivityImpl(activityRepository) private val saveActivity = SaveActivityImpl(activityRepository) private val deleteActivity = DeleteActivityImpl(activityRepository) private val isActivitySaved = IsActivitySavedImpl(activityRepository) }

To illustrate other options (and avoid creating all the dependencies from scratch for every test), we are creating all the dependencies as properties of our test class. Because of that, we have created our own TestScope and TestDispatcher to pass into the ApplicationRepository since we are not inside a runTest block anymore. That is also a valid approach for providing scopes and dispatchers to components.

However, the most important thing to mention is that we have to pass our newly created testDispatcher to the CoroutineRule. Otherwise, we will have multiple schedulers, and the tests will fail:

@get:Rule val coroutineRule = CoroutineRule(testDispatcher)

With all the dependencies set up, writing the test itself can't be any easier:

@Test fun `calling loadNewActivity() triggers the api client`() = runTest { // Arrange val viewModel = NewActivityViewModel( getRandomActivity, saveActivity, deleteActivity, isActivitySaved ) // Act viewModel.loadNewActivity() runCurrent() // Assert verify(mockApiClient, times(1)).getActivity() }

Now that you know what integration tests are and how to write them, you can write as many as you want for your application. We will not write any more integration tests in this article since they will be repetitive. Still, you can check the finish branch for more examples.

Writing Jetpack Compose UI tests

When I started writing this article, I had no idea how enormous it would become. I would have probably been too lazy to write it if I knew.

That said, we are on the final stretch, so buckle up.

In this section, we will look into how we can write UI tests for Jetpack Compose.

The approach to writing tests for composables is the same as for regular tests. We can write small unit tests, testing composables in isolation, or medium and large integration tests, testing whole screens of the application.

As before, we will start small and cover all the basics so you can comfortably write Compose UI tests on your own.

Before we start, we will need to set up the dependencies.

Android Studio automatically includes the androidx.compose.ui:ui-test-junit4 library in the Compose projects, so the only one we need to add to be able to run Compose tests is:

debugImplementation("androidx.compose.ui:ui-test-manifest:$compose_version")

Now, let's open up NewActivityScreen.kt and generate a test for it inside the androidTest folder.

One thing we need to do before we can start writing tests is to add a ComposeTestRule. It allows us to set composable content on the screen of our test device.

For testing composables in isolation, we can create ComposeTestRule using createComposeRule() function:

class NewActivityScreenTest { @get:Rule val composeTestRule = createComposeRule() }

Note: We needed the ui-test-manifest dependency for this rule to work properly.

We will look at the scenario of how to test a whole Activity (again, the Android one) later on.

Now that we have our ComposeTestRule let's create a simple test that displays a NewActivityCard and asserts that the title is displayed correctly. Luckily, we already have some test Activity models available in the androidTest folder from testing the database.

To start displaying composables on the device we can use:

composeTestRule.setContent { // Compose world }

So let's compose the NewActivityCard in our test:

@Test fun activityNameDisplayedOnACard() { composeTestRule.setContent { NewActivityCard( modifier = Modifier.fillMaxWidth(), activity = androidActivity1, isFavorite = false, onFavoriteClick = { }, onLinkClick = { } ) } }

This test will now display a NewActivityCard on the screen.

We can also use the ComposeTestRule to make assertions about our composables. But before we do that, we need to understand the concept of semantics in Compose.

Semantics in Compose

In Compose, there is a Composition - a tree-like structure that consists of composables that describe the UI. Parallel to that, there is another tree, called the Semantics tree. It describes the UI in an alternative manner. It gives the UI components semantic meaning that makes UI understandable for accessibility features and testing framework.

Another way to put it is that the Composition contains the information on how to draw the UI components, while the semantics tree contains the information about what those components mean.

When testing Jetpack Compose UI, we will be using the Semantics tree to look up components on the screen and make assertions about them. Therefore, it can be beneficial to visualize how the semantic tree looks for the given UI.

We can do it in tests with the help of ComposeTestRule:

composeTestRule.onRoot().printToLog(tag = "SEMANTICS TREE")

Note: SEMANTICS TREE is just a tag, not a requirement.

It will print all the information about semantic nodes to the debug level logs.

Here is an example of how the semantics tree looks for our NewActivityCard:

Printing with useUnmergedTree = 'false' Node #1 at (l=0.0, t=66.0, r=1080.0, b=878.0)px |-Node #2 at (l=0.0, t=66.0, r=1080.0, b=878.0)px |-Node #3 at (l=66.0, t=128.0, r=277.0, b=180.0)px | Text = '[Recreational]' | Actions = [GetTextLayoutResult] |-Node #4 at (l=937.0, t=121.0, r=1003.0, b=187.0)px | Role = 'Button' | Focused = 'false' | ContentDescription = '[Save Activity]' | Actions = [OnClick] | MergeDescendants = 'true' |-Node #7 at (l=362.0, t=312.0, r=718.0, b=386.0)px | Text = '[Learn to dance]' | Actions = [GetTextLayoutResult] ...

As you can see, we can easily understand what individual UI components do.

For example:

|-Node #4 at (l=937.0, t=121.0, r=1003.0, b=187.0)px | Role = 'Button' | Focused = 'false' | ContentDescription = '[Save Activity]' | Actions = [OnClick] | MergeDescendants = 'true'

We have a button here, which we can click on and save our activity.

Note: If we pass isFavorite = true to our card, the ContentDescription will be [Delete Activity].

To use the semantics tree in our tests, ComposeTestRule has a series of finder onNode() methods that return a SemanticsNodeInteraction:

/** * Represents a semantics node and the path to fetch it * from the semantics tree. One can interact with this node * by performing actions such as [performClick], assertions * such as [assertHasClickAction], or navigate to other nodes * such as [onChildren]. */ class SemanticsNodeInteraction

Here are the examples of assertions we can make on a SemanticsNodeInteraction:

And here are the actions we can perform:

To have this information readily available, here is an awesome Compose testing cheat sheet, prepared by Google.

Now that we understand how to use the semantics tree to write Compose UI tests let's return to our test.

Testing Composables in isolation

Testing nodes with text

With our first test, we want to assert that the activity name is displayed correctly on the card.

For finding a node with a static text we can use ComposeTestRule's onNodeWithText() method. After that we will call assertIsDisplayed() on it.

Here is the final test:

@Test fun activityNameDisplayedOnACard() { composeTestRule.setContent { NewActivityCard( modifier = Modifier.fillMaxWidth(), activity = androidActivity1, isFavorite = false, onFavoriteClick = { }, onLinkClick = { } ) } composeTestRule.onNodeWithText(androidActivity1.name) .assertIsDisplayed() }

Testing nodes with content description

However, not all UI components will have text on them, so we need other means to access their SemanticsNodeInteraction.

One such example is the favorite button, which allows the user to save or delete an activity.

Let's test that this button triggers the onFavoriteClick function.

As we have discussed previously, for interaction with components, especially lambdas, the easiest route is to use Mockito. So let's use it.

This button doesn't have any text, but it does have a content description. That is another way how we can access a node - with ComposeTestRule's onNodeWithContentDescription() method.

The content descriptions are stored in the strings.xml file, so we will need a Context to access them. However, we already know how to get a Context in instrumented tests from the previous examples.

With that in mind, here is our final test:

@Test fun onFavoriteClickCallbackIsTriggered() { val onFavoriteClick: (isFavorite: Boolean) -> Unit = mock() val isFavorite = false composeTestRule.setContent { NewActivityCard( modifier = Modifier.fillMaxWidth(), activity = androidActivity1, isFavorite = isFavorite, onFavoriteClick = onFavoriteClick, onLinkClick = { } ) } val contentDescription = ApplicationProvider.getApplicationContext() .getString(R.string.cd_save_activity) composeTestRule.onNodeWithContentDescription(contentDescription) .performClick() verify(onFavoriteClick, times(1)).invoke(!isFavorite) }

Testing nodes with tags

There is a third option if we can't find our UI components using text or content description.

We can manually add a testTag to our component to find it later. Some people might have a knee-jerk reaction to the notion that we are changing production code to make our tests run, and I would agree with that sentiment.

However, in Jetpack Compose, we sometimes don't have other options, and the toolkit embraces this practice. That's why the ComposeTestRule has a method onNodeWithTag(testTag: String).

In this test, we will test if clicking a link on the activity card triggers the onLinkClick callback. We obviously can use both text and content description to find this node, but let's pretend we can't and use a testTag to find this node in the semantics tree.

First, let's add a Tags object file to our project (not the androidTest module). And add a tag for our link button:

object Tags { const val ActivityLink = "tag_activity_link" }

Note: I am using the Pascal case naming convention for constants since it is used throughout the Compose framework.

Now let's open the NewActivityScreen.kt file and find our TextButton. It should be somewhere around line 138.

To add a test tag to a composable, we need to use Modifier's testTag() method:

TextButton( modifier = Modifier .align(alignment = Alignment.CenterHorizontally) .testTag(Tags.ActivityLink), onClick = { onLinkClick(activity.link) } ) { ... }

And that is it. We can now find this composable as a node in the semantics tree using this tag and use it in our test. All the other concepts should already be familiar.

Here is the finished test:

@Test fun onLinkClickCallbackIsTriggered() { val onLinkClick: (link: String) -> Unit = mock() composeTestRule.setContent { NewActivityCard( modifier = Modifier.fillMaxWidth(), activity = androidActivity1, isFavorite = false, onFavoriteClick = { }, onLinkClick = onLinkClick ) } composeTestRule.onNodeWithTag(Tags.ActivityLink) .performClick() verify(onLinkClick, times(1)).invoke(androidActivity1.link) }

Large UI Compose tests with Hilt

To finish this article with a bang, we will write a large UI test for the whole application. But there is one more crucial part of Android testing that we haven't yet discussed.

Testing dependency injection with Hilt.

Luckily, we can do that in this test and end on a double bang instead.

Here are the steps that we will replicate with this UI test:

Open the app and wait for an activity to load;

Click refresh and wait for a new activity to load;

Click save to favorites;

Go to the Favorites screen and ensure that the saved activity is in the list;

Click delete and ensure that the activity is no longer in the list;

Assert that the "no saved activities" info message is displayed.

Moreover, our test will use Hilt to inject dependencies. We will swap the ActivityApiClient for a test ApiClient using the MockWebServer, and the Room database for an in-memory instance.

Setting up Hilt testing

Let's start by adding Hilt testing dependencies to our project:

androidTestImplementation "com.google.dagger:hilt-android-testing:$hilt_version" kaptAndroidTest "com.google.dagger:hilt-android-compiler:$hilt_version"

Now, let's create a new test for BoredomBusterApp.kt Composable.

First, we have to annotate this test with @HiltAndroidTest annotation, which will generate the Hilt components. Second, we need to add a HiltAndroidRule and pass our test instance to it:

@HiltAndroidTest class BoredomBusterAppTest { @get:Rule val hiltRule = HiltAndroidRule(this) }

With that out of the way, to use Hilt in tests, we need an Application class that supports Hilt. Since our app doesn't need anything from our own Application class, we can use HiltTestApplication provided by hilt-android-testing library. However, if you need to use a custom application class, there is a solution in the official documentation.

The next step is to set up a custom runner, which will set up this application for tests. It sounds scary, but it really isn't.

Let's create a new di package inside the androidTest module and add a HiltTestRunner class to it:

class HiltTestRunner : AndroidJUnitRunner() { override fun newApplication( classLoader: ClassLoader?, name: String?, context: Context? ): Application { return super.newApplication( classLoader, HiltTestApplication::class.java.name, context ) } }

Now all we have to do is to open the module-level build.gradle file and replace the existing testInstrumentationRunner inside defaultConfig with our new one:

testInstrumentationRunner "eu.maxkim.boredombuster.di.HiltTestRunner"

Replacing Hilt modules for tests

We have two options if we want to replace the production Hilt bindings with test ones. We can either replace the whole Hilt module containing the bindings or bind fake components for each test individually.

We will discuss the first scenario. However, if you only want to swap bindings for individual tests, it is quite simple to do. For that, refer to the Hilt testing documentation. But keep in mind that the second approach can noticeably slow down the execution of your tests.

We will start by replacing the DbModule containing AppDatabase and ActivityDao bindings.

Let's create a new object TestDbModule inside the di package we have just created and annotate it with @Module.

Next, we have to specify in which component to install this module, just like we do with @InstallIn in production modules, and specify which module to replace. We can achieve both these goals with the @TestInstallIn annotation, which we can use as follows:

@Module @TestInstallIn( components = [SingletonComponent::class], replaces = [DbModule::class] ) object TestDbModule { }

Apart from that, it is just a regular Hilt module, and we can just provide our dependencies. We have already looked at how to create an in-memory Room database, so here is the final code:

@Module @TestInstallIn( components = [SingletonComponent::class], replaces = [DbModule::class] ) object TestDbModule { @Provides @Singleton fun provideRoom(@ApplicationContext context: Context): AppDatabase { return Room.inMemoryDatabaseBuilder( context, AppDatabase::class.java ).build() } @Provides @Singleton fun provideActivityDao(appDatabase: AppDatabase): ActivityDao { return appDatabase.activityDao() } }

Next, we will replace the NetworkModule. While everything stays the same as when we used the MockWebServer for testing ActivityRemoteDataSourceImpl, we have to make some additional considerations since we will be running our UI test on a real Android system.

Before we start, we need to add the MockWebServer library as a dependency to androidTest module:

androidTestImplementation "com.squareup.okhttp3:mockwebserver:$okhttp_version"

However, there is one problem. When running a MockWebServer in the instrumented tests, this newer version will conflict with Retrofit's older okhttp3 version. I am a bit puzzled why this wasn't an issue when running local tests, but I will think about it some other day.

That said, the easiest way to resolve this problem is to force a newer version of the okhttp library by adding a resolution strategy to the end of the module-level build.gradle file:

dependencies { ... } configurations.all { resolutionStrategy { force "com.squareup.okhttp3:okhttp:$okhttp_version" } }

With that out of the way, the next issue is that the mockWebServer.url("/") method that we used for passing a base URL to the Retrofit is considered a network operation. And as you most certainly are aware, Android restricts using network operations on the main thread.

Switching threads in a Hilt modules is not a trivial matter, so I used the solution provided in this medium article:

@Provides @Singleton @BaseUrl fun provideBaseUrl(mockWebServer:MockWebServer): String { var url = "" val thread = Thread { url = mockWebServer.url("/").toString() } thread.start() thread.join() return url }

Now, let's finish our TestNetworkModule, which replaces the NetworkModule and provides an ActivityApiClient that uses the MockWebServer.

Here is the final code:

@Module @TestInstallIn( components = [SingletonComponent::class], replaces = [NetworkModule::class] ) object TestNetworkModule { @Provides @Singleton fun provideOkHttpClient(): OkHttpClient { return OkHttpClient.Builder().build() } @Provides @Singleton fun provideMockServer(): MockWebServer { return MockWebServer() } /** * We need to jump through the hoops a bit * to avoid NetworkOnMainThread exception * in our UI tests. */ @Provides @Singleton @BaseUrl fun provideBaseUrl(mockWebServer:MockWebServer): String { var url = "" val thread = Thread { url = mockWebServer.url("/").toString() } thread.start() thread.join() return url } @Provides @Singleton fun provideMoshi(): Moshi { return Moshi.Builder().add(ActivityTypeAdapter()).build() } @Provides @Singleton fun provideRetrofit( okHttpClient: OkHttpClient, moshi: Moshi, @BaseUrl baseUrl: String ): Retrofit { return Retrofit.Builder() .baseUrl(baseUrl) .client(okHttpClient) .addConverterFactory(MoshiConverterFactory.create(moshi).asLenient()) .build() } @Provides @Singleton fun provideApiClient(retrofit: Retrofit): ActivityApiClient { return retrofit.create(ActivityApiClient::class.java) } }

However, we are not done with network issues in tests yet. But this will be the last one, I promise.

Now the problem is that we are not using any encryption for our MockWebServer, and starting with Android 9, the cleartext communication is disabled by default for network security reasons.

Since we don't need this security level for debug builds that UI test use, the easiest fix is to enable cleartext traffic for debug builds while leaving it off for production builds.

To achieve that, we need to create a new /debug folder inside the /src and add a new debug AndroidManifest.xml file, which will be merged with the real one for debug builds.

We only need to change one flag in the debug manifest:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" package="eu.maxkim.boredombuster"> <application android:usesCleartextTraffic="true" tools:ignore="MissingApplicationIcon,UnusedAttribute" /> manifest>

We are now ready to use our test Hilt bindings in UI tests. Hilt will automatically inject them as dependencies where needed.

And if we want to inject a component directly into the test, it works just like in Android components. We can use @Inject annotation with a lateinit property.

However, to populate those properties, we need to call hiltRule.inject().

Let's add mockWebServer and database instances to our test to see how it works, and clean them up after testing for good measure:

@HiltAndroidTest class BoredomBusterAppTest { @get:Rule val hiltRule = HiltAndroidRule(this) @Inject lateinit var mockWebServer: MockWebServer @Inject lateinit var database: AppDatabase @Before fun init() { hiltRule.inject() } @After fun tearDown() { mockWebServer.shutdown() database.close() } }

Preparing test models

As we have mentioned before, there are ways to share files between test and androidTest if you want to, but for now, let's create a TestAndroidResponses.kt file in the androidTest module and put some test responses in it:

// TestAndroidResponses.kt val successfulAndroidResponse1 = """ { "activity": "Go to a music festival with some friends", "type": "social", "participants": 4, "price": 0.4, "link": "", "key": "6482790", "accessibility": 0.2 } """.trimIndent() val successfulAndroidResponse2 = """ { "activity": "Learn how to use a french press", "type": "recreational", "participants": 1, "price": 0.3, "link": "https://en.wikipedia.org/wiki/French_press", "key": "4522866", "accessibility": 0.3 } """.trimIndent()

Also, let's add the parsed versions to our TestAndroidModels.kt file:

// TestAndroidModels.kt val responseAndroidActivity1 = Activity( name = "Go to a music festival with some friends", type = Activity.Type.Social, participantCount = 4, price = 0.4f, accessibility = 0.2f, key = "6482790", link = "" ) val responseAndroidActivity2 = Activity( name = "Learn how to use a french press", type = Activity.Type.Recreational, participantCount = 1, price = 0.3f, accessibility = 0.3f, key = "4522866", link = "https://en.wikipedia.org/wiki/French_press" )

Testing Compose Activity

With all the preparations out of the way, we can now start testing our MainActivity.

For testing composables in isolation we were creating a ComposeTestRule with the createComposeRule() function.

However, we need to create an AndroidComposeTestRule for testing Android activities. We can do it with a handy function createAndroidComposeRule(), which takes an Activity as a type.

We will use that to create our compose rule, but we also want to ensure that the Hilt rule is always applied first. We can do it by adding an order argument to our Rules.

Here is how our rules look after setting everything up:

@HiltAndroidTest class BoredomBusterAppTest { @get:Rule(order = 1) val hiltRule = HiltAndroidRule(this) @get:Rule(order = 2) val composeTestRule = createAndroidComposeRule() ... }

Now we can finally write the test itself.

When writing large end-to-end UI tests, we usually still test concrete scenarios. But just to illustrate the concept, we will write a test that clicks all over the app and call it a day (finally!).

When using createAndroidComposeRule() we don't need to call setContent() ourselves anymore, since it will create our MainActivity for us.

Another important concept when UI testing the whole app is that we will probably need to wait for stuff to appear.

There is a convenient ComposeTestRule method for that, which we can use to wait until the activity card appears on the screen after loading:

fun waitUntil(timeoutMillis: Long!, condition: (() -> Boolean)?): Unit

It will just wait around (not quite, but we will discuss it later) until the given condition is satisfied. We can also specify the timeout after which the test will fail. By default, the timeout is 1000ms.

In our case, after loading a new activity, we will wait around until the node with activity's name appears on the screen. And to make things a bit cleaner, we will extract this logic in a separate method:

private fun waitUntilVisibleWithText(text: String) { composeTestRule.waitUntil { composeTestRule.onAllNodesWithText(text) .fetchSemanticsNodes().size == 1 } }

This method will just wait around until there is at least one node with the given text.

To make our test more readable, let's extract all the interactions into separate private methods, which we will also be able to use in other tests if we wish.

For example, we can create a method that clicks on a node with a content description:

private fun clickOnNodeWithContentDescription(@StringRes cdRes: Int) { val contentDescription = ApplicationProvider.getApplicationContext() .getString(cdRes) composeTestRule.onNodeWithContentDescription(contentDescription) .performClick() }

And use it in a bunch of action methods for our test:

private fun saveAsFavorite() { clickOnNodeWithContentDescription(R.string.cd_save_activity) } private fun deleteFromFavorites() { clickOnNodeWithContentDescription(R.string.cd_delete_activity) } private fun refreshActivity() { clickOnNodeWithContentDescription(R.string.cd_refresh_activity) }

To add methods for switching between bottom navigation tabs, let's add some new tags:

object Tags { ... const val ActivityTab = "tag_activity_tab" const val FavoritesTab = "tag_favorites_tab" }

And add them to the BottomNavigationBar.kt:

listOf( Destination.Activity, Destination.Favorites ).forEach { destination -> val testTag = when (destination) { Destination.Activity -> Tags.ActivityTab Destination.Favorites -> Tags.FavoritesTab else -> "" } BottomNavigationItem( modifier = Modifier.testTag(testTag), ...

Now we can find these nodes and click on them for navigation:

private fun navigateToFavorites() { composeTestRule.onNodeWithTag(Tags.FavoritesTab) .performClick() } private fun navigateToActivity() { composeTestRule.onNodeWithTag(Tags.ActivityTab) .performClick() }

Lastly, let's add a method to enqueue an activity json on our MockWebServer:

private fun enqueueActivityResponse(activityJson: String) { mockWebServer.enqueue( MockResponse() .setResponseCode(200) .addHeader("Content-Type", "application/json; charset=utf-8") .setBody(activityJson) ) }

Now we have everything we need to test the scenario outlined at the beginning of this section.

Here is the final test:

@Test fun refreshingSavingAndDeletingWorksCorrectly() { enqueueActivityResponse(successfulAndroidResponse1) waitUntilVisibleWithText(responseAndroidActivity1.name) enqueueActivityResponse(successfulAndroidResponse2) refreshActivity() waitUntilVisibleWithText(responseAndroidActivity2.name) saveAsFavorite() navigateToFavorites() composeTestRule.onNodeWithText(responseAndroidActivity2.name) .assertIsDisplayed() deleteFromFavorites() composeTestRule.onNodeWithText(responseAndroidActivity2.name) .assertDoesNotExist() val noActivitiesMessage = ApplicationProvider.getApplicationContext() .getString(R.string.message_empty_activity_list) composeTestRule.onNodeWithText(noActivitiesMessage) .assertIsDisplayed() }

Other considerations when testing Compose

Jetpack Compose is a huge toolkit, and obviously, we didn't cover every aspect of it when it comes to testing.

However, before we part our ways, here are some pointers that might be useful for testing more complex scenarios with Compose.

Using unmerged tree

Sometimes nodes merge together the semantic information about their children, for example, if two Text composables are composed side-by-side.

First of all, remember that you can always see how your semantics tree looks for debugging:

composeTestRule.onRoot().printToLog("TAG")

Secondly, all the finder methods have a useUnmergedTree argument, which you can use to search the unmerged version of the semantics tree:

composeTestRule.onNodeWithText("My Text", useUnmergedTree = true) .assertIsDisplayed()

Synchronization

Just like the test coroutine builder, the Compose doesn't run in real-time during the tests and has a virtual clock.

During tests, when the UI state of a composable changes it doesn't automatically trigger recomposition as it would when running the app normally.

The advancement of virtual clock and recomposition is usually triggered by the assertion methods on a SemanticsNodeInteraction. Likewise, methods like waitUntil will advance the clock frame by frame if the main clock is in the autoAdvance mode.

Speaking of which, if you would like to take manual control of the main clock, you can set autoAdvance to false:

composeTestRule.mainClock.autoAdvance = false

This will allow you to control the main clock manually by using methods like:

composeTestRule.mainClock.advanceTimeByFrame() composeTestRule.mainClock.advanceTimeBy(milliseconds)

The are some other nuances with synchronization in Compose, so if you are interested in this topic, please refer to the official documentation.

Custom semantic properties

You can create your own semantic properties to expose for your tests if you want. You can read about that in the official documentation.

UI tests with Compose and Views

If you have a hybrid UI app that uses both Compose and the View system, you can write tests that combine Espresso and ComposeTestRule. No additional setup is needed. You can just use them together in your tests.

Conclusion

When I first set out to write this article, I was sure that it would take no more than a couple of evenings. However, it turns out that testing Android applications is quite a big topic, and there is a lot of ground to cover.

Hopefully, I have discussed the most common scenarios, and this information is a good start for writing all kinds of tests for your Android apps.

Once again, you can find everything that we have talked about on GitHub in the finish branch. I will throw some more tests in there as well for reference.

If you have any questions about testing or Android development in general, or if you think I missed some crucial aspects of testing, feel free to leave your comments. I would appreciate the feedback.

See you next time.

Your friend,

Max

Things every Kotlin Developer should know about Coroutines. Part 5: Cancellation.

Max Kim — Fri, 14 Jan 2022 17:00:57 GMT

As much as we had talked about cancellation in the last part, in this article, we will often touch upon exception handling. Since, as discussed previously, these two concepts use the same mechanism.

That said, cancellation in the coroutines library is not as straightforward as it might seem. Misusing it can produce subtle bugs and puzzle developers unfamiliar with its inner workings.

So let’s get cracking.

Cancelling a coroutine

Like with exception propagation, cancellation in coroutines is managed by a Job. Moreover, cancellation is nothing more than throwing a CancellationException. The critical distinction here is that if a coroutine throws a CancellationException, it is considered to have been cancelled normally, while any other exception is considered a failure.

Another difference is that while a regular exception in a child coroutine will trigger the cancellation of its parent (unless it’s using a SupervisorJob), the CancellationException will not.

Now, let’s see how that works in practice.

First of all, a Job is our handle to a coroutine, and it has a lifecycle. If you are not familiar with the lifecycle of a Job, please refer to the Part 4 of this series.

We can cancel a coroutine by calling the .cancel() function on its Job.

/** * Cancels this job with an optional cancellation[cause]. * A cause can be used to specify an error message * or to provide other details on * the cancellation reason for debugging purposes. */ public fun cancel(cause: CancellationException? = null)

You can also specify a cause for cancellation, but it has to be a subtype of the CancellationException and, therefore, it will always lead to normal cancellation.

When you call .cancel() on a Job, it triggers the following events:

The Job goes into the Cancelling state and cannot be used as a parent to new coroutines or do suspending work anymore;

At the first suspension point that cooperates with cancellation (or after manually calling ensureActive(), more on that later), a CancellationException is thrown, prompting the cancellation of all children, but not its parent;

After all the children are cancelled, the Job moves to the Cancelled state.

Both CoroutineScope and CoroutineContext have an extension function .cancel(cause: CancellationException? = null). These functions just get a Job from the corresponding context and call .cancel(cause) on that.

Here is a simple example of how cancellation works:

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) fun main(): Unit = runBlocking { val parentJob = scope.launch { println("Starting the parent job!") launch { while (isActive) { delay(10) println("Doing some work...") } }.invokeOnCompletion { println("Cancelling all work! ") } } parentJob.invokeOnCompletion { println("The parent job is cancelled!") } delay(50) parentJob.cancel() // Take note of this delay!!! delay(100) println("Main is done!") } Output: Starting the parent job! Doing some work... Doing some work... Doing some work... Doing some work... Cancelling all work! The parent job is cancelled! Main is done!

We have a parent coroutine with a long-running child coroutine in this example. After some time, we cancel the parentJob, which cancels both parent and child coroutines as expected.

However, as we now know, calling .cancel() doesn't stop a Job dead in its tracks but only triggers the beginning of cancellation. Therefore if we removed the delay(100) after cancelling our job, we would get the following output:

Starting the parent job! Doing some work... Doing some work... Doing some work... Doing some work... Main is done! <- This is printed immediately! Cancelling all work! The parent job is cancelled!

“Main is done!” is printed immediately after calling .cancel() because the parent runBlocking coroutine will continue its execution, while the cancellation of the parentJob will proceed asynchronously.

In this case, we are lucky that cancellation is almost immediate, and we get all the messages printed out. However, since our parent coroutine is not a child of runBlocking, the structured concurrency principle does not apply, and the runBlocking coroutine will not wait for the cancellation to complete.

If we are not careful with such cancellations, it could lead to subtle bugs and race conditions.

That said, we have used the .delay() function for illustration purposes only. It is a horrible solution to this problem in actual code.

The proper way to wait for a Job’s completion is to call job.join().

The .join() function will suspend the calling coroutine until the joined Job is fully completed. Keep in mind that .join() will always continue normally, regardless of how the joined Job has been completed, as long as the Job of the calling coroutine is active.

Here is how the proper cancellation of the parentJob in our example would look like:

parentJob.cancel() parentJob.join() println("Main is done!")

Moreover, this is such a common practice in coroutines that the library offers an extension function Job.cancelAndJoin(), which does precisely that - calls .cancel() and .join() immediately afterward.

parentJob.cancelAndJoin() println("Main is done!")

By calling cancelAndJoin(), we are cancelling our job and suspending the calling coroutine until the job has finished all the cancellation work.

Understanding suspension points

As stated earlier, the CancellationException is generally thrown at the first suspension point that cooperates with cancellation.

While a suspension point doesn’t necessarily mean your code will automatically cooperate with cancellation, all suspend functions (with one exception that I am aware of, which we will discuss in a bit) from the coroutines library are safe to cancel. Therefore, it is crucial to quickly identify them in your code to avoid redundant cooperation with cancellation.

The easiest way to identify suspension points is with help from the IDE. If you are writing Kotlin code, chances are you are using an IntelliJ IDEA based IDE, in which case suspension points are conveniently displayed in the gutter:

IntelliJ IDEA marks every call to a suspend function with a special arrow symbol.

While every suspend function in the coroutines library is a valid suspension point and is cancellable, marking your own functions with the suspend modifier does not mean it will necessarily suspend a coroutine or make it cancellable.

Here is an example:

suspend fun doStuff() { println("I do stuff!") }

This function does not have any suspension points, and the IDE will warn you about the redundant suspend modifier. That said, if you call this function, the IDE will display the suspension symbol in the gutter regardless.

For every rule, there is an exception

While the example above doesn’t support cancellation because we wrote a lousy suspend function, there is a case when cancellation is not supported by a suspending function from the coroutines library by design.

This exception is the suspendCoroutine function. Diving deep into the specifics of this function is out of the scope of this article. Still, it suspends current execution and runs a non-suspend block, allowing to explicitly continue the coroutine execution with a series of callbacks.

This functionality is needed to bridge the suspending world with other asynchronous solutions. However, there is a better function for that, which we will discuss in a minute.

For now, let’s take a look at this example:

private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) fun main() = runBlocking { val job: Job = scope.launch { while (true) { doStuff() } } delay(5) println("Cancelling the job!") job.cancelAndJoin() println("Main is done!") } suspend fun doStuff() { // this is proper suspension point // but it will not throw a // CancellationException suspendCoroutine<Unit> { continuation -> continuation.resume(Unit) } println("I do stuff!") }

If we run this code, we will get:

... I do stuff! I do stuff! I do stuff! ... // Forever and ever, since we have // joined the job after cancel
This job will never get cancelled, and the runBlocking coroutine will continue waiting indefinitely since we have joined the cancelled Job.

This function is not cancellable because there is a very similar function - suspendCancellableCoroutine, which, as its name suggests, supports cancellation while providing the same functionality.

Here is the adjusted doStuff() function:

suspend fun doStuff() { suspendCancellableCoroutine<Unit> { continuation -> continuation.resume(Unit) } println("I do stuff!") }

Now, if we rerun the code, we will get a desired and predictable outcome:

... I do stuff! I do stuff! Cancelling the job! I do stuff! I do stuff! ... Main is done!
In this case, a suspendCancellableCoroutine will throw a CancellationException at its suspension point as soon as the Job gets cancelled, just as it should.

We can also achieve the same correct cancellation behavior by calling any other suspend function from the coroutines library (or that cooperates with cancellation), for example, delay(1).

Because of this behavior, there is little reason to use suspendCoroutine - a suspendCancellableCoroutine is always a safer option. Apart from cooperation with cancellation, suspendCancellableCoroutine provides a invokeOnCancellation { } callback that can be used to clean up resources.

That said, given that these functions are primarily used to write adapters to other asynchronous libraries, you will probably never use them. Almost all adapters you would ever need are already provided by either the coroutines team or the libraries' authors.

However, it is still important to be aware of this behavior for learning purposes.

Cooperating with cancellation

While suspend functions coming from the coroutines library are safe to cancel, you should always think about cooperating with cancellation when writing your own code.

There are a couple of ways to do that.

Checking the state of a Job

One way to make your code cancellable is to explicitly check the current Job's state.

The most convenient way to do this is by using the CoroutineScope.isActive extension property.

We have done it numerous times in examples throughout this series with while (isActive) loops.

Example:

scope.launch { // a periodical work while (isActive) { // do work delay(1000) } }

There is a similar extension CoroutineContext.isActive, which works exactly the same way. Both these functions check the isActive property on the underlying Job.

Also, keep in mind that you can also check the isCancelled property if you have a reference to the Job. However, in most cases it is redundant and there are no corresponding extension functions for either CoroutineScope or CoroutineContext.

ensureActive()

Another common way to check for cancellation is to call ensureActive(), which is an extension function available for Job, CoroutineScope, and CoroutineContext.

This function is a great option for cases where you would otherwise write a if (isActive) statement. Moreover, under the hood ensureActive does just that, but it also throws a CancellationException for good measure:

public fun Job.ensureActive(): Unit { if (!isActive) throw getCancellationException() }

Note: This function uses getCancellationException() to include the original cause of cancellation.

Just like the isActive check, ensureActive() is mostly used inside coroutines.

Example:

scope.launch { // a long running for loop // without suspension points for (item in items) { ensureActive() println("Processing item...") } }

Alternatively, you can use ensureActive() on a coroutineContext inside suspend functions, since, as opposed to checking isActive, it throws a CancellationException and will stop the execution:

suspend fun doSomeWork() { // do some work coroutineContext.ensureActive() // do some more work }

yield()

From the documentation: Yields the thread (or thread pool) of the current coroutine dispatcher to other coroutines on the same dispatcher to run if possible.

The purpose of the yield() function is to free up the current thread to allow other coroutines to run on it. In practice, it suspends current execution and immediately resumes it.

In general, any suspended coroutine is not guaranteed to resume running on the same thread if the dispatcher allows it.

It can be beneficial to use yield() during CPU heavy work or during work that can exhaust the thread pool.

However, it is also common practice to use yield() to cooperate with cancellation.

Example:

suspend fun doHeavyWork() { withContext(Dispatchers.Default) { repeat(1000) { yield() // do heavy work } } }

It can also be used in coroutines instead of ensureActive() if you need the added benefit of yielding the thread.

Cleaning up

Sometimes you have to clean up resources when a coroutine is cancelled. Luckily, it is quite easy, since cancellation throws a CancellationException and like any other exception, we can catch it in a try-catch block and do necessary clean up in a finally block.

However, before we discuss cleaning up in more detail, I want to address a common mistake that can be overlooked when using a try-catch block in coroutines.

Interrupted cancellation

Take a look at the following example:

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) fun main() = runBlocking { val job = scope.launch { try { println("Doing work...") delay(Long.MAX_VALUE) } catch (e: Exception) { println("The work was interrupted!") } println("How am I still running?") } delay(100) job.cancelAndJoin() println("Main is done!") } Output: Doing work... The work was interrupted! How am I still running? Main is done!

As you see, even though we cancel our Job, it still completes until the end.

Let’s break down why this happens.

When we call job.cancelAndJoin() the job goes into the Cancelling state, and since at that moment the coroutine is suspended by delay(Long.MAX_VALUE), which is a cancellable suspend function, this suspension point throws a CancellationException.

Since it is a sub-type of Exception, we catch it inside the try-catch block and handle it manually.

After that, the coroutine will continue its execution, albeit in the Cancelling state. It means that for it to throw another CancellationException, it has to reach another suspension point. And given that in our example we don’t have any after the try-catch block, and we don’t explicitly check for cancellation, the coroutine will run all the way until the end.

This is a consequence of managing explicit cancellation with exceptions, and we have to be aware of this.

If we know that our coroutine can be explicitly cancelled and we are using a try-catch block, the common practice is to always rethrow a CancellatonException.

try { println("Doing work...") delay(Long.MAX_VALUE) } catch (e: Exception) { println("The work was interrupted!") if (e is CancellationException) { throw e } }

With this adjustment in place, our coroutine will get cancelled as expected:

Output: Doing work... The work was interrupted! Main is done!
Tools for cleaning up

With that little detail out of the way, let’s take a look at how we can go about cleaning up resources after cancellation.

If we need to do clean up in case of a cancellation only, we can catch a CancellationException and do necessary work inside the catch block:

try { println("Doing work...") delay(Long.MAX_VALUE) } catch (e: CancellationException) { // do clean up // and don't forget to rethrow the CancellationException throw e }

Alternatively, we can do clean up regardless of the outcome, using a finally block:

try { println("Doing work...") delay(Long.MAX_VALUE) } finally { // do clean up }

That said, there is a catch (as there always seems to be with the coroutines library).

At this point, our Job is in the Cancelling state, which means it can no longer suspend execution. Therefore, any attempt to call a suspend function, for example, inside the finally block, will throw another CancellationException. Still, we might need to run some suspending functions as a part of a clean-up logic after cancellation.

Luckily, the coroutines library has a tool that allows doing just that - a special Job called NonCancellable.

The NonCancellable job is always active and is designed for use with the withContext function to handle cases as described above. withContext(NonCancellable) will switch to this non-cancellable job before checking for cancellation. Therefore it can be called even from a cancelled coroutine.

That said, let’s summarise everything we have learned about cleaning up with the following example:

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) fun main() = runBlocking { val job = scope.launch { try { println("Doing work...") delay(Long.MAX_VALUE) } catch (e: CancellationException) { println("The work was cancelled!") throw e } finally { withContext(NonCancellable) { delay(1000) println("Did some suspending clean up") } println("Clean up is done!") } println("I will never be printed...") } delay(100) job.cancelAndJoin() println("Main is done!") } Output: Doing work... The work was cancelled! // delaying 1 sec Did some suspending clean up Clean up is done! Main is done!

A word of caution, however. Since NonCancellable is a Job, it can be used as a part of any CoroutineContext given its flexible API. But it was designed for use with the withContext function only. So using it with coroutine builders launch or async (you should never use any Job there anyways, as described in Part 3 of this series) will break structured concurrency in every possible way and should never be done.

Cancellation after a timeout

In some cases, you might want to cancel some work after a timeout. For that, the coroutines library provides a very convenient function withTimeout. Here’s its declaration:

public suspend fun withTimeout(timeMillis: Long, block: suspend CoroutineScope.() -> T): T

It runs a suspending block, and after a specified timeout, it throws a TimeoutCancellationException, a subtype of CancellationException.

There is also a less aggressive version of this function - withTimeoutOrNull, which after a specified timeout, cancels its block and returns null without throwing an exception.

These functions are suspending scope functions by nature. They provide a scope just like coroutineScope, supervisorScope, and withContext functions. To be more specific, it will behave exactly like a coroutineScope function, only with a timeout.

Example:

fun main(): Unit = runBlocking { launch { try { withTimeout(100) { delay(400) } } catch (e: TimeoutCancellationException) { println("The coroutine has timed out!") } } } Output: The coroutine has timed out!

When using the withTimeout function, after the timeout, it will cancel the parent coroutine (which will also cancel all its children) if the exception wasn’t explicitly handled. If you want other behavior or a better clean-up logic without using try-catch, consider using withTimeoutOrNull instead.

Conclusion

The concept of cooperative cancellation is not something we have to deal with often in other asynchronous solutions. Therefore, it might prove challenging to newcomers and seasoned developers alike.

Neglecting basic principles of cooperative cancellation can lead to memory leaks, wasted resources, and subtle bugs. Because of that, it might seem that it is too much hassle for a feature that shouldn’t be that complicated.

And it is a fair point. The coroutines library has quite a steep learning curve.

However, in my opinion, the resulting API of launching coroutines and elegant solution to establishing parent-child relationships is something that JetBrains deserve an applaud for, and it is a fair trade-off, all things considered.

That said, I have a couple of topic ideas for the next part of this series, but I will have to sleep on that, so no promises.

See you next time.

Your friend,

Max

Things every Kotlin Developer should know about Coroutines. Part 4: Exception Handling.

Max Kim — Wed, 05 Jan 2022 19:28:23 GMT

In Part 3, we have discussed structured concurrency, which was introduced to the coroutines library primarily as a solution to exception handling and cancellation.

Because of that, these two concepts go hand in hand, and even though we will not focus on cancellation just yet, we will inevitably mention it throughout this article since both of them share the same mechanism.

That mechanism is a Job. It enforces structured concurrency by creating parent-child relationships between coroutines and manages exception propagation and cancellation.

Therefore, before talking about exception handling, we should understand what a Job is and how it works.

Lifecycle of a Job

A Job is an entity with a lifecycle that acts as a handle to a coroutine. Every coroutine's Job goes through several states that culminate in its completion.

The lifecycle of a Job looks like this:

A Job has six states which fall under three main categories:

Initial state - New, Active

Transient state - Completing, Cancelling

Final state - Completed, Cancelled

A launched coroutine immediately goes into the Active state, unless an optional parameter start = CoroutineStart.LAZY is passed to the coroutine builder, in which case it starts in the New state.

A Job in the New state can be started and moved to the Active state by either calling job.start() or job.join().

When a coroutine has finished its work, it goes to the Completing state, where it awaits the completion of all its children - which, as you now know, is an integral part of the structured concurrency principle.

If an exception or cancellation happens during either the Active or Completing state, the Job moves to the Cancelling state, where it awaits the cancellation of all its children.

After all the children have finished or are cancelled, the Job moves to either the Completed or Cancelled state.

Note that these states are not publicly exposed. To find out the state of a Job we can use public properties isActive, isCancelled, and isCompleted.

Exception propagation

Now that we understand the lifecycle of a Job, let’s talk about exception propagation. It works as follows:

If a child coroutine fails, it propagates the exception to its parent.

The parent cancels itself and consequently cancels all its children. The parent will wait in the Cancelling state until all the children are cancelled.

The parent propagates the exception up to its parent or throws the exception if it is a root coroutine and the exception was not caught.

Both exception propagation and cancellation work the same way. Moreover, both are just cancellation with a cause of type Throwable, where an explicit cancellation by the user throws a CancellationException, which gets special treatment.

The actual implementation of this mechanism is quite complex, but here is an example from the source code for illustration:

/** * ... * Returns `true` if exception is handled, `false` otherwise * (then caller is responsible for handling an exception) * ... */ public open fun childCancelled(cause: Throwable): Boolean { if (cause is CancellationException) return true return cancelImpl(cause) && handlesException }

Whenever a child coroutine is cancelled, the parent first checks whether it was cancelled with a CancellationException, in which case it returns true, meaning that the exception is handled and there is nothing more to do. Otherwise, it will process and propagate the exception.

Let’s see, how it works in practice:

val scope = CoroutineScope(Job() + Dispatchers.Default) fun main(): Unit = runBlocking { // Main Job scope.launch { // Child 1 launch { while (isActive) { // run } }.printOnComplete("Child 1 is cancelled!") // Child 2 launch { delay(500) println("Here goes boom...") throw IllegalArgumentException("Boom!") }.printOnComplete("Child 2 is cancelled!") }.printOnComplete("Main Job has completed!") // Random coroutine on the same scope scope.launch { while (isActive) { // run } }.printOnComplete("Random coroutine is cancelled!") delay(1000) }

Note: printOnComplete is a custom extension function for brevity.

fun Job.printOnComplete(message: String) { invokeOnCompletion { println(message) } }

In this example, we launch a new coroutine inside a CoroutineScope. This main coroutine has two children, one of which runs while the coroutine is active, and the second throws an exception after a small delay. There is also a random independent coroutine running in the same scope.

If we run this code, the output will print:

Output: Here goes boom... Child 1 is cancelled! Child 2 is cancelled! Random coroutine is cancelled! Exception in thread "DefaultDispatcher-worker-2" java.lang.IllegalArgumentException: Boom! ... Main Job has completed!

This is how standard exception propagation looks like.

Note: Uncaught exceptions will get passed to the thread’s default exception handler. On JVM it will be just logged to the console, like in this case, while, for example, in Android it will crash the application.

In this case, an exception in the Child 2 was propagated all the way up to the scope, triggering cancellation of the whole coroutine tree.

However, keep in mind that coroutines have to be cancellable for error propagation to work correctly.

If we change the code of one of the children to something like this:

// Child 1 launch { // we have changed isActive to true while (true) { // run } }.printOnComplete("Child 1 cancelled!")

And run the code again, we will get:

Here goes boom... Random coroutine is canceled! Child 2 is canceled!

And that’s it.

The exception will never get thrown by the parent coroutine. As we have discussed before, a parent coroutine always waits for its children to complete. However, because we have introduced an infinite loop inside the Child 1, it will never complete and the parent will keep waiting indefinitely, or in this case while the main is running.

That said, the problem here is not the infinite while (true) loop itself, but the fact that this child coroutine is not cooperating with cancellation - a topic we will discuss in Part 5 of this series.

Job vs SupervisorJob

In the example above, the whole scope was cancelled because one of the children threw an exception. In many cases however, this behavior is undesirable. We would probably want all the other independent coroutines in the same scope to continue running.

This is where a SupervisorJob comes into play. You might have noticed that in the example above we have used a Job() inside the scope’s CoroutineContext. A regular Job cancels itself and propagates exceptions all the way to the top level, while SupervisorJob relies on coroutines to handle their own exceptions and doesn't cancel other coroutines.

From the documentation: A failure or cancellation of a child does not cause the supervisor job to fail and does not affect its other children.

That said, uncaught exceptions will always be thrown regardless of the Job implementation.

Incidentally, the implementation of the SupervisorJob is very simple. It overrides a single function from the regular Job implementation:

private class SupervisorJobImpl(parent: Job?) : JobImpl(parent) { override fun childCancelled(cause: Throwable): Boolean = false }

This is the same function we looked at earlier. In a SupervisorJob it always returns false, meaning that the exception is not handled and coroutines should handle exceptions themselves.

For this reason, in Part 2 we have mentioned that in most cases it makes sense to use a SupervisorJob() in a top-level scope. This way it won’t get cancelled as soon as one of its children throws an exception.

The same goes for suspending scope builders - a coroutineScope will go down with its children, while a supervisorScope will not.

Here is an example with a coroutineScope:

fun main() = runBlocking { val result = coroutineScope { launch { delay(100) throw IllegalArgumentException("A total fiasco!") } launch { delay(200) println("Hi there!") } "Result!" } println("Got result: $result") } Output: Exception in thread "main" java.lang.IllegalArgumentException: A total fiasco! ...

And the same example with a supervisorScope:

fun main() = runBlocking { val result = supervisorScope { launch { delay(100) throw IllegalArgumentException("A total fiasco!") } launch { delay(200) println("Hi there!") } "Result!" } println("Got result: $result") } Output: Exception in thread "main" java.lang.IllegalArgumentException: A total fiasco! ... Hi there! Got result: Result!

A special case of an Async builder

Different coroutine builders treat exception propagation differently. While launch automatically propagates exceptions when they are thrown, the async coroutine builder is a little bit special in that regard.

When an exception is thrown inside the async builder that is used as a root coroutine it will rely on the user to consume the exception.

val scope = CoroutineScope(Job() + Dispatchers.Default) fun main(): Unit = runBlocking { val deferred = scope.async { delay(50) throw IllegalStateException("Async Boom!") } delay(100) println("I'm done") } Output: I'm done

The exception in this case will never be thrown. It will only be thrown when .await() is called on the Deferred result:

val scope = CoroutineScope(Job() + Dispatchers.Default) fun main(): Unit = runBlocking { val deferred = scope.async { delay(50) throw IllegalStateException("Async Boom!") } delay(100) // the exception will be thrown here deferred.await() println("I'm done") } Output: Exception in thread "main" java.lang.IllegalStateException: Async Boom!

Note: Deferred is just a Job that returns a result.

The async builder will also behave the same way when used inside a supervisorScope, since a supervisorScope will not notify its parent about exceptions and will rely on children to handle them. In other words, coroutines inside a supervisorScope can be treated as root coroutines.

val scope = CoroutineScope(Job() + Dispatchers.Default) fun main(): Unit = runBlocking { scope.launch { supervisorScope { println("I am the supervisor scope!") val deferred = async { delay(50) throw IllegalArgumentException("Async Boom!") } println("Supervisor scope done!") } } delay(200) println("Main is done!") } Output: I am the supervisor scope! Supervisor scope done! Main is done!

And just like in the example with the root async builder, the async exception inside the supervisorScope will be thrown only if .await() is called.

Note: When using async as a child coroutine or inside a coroutineScope, the exception will be thrown without calling .await() and immediately propagated to the parent, even if wrapped in try-catch.

Handling exceptions

Now that we understand how exception propagation works in the coroutines library, let’s talk about the most important part - handling thrown exceptions.

For that you have a couple of options.

try-catch

The most straightforward way to handle exceptions is with a try-catch block like you would anywhere else in your code. This way the exceptions get handled immediately without triggering exception propagation and cancellation:

val scope = CoroutineScope(Job() + Dispatchers.Default) fun main(): Unit = runBlocking { scope.launch { launch { try { delay(10) throw IllegalArgumentException("A complete failure!") } catch (e: Exception) { println("Child 1 has recovered from: ${e.message}") } } launch { delay(50) println("Child 2 is OK!") } } delay(100) println("Main is done!") } Output: Child 1 has recovered from: A complete failure! Child 2 is OK! Main is done!

That said, keep in mind that in cases described in the previous section, the async builder will throw exceptions only when .await() is called, and it should be wrapped with try-catch:

fun main(): Unit = runBlocking { supervisorScope { val deferred = async { delay(50) throw IllegalArgumentException("An utter collapse!") } try { deferred.await() } catch (e: Exception) { println("Supervisor has recovered from: ${e.message}") } println("Supervisor scope is done!") } delay(100) println("Main is done!") } Output: Supervisor has recovered from: An utter collapse! Supervisor scope is done! Main is done!

runCatching

For more idiomatic Kotlin, you can use runCatching function that comes from Kotlin’s standard library. All it does under the hood, is wraps a block of code in try-catch and returns a Result wrapper:

public inline fun T.runCatching(block: T.() -> R): Result { return try { Result.success(block()) } catch (e: Throwable) { Result.failure(e) } }

Here is an example:

fun main(): Unit = runBlocking { launch { delay(10) val result = runCatching { throw IllegalArgumentException("An absolute disaster!") } when { result.isSuccess -> println("I got: ${result.getOrNull()}") result.isFailure -> println("I have recovered from: ${result.exceptionOrNull()?.message}") } } delay(100) println("Main is done!") } Output: I have recovered from: An absolute disaster! Main is done!

CoroutineExceptionHandler

You might remember that in Part 1 of this series we briefly mentioned the CoroutineExceptionHandler - a context Element that processes uncaught exceptions in coroutines. Now it’s time to discuss it in more detail.

The main difference between handling exceptions with a CoroutineExceptionHandler and a try-catch block is that when an exception gets to a CoroutineExceptionHandler the coroutine had already completed and you can no longer recover from the exception. That is why a CoroutineExceptionHandler should be used as a last-resort measure for exceptions that hadn't been handled differently.

The CoroutineExceptionHandler will only work if it is added to the context of either a CoroutineScope or a root coroutine. Adding it to child coroutines will have no effect, since they will automatically propagate exceptions to their parent. The exception here (no pun intended) are the coroutines that are launched directly inside a supervisorScope, since they are responsible for handling their own exceptions.

Here are some examples:

val handler = CoroutineExceptionHandler { coroutineContext, throwable -> println("Handler has caught: ${throwable.message}") } val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) fun main(): Unit = runBlocking { // we are adding a handler to the // context of a root coroutine scope.launch(handler) { delay(10) throw IllegalArgumentException("An awful crash!") } delay(100) println("Main is done!") } Output: Handler has caught: An awful crash! Main is done!

As an alternative we could have added the handler to our scope directly:

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default + handler)

In which case there would be no need to add it every time to the context of a root coroutine. That said, if you are using a predefined scope you might not have this option.

As we have mentioned earlier, we can also use a CoroutineExceptionHandler inside a supervisorScope:

val handler = CoroutineExceptionHandler { coroutineContext, throwable -> println("Handler has caught: ${throwable.message}") } fun main(): Unit = runBlocking { supervisorScope { launch(handler) { delay(10) throw IllegalArgumentException("A shocking mishap!") } } delay(100) println("Main is done!") } Output: Handler has caught: A shocking mishap! Main is done!

However, this use case is quite rare and in most cases other error handling solutions will make more sense.

Things to keep in mind

Suppressed exceptions

One thing to keep in mind is that if multiple children fail with an exception, the first thrown exception will get propagated, while others exceptions will get attached to it as suppressed exceptions:

private val scope = CoroutineScope(Job() + Dispatchers.Default) fun main(): Unit = runBlocking { scope.launch { launch { delay(100) throw IllegalStateException("First Boom!") } launch { delay(100) throw IllegalStateException("Second Boom!") } } delay(500) } Output: Exception in thread "DefaultDispatcher-worker-2" java.lang.IllegalStateException: First Boom! ... Suppressed: java.lang.IllegalStateException: Second Boom! ...

Job’s invokeOnCompletion

You can add an invokeOnCompletion callback to a Job to see if there were exceptions during its execution:

job.invokeOnCompletion { throwable -> when (throwable) { is CancellationException -> println("Job was cancelled!") is Throwable -> println("Job failed with exception!") null -> println("Job completed normally!") } }

However, keep in mind that if you catch the exception with a try-catch block, it will not get passed to this callback.

CancellationException

CancellationExceptions will not get passed to a CoroutineExceptionHandler, therefore it should not be be relied upon as a resource clean-up mechanism.

For example, a common source of bugs in Android is using a CoroutineExceptionHandler to revert the state of UI in case of an exception inside a ViewModel. In most cases, there is nothing wrong with that, but keep in mind that in that case explicitly cancelling your coroutines might result in a broken UI state.

Conclusion

Handling exceptions in coroutines is not a straightforward task and will require some practice to get hold of all the concepts it envelops. Frankly, for me it was one of the most confusing parts about the coroutines library.

The most important part about all of this, once again, is to understand structured concurrency. Then, in my experience, it all magically clicks into place.

In the next part, we will tackle a sibling of exception handling - cancellation, which should be a breeze now that we understand the underlying mechanisms.

See you then.

Your friend,

Max

Things every Kotlin Developer should know about Coroutines. Part 3: Structured Concurrency.

Max Kim — Thu, 23 Dec 2021 12:54:45 GMT

If you watch a coroutines video dated before their stable launch in Kotlin 1.3, you might notice that the way coroutines were used in their "experimental" phase is a bit different from now.

For example, at KotlinConf 2017, in his Introductions to Coroutines, Roman Elizarov presented a simple code snippet on how to launch a coroutine:

// fire and forget a coroutine! 🚀 fun postItem(item: Item) { launch { val token = requestToken() val post = createPost(token, item) proccessPost(post) } }

Nowadays, this code won't even compile because not long before its stable release, the coroutines library underwent a major design shift called Structured Concurrency.

Understanding Structured Concurrency

If you are coming from Part 2 of this series, you should already understand structured concurrency and why we need it. However, let’s recap and elaborate on this concept, so everyone is on the same page.

The idea behind structured concurrency is quite simple, regardless of how intimidating it might sound. It requires every coroutine to run in a defined scope that manages a parent-child relationship between coroutines.

This achieves a couple of things:

Coroutines are always accounted for and never leak resources;

Parent coroutines always wait for children to complete, which makes concurrency predictable;

Exceptions are always propagated and never lost;

Cancellation is easy and doesn't require passing cancellation tokens to children like many other asynchronous solutions.

Here is an example of structured concurrency:

private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) fun main() = runBlocking { val mainJob = scope.launch { println("Starting the main job!") launch { while (isActive) { delay(10) println("I am child 1!") } } launch { while (isActive) { delay(20) println("I am child 2!") } } } mainJob.invokeOnCompletion { println("The main job is completed/cancelled!") } delay(50) // this will cancel the main coroutine // and all its children scope.cancel() delay(500) println("Finishing main()...") } Output: Starting the main job! I am child 1! I am child 2! I am child 1! I am child 1! I am child 2! I am child 1! The main job is completed/cancelled! Finishing main()...

Among other things, structured concurrency allows cancelling all running coroutines and their children easily. This is just an illustration of this concept, and we will dive deep into cancellation in Part 5 of this series.

The legacy woes

However, given that structured concurrency was a pretty late addition to the coroutines, some legacy woes still haunt the developers of the coroutines library, while confusing less experienced adopters.

One such woe is the GlobalScope. As we have discussed in Part 2, it doesn't have a Job attached to it, and coroutines launched inside the GlobalScope will not adhere to the structured concurrency principle.

It was introduced as an “easy way” to migrate from the legacy unstructured way of launching coroutines as described in the introduction of this article to the version of the coroutines library where launching a coroutine requires a scope.

In Kotlin 1.5, GlobalScope was marked with @DelicateCoroutinesApi annotation to discourage developers from using it. Moreover, JetBrains are planning to remove this API altogether in later releases as a part of gradual removal of APIs that allow for unstructured concurrency.

Here is an example, where we attempt to use the GlobalScope as we would a normal scope:

@OptIn(DelicateCoroutinesApi::class) fun main() = runBlocking { GlobalScope.launch { while (isActive) { delay(10) println("I'm running!") } } delay(100) println("Cancelling GlobalScope!") GlobalScope.cancel() delay(500) }

Even though this code looks like it makes sense, running it will throw an exception:

IllegalStateException: Scope cannot be cancelled because it does not have a job: kotlinx.coroutines.GlobalScope@1a93a7ca

The GlobalScope doesn't allow for a structured way to manage its coroutines. It has to be done manually, which is tedious and error-prone.

Another legacy woe is the flexibility of the CoroutineContext, which, as you now know, mirrors a functionality of a map and doesn't impose any restrictions on how you can use it.

Here is a very informative GitHub issues thread that illustrates one of the problems this can lead to.

Let’s take a look at the example from that thread (with minor tweaks):

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) fun main() = runBlocking { val childJob = Job() val mainJob = scope.launch { println("Starting the main job!") launch(childJob) { while (isActive) { delay(100) println("Scope is active: ${scope.isActive}") } } } mainJob.invokeOnCompletion { println("The main job is completed/cancelled!") } scope.cancel() delay(500) println("Finishing main()...") }

Taking into account the philosophy behind structured concurrency, one might assume that cancelling the scope in this example will cancel both the mainJob and the childJob.

However, if we run the code:

Starting the main job! The main job is completed/cancelled! Scope is active: false Scope is active: false Scope is active: false Scope is active: false Finishing main()...

As you can see, structured concurrency is not a very rigid concept. We can easily break it (in most cases unintentionally), given the very flexible API of the coroutines library.

However, the behavior demonstrated in this example is intentional - by introducing a new Job into the coroutineContext, we explicitly override the parent-child relationship.

That said, in the above-mentioned GitHub thread, Roman Elizarov has provided two very good rules of thumb to make using coroutines predictable and avoid unintentional leaks and behaviors:

When using a CoroutineContext you should not have a Job there.

When using a CoroutineScope you should always have a Job there.

The above rules are slightly edited to improve readability.

He admitted that if they had designed the coroutines library today, they would have restricted this API. And at the moment he doesn't have a good solution for this problem, except for following the rules as mentioned above.

Structured concurrency in practice

By following the recommendations outlined in this series, beginners won't get in trouble when using coroutines and won't break structured concurrency. However, when writing their own coroutine APIs, more advanced developers must know how to follow the principles of structured concurrency in practice.

In the following section, I would like to discuss an example from Android’s lifecycle library and illustrate this point. You don't have to be familiar with Android to follow this example since my goal is to demonstrate a case of broken structured concurrency, not focus on Android’s APIs.

This example might seem quite advanced for some readers, but if this is the case, at least be aware that these considerations exist, and even engineers at Google sometimes stumble when designing coroutines APIs.

The story of a broken API

The full story is outlined in this article by Manuel Vivo.

In Android, we have to be constantly aware of the lifecycle of our UI components since they can be destroyed and recreated quite often. Because of that, we need a robust solution that doesn't leak resources when using coroutines from such components.

One of these solutions provided by the lifecycle library is repeatOnLifecycle, which can be used as follows:

class MyActivity : AppCompatActivity() { private val viewModel by viewModels() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) lifecycleScope.launch { repeatOnLifecycle(Lifecycle.State.STARTED) { viewModel.uiStateFlow.collect { // Collect ui state } } } lifecycleScope.launch { repeatOnLifecycle(Lifecycle.State.STARTED) { viewModel.someOtherFlow.collect { // Collect some other data } } } } }

In this example, lifecycleScope is a scope provided by the lifecycle library. It follows the lifecycle of the given LifecycleOwner. If you are an Android developer and want to know why we cannot rely on that alone or on lifecycleScope.launchWhenStarted { ... } when collecting flows, you can refer to this article.

As you can see, this API is quite cumbersome. If we need to collect from multiple flows, we have to launch a new coroutine for each one since collect will suspend the coroutine it runs in. At first glance, it looks like boilerplate and can be improved with Kotlin’s extension functions.

Following the same logic, in one of the alphas of the lifecycle library, Google had introduced the LifecycleOwner.addRepeatingJob API, which looked like this:

public fun LifecycleOwner.addRepeatingJob( state: Lifecycle.State, coroutineContext: CoroutineContext = EmptyCoroutineContext, block: suspend CoroutineScope.() -> Unit ): Job = lifecycleScope.launch(coroutineContext) { repeatOnLifecycle(state, block) }

It hid the boilerplate and allowed for a seemingly cleaner code:

class MyActivity : AppCompatActivity() { private val viewModel by viewModels() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // AppCompatActivity is a LifecycleOwner addRepeatingJob(Lifecycle.State.STARTED) { viewModel.uiStateFlow.collect { // Collect ui state } } addRepeatingJob(Lifecycle.State.STARTED) { viewModel.someOtherFlow.collect { // Collect some other data } } } }

However, if we look deeper, this API is quite problematic. It can break structured concurrency and introduce subtle bugs.

While repeatOnLifecycle is a regular suspending function, the addRepeatingJob is a non-suspending function that launches a new independent coroutine in the lifecycleScope. Still, developers might be tempted to write code like this:

val job = lifecycleScope.launch { addRepeatingJob(Lifecycle.State.STARTED) { viewModel.someDataFlow.collect { // Collect some data } } } // ...if something went wrong job.cancel()

If you understand how structured concurrency works, you know what will happen.

The someDataFlow.collect { } will not get cancelled after job.cancel() is called, although that would be a developer’s intention.

Here is how this example would look in a simplified code for better understanding:

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) fun main() { runBlocking { val mainJob = scope.launch { println("Starting the main job!") // this is an independent coroutine, // not a child coroutine scope.launch { while (isActive) { delay(100) println("I'm alive!!!") } } } mainJob.invokeOnCompletion { println("The main job is completed/cancelled!") } delay(100) mainJob.cancel() delay(500) println("Finishing main()...") } } Output: Starting the main job! The main job is completed/cancelled! I'm alive!!! I'm alive!!! I'm alive!!! I'm alive!!! I'm alive!!! Finishing main()...

Similar to the example where we introduced a new Job into the context, there is no parent-child relationship between these two coroutines, which might not be immediately apparent to less experienced developers.

Because of this issue, Google removed the addRepeatingJob API from the lifecycle library.

This example illustrates why structured concurrency is crucial when using coroutines and should always be kept in mind.

Conclusion

The coroutines library went through some growing pains and is still evolving. Even though structured concurrency is the underlying principle of the modern coroutines API, there are still many ways to break it.

Therefore, it is important to be aware of the unstructured concurrency pitfalls so you can avoid them and write better code. Hopefully, this article managed to shine some light on this less-discussed side of the coroutines library.

If you are interested to learn more about how Kotlin coroutines were designed and how structured concurrency came about, I highly recommend watching this presentation from Roman Elizarov.

That said, in Part 4, we will dive deep into error handling in coroutines.

See you then.

Your friend,

Max

Things every Kotlin Developer should know about Coroutines. Part 2: CoroutineScope.

Max Kim — Tue, 14 Dec 2021 13:41:55 GMT

In my experience, CoroutineScope is one of the less understood parts of the coroutines library, even though it is one of the most important. In Android, we are spoiled with coroutine scopes kindly provided to us by lifecycle libraries, but for many developers, things quickly get confusing as soon as there is a need to create a custom CoroutineScope, or if they need to write coroutines in an environment that doesn't provide a pre-defined scope.

That said, by the end of this article, you will know everything you need to use the CoroutineScope comfortably and correctly.

What is a CoroutineScope

Declaration

First, we have to understand what a CoroutineScope is. There is no better place to look for the answers than its declaration:

public interface CoroutineScope { public val coroutineContext: CoroutineContext }

As you can see, it is a very simple interface, but there is quite a lot to unpack here.

A CoroutineScope is just a simple wrapper for a CoroutineContext. In a technical sense, it is nothing more than a CoroutineContext, and the only reason it exists and has a different name is to differentiate the intended purpose of the two.

You can read more about this in Roman Elizarov's blog post on the topic. I like how in the beginning of his post he gives an example of this concept:

Different uses of physically near-identical things are usually accompanied by giving those things different names to emphasize the intended purpose. Depending on the use, seamen have a dozen or more words for a rope though it might materially be the same thing.

So why do we need to have this separate CoroutineScope?

Intended purpose of the CoroutineScope

Coroutines are very cheap and we are encouraged to create them as we see fit. We can launch coroutines in different ways from many different places. Some might complete fast, and some might take a long time. Some might have multiple child coroutines of their own. And any of them can potentially fail.

In the early days of the coroutines library, we would launch coroutines in a fire-and-forget manner. However, if we would try to manage all those asynchronously running coroutines in an application that has components with a limited lifecycle, for example, a UI screen that could be closed by the user and should cancel all its work, the complexity of coroutine management would grow exponentially.

Therefore, at one point in its development, the coroutines library had a major ideology shift called Structured Concurrency. It aimed for all coroutines to be launched in a defined scope, which would allow for an easy way to manage cancellation, exception handling and not allow resource leaking.

And that is the intended purpose of a CoroutineScope - to enforce structured concurrency.

We will focus on structured concurrency and how to practically comply with its principles in Part 3 of this series. For now, however, there is still much to discuss about the CoroutineScope itself.

Coroutine launchers

There are two ways to launch a new coroutine - with either launch or async function. Let's quickly look at their declaration.

public fun CoroutineScope.launch( context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, block: suspend CoroutineScope.() -> Unit ): Job

public fun CoroutineScope.async( context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, block: suspend CoroutineScope.() -> T ): Deferred

As much as I would like to dissect every parameter and inner workings of these functions, I will not bore you with that. The main takeaway, which is essential to know and understand, is that these are extension functions on the CoroutineScope interface.

That is why we cannot launch a new coroutine without a scope.

We will return to this concept throughout this article.

Creating your own scopes

Scope builder functions

There are two types of scope builder functions - suspending and non-suspending. Since we can only call suspending functions from a coroutine, we cannot use them to create our top-level scopes. Still, they are very useful, and we will discuss them later.

To create a top-level scope we can use one of the following builder functions:

MainScope()

CoroutineScope(context: CoroutineContext)

Notice that they are functions - in Kotlin, we often use the pascal case in function names if they build and return an object. That makes for a cleaner and more readable API:

// this is a function that returns an instance // of CoroutineScope, not a constructor val mainScope = MainScope()

The main difference between these two scopes is that the MainScope() uses Dispatchers.Main for its coroutines, making it perfect for UI components, and the CoroutineScope() uses Dispatchers.Default by default.

Another difference is that CoroutineScope() takes in a CoroutineContext as a parameter.

If you have read Part 1 of this series, you should be familiar with CoroutineContext and how to use it.

Here are some examples:

val scope1 = CoroutineScope(SupervisorJob()) val scope2 = CoroutineScope(SupervisorJob() + Dispatchers.IO) val scope3 = CoroutineScope(SupervisorJob() + CoroutineName("MyScope"))

Note that we are using SupervisorJob instead of Job. It is an important concept regarding error handling, which we will discuss in-depth in Part 4 of this series.

There are a couple of things to consider when creating a scope using the CoroutineScope() function.

The context parameter is mandatory. That said, if you don't pass a Job element, a default Job() will be created since a scope must have a Job to enforce structured concurrency. Also, if we don't pass a coroutine dispatcher, Dispatchers.Default will be used.

However, given that not every developer knows the inner workings of these functions, I find it convenient and more readable to define the context of my scopes explicitly:

// even though adding Dispatchers.Default is not necessary, // I find it more readable to state every element // of the context explicitly val appScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)

When using the MainScope() function, however, we don't need to specify the context - it automatically creates a context with a SupervisorJob and a Dispatchers.Main:

public fun MainScope(): CoroutineScope = ContextScope(SupervisorJob() + Dispatchers.Main)

If you need to add an Element to the MainScope you can use the plus operator function, just like we would with a CoroutineContext:

val mainScope = MainScope() + CoroutineName("MainScope")

Legacy convention

When CoroutineScope was first introduced into the coroutines library, the official documentation described another way to create scopes. And although the documentation was since updated to recommend a more readable and straightforward way to create scopes as described above, you might still stumble across the legacy way in some codebase.

The legacy way recommended creating coroutine scopes by implementing the CoroutineScope interface:

// standard implementation class MyComponent : CoroutineScope { override val coroutineContext: CoroutineContext = SupervisorJob() + Dispatchers.Default }

// implementation using delegation class MainActivity : AppCompatActivity(), CoroutineScope by MainScope()

However, you should always use the non-legacy approach in your code, which is more straightforward to use.

Suspending scoped concurrency

Suspending scope builders

We are not done with scope builder functions just yet. We have looked at non-suspending ways to create coroutine scopes, but as I have mentioned, there are also suspending ones.

There are two, to be exact:

public suspend fun coroutineScope(block: suspend CoroutineScope.() -> R): R

public suspend fun supervisorScope(block: suspend CoroutineScope.() -> R): R

There is also a third function that you are already familiar with, which is very similar:

public suspend fun withContext( context: CoroutineContext, block: suspend CoroutineScope.() -> T ): T

Although the implementation of withContext() is similar to that of coroutineScope()(but a bit more complicated), its intended purpose is to switch context within a suspending function, not to provide a scope. It might seem confusing, just as with CoroutineScope being the same thing as CoroutineContext, but once again - the intended purpose is the important part.

That said, we will not discuss the withContext() function and focus on the two functions that explicitly provide a scope, even though technically you can do the same things with withContext(), since all these functions take block: suspend CoroutineScope.() -> T as an argument and allow launching new coroutines inside this block.

With that out of the way, let's take a look at a practical example.

Why do we need suspending scope builders

As you now know, the coroutine launcher functions launch and async are extension functions on the CoroutineScope. We cannot launch new coroutines outside of a coroutine scope. That also means we cannot launch new coroutines from suspending functions since they are regular functions that undergo a "minor" transformation during compilation.

However, there are certainly use cases where we would like to do that.

Here is an example:

val dataUrls = listOf("url1", "url2", "url3") fun main() { runBlocking { val time = measureTimeMillis { downloadAllData(dataUrls) .forEach(::println) } println("Done in: $time ms") } } suspend fun downloadAllData(urls: List<String>): List { return urls.map { url -> downloadData(url) } } suspend fun downloadData(url: String): Data { return withContext(Dispatchers.IO) { delay(100) Data("I am data from: $url") } } data class Data(val content: String) Output: Data(content=I am data from: url1) Data(content=I am data from: url2) Data(content=I am data from: url3) Done in: 329 ms

Predictably, we got our data downloaded sequentially in about 300ms. Of course, we could add async to each call of downloadData in our top-level coroutine, but that would be detrimental to the quality and reusability of our code. We can do better than that.

With the help of suspending scope builders, we can load all our data concurrently inside the downloadAllData function:

suspend fun downloadAllData(urls: List<String>): List { return coroutineScope { urls.map { url -> async { downloadData(url) } } .map { deferred -> deferred.await() } } } Output: Data(content=I am data from: url1) Data(content=I am data from: url2) Data(content=I am data from: url3) Done in: 129 ms

An important thing to note about suspending scope builders is that they return only when all their child coroutines have finished. This enforces structured concurrency and adheres to one of the main ideologies of the coroutine library - that suspending functions execute sequentially, just like the regular code. So in the example above, even though we launch multiple new coroutines inside the downloadAllData function, it will only return when all the work is done, without leaking coroutines. We will talk more about it in the best practices section.

The supervisorScope() is the same as coroutineScope(), but uses a SupervisorJob for its context instead of a Job. We will discuss everything there is to know about using Job and SupervisorJob in Part 4 of this series dedicated to error handling.

A few words about GlobalScope

This article would not be complete if we didn't mention the infamous GlobalScope. It had confused so many developers that in Kotlin 1.5 JetBrains marked it with @DelicateCoroutinesApi, which requires an opt-in to use it.

There are a couple of things you need to know about the GlobalScope, which should be easier to understand now that you know how scopes work and why we need them.

First of all, the GlobalScope doesn't adhere to the structured concurrency principle, which, as you now know, is a big deal in coroutines. It doesn't have any Job tied to it, and it is running during the whole lifetime of an application.

It might have its uses, but to use the GlobalScope correctly, you have to manage every coroutine launched inside it manually, keeping track of their jobs and not forgetting to .join() those jobs to other coroutines if your use case requires it.

You have to know what you are doing when using the GlobalScope, and even then, you might still introduce some subtle bugs if your attention slips.

So the recommendation is to avoid it altogether.

You can read more about this topic in this post by Roman Elizarov.

Conventions and Best Practices

We have already discussed quite a few examples of using the CoroutineScope correctly. However, there are still some things that you should keep in mind.

First of all, as we have mentioned earlier - do not ever launch new unbounded coroutines from a suspending function. Nothing should be left running in the background when a suspending function returns.

You should never write code like this:

suspend fun launchWorker() { ... // any suspending code CoroutineScope(Dispatchers.IO).launch { doWork() } }

Even if you keep a job handle to this new coroutine - this implementation is very smelly. It will make your code unpredictable, and you will break the structured concurrency principle.

If you need to write a function that launches a new coroutine, the convention is to use a regular extension function on the CoroutineScope - just like the launch and async functions.

The correct way to implement the example above would be:

fun CoroutineScope.launchWorker() { launch { // switch the dispatcher inside doWork() if needed // as we have discussed in Part 1 doWork() } }

Now you can launch your custom coroutines safely inside the context of a scope.

This convention also follows the pattern that launching a new coroutine returns immediately while suspending functions return only after all the work is completed.

Another best practice for creating your own CoroutineScope is to keep it bound to the lifecycle of some component. For example, in Android, we have viewModelScope attached to the ViewModel, and lifecycleScope attached to the LifecycleOwner. As soon as these components are destroyed, their scopes are immediately cancelled, preventing leaking coroutines.

This is a good practice regardless of the platform. You might have an application-level CoroutineScope, which might not need explicit cancelling, but for any other use case, you should limit the lifecycle of your scopes:

class MyComponent() { val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) ... fun onDestroy() { ... scope.cancel() } }

Lastly, it is more clean and readable to use extension properties and functions like isActive, cancel(), and ensureActive() on your CoroutineScope not on the CoroutineContext even though they are the same thing. "Cancelling a scope" is immediately apparent, while "cancelling a context" occasionally might raise some questions just because of the naming.

Conclusion

You might have noticed a trend that despite having a very flexible API, the coroutines library has a set of simple, straightforward recommendations and practices, which make using coroutines much less intimidating, especially when starting out.

Hopefully, after reading this article, using the CoroutineScope will be smooth sailing.

In Part 3, we will dive deeper into the practical side of structured concurrency. This more advanced subject will nicely round up our discussion about CoroutineContext and CoroutineScope before moving on to meatier topics like exception handling.

See you next time.

Your friend,

Max

Things every Kotlin Developer should know about Coroutines. Part 1: CoroutineContext.

Max Kim — Thu, 02 Dec 2021 08:24:10 GMT

The CoroutineContext is the backbone of the coroutines library. Every coroutine you launch will have a context. However, given its nature and flexible API, it might prove pretty tricky to use it correctly.

In Part 1 of my series about coroutines, I will take a close look at the CoroutineContext and discuss the best practices on how to use it.

CoroutineContext Under the Hood

To kick this article off, let's take a look at the declaration of CoroutineContext:

/** * Persistent context for the coroutine. * It is an indexed set of [Element] instances. * An indexed set is a mix between a set and a map. * Every element in this set has a unique [Key]. */ @SinceKotlin("1.3") public interface CoroutineContext

As we can see from the KDoc, in broad terms, the CoroutineContext is just a Map that stores a set of Element objects that have a unique Key.

We can access those Elements using a Key, just as we would in a normal Map:

/** * Returns the element with the given [key] from this context or `null`. */ public operator fun get(key: Key<E>): E?

However, notice that the Key is typed. We will discuss that a bit later.

CoroutineContext Elements

Since CoroutineContext is nothing more than a container, the most important part is its content.

An Element is anything a coroutine might need to run correctly. The most common examples would be:

Job - a cancellable handle to a coroutine with a lifecycle;

CoroutineDispatcher, MainCoroutineDispatcher - dispatchers for a coroutine to run on;

CoroutineId, CoroutineName - elements mainly used to debug coroutines;

CoroutineExceptionHandler - an element that handles uncaught exceptions.

There are many more elements defined in the coroutines library, but these are the main ones that you would use in your code.

When it comes to the implementation of Elements, it is curious how the coroutines library uses typed Keys.

Here is how we would get a Job from the coroutine context, using a Key:

val job = coroutineContext[Job]

As you can see, the Key is just the name of the Element we want to access. This is not a syntax you see often, but it is a perfectly valid Kotlin syntax nevertheless.

The Key for each Element is just a plain companion object of that element that implements Key interface, and therefore, we can use it as a Key for the given type.

Here is an example:

public interface Job : CoroutineContext.Element { /** * Key for [Job] instance in the coroutine context. */ public companion object Key : CoroutineContext.Key

Modifying a CoroutineContext

A CoroutineContext behaves like an immutable map - it doesn't have a set function. Therefore, you can read stored elements, but can't modify them directly:

// we can read the elements stored in a context by their Key val job = coroutineContext[Job] // we cannot modify stored elements coroutineContext[Job] = Job() <- compiler error

That doesn't mean, however, that we cannot modify a CoroutineContext. For that, it has dedicated functions, such as:

/** * Returns a context containing elements from this context * and elements from other [context]. * The elements from this context with the same key * as in the other one are dropped. */ public operator fun plus(context: CoroutineContext): CoroutineContext

/** * Returns a context containing elements from this context, * but without an element with the specified [key]. */ public fun minusKey(key: Key<*>): CoroutineContext

/** * Accumulates entries of this context starting with[initial] value * and applying[operation] from left to right to current accumulator value * and each element of this context. */ public funfold(initial: R, operation:(R, Element)-> R): R

Out of the functions mentioned above, in most cases, you would only use the plus operator function, which uses the fold function under the hood.

If you have used coroutines before, the plus operator should be very familiar to you:

launch(Dispatchers.IO + CoroutineName("TestCoroutine")) { doStuff() }

Keep in mind that this plus is not associative. In other words, context1 + context2 is not the same as context2 + context1 since all the keys from the left context will be overwritten by the keys from the right context. Of course, It doesn't matter when combining two distinct Elements as in the example above, but when combining sets of Elements, this becomes an important consideration.

And yes, this example also means that every Element is also a CoroutineContext to allow for such a syntax:

/** * An element of the [CoroutineContext]. An element * of the coroutine context is a singleton context by itself. */ public interface Element : CoroutineContext

Each Element by itself is a valid CoroutineContext that can be combined with other Elements and/or CoroutineContexts.

This also means that we can use the get syntax on any Element:

// nonsense, but api allows it val job = Job()[Job]

That is not something that you would ever use in your code. Still, I find this example somewhat educational to illustrate the point above and the flexibility of coroutines API.

The rest of the CoroutineContext's public API is realized with the help of extension functions and properties that access some functionality of an Element.

Here is an example of a property that checks whether or not a CoroutineContext is active:

public val CoroutineContext.isActive: Boolean get() = this[Job]?.isActive == true

We will not focus on these extensions for now, since in most cases, it would make sense to use similar functions on a CoroutineScope, but we will talk about it in Part 2 of this series.

Best Practices and Recommendations

As you have seen, the CoroutineContext API is very flexible and allows us to add and combine different elements as we see fit.

However, you should almost never do that.

These flexible APIs are one of the reasons for the steep learning curve of the coroutines library. The thing is that most of that flexibility is not meant for the end-user. We will discuss why it is this way in one of the later parts of this series.

It is very easy to mess things up, especially when starting out using coroutines. So, to make things a bit easier, here are some recommendations on using the CoroutineContext.

First of all, the only elements you should ever consider manually adding to the context when launching a new coroutine are CoroutineDispather (or MainCoroutineDispatcher) and CoroutineExceptionHandler. In some specific debug cases, you can also use CoroutineName.

Here is an example of changing a dispatcher:

fun main() { runBlocking { println("I am running on ${Thread.currentThread().name}") launch(Dispatchers.IO) { workOnIO() // this might be blocking } } } suspend fun workOnIO() { delay(100) println("Now I have switched to ${Thread.currentThread().name}") } Output: I am running on main Now I have switched to DefaultDispatcher-worker-1

Important! runBlocking should never be used outside tests and examples like these. In production code, coroutines must have a proper scope. I am using it in this article for illustrational purposes only.

One thing to keep in mind here is that Dispatchers.IO shares threads with Dispatchers.Default. Therefore we get this output.

Also notice that when we manage our dispatchers from the top-level coroutine, we might launch a suspending function that will block our thread. For example, if the workOnIO function instead of the non-blocking delay() called Thread.sleep(), or, more realistically, read from a huge file.

A coroutine will wait for a suspending function to finish regardless since the execution of suspending functions is sequential, but if we don't block the thread while waiting for a coroutine to resume, it is free to do other work.

With that in mind, there is one recommendation about dispatchers that comes from Kotlin's project lead Roman Elizarov, who was the lead designer of coroutines library before that.

Here is an important excerpt:

Suspending functions add a new dimension to code design. It was blocking/non-blocking without coroutines and now there is also suspending/non-suspending on top of that. To make everybody’s life simpler we use the following convention: suspending functions do not block the caller thread. The means to implement this convention are provided by the withContext function.

With that convention in mind, here is how we could improve that code:

fun main() { runBlocking { launch { println("I am running on ${Thread.currentThread().name}") workOnIO() } } } suspend fun workOnIO() { withContext(Dispatchers.IO) { delay(100) println("Now I have switched to ${Thread.currentThread().name}") } } Output: I am running on main Now I have switched to DefaultDispatcher-worker-1

Function workOnIO might still block a thread, but not the thread we are calling it from. Also, by following this convention, you won't have to check every time what happens inside a suspending function and whether you need to switch threads for it.

When it comes to CoroutineExceptionHandler, we will talk about it in more detail when we get to exception handling in coroutines. For now, here is a simple example:

fun main() { val scope = CoroutineScope(Dispatchers.Default) val exceptionHandler = CoroutineExceptionHandler { _, throwable -> println("I have caught: ${throwable.message}") } runBlocking { scope.launch(exceptionHandler) { println("I am running!") delay(100) error("A nasty exception!") } delay(200) println("I am OK!") } } Output: I am running! I have caught: A nasty exception! I am OK!

Lastly, sometimes it might prove handy to identify your coroutines for debug purposes. You can do it using CoroutineName element:

fun main() { runBlocking { launch(CoroutineName("A")) { identify() } launch(CoroutineName("B")) { identify() } } } suspend fun identify() { val coroutineName = coroutineContext[CoroutineName]?.name println("I am called from: $coroutineName") } Output: I am called from: A I am called from: B

You can also use the -Dkotlinx.coroutines.debug JVM option to see the specified coroutine name in the logs.

You should rarely modify a CoroutineContext outside of these use cases unless you know what you are doing. Otherwise, it might break things you are not even aware of and result in hard-to-find bugs. Especially when introducing a new Job into the context - a topic we will discuss in a later article.

Conclusion

If you stick to these recommendations, you won't have much trouble using the CoroutineContext. I could have just given you those and called it an article, but I believe it is crucial to understand the inner workings of the tools we use.

Next time, we will look into the CoroutineScope, which has more in common with the CoroutineContext than you might think.

See you next time,

Your friend,

Max

A Practical Guide to Kotlin's inline Modifier

Max Kim — Mon, 04 Oct 2021 08:48:26 GMT

I fell in love with Kotlin as soon as I switched to it from Java about 4 years ago. And although I was writing Kotlin code on a regular basis ever since, I didn't start using some of its more advanced features until quite recently.

I wish I had started playing around with the more idiomatic ways to write Kotlin code much sooner since it improves the quality of the code and makes writing code much more enjoyable. I agree that you can easily get by without ever using the less-known Kotlin features, however, in the hands of more dedicated software enthusiasts, those features can help improve the code dramatically.

In this article, we will go through one of those features - the inline modifier. And yes, it means we will also take a close look at the modifiers that are closely linked with the inline functions - noinline, crossinline, and reified.

Contents

1. Inline modifier 1.1. Inline functions 1.2. Inline properties 1.3. Inline classes 2. Noinline modifier 3. Crossinline modifier 3.1. Understanding non-local returns 3.2. The problem and the crossinline solution 4. Reified modifier
1. Inline modifier

1.1. Inline functions

In Kotlin, you cannot throw a stone without hitting a higher-order function. In layman's terms, those are functions that either take functions as parameters or return a function. This makes Kotlin a very flexible language and allows for intuitive functional programming as well as easy creation of DSLs among many other things.

But as with most amazing things in life, there is a catch. Using many higher-order functions can cause a significant performance impact during runtime since every function compiles to an object that captures a closure. A closure is a fancy way of describing the variables that this function accesses but are declared outside of its scope. Therefore, without a clever solution from the folk at JetBrains, Kotlin might as well have been called the runtime overhead language.

That solution is the inline modifier.

When a function is marked with inline the compiler doesn't create new objects but rather inserts the given code where an inline function is called.

Let's take a look at a simple example:

fun main() { doubleAction( { println("Hello") }, { println("World!") } ) } fun doubleAction( action1: () -> Unit, action2: () -> Unit ) { action1() action2() }

If we decompile the bytecode of this block back to Java and look at the main() function, we will see:

public static final void main() { doubleAction((Function0)null.INSTANCE, (Function0)null.INSTANCE); }

To be honest, at first glance this looks like someone is looking for a creative way to get a NullPointerException but let's not concern ourselves with the ways of Kotlin bytecode decompiler.

What we should note here is that our main is calling the doubleAction function and our two lambdas are now instances of Function0 object.

Now, let's see what happens if we put the inline modifier in front of the doubleAction function:

inline fun doubleAction( action1: () -> Unit, action2: () -> Unit ) { action1() action2() }

Just by doing that, after compiling this code into bytecode and decompiling back to Java (and a little bit of cleanup to illustrate the point) the body of our main function reads:

public static final void main() { String var1 = "Hello"; System.out.println(var1); var1 = "World!"; System.out.println(var1); }

Now that is much more efficient! The compiler even reuses the String variable.

I hope that this example nicely illustrates the benefits of using the inline modifier for higher-order functions. It will inline the function itself as well as lambdas that are passed as arguments.

In summary

The inline modifier provides a noticeable performance boost if you write a lot of higher-order functions, especially in a big codebase, so use it!

Also, for those of you writing Android UI with Jetpack Compose, inline will become your friend pretty fast.

However, a word of caution must be mentioned here. It is not recommended to inline large functions, since it can considerably bloat the generated code. Inlining, like everything else really, is good in moderation.

It works great with short functions, especially when using loops and working with collections.

For example, in Kotlin standard library the scope functions (let, apply, also, run, and with) are marked with inline, as well as extension functions that work with Iterable collections, such as map, forEach, fold and many others.

1.2. Inline properties

Marking higher-order functions is not the only use of the inline modifier, however. One of the less-known features of the Kotlin language are inline properties.

Let's take a look at the following example:

var complexProperty: Int get() { val x = 2 val y = 4 return x + y } set(value) { val adjustedValue = value + 10 println("Setting adjusted value $adjustedValue") } fun main() { complexProperty = 4 val calculatedProperty = complexProperty println("The property is $calculatedProperty") }

Take note that these are not regular getter and setter methods that read/write a backing field. We will discuss it in a bit.

The accessors of Kotlin properties are compiled to regular methods, which then are used throughout the code. So our example after the bytecode magic will read:

public static final void main() { setComplexProperty(4); int calculatedProperty = getComplexProperty(); String var1 = "The property is " + calculatedProperty; System.out.println(var1); }

If you have paid attention until now, you probably know what we are about to do.

Yes, we can mark the property as inline, which will make the accessors of the property work like regular inline functions, even though they are not higher-order.

So after marking our property with inline:

inline var complexProperty: Int get() { val x = 2 val y = 4 return x + y } set(value) { val adjustedValue = value + 10 println("Setting adjusted value $adjustedValue") }

We will get:

public static final void main() { // Setter int value$iv = 4; int adjustedValue$iv = value$iv + 10; String var3 = "Setting adjusted value " + adjustedValue$iv; System.out.println(var3); // Getter int x$iv = 2; int y$iv = 4; int calculatedProperty = x$iv + y$iv; String var6 = "The property is " + calculatedProperty; System.out.println(var6); }

Exactly what we would expect from an inlined function.

We can also mark individual accessors as inline:

var complexProperty: Int inline get() { ... } set(value) { ... }

Or:

var complexProperty: Int get() { ... } inline set(value) { ... }

And of course, have read-only properties:

inline val complexProperty: Int get() { ... }

Inline property restriction

There is a reason why we didn't use a property with regular getter and setter in our example. That reason is that the inline modifier is only allowed for accessors that don't have a backing field.

Backing field is an identifier field that doesn't allow us to go into an infinite loop when setting a property.

1.3. Inline classes

Inline classes are another less-known feature of Kotlin that became stable in Kotlin 1.5.0, and even though they are not using the inline modifier directly in their stable version, they did during the experimental phase in earlier Koltin versions, and their functionality is the same as we have seen with previous inlined examples.

Inline classes act as a wrapper around a type to improve readability and decrease the probability of runtime bugs. The regular wrapper class would have a noticeable performance hit during runtime due to additional heap allocations. The inline classes don't, while keeping all the benefits.

Below is a snippet of code where we should consider using a wrapper:

fun main() { login("qwerty", "email@qwerty.com") } fun login(email: String, password: String) { println("Please don't mix up my parameters") }

As you can see, this code will compile nicely but would break during runtime (if it had some login logic of course).

This is where inline classes shine.

We can re-write the following code as follows:

fun main() { login(Email("email@qwerty.com"), Password("qwerty")) } fun login(email: Email, password: Password) { println("Please don't mix up my parameters") } @JvmInline value class Email(val email: String) @JvmInline value class Password(val password: String)

Before Kotlin 1.5.0 we would write:

inline class Email(val email: String)

But this syntax is deprecated now and will throw a warning.

When using this approach it will be much harder to mix up our types, and during runtime no new objects will be created.

Moreover, the inline classes can have init blocks, functions, and properties (with the same restrictions as the inline properties):

@JvmInline value class Email(val email: String) { init { require(email.isValidEmail()) } } @JvmInline value class Password(val password: String) { val isSecure: Boolean get() = password.contains('!') }

If you want some more practical inspiration on the inline classes, you can take a look at this article by Jake Wharton.

2. Noinline modifier

At this point, we hopefully have a decent understanding of how inlining works, therefore let's take a look at the modifiers that work in the context of inline functions.

The first of those modifiers is quite straightforward.

If we don't want to (or can't) inline a lambda that is passed as a parameter to an inline function, we can mark it as noinline.

Here are a couple examples where we might wan't to mark our lambda parameter as noinline:

inline fun doubleAction( action1: () -> Unit, action2: () -> Unit ) { action1() // the following two cases won't compile // we cannot assign an inline lambda to a variable val x = action2 // we cannot pass an inline lambda to a non-inline function singleAction(action2) } /** * For some reason this function is not inlined. * It might be too large or comes from external * library that we don't have any control over */ fun singleAction(action: () -> Unit) { action() }

This can easily be fixed by telling the compiler that we don't want to inline the action2 lambda. All we need to do is mark it as noinline:

inline fun doubleAction( action1: () -> Unit, noinline action2: () -> Unit ) { ... }

Now the above code will compile and work nicely.

Needless to say that if you have and inline function with one lambda as a parameter, in most cases it wouldn't make sense to mark in as noinline, and the IDE will promptly give you warning in that case.

However, it depends on what we do with that lambda parameter.

Here is an example from the Kotlin Coroutines library:

public suspend inline operator fun CoroutineDispatcher.invoke( noinline block: suspend CoroutineScope.() -> T ): T = withContext(this, block)

The withContext is a regular function and we cannot pass an inlined lambda to it (more on why in the crossinline section):

public suspend fun withContext( context: CoroutineContext, block: suspend CoroutineScope.() -> T ): T

But we can still inline the withContext function where we call invoke on our CoroutineScope so this is another good example of noinline modifier in practice.

3. Crossinline modifier

To understand why we might need the crossinline modifier, we must first have a good understanding of non-local returns in Kotlin.

If you are familiar with this concept, feel free to skip the next part.

3.1. Understanding non-local returns

There are only 3 places in Kotlin where we can use a normal return without any additional labels:

Named functions
fun regularNamed(isSleepy: Boolean) { if (isSleepy) { return } // do stuff }

Anonymous functions (do not confuse them with lambdas)

fun printEven(listOfInts: List<Int>) { listOfInts.forEach(fun(x: Int) { if (x % 2 == 0) { println(x) } else { /** * This will return at the anonymous fun * and continue forEach iteration. * Lambda would have returned at printEven * since forEach is inlined. */ return } }) }

In most cases, we wouldn't use anonymous functions. However, keep in mind that anonymous functions allow us to specify an explicit return type, while lambdas don't.

Inline functions

fun weAllFloat(list: List<Any>) { list.forEach { if (it !is Float) { /** * Once again, forEach is inline * and will return at weAllFloat. * If we would like to continue looping, * we should use a local return@forEach */ return } else { it.float() 🎈 } } }

These are non-local returns.

To use a return inside a lambda, we must use either a default or a custom label:

// not the cleanest code, but illustrates our point val hasString = lambda@{ list.forEach { if (it is String) { return@lambda true } } return@lambda false } print(hasString())

These are local returns.

The reason we can use a non-local return inside an inlined lambda is that it will just return from the enclosing function, where the code will be inlined.

3.2. The problem and the crossinline solution

But there is a problem that can arise with the inlined lambdas and their non-local returns:

fun main() { inlineFunction { return // this is fine, no compile error here } } inline fun inlineFunction(inlineLambda: () -> Unit) { randomFunction { inlineLambda() // compile error } } fun randomFunction(nonInlineLambda: () -> Unit) { nonInlineLambda() }

The nonInlineLambda is a regular lambda and we cannot use a non-local return inside a regular lambda. Inline lambdas, however, allow non-local returns, and in this case, it would be inlined inside a regular lambda.

The compiler doesn't like that idea and since it cannot guarantee that we won't try to pass a non-local return inside an inline lambda to a regular function, it just doesn't allow passing inline lambdas to regular functions altogether.

We've had a very similar example in the noinline section, where we passed an inline lambda to the regular withContext function. In that case, the problem was solved by not inlining the lambda at all, which is one way to do it.

The other solution is the crossinline modifier. By marking a lambda parameter with crossinline we prohibit using the non-local return inside that inline lambda, and therefore can safely pass it to a regular function.

That said, let's fix our code:

fun main() { inlineFunction { // the non-local return won't compile here anymore return@inlineFunction } } inline fun inlineFunction(crossinline inlineLambda: () -> Unit) { randomFunction { inlineLambda() // now this is perfectly fine } } fun randomFunction(nonInlineLambda: () -> Unit) { nonInlineLambda() }

Now we can have all the benefits of our inlineLambda and the compiler won't have to worry about non-local returns.

A good example of crossinline in the Kotlin standard library is the sortBy function:

public inline fun > MutableList.sortBy( crossinline selector: (T) -> R? ): Unit
It passes the selector down to a regular function, but still inlines the comparator logic.

4. Reified modifier

Finally, we got to the final modifier that we will discuss today. This is probably my favorite one since it allows for some clever solutions.

Let's take a look at a simple example:

fun main() { val json = "{ ... }" val user = json.asObjectFromJson(User::class.java) } fun String.asObjectFromJson(classType: Class<T>): T? { // validate json // do some deserialization // return an instance of classType }

In a regular function, type T is only available during compile time and is erased at runtime. Therefore normally, we cannot infer the class of T at runtime and have to pass a Class as a parameter.

The reified modifier fixes this inconvenience. However, keep in mind that we can only use reified in the inlined functions.

Here is how we can improve our code using the reified modifier:

fun main() { val json = "{ ... }" // the call looks prettier as well val user = json.asObjectFromJson() } inline fun <reified T> String.asObjectFromJson(): T? { // validate json // do some deserialization // we can access the class of T during runtime now! return T::class.java.newInstance() }

By marking our generic T as reified we can use it inside the function as if it was a normal class.

The inline function makes this possible without using reflection, however, if you need to use it, reflection also becomes available for the reified types as well as operators like is and as that work with classes.

One of the most common examples of reified in the Kotlin standard library is the Iterable extension function filterIsInstance:

list.filterIsInstance<String>()
Conclusion

When switching from Java to Kotlin, it can be very tempting to continue writing Java code, only using Kotlin. Kotlin will not stop you from doing that.

However, Kotlin offers so much more and any Kotlin user would be doing themselves a huge disservice by missing out on a huge variety of features that Kotlin provides.

Today we have looked at some of those features, and, hopefully, this information will help you write better idiomatic Kotlin code.

See you next time.

To growing and sharing,

Your friend,

Max

Understanding Layouts in Jetpack Compose

Max Kim — Sun, 25 Jul 2021 17:28:39 GMT

In my previous article Things you need to know before switching to Jetpack Compose, I discussed the basic principles of building UI using Jetpack Compose.

Today, let's dive a little deeper into how layouts work in Compose and learn how to build a more complex UI.

Contents

1. The basics of layouting in Compose / Three basic layout 2. Dissecting the layouts 3. The Modifier. Size / Appearance / Interactivity 4. Summary
The basics of layouting in Compose

Before we begin

Nesting layouts in .XMLs, is considered very bad practice since the performance hit due to remeasuring and recalculating the position of children is quite noticeable, especially when nesting more heavyweight layouts.

One of the main differences in Compose that fundamentally changes how we structure UI is that Compose doesn't allow measuring of layout children more than once. In fact, it will even throw a RuntimeException if that ever happens.

Therefore, you can nest composables as much as you like without worrying about performance.

With that out of the way, let's dive in!

The first thing to remember about composable functions is that they don't return anything, or rather they return Unit since we live in the Kotlin world. This might confuse some folk coming from React Native or Flutter, where similar functions do return components or widgets to build UI.

In Compose, we describe our UI, and every composable we put inside a composable function will be reflected on the screen in one way or another.

For example:

@Composable fun Haiku() { Text(text = "I write, erase, rewrite") Text(text = "Erase again, and then") Text(text = "A poppy blooms.") }
This is a perfectly fine composable, which draws every one of the Text composables on the screen.

However, we didn't specify how exactly we want to display our lines of text, and therefore we get a quite predictable result:

Three basic layouts

If you have read my previous article, you might remember that we have used a Row to display the elements one after the other, or in other words in a row.

It would only make sense then to have another layout composable called Column. And, in fact, we do.

These are the main building blocks of UI in Compose. In most cases, we will use a combination of Rows and Columns to get the desired result.

There is another basic layout that we can use, called Box.

Here is an illustration of these basic layouts, courtesy of the official Compose documentation:

Speaking about how these layouts stack children, we could say that:

Column is similar to vertical LinearLayout;

Row is similar to horizontal LinearLayout;

Box is similar to FrameLayout.

But please keep in mind that these composable layouts are much more than their imperative counterparts. In fact, in most cases, these three layouts are all you need to build any UI. Using only LinearLayouts to build our UI would be a huge no-no. However, since nesting in Compose doesn't affect performance - this is the standard way here.

Note: There is a ConstraintLayout in Compose that allows a more sophisticated layouting. I will probably write a separate article about it but keep in mind that even though ConstraintLayout was a recommended way to build layouts until now to avoid nesting layouts, in Jetpack Compose, you don't actually need it.

Now, let's return to our haiku and try to fix it.

In order to display the Text lines in a column, all we have to do is to wrap them inside a Column composable:

@Composable fun Haiku() { Column { Text(text = "I write, erase, rewrite") Text(text = "Erase again, and then") Text(text = "A poppy blooms.") } }
Which gives us the desired outcome:

One thing to keep in mind here is that if you don't specify the layout of the children, they will be affected by the parent of the composable.

For example, the following code will give us the same result:

class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { // This Column will affect the contents of our composable Column { Haiku() } } } } @Composable fun Haiku() { Text(text = "I write, erase, rewrite") Text(text = "Erase again, and then") Text(text = "A poppy blooms.") }
But in this case, the composable has no say in how its children will be laid out. If someone calls our Haiku from the context of a Row layout, our composable will produce an undesired result. Therefore, this approach is not recommended, just something to keep in mind for educational purposes.

Dissecting the layouts

As I have said before, these basic layouts are much more than meets the eye. In fact, they provide us with everything we might need to build UI.

Let's see what we can do with them.

For that, here is a quick tip for those who don't use shortcuts much.

You can press CMD/Ctrl + P inside a constructor's or function's argument brackets, and Android Studio will show every possible argument with default values.

Note: you can also do it inside the trailing lambda since technically, it is an argument you pass.

I cropped this image a bit to be legible on smaller screens, but you get the point.

This way, you can always see what options are available to you. And if you need some additional information, nothing beats opening a source code and reading the declaration.

With that out of the way, let's see what we can do with our Column.

The Column

@Composable inline fun Column( modifier: Modifier = Modifier, verticalArrangement: Arrangement.Vertical = Arrangement.Top, horizontalAlignment: Alignment.Horizontal = Alignment.Start, content: @Composable ColumnScope.() -> Unit )
At first glance, there isn't much. However, the first parameter that takes in a Modifier is a true powerhouse in the Compose world, and you will be using it a lot.

Let's leave it for now and take a look at the other parameters.

The content

The content is a function with a ColumnScope as a receiver. If you are not familiar with this Kotlin concept, you can read about it here. What it does is it makes the ColumnScope as this inside the function.

This is the content we want to display inside our Column.

The horizontalAlignment

horizontalAlignment defines how we align our content horizontally, and all the expected options are supported:

However, please note that arguments of type Alignment.Vertical will not be accepted here. Those are used in the Row layout.

The verticalArrangement

The idea of arrangement might be new to some people coming to declarative UI. Still, even in the imperative approach, we had a similar concept when defining how to position chained items inside a ConstraintLayout.

verticalArrangement defines how children will be arranged along the height of the column.

Here are the available options for Arrangement.Vertical:

And before we tackle the modifier, let's take a look at the arrangement/alignment options for the other basic layouts.

The Row

The Row is pretty much the same as the Column:

@Composable inline fun Row( modifier: Modifier = Modifier, horizontalArrangement: Arrangement.Horizontal = Arrangement.Start, verticalAlignment: Alignment.Vertical = Alignment.Top, content: @Composable RowScope.() -> Unit )
The main difference is that the Arrangement and Alignment are switched.

The verticalAlignment therefore takes an Alignment.Vertical as an argument, which has all the usual alignments.

And horizontalArrangement takes the Arrangement.Horizontal object, where Arrangement.Top becomes Arrangement.Start and Arrangement.Bottom becomes Arrangement.End.

The Box

Lastly, we have the Box.

@Composable inline fun Box( modifier: Modifier = Modifier, contentAlignment: Alignment = Alignment.TopStart, propagateMinConstraints: Boolean = false, content: @Composable BoxScope.() -> Unit )
As we have mentioned, the Box behaves similar to FrameLayout when arranging children, therefore there is no Arrangement parameter. We can only specify the Alignment, which has all the alignments we would expect to find there.

The propagateMinConstraints is nothing to concern ourselves about given the scope of this article, but for some quick info, we can refer to the KDoc:

If propagateMinConstraints is set to true, the min size set on the Box will also be applied to the content, whereas otherwise, the min size will only apply to the Box.

The Modifier

With that, we come to the modifier. Although we are talking about layouts today, you can apply the Modifier to any composable, which allows us to, yes, you've guessed it, modify the composable. And layouts are composables, after all.

There are a lot of things we can do with the Modifier, but for the sake of keeping this article at a manageable size, we will only look at the most common use cases.

That said, first things first. Before looking into specific modifiers, let's once again start by understanding what the Modifier object really is.

Under the hood

Here is what we can find in the declaration.

/** * An ordered, immutable collection of modifier elements * that decorate or add behavior to Compose UI elements. * For example, backgrounds, padding, and click event listeners * decorate or add behavior to rows, text, or buttons. */ interface Modifier
We can see that the Modifier represents a collection of modifier elements that change the appearance or behavior of composables.

The Modifier.Element is also a simple interface. Every modification that we can apply to composables implements this interface, which allows it to be stacked into a Modifier chain.

/** * A single element contained within a Modifier chain. */ interface Element : Modifier
There are a lot of Modifier.Elements that Compose gives us out of the box, and as you can see, this approach is very flexible and allows us to write custom modifiers if needed.

By clicking the green I↓ button next to the declaration, we can see all the available Modifiers.

There are Background, SizeModifier, PaddingModifier, and many others that we will regularly use in Compose.

Don't worry, you don't need to memorize these implementations. Or, to be frank, even know that they exist.

I just wanted to dig a little bit deeper and show how it all works for educational purposes. Compose provides us with simple and intuitive DSL for using modifiers and you won't need to know the specifics of the implementation if you don't want to. However, I believe that knowing how the stuff we regularly use works makes us much better developers.

How chaining modifiers works

As you might have already seen in my previous article, we can use the modifiers as follows:

@Composable fun Haiku() { Column( modifier = Modifier .fillMaxWidth() .padding(10.dp) .background( color = Color.Blue ) ) { Text(text = "I write, erase, rewrite") Text(text = "Erase again, and then") Text(text = "A poppy blooms.") } }
This is how a chain of modifiers looks in code.

Note: Please keep in mind that the modifiers will be applied in the specified order, which has an effect on how the final result will look. For example, in the code above, the padding will be applied before the background. Therefore, the blue background will be inside the padding, and the padding itself won't have any color. If we had specified the padding after the background, then the whole composable's background would be blue, including the padding.

And before I bore you to death with going through the source code, let's take a look at it one last time and see how it all comes together.

Let's take .padding() as an example:

fun Modifier.padding(all: Dp) = this.then( PaddingModifier( start = all, top = all, end = all, bottom = all, rtlAware = true, inspectorInfo = debugInspectorInfo { name = "padding" value = all } ) )
It is a simple Kotlin extension function that creates a new PaddingModifier, which implements Modifier.Element, and passes it to the existing Modifier through the then function.

/** * Concatenates this modifier with another. * Returns a Modifier representing this modifier * followed by other in sequence. */ infix fun then(other: Modifier): Modifier = if (other === Modifier) this else CombinedModifier(this, other)
As you can see, the then function adds a new Modifier to the existing chain and returns the resulting Modifier so that the chain can continue.

Not that we know how Modifier works, let's finally look at some of the most used modifiers.

Modifying the size

Most commonly, the Modifier is used for specifying the size of a composable.

// Set the width and/or height of a composable // to specific size in Dp .width(width: Dp) .height(height: Dp)
// Fill all available space for width and/or height // Equivalent of "match_parent" // // Can be specified with a fraction argument // to fill a fraction of available space .fillMaxWidth(fraction: Float = 1f) .fillMaxHeight(fraction: Float = 1f)
// Fill all available space for both width and height // // Can be specified with a fraction argument // to fill a fraction of available space .fillMaxSize(fraction: Float = 1f)
Modifying the appearance

And here are some common Modifiers that are used for changing the appearance of a composable.

// Adds padding to the composable .padding(all: Dp) .padding( horizontal: Dp = 0.dp, vertical: Dp = 0.dp ) .padding( start: Dp = 0.dp, top: Dp = 0.dp, end: Dp = 0.dp, bottom: Dp = 0.dp )
// Modifies the alpha/scale/rotation .alpha(alpha: Float) .scale(scale: Float) .scale(scaleX: Float, scaleY: Float) .rotate(degrees: Float)
// Specifies the color and shape of the background .background( color: Color, shape: Shape = RectangleShape )
// Adds a border .border( width: Dp, color: Color, shape: Shape = RectangleShape )
// Clips the content to shape or bounds .clip(shape: Shape) .clipToBounds()
Modifying the interactivity

Modifiers are also used to describe the behavior of a composable, or, in other words, how we can interact with it.

// Adds click functionality to the composable // Use .combinedClickable for long clicks and double clicks .clickable( enabled: Boolean = true, onClick: () -> Unit )
// Adds scrolling functionality to the composable // Yes, anything can become a ScrollView! .verticalScroll( state: ScrollState, enabled: Boolean = true, ) .horizontalScroll( state: ScrollState, enabled: Boolean = true, )
// Adds focus listener to the composable .onFocusChanged(onFocusChanged: (FocusState) -> Unit) // Adds key event listener to the composable .onKeyEvent(onKeyEvent: (KeyEvent) -> Boolean) // Adds size listener to the composable .onSizeChanged(onSizeChanged: (IntSize) -> Unit) /// ... and other listeners
Of course, this is just scratching the surface of what we can do in Compose through modifiers, but this gives a pretty good idea about how things work in this new toolkit.

Summary

We have gone through a lot of information today, haven't we?

Thanks a lot for sticking until the end.

Just to recap:

In Compose, almost everything can be drawn with Rows, Columns, and an occasional Box. There is no need for complex layouts like ConstraintLayout since nesting elements don't affect the performance as it was in the old days.

Compose is very flexible and gives us many ways how to align and arrange elements. As well as style and add behavior to our composables through the Modifier object that allows us to achieve almost any result right out of the box. And if not, you can always write your own modifiers and custom layouts.

And of course, there is no better way to learn things than doing them yourself. So fire up Android Studio, play around with Compose, and see how it works.

But keep in mind that it can become quite fun and addictive when you get a grip on it.

Until next time,

Your friend,

Max

Things you need to know before switching to Jetpack Compose

Max Kim — Mon, 12 Jul 2021 09:39:13 GMT

With the release of the stable version of Jetpack Compose just around the corner, here are some things you need to know before switching from the imperative, XML-based style for building UI, to the new Android’s toolkit for building native UI declaratively.

First, let's get the basics out of the way

What does it mean to build UI declaratively rather than imperatively? Let's quickly break down the main difference between these two styles.

The imperative style focuses on how. You provide step-by-step instructions on how you would like to get to your desired result. This is how we were building UI in Android applications all this time. The simplified illustration of the imperative style would be:

-> Go to the kitchen. -> Open the fridge. -> Take eggs from the fridge. -> Put eggs in a pan. -> Wait 5 minutes. -> Put eggs from the pan on a plate.
The declarative style, on the other hand, focuses on what. You describe what result you want to achieve. The above example would look something like this:

-> I want fried eggs.
The declarative approach does remove quite a lot of boilerplate, provided you have a buddy who knows how to cook. Luckily for us, in the Android UI building world, Jetpack Compose is that buddy.

Other examples of building UI declaratively in the mobile development are ReactNative, Flutter, and SwiftUI.

How to use Compose for building UI

To draw UI, Compose uses regular Kotlin functions annotated with @Composable. Therefore, these functions are often referred to as composables.

Here are some key points regarding composable functions to keep in mind:

Composable functions can only be called from within the scope of other composable functions.

Composable functions don't return anything. They don't return any Views or Widgets but rather describe the UI.

Composable functions can take in arguments and you can use regular Kotlin expressions within the composable function as you would within regular functions.

Composable functions should behave the same way when called multiple times with the same arguments, without using or modifying global properties and variables.

As opposed to the regular naming convention of functions in Kotlin, names of composable functions start with a capital letter.

With that out of the way, let's look at how to use Jetpack Compose in practice.

Let's say we need to build the following UI element:

Now, to achieve this result, we need to describe the following things in our composable function:

We need a Text and a Checkbox, arranged in a Row, with some Space in between.

The whole Row should be modified to have a gray RoundedBorder and some Padding to let the elements inside breathe.

The elements inside should be CenteredVertically, for a more pleasant look.

Let's create our Composable and, without being too preoccupied with the syntax at this stage, see how our description looks in Kotlin:

@Composable fun FollowTheBlog() { Row( modifier = Modifier .border( width = 1.dp, color = Color.Gray, shape = RoundedCornerShape(5.dp) ) .padding(14.dp), verticalAlignment = Alignment.CenterVertically, ) { Text("Check to follow the blog for awesome content!") Spacer(modifier = Modifier.width(8.dp)) Checkbox( checked = false, onCheckedChange = { checked -> // some follow the blog action } ) } }
This code should be quite intuitive and easy to read, even for those not fluent in Kotlin, which is a major step up from how we used to build our Android UI.

Now, if we run our composable, it will indeed produce the desired result in terms of visuals but, if we try to interact with it, we will notice some unexpected behavior:

The Single Source of Truth

The main premise of Jetpack Compose is to represent the current state of UI on the screen and, as opposed to when using views, clicking the checkbox emitted by Compose doesn't visually change it because we haven't changed the state of our UI.

Coming from the imperative style of building UI, this approach might seem unintuitive and redundant, but this is one of the key concepts in declarative UI.

The main benefit of this approach is that Compose makes it much easier to manage the state of UI in one place. This allows us to draw UI based on a single source of truth - the current state of UI - without needing to synchronize the state between multiple components, as was often the case when using an XML/View-based approach.

Understanding State

Since composable functions represent the state of UI, the only way to update UI is to run the composable function again but with different arguments representing the current state. In Compose, this is called Recomposition.

So if we look at our code above, we see that we have described our Checkbox with an argument checked = false, which is exactly what we got.

Considering this, we could fix our checkbox with the following steps:

When describing our Checkbox, we will set the parameter checked to a variable.

We will toggle that variable in the onCheckedChange callback.

We need that variable to persist between the recompositions.

We need to trigger the recomposition when the user clicks the checkbox.

The first two steps are quite straightforward. It could look something like this:

Checkbox( checked = isChecked, onCheckedChange = { checked -> isChecked = checked // some follow the blog action } )
The last two steps, however, might present some challenges for people new to Compose.

Let's break them down.

First, we need to persist the value of the isChecked variable between recompositions or, in other words, multiple runs of the function. The first answer that comes to mind would be to declare it as a global variable outside the scope of the composable function.

However, those who paid attention earlier would notice that this would violate one of the key points:

...without using or modifying global properties and variables

Moreover, the state of a checkbox represents the local state - other components don't necessarily need to know or influence how the checkbox is rendered.

Therefore, a better solution would be to manage this state inside our composable function, but it takes us back to square one with our persistence problem.

Luckily for us, Compose has an elegant built-in solution for this problem, as well as the problem with triggering the recomposition.

Here is how this solution looks:

var isChecked by remember { mutableStateOf(false) }
This one line can be quite a brain bender for people who are new to Compose and/or are not used to more advanced Kotlin syntax, so let's break it down.

First, let's take a look at the mutableStateOf function.

If you have read my previous blog post 7 Tips for Becoming a Better Developer, you know that I like to dive into the source code to understand the API of a framework better, so buckle up.

The signature of this function is as follows:

fun mutableStateOf( value: T, policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy() ): MutableState
We can see that this function takes in a value of generic type and returns an object implementing an interface MutableState : State. The policy parameter has a default value so let's not concern ourselves with it for the time being.

The value represents the initial value of that state, and in our case, we pass false for our checkbox to be unchecked.

If we go down the rabbit hole into the source code to find the actual implementation of our MutableState object, we will find:

/** * A single value holder whose reads and writes are observed by Compose. * ... */ internal open class SnapshotMutableStateImpl( value: T, override val policy: SnapshotMutationPolicy ) : StateObject, SnapshotMutableState
The most important part is the first line of the KDoc.

Without getting stuck on the implementation details, we can see that this state object acts as an observable.

In practice, it means that Compose will observe our state and when the value changes it will schedule a recomposition of any composable subscribed to it.

The composable subscribes to a state when it reads its value.

In other words - when setting the initial value, the composable will subscribe to changes in our state. As soon as we change the state inside the onCheckedChange callback, it will trigger the recomposition.

Next is the remember { } function.

/** * Remember the value produced by [calculation]. * [calculation] will only be evaluated during the composition. * Recomposition will always return the value produced by composition. */ @Composable inline fun remember( calculation: @DisallowComposableCalls () -> T ): T
The implementation details of this function can seem quite tricky, especially for less experienced programmers, but once again, reading the KDoc is more than enough for understanding what the function does.

The key takeaway is as follows:

As opposed to regular Kotlin functions, composable functions have a memory which persists across recompositions and even across configuration changes. remember function allows you to access that memory during recompositions. This means that by wrapping our state inside the remember function, we allow Compose to access its value during the next recomposition.

This means that when we change the value inside the isChecked state and trigger recomposition, the next time our function runs, it will remember our value.

Please note that remember doesn't work for configuration changes. For that, we would use a similar function rememberSaveable, which uses Bundle under the hood.

Lastly, we have the by keyword.

This is a feature of Kotlin called Delegated Properties. It allows manual implementation of the setter and the getter of a property.

In this case, it unwraps the value property inside the MutableState object and allows us to access it as we would a regular property.

Without it:

var isChecked = remember { mutableStateOf(false) }
We would have to access the value of our state directly:

Checkbox( checked = isChecked.value, onCheckedChange = { checked -> isChecked.value = checked // some follow the blog action } )
Note: As of writing this post, you have to manually add the following imports for the by keyword to work correctly.

import androidx.compose.runtime.getValue import androidx.compose.runtime.setValue
In summary, here is what we have achieved with that line:

We have created a isChecked variable, which is a state.

The Compose will subscribe to our state during the initial composition when setting the initial value. The value writes that happen in the onCheckedChange callback will trigger recomposition.

During the recomposition, Compose will remember the value of the state from the initial composition and render UI correctly.

We have used an advanced Kotlin feature to unwrap the value of our state so that we can use it as a regular property.

How it all comes together

This is just scratching the surface of the topic of state management in Compose. For those willing to learn more, I will leave a link to the official documentation.

For now, however, let's see how our code looks with all the fixes:

@Composable fun FollowTheBlog() { var isChecked by remember { mutableStateOf(false) } Row( modifier = Modifier .border( width = 1.dp, color = Color.Gray, shape = RoundedCornerShape(5.dp) ) .padding(14.dp), verticalAlignment = Alignment.CenterVertically, ) { Text("Check to follow the blog for awesome content!") Spacer(modifier = Modifier.width(8.dp)) Checkbox( checked = isChecked, onCheckedChange = { checked -> isChecked = checked // some follow the blog action } ) } }

And with that, we have a working checkbox!

Switching to Jetpack Compose

Moving forward, Jetpack Compose will be a primary way to build UI on Android, and, sooner or later, the developers will have to embrace it.

To make things easier, here are some things to keep in mind when switching to Jetpack Compose:

You have to use Kotlin to utilize Jetpack Compose fully.

Compose is written in Kotlin, so its Java compatibility is limited, and there are no plans to support it in the future. Therefore, if you haven't already, this might be a good point to start learning Kotlin. The good news is that Kotlin is awesome, and for Java developers, it shouldn't take more than a couple of weeks to start developing in Kotlin comfortably.

Jetpack Compose is fully compatible with the old .XML/View-based way of building UI.

You can start migrating your project to Compose on a screen-by-screen basis, or even add Compose components to existing .XML layouts or ViewGroups. You can do it with a ComposeView, which you can use as a regular View. It has a setContent { } function that allows you to add composables to existing UI.

composeView.setContent { // you can use composables here, // which will be added to the view Text(text = "I am Compose inside this View!") }
It also works great the other way around. You can use regular Views or layouts inside the Composable scope. For that, you can use a composable function AndroidView, which has a factory that provides a context and allows you to inflate Views or layouts.

setContent { AndroidView( factory = { context -> // use this context to inflate views or layouts TextView(context).apply { text = "I am a View inside Compose!" } } ) }
You can find more information on interoperability API in the official documentation.

Jetpack Compose can be easily integrated with common Android libraries and popular stream-based solutions

Compose comes with support for ViewModels, Navigation, Paging, as well as other Android libraries. It also provides an API to listen to LiveData, Flow or RxJava's Observable and represent their values as State.

This makes integrating Compose into an existing project much easier, especially if the project has an architecture with a unidirectional data flow.

As always, there is a lot of useful information about that in the documentation.

Some other things to keep in mind

To start using Jetpack Compose, you need at least the Arctic Fox version of Android Studio, which as of the time of writing is available in Beta.

Most people will probably start using Compose in an existing project. While adding Compose to an existing project shouldn't be too hard, depending on the state of your dependencies (pun not intended), it can be a bumpy ride. To make things easier, please refer to this guide and be sure to upgrade the Gradle plugin to the latest version.

At the time of this writing, the Compose Compiler requires Kotlin version 1.4.32. If you are using 1.5 features in your project, you might have to wait a bit or use the suppressKotlinVersionCompatibilityCheck flag, which might cause unexpected behavior.

Compose allows you to preview your UI without building your app, which greatly speeds up development. You can also interact with the preview as you would on a normal device. However, depending on your version of Android Studio, this feature might be experimental and therefore hidden. To turn in on, go to Preferences -> Experimental -> Enable interactive and animation preview tools.

For many of us who are using ConstraintLayout on a daily version, Compose has its own version. MotionLayout is not supported just yet, but the Compose team is working on supporting it.

Conclusion

Jetpack Compose is a huge toolkit, and one can probably write a whole book about it. It makes writing beautiful UI much easier and offers quite a few APIs and features that allow us to build UI in ways that weren't possible with layouts and views.

Compose has already hit a release candidate version and will be available as a stable version in no time. As I have noted before, this will be a new standard for Android development. Therefore, now is as good a time as any to start learning it.

I am truly excited about this new chapter in Android development and the journey that lies ahead. Hopefully, for some people, this post will make starting this journey a little bit easier.

See you next time.

To starting new journeys,

Max.

7 Tips for Becoming a Better Developer

Max Kim — Mon, 05 Jul 2021 19:12:35 GMT

Most of the writing on software development is very technical, aimed at researching and solving a particular problem. Such writing provides tremendous value, and I imagine most of what I will write in this blog will be just that - posts focusing on technical aspects of certain languages, platforms, and frameworks.

For this first entry, however, I would like to take a look at the bigger picture and think about the main things that helped me a lot in becoming a better developer in the past couple of years.

Most of the examples in this blog post are related to Android development. Still, the concepts are applicable to any field.

Tip #1: Know your domain

If you have chosen something as your craft, and are spending most of your waking hours doing it, it would only make sense to always improve and hone that skill.

Regardless of your current experience, never stop learning. Don't ever make a mistake and assume that you know something already and there is nothing to learn. Even the basics. By doing that, you shut your brain off to any possibility of learning something new, and there is always something to learn.

Remain curious, be open-minded, and always ask questions. Never be content with things you don't know. Never settle with what you do know. Especially when it comes to your area of expertise.

“Sell your cleverness and buy bewilderment.” - Rumi

Here are some things that have helped me a lot to become a better Android developer. The principles, however, apply to any language and platform.

Start searching for answers in the source code and the documentation. By reading the source code of Kotlin and Android, I got many great ideas that I now regularly use in my projects, and it helped a lot to improve my style as well.

Strive to fully understand things that you use on a daily basis. If you are an Android developer like me, start with Activities and Fragments, you will use them in every single application. Open up the source for AppCompatActivity and go through all the public methods it exposes. Look for things you never knew existed. Do the same for Fragment. Modern IDEs make it so easy and you will learn a lot. Make a habit of CMD/Ctrl + clicking classes and see what’s inside.

Stay informed about new things in your domain. Find a newsletter, read blogs, watch YouTube - do anything to stay in touch with what is happening in your chosen field.

Tip #2: Know your tools

Every craftsman has to constantly improve their knowledge of the tools they use. If your main line of work is being a developer, I imagine you spend a lot of time in some kind of text editor, or, most probably an IDE. Nowadays, IDEs are very advanced and it’s highly likely you don't know most of the features your IDE offers. Some of the features might not be useful to you personally, but you won't know it if you don't even suspect they exist.

Here are some things to get you started:

Google and try out different productivity tips for your IDE.

Learn and use the shortcuts for actions you are using repetitively.

See if there is a template/snippet functionality in your IDE.

Invest some time in setting up custom lint rules to quickly spot errors and code smells.

Browse available plugins and see if any can help improve your workflow.

Apart from the IDE/text editor, make sure to spend some time looking into features and productivity tips for your Mac/PC, whatever you use. It is your main tool when it comes to coding, so make sure you are comfortable with it.

There should not be a single thing that is detrimental to your workflow and the quality of your work. If there is, someone online has probably found a solution. Go find it.

Tip #3: Sharpen your micro and macro

There are two concepts you have probably heard of, being a developer - Clean Code and Clean Architecture. I like to refer to them as micro and macro.

Clean Code is your micro - how you write your code, the naming conventions, the style/conventions of your language of choice, the structure of your functions, DSL, etc.

Clean Architecture is your macro - the architecture of your software, the way you structure your files, and what public APIs you expose.

When it comes to the Clean Code, or your micro, there are a lot of things you can do to improve it, but if you don't know where to start, I would recommend Robert. C. Martin's book Clean Code, which popularized the concept. Or just google it, there is a lot of material on the topic. The main point here is that your code should make sense and be easily readable by your fellow developers. Or by you after a year or so.

The Clean Architecture is a harder nut to crack, especially if you are just starting out. For the beginners out there I would recommend focusing on learning Clean Code and the specifics of your language/platform. As soon as you get a grasp of that, learn the most popular architectural pattern for your platform. In the case of Android, it would be MVVM. After that, learn the Clean Architecture, which also has an excellent corresponding book by Robert. C. Martin.

Moreover, all architectural patterns aim to solve certain problems, they have evolved over time and became what they are for a reason. Make sure you know and understand what those problems are, and don't blindly copy the patterns just to use them. It would certainly be better than not using any pattern at all, however, the main point I am trying to make here is if you are doing something, understand the why behind it.

Some would say that in smaller projects it doesn't make sense to complicate the codebase with the boilerplate that might come from implementing a Clean Architecture pattern or any other pattern for that matter, and I would argue that how you do anything is how you do everything. Your attitude towards your work is a habit and it can only go two ways.

Tip #4: Writers are readers

I love books and I am fascinated by the people who write them. Many, if not all, of the most accomplished writers, are first and foremost readers themselves - because of their love for the craft but also to fuel their creativity.

I don't see why it should be any different for writing code.

There are a lot of open-source projects that you can learn from. Tutorials and documentation are often good for learning isolated cases. By reading real projects, you learn how it all comes together. It is one of the best ways to learn both macro and micro. So do yourself a favor and let GitHub become your library.

If a project's author is better than you, you will learn a lot. And if, on the other hand, you happen to be further along on this journey, you can train your brain to spot things that can be improved. You should be doing it with your own code anyway. It is a win-win situation.

And if you don't understand or don't agree with something you see, don't dismiss it immediately. Think about it and understand it. Talk with other people about code. Discuss ideas. Always question your logic. We are creatures of habit, but for many people, unfortunately, habits mean living in the past, repeating engrained neurological patterns again and again without any potential for growth. Just as life can get stale and uneventful because of routine, your code can and will get stale without active and mindful participation.

Here is an awesome curated list for all you Android developers to get you started.

And if you are not an Android developer, you know what to do.

Tip #5: Do not ever sacrifice the quality of your code

In science, there is a concept called entropy - a measure of disorder in a given system. Or in layman's terms - as time goes on, things tend to fall apart. Everything that is orderly, will always tend towards disorder.

Code is no different.

There are many reasons why code will degrade over time and turn into an unmanageable pile of spaghetti on some occasions. It might be a result of poor planning, it might happen because of some shortcuts we continuously take during development, it might happen because of time constraints, it might happen because we lose passion for a project and abandon things at a “good enough” state.

Never stop at the point when your code works. Try to see how you can improve the structure of your code, how you can make your code more readable and elegant. It might sound like a lot of work in the beginning but, eventually, your first drafts will start coming out very close to the final result.

If you had finished your coding session late at night, make a habit of reviewing it in the morning, and see if you still like what you wrote and things make sense.

Avoid taking shortcuts.

When a thought creeps in to make it a little bit easier for yourself, sacrificing the code quality in the process, catch that thought immediately and make it a trigger for yourself to step up your game.

There will be times when you will be pressured by time and will have to find solutions fast. Never see it as an excuse for sloppy code. See it as a challenge and a test for everything you have learned so far. Train yourself to maintain a professional approach to your work and never drop your standards, especially when things are falling apart around you.

And just to make things clear - I do not ask you to write perfect code.

I ask you not to write code that is worse than what you are capable of.

Tip #6: Be active and engaged at what you do

One of my main passions in life is learning how to learn. Trust me, this simple skill is a game-changer for anything you do in life. I love learning and constant growth, and for that reason, I have a major beef with schools and our outdated education system. Don't worry, I will not go on a huge tangent about that, but there is a reason I mentioned schools here.

From a young age, school taught us to sit still, passively absorb information, and expect others to have all the answers.

That is not how learning works.

One of the most important components of learning is being active and engaged, just like you had been learning before you went to elementary.

The same applies to writing code. When you are actively thinking and are engaged in the process, you will make fewer mistakes, write better code, and every coding session will become a learning session as well.

Let's talk about every developer's best friend for a minute. Yes, StackOverflow. Without any doubt, it is one of the most valuable resources for any developer. However, if you are more advanced and looking for ways to improve, I want you to pay attention to how you use it.

Many developers become too dependant on StackOverflow. They expect it to have all the answers to every question they might have during the development process.

You can certainly copy-paste other people's code, and it might be the best piece of code for your problem. There is nothing wrong with that. All I ask you is this - actively think and digest that code while you are at it.

Understand the code and make it your own.

And before we move on, just as a thought experiment ask yourself one simple question. If, as an exercise, you were not allowed to use StackOverflow for one day, and had to search for solutions on your own, in the documentation and the source code, would it make you a better developer?

Tip #7: Take care of your body

And here is the topic I wish got discussed more often in our community. First things first. I am not a nutrition or fitness expert but I feel like this needs to be mentioned here. Sometimes we get too involved in certain areas of our life, often times our career, while forgetting the others. But I would argue that there is nothing more important than our well-being. Especially for us, programmers.

I don't want to beat a dead horse here. We all know and heard a thousand times how bad it is to sit in front of a computer all day, eating pizza, and ignoring sunshine. Much fewer of us have an established routine to make ourselves healthier.

It all comes to priorities. Doing things without seeing an immediate benefit is incredibly hard, especially if the alternative is more satisfying, or doesn't require effort. I can name many reasons why being healthy will benefit your career as a software developer. For one, everyone knows the difference between a foggy slow brain, starved of nutrients and oxygen, and a well-rested brain fueled by proper nutrition.

However, I feel like there are many more important reasons than programming, or any career for that matter, why you should consider shining some consciousness onto the health and fitness area of your life and establishing a health-focused routine that will serve you for years to come. Becoming a better software developer will come as a bonus.

Here are some of my reasons:

I want to have a healthy body and energy to have many adventures and maximize my life experiences in every way, for as long as I can.

I want to be the best lover for my partner.

I want to set an example for my future children of what it means to be a self-responsible, conscious human being.

Find your reasons and make sure they will drive you.

Bonus Tip #8: Improve the interface

With all the heavy hitters out of the way, here is a small bonus one, that helped me a lot in the past couple of months. I have been using computers since childhood, learning how to use one as I went along. As a result, I developed some less than optimal habits.

As we have discussed earlier, we should always learn how to use our tools more efficiently. However, there is one more thing that stands in the way between our thoughts and the final code in the IDE - the interface between yourself and your computer.

Or your hands, for less technical folk out there.

It shouldn't be a surprise that your typing speed will impact your coding speed. However, there is one more benefit for typing faster.

Our brains are incredibly complicated biological machines, designed to process a huge amount of data. And when you force it to slow down, it will eventually become bored, disengage, and your thoughts will wander somewhere else. Just imagine reading a book one word at a time, with pauses in between.

On the other hand, when your hands are capable of putting information into your computer much faster, you will be able to concentrate on your code and more reliably achieve the flow state. You will not be distracted by typos and huge pauses needed for typing out the code. Imagine a master pianist. How good would their music be, if they had to focus on where to put their fingers?

So speaking of my childhood typing habits, I have recently noticed that my right hand is very passive while typing, and my fingers are very chaotic. So I started googling the correct typing techniques and found this incredible website https://www.typing.com/ to help me out.

After just a couple of months of training, my development speed improved a lot, so maybe it will also help you. It has a free version and I am not affiliated with them in any way.

And by the way, your brain will thank you for learning something new.

Before we part our ways...

... there is a last piece of advice I want to give you, especially, if you are just starting out as a developer. If the amount of information feels overwhelming, in this post or anywhere else on the web, don't sweat it. And don't even try to implement everything at once. Pick something, one small thing, and see if it works for you. And keep adding to it as time goes on. Remember - little by little, a little becomes a lot.

The main point is not to memorize these tips or perfect everything I talk about here. The main point is to constantly try out new things and see if they benefit you in any way. The above-mentioned tips are those that stuck with me and helped me tremendously.

Be curious and experiment.

See you next time.

To growth, and learning,

Max