DEV Community: Aleksander Jaworski

Kotlin Multiplatform: Writing Platform Specific Implementations with Contract Testing

Aleksander Jaworski — Thu, 11 May 2023 15:53:39 +0000

This article was originally posted on my blog, for better viewing experience try it out there.

Even though The Kotlin Multiplatform ecosystem is getting bigger every day, there are cases where we need to write platform specific implementations by hand. Either because it's too specific to our domain, or because of legal reasons.

In these cases, we will need to write multiple implementations ourselves. Besides the implementation, we will also need to verify that all the implementations work in the same way between platforms. Otherwise, the shared code might be unpredictable and produce different behavior between platforms.

In this article, I'll cover how to write platform specific implementations for retrieving the device language and formatting days of the week depending on this language. To verify that both implementations work correctly, I'll show how you can write one test to cover all the implementations, reducing boilerplate and increasing alignment between platforms.

The project repository is on GitHub, however due to iOS testing issues with Compose Multiplatform, Compose was commented out in order to fix the tests. This branch enables the UI, but breaks tests.

How to write platform specific code

There are two main ways of achieving this, I'll try to summarize each briefly.

Expect Actual

This is the official way of providing platform specific implementations, it is nice for top level helper function or data structures with common properties, but also some platform specific ones (required by the platform).

The downside of this approach is that these implementations are final, and in most cases this makes them hard to replace with a Test Double when testing.

Shared Interface with platform specific implementations

In this case, there is an interface which establishes a "contract" that the platforms need to follow through their implementation.

The platform specific implementations can be written in two ways:

Using the Native programming language, (e.g. Swift implementation that is passed in from the iOS platform to the shared code)
Using Kotlin, while targeting a specific platform: Kotlin/JVM, Kotlin/Native, Kotlin/JS.

The first option might be valid for complex implementations which might be hard to write using Kotlin, like Cryptography. However, this solution is harder to maintain, because it requires separate tests in Kotlin and in the Native language.

The second option requires using "native APIs" (like platform.Foundation) from Kotlin, which might be difficult. The upside is that it is easier to test and all the code resides in the shared codebase, making it easier to maintain and reason about.

Because the shared code depends on an interface, it makes it easier to replace with a Test Double when testing. Production apps use the real implementations, and the test code can use a Fake implementation. Because of this, the article will use the latter approach.

Providing the device language

These implementations are pretty straight forward, so I won't get into the details too much. In the common code, we have an interface and a data class:

data class Language(val value: String)

interface LocaleProvider {

    fun getLanguage(): Language
}

And both platform implementations are one-liners:

import java.util.Locale

class AndroidLocaleProvider : LocaleProvider {

    override fun getLanguage(): Language = 
        Language(Locale.getDefault().language)
}

import platform.Foundation.NSLocale
import platform.Foundation.currentLocale
import platform.Foundation.languageCode

class IosLocaleProvider : LocaleProvider {

    override fun getLanguage(): Language =
        Language(NSLocale.currentLocale.languageCode)
}

These simple implementations allow us to retrieve the device language based on the phone settings.

However, we still need a way of instantiating these implementations, and currently, this can't be done in the common code. We can, however, create an expect actual function which will create "an instance" of the interface:

expect fun createLocaleProvider(): LocaleProvider

actual fun createLocaleProvider(): LocaleProvider = 
    AndroidLocaleProvider()

actual fun createLocaleProvider(): LocaleProvider = 
    IosLocaleProvider()

These functions can be used for creating the production implementation and then introducing it to the dependency graph, or for testing the production implementations.

Formatting the day of the week

Now that we have a way of retrieving the device language, we can format the day based on that language. The next implementations are a little bit more complex, but should be still easy to understand. Just like previously, we start out with an interface:

interface DayOfWeekNameProvider {

    fun getLongName(dayNumber: Int): String?
}

expect fun createDayOfWeekNameProvider(
    localeProvider: LocaleProvider
): DayOfWeekNameProvider

The Android implementation uses the java.util.Calendar, which is pretty much what would be done in native Android apps:

class AndroidDayOfWeekNameProvider(
    private val localeProvider: LocaleProvider
) : DayOfWeekNameProvider {

    override fun getLongName(dayNumber: Int): String? {
        val calendar = Calendar.getInstance()
        calendar.set(Calendar.DAY_OF_WEEK, dayNumber)
        val locale = Locale(localeProvider.getLanguage().value)
        return calendar.getDisplayName(Calendar.DAY_OF_WEEK, Calendar.LONG, locale)
    }
}

actual fun createDayOfWeekNameProvider(
    localeProvider: LocaleProvider
): DayOfWeekNameProvider =
    AndroidDayOfWeekNameProvider(createLocaleProvider())

The Kotlin / Native implementation is more out of the ordinary, because we need to connect the Kotlin world with the iOS world:

class IosDayOfWeekNameProvider(
    private val localeProvider: LocaleProvider
) : DayOfWeekNameProvider {

    override fun getLongName(dayNumber: Int): String? {
        val dateFormatter = NSDateFormatter().apply {
            this.locale = NSLocale(localeProvider.getLanguage().value)
        }
        val index = dayNumber % 7
        return dateFormatter.weekdaySymbols[index].toString()
    }
}

actual fun createDayOfWeekNameProvider(
    localeProvider: LocaleProvider
): DayOfWeekNameProvider =
    IosDayOfWeekNameProvider(localeProvider)

As you can see, both implementations are still pretty easy to understand and are fully written in Kotlin. The best part is that they work:

English locale

German locale

However, there is a problem with the current implementation, can you spot it...?

On start-up, the both apps show a different day of the week. For Android, day 1 is Sunday and for iOS it is Monday. If we released this app to production, the user experience would be different between platforms. Additionally, it could cause unexpected behavior if we were to save the days to a database or send them to an API.

Verifying platform implementations

Test class for each implementation

The first solution for verifying these two implementations could be writing a test for each implementation. This is ok, but it has some drawbacks:

More code means more maintenance. When changing something, the work is multiplied for each platform (tests + implementation).
It is easy to forget about the other platforms, without due diligence, the tests could be misaligned and pass even though the platform implementations are different

Keeping in mind, we want those two implementations to behave in the same way, it would be best to have one test that verifies all the platforms. This can be achieved by writing a Contract test.

Contract test for verifying all platforms

A Contract test is written once in commonTest, and depending on the target, it uses the corresponding implementation for that platform. A contract test for the DayOfWeekNameProvider can be as follows:

class DayOfWeekNameProviderContractTest {

    @Test
    fun `Day number 1 is Monday`() =
        longNameTestCase(dayNumber = 1, "Monday")

    @Test
    fun `Day number 2 Tuesday`() =
        longNameTestCase(dayNumber = 2, "Tuesday")

    @Test
    fun `Day number 3 Wednesday`() =
        longNameTestCase(dayNumber = 3, "Wednesday")

    @Test
    fun `Day number 4 Thursday`() =
        longNameTestCase(dayNumber = 4, "Thursday")

    @Test
    fun `Day number 5 Friday`() =
        longNameTestCase(dayNumber = 5, "Friday")

    @Test
    fun `Day number 6 Saturday`() =
        longNameTestCase(dayNumber = 6, "Saturday")

    @Test
    fun `Day number 7 Sunday`() =
        longNameTestCase(dayNumber = 7, "Sunday")

    private fun longNameTestCase(dayNumber: Int, expectedName: String) {
        val sut =
            createDayOfWeekNameProvider(FakeLocaleProvider("en"))

        val result = sut.getLongName(dayNumber)

        assertEquals(expectedName, result)
    }
}

The above test could be improved by also verifying a different language and testing out some boundary case values like -1, 0 or 8. The test also uses a testCase function, which is one way of doing parameterized tests on Kotlin Multiplatform.

The test results for the current implementation look like this:

The iOS tests pass, however the Android implementation is shifted by one day, so fixing it is just a matter of adding + 1 to the day number:

override fun getLongName(dayNumber: Int): String? {
    val calendar = Calendar.getInstance()
    calendar.set(Calendar.DAY_OF_WEEK, dayNumber + 1)
    val locale = Locale(localeProvider.getLanguage().value)
    return calendar.getDisplayName(Calendar.DAY_OF_WEEK, Calendar.LONG, locale)
}

Summary

Hopefully by now, you have an idea of how platform implementations can be created. Writing everything in Kotlin might seem awkward at first, but there are many benefits for doing it, as I hopefully laid out in this article.

Because everything is in Kotlin, we can verify all implementations with one contract test that ensure that all the implementations are aligned and work in the same expected way.

Such contract testing can be used anywhere where we have multiple implementations, like Production and Fakes or Flavor specific implementations.

Testing on Kotlin Multiplatform and a Strategy to Speed Up Development Time (2023 Update)

Aleksander Jaworski — Sat, 15 Apr 2023 06:00:00 +0000

This article was originally posted on my blog, for better viewing experience try it out there.

The main focus of Kotlin Multiplatform (KMP) is to avoid duplicating domain logic on different platforms. You write it once and reuse it on different targets.

If the shared code is broken, then all its platforms will work incorrectly and in my opinion, the best way to ensure that something works correctly is to write a tests covering all edge cases.

Because the KMP code base is the heart of multiple platforms, it's important that it contains as few bugs as possible.

In this article, I'll share my experience on writing tests for Kotlin Multiplatform, along with my strategy for speeding up development using tests. At FootballCo we use this strategy for our app, and we see that it helps our development cycle.

Even though the article focuses on Kotlin Multiplatform, a lot of the principles can also be applied to plain Kotlin applications or any other type of applications for that matter. Before starting, let me ask this question:

Why bother with testing at all?

Some engineers see tests as a waste of time, let me give some examples to change their mind.

Tests provide a fast feedback loop , after a couple of seconds you know if something works, or it doesn't. Verification through the UI requires building the whole app, navigating to the correct screen and performing the action. Which you can image, takes a lot more time.
It's easier to catch edge cases looking at the code , a lot of the times the UI might not reflect all possible cases that might happen.
Sometimes it's hard to set-up the app in the correct state for testing (e.g. network timeout, receiving a socket). It might be possible, but setting up the correct state in tests is much faster and easier.
A well written test suite is a safety net before the app is released. With a good CI set-up, regressions / bugs don't even reach the main branch because they are caught on PRs.
Tests are built in documentation , which needs to reflect the actual implementation of the app. If it isn't updated, then the tests will fail.

The Kotlin Multiplatform testing ecosystem

Testing Framework

Compared to the JVM, the Kotlin Multiplatform ecosystem is still relatively young. JUnit can only be used on JVM platforms, other platforms depend on the Kotlin standard library testing framework.

An alternative way for testing Kotlin Multiplatform code would be to use a different testing framework like Kotest. I don't have much experience using it, however I found it to be less reliable than writing tests using the standard testing framework (kotlin.test). For example: I was unable to run a singular test case (a function) through the IDE.

The standard testing library does lack some cool JUnit 5 features like parameterized tests or nesting, however it is possible to add them with some additional boilerplate: Kotlin Multiplatform Parameterized Tests and Grouping Using The Standard Kotlin Testing Framework

Assertions

Kotest also has a great assertion library in addition to the testing framework, which works flawlessly and can be used alongside the Kotlin standard library testing framework. Another library is Atrium, however it doesn't support Kotlin / Native.

Mocking

For a long time, Kotlin Multiplatform did not have a mocking framework, things seem to have changed because Mockk now supports Kotlin Multiplatform. However, there still might be issues on the Kotlin / Native side. An alternative to using a mocking framework is writing the mock or any other test double by hand, which will be explained in more detail in the next section.

Mocking is prevalent in tests that treat a single class as a unit, so let's touch on what can be defined as a unit before diving into the Kotlin Multiplatform testing strategy.

The mock keyword is overloaded and misused in a lot of places. I won't get into the reasons why, but if you're interested in learning more about it, take a look at this article Mocks Aren’t Stubs

Definition of a Unit

One unit, one class

On Android, a unit is usually considered one class where all of its dependencies are mocked , probably using a framework like Mockito or Mockk. These frameworks are really easy to use, however they can be, easily abused, which leads to brittle tests that are coupled to the implementation details of the system under test. The upside is that, these types of unit tests are the easiest to write and read (Given that the number of mock logic is not that high).

Another benefit is that all the internal dependencies API (class names, function signature etc.) are more refined because they are used inside the tests (e.g. for setting up or verification) through mocks. The downside of this is that the these mocks often make refactoring harder, since changing implementation details (like for example extracting a class) will most likely break the test (because the extracted class needs to be mocked), even though the behavior of the feature did not change.

These types of tests work in isolation, which only verify that one unit (in this case, a class) works correctly. In order to verify that a group of units behave correctly together, there is a need for additional integration tests.

One unit, multiple classes

An alternative way of thinking about a unit could be a cohesive group of classes for a given feature. These tests try to use real dependencies instead of mocks , however awkward, complex or boundary dependencies (e.g. networks, persistence etc.) or are still replaced with a test double (usually written by hand instead of mocked by a framework).

The most frequent test doubles are Fakes, which resemble the real implementation but in a simpler form to allow testing (e.g. replacing a real database with an in-memory one).

There are also Stubs which are set-up before the action (AAA) allowing the system under test to use predefined values (e.g. instead of returning system time, a predefined time value is returned).

Having a modularized project allows for creating a "core-test" module which contains all public Test Doubles. Thanks to this, they can be re-used across all other modules without having to duplicate implementations

My strategy for testing Kotlin Multiplatform

Because mocking the Kotlin Multiplatform is far from perfect, I went the path of writing test doubles by hand. The problem with this is that if we wanted to write every Kotlin Multiplatform unit test like on Android (unit == class). We would be forced to create interfaces for every class along with a test double for it. Which would add unnecessary complexity just for testing purposes.

This is why I decided for the most part to treat a unit as a feature / behavior (group of classes). This way, there are less test doubles involved, and the system is tested in a more "production" like setting.

Depending on the complexity, the tests might become integration tests rather than unit tests, but in the grand scheme of things it's not that important as long as the system is properly tested.

The system under test

Most of the time, the system under test would be the public domain class that the Kotlin Multiplatform module exposes or maybe some other complex class which delegates to other classes.

If we had a feature that allowed the user to input a keyword and get a search result based on that keyword, the Contract / API could have the following signature:

fun performSearch(input: String): List<String>

This could be a function of an interface, a use case or anything else, the point is that this class has some complex logic.

Tests for this feature could look like this:

class SuccesfulSearchTest

class NetworkErrorSearchTest

class InvalidKeywordSearchTest

Each test class exercise a different path that the system could take. In this case, one for a happy path, and two for unhappy paths. They could only focus the domain layer where the network API is faked, or they could also include the data layer where the real network layer is used but mocked somehow (e.g. Ktor MockEngine, SQLDelight In-Memory database, GraphQL Mock Interceptor).

The keyword validation might contain a lot of edges which may be hard to test through the InvalidKeywordSearchTest which could only focus on the domain aspects of what happens on invalid keywords. All the edge cases could be tested in a separate class:

class KeywordValidatorTest {

    fun `"ke" is invalid`()
    fun `"key" is valid`()
    fun `" ke " is invalid`()
    fun `" key " is valid`()
}

The example above is pretty simple, however, testing the KMP "public Contract / API" is a good start.

For complex logic that does not involve orchestrating other classes (e.g. conversions, calculations, validation), try to extract a separate class which can be tested in isolation. This way you have one granular test which covers all the complex edge cases while keeping the "integration" tests simpler by only caring about one or two cases for the complex logic (making sure it is called)

Test set-up with Object mothers

Because this strategy might involve creating multiple test classes, this means that the system under test and its dependencies need to be created multiple times. Repeating the same set-up boilerplate is tedious and hard to maintain because one will require change in multiple places.

To keep things DRY, object mothers can be created, removing boilerplate and making the test set-up simpler:

class SuccesfulSearchTest : KoinTest {

    private lateinit api: Api
    private lateinit sut: SearchEngine

    @BeforeTest
    fun setUp() {
        api = FakeApi()
        sut = createSearchEngine(api)
    }

    // ...
}

fun createSearchEngine(
    api: SearchEngine, 
    keywordValidator: KeywordValidator = KeywordValidator()
) =
    SearchEngine(api, keywordValidator)

The top level function, createSearchEngine, can be used in all the SearchTests for creating the system under test. An added bonus of such object mothers is that irrelevant implementation details like the KeywordValidator are hidden inside the test class.

Such object mothers can also be used for creating complex data structures like REST schemas or GraphQL queries

Test set-up with Koin

Another way to achieve the set-up would be to use dependency injection, luckily Koin allows for easy test integrations, which more or less comes down to this:

class SuccesfulSearchTest : KoinTest {

    private val sut: SearchEngine by inject()

    @BeforeTest
    fun setUp() {
        startKoin {
            modules(systemUnderTestModule, testDoubleModule)
        }
    }

    @AfterTest
    fun teardown() {
        stopKoin()
    }

    // ...
}

The test needs a Koin module which will provide all the needed dependencies. If the Kotlin Multiplatform code base is modularized, the systemUnderTestModule could be the public Koin module that is attached to the dependency graph (e.g. module, dependency graph). An example test suite which uses Koin for test set-up can be found in my ktor-mock-tests repository.

Contract tests for Test Doubles

When creating test doubles, there might be a point when they start becoming complex, just because the production code they are replacing is also complex. Writing tests for test helpers might seem unnecessary, however, how would you otherwise prove that a test double behaves like the production counterpart? Contract tests serve that exact purpose, they verify that multiple implementations behave in the same way (that their contract is preserved).

For example, the system under test uses a database to persist its data, using a real database for every test will make the tests run a lot longer. To help with this, a fake database could be written to make the tests faster. This would result in the real database being used only in one test class and the fake one in all other cases.

Let's say that real database has the following rules (contract):

adding a new item updates a "reactive stream"
new items cannot overwrite an existing item if their id is the same

The contract base test could look like this:

abstract class DatabaseContractTest {

   abstract var sut: Dao

   @Test
   fun `New items are correctly added`() {
        val item = Item(1, "name")

        sut.addItem(item)

        sut.items shouldContain item
   }

   @Test
   fun `Items with the same id are not overwritten`() {
        val existingItem = Item(1, "name")
        sut.addItem(existingItem)
        val newItem = Item(1, "new item")

        sut.addItem(newItem)

        assertSoftly {
            sut.items shouldNotContain newItem
            sut.items shouldContain existingItem
        }
   }
}

The base class contains the tests which will be run on the implementations (real and fake database):

class SqlDelightDatabaseContractTest : DatabaseContractTest() {
    override var sut: Dao = createDealDatabase()
}

class FakeDatabaseContractTest : DatabaseContractTest() {
    override var sut: Dao = createFakeDatabase()
}

This is just a trivial example to show a glimpse of what can be done with contract tests. If you'd like to learn more about this, feel free to check out these resources:
ContractTest, Outside-In TDD - Search Functionality 6 (The Contract Tests)

Big shout out to Jov Mit for creating so many Android related testing content which inspired this testing strategy (If you're interested in Test Driven Development, be sure to check out his insightful screencast series on YouTube).

Benefits of the Strategy

Development speed

The strategy I'm proposing would verify the KMM feature / module correctness at a larger scale instead of focusing on verifying individual classes. This more closely resembles how the code behaves in production, which gives us more confidence that the feature will work correctly in the application. This in turn means that there is less need to actually open up the application every time.

Building applications using Kotlin Multiplatform usually takes longer than their fully native counterparts. The Android app can be built relatively fast thanks to incremental compilation on the JVM, however for iOS the story is different. Kotlin / Native compilation in itself is pretty fast, the issue arises when creating the Objective-C binary where the gradle tasks linkDebugFrameworkIos and linkReleaseFrameworkIos are called. Luckily, tests avoid that because they only compile Kotlin / Native without creating the Objective-C binary.

Ignoring the build speed issues, let's say that the build didn't take longer. Building the whole application means building all of its parts. But when we work on a feature, we typically only want to focus and verify a small portion of the entire application. Tests allow just that, verifying only a portion of the app without needing to build everything. When we're finished working on a feature, we can plug the code into the application and verify that it correctly integrates with other parts of the application.

Test function / test case names

Because these tests focus more on the end result of the feature rather than on implementation details of a single class, the test function names reflect the behavior of the feature. A lot of time, this behavior also represents the business requirements of the system.

Refactoring

With this testing strategy, refactoring would be easier because the tests don't dive into the implementation details of the system under test (like mocks tend to do). They only focus on the end result, as long as the behavior remains the same*, then the tests don't care how it was achieved.

* And it should be the same, since that's what refactoring is all about.

Kotlin Multiplatform threading

The new memory model is the default now, so there are no limitations like in the old memory model. To read more about the old one, you can visit the previous version of this article which covers that.

Test double reusability

The last thing I want to touch on is test double reusability. To keep the code DRY, the test doubles could also be moved to a common testing module, which helps with its reusability. For example, the data layer test doubles (e.g. network or persistence) can be often reused for UI tests. An example of this can be found in my Ktor Mock Engine article, where the integration tests and UI tests use the same engine for returning predefined data (not strictly a test double, but you get the idea). The repository in the article is Android only, but it can easily be applied to Kotlin Multiplatform since Ktor has great support for it.

Downsides of the Strategy

Test speed*

The first thing I want to address is the test speed because no one wants to wait too long for the tests to complete. Tests which treat unit as a class are superfast, but only when they use normal test doubles. Mocking frameworks with all their magic take up a lot of time and make the tests much slower compared to a test double written by hand.

The test strategy I'm proposing does not use any mocking framework, only test doubles written by hand. However, the tests might use a lot more production code in a single test case, which does take more time. From my experience working with these types of tests on Kotlin Multiplatform, I didn't see anything worrying about the test speed (besides Kotlin / Native taking longer). Additionally, if the KMM code base is modularized then only the tests from a given module are executed, which is a much smaller portion of the code base.

* Test speed is a subjective topic, where every one has a different opinion on it. Martin Fowler has an interesting article which touches on this topic: bliki: UnitTest

Test readability

As I said before, these tests tend to be more on the integration side than the unit side (depending on how you define it). This means that more dependencies are involved, and more set-up is required.

To combat this, I recommend splitting the tests into multiple files, each focusing on a distinctive part of the behavior. Along with object mothers, the set-up boilerplate can be reduced and implementation details hidden.

To understand these tests, more internal knowledge about the system under test is required. This is a doubled edged sword because the tests are not as easy to understand, but after you understand them you'll most likely know how the system under test works along with its collaborators.

Hard to define what should be tested

Tests where unit is class are easy to write because they always focus on a single class. When a unit is a group of classes, it is hard to define what the group should be, how deep should the test go?

Unfortunately, there is no rule that works in every case. Every system is different, and has different business requirements. If you start noticing that the test class is becoming too big and too complex, this might be a sign that the test goes too deep.

There might be a feature which just keeps growing, and the test becomes really hard to understand. In such cases, it might be good to refactor the SUT and extract some cohesive group of logic to a separate class which can be tested more granularly. Then the original test uses a Test Double for the extracted class, making it easier to understand. This does require refactoring test code, but makes the Test Suite easier to understand

CI / CD

Tests are useless when they are not executed, and it's not a good idea to rely on human memory for that. The best way would be to integrate tests into your Continuous Integration, so they are executed more frequently.

For example, tests could be run:

On every PR, making sure nothing broken is merged to the main branch.
Before starting the Release process.
Once a day
All of the above combined.

For Kotlin Multiplatform, it is important to execute test for all targets. Sometimes everything works on the JVM, but Kotlin Native fails (e.g. Regex, NSDate). So the best way of making sure every platform behaves in the same way is to run tests for all targets

Summary

In my opinion, Kotlin Multiplatform should be the most heavily tested part of the whole application. It is used by multiple platforms, so it should be as bulletproof as possible.

Writing tests during development can cut down on compilation time and give confidence that any future regressions (even 5 minutes later) will be caught by the test suite.

I hope this article was informative for you, let me know what you think in the comments below!

Kotlin Multiplatform Parameterized Tests and Grouping Using The Standard Kotlin Testing Framework

Aleksander Jaworski — Mon, 11 Jul 2022 08:00:52 +0000

This article was originally posted on my blog, for better viewing experience try it out there.

I covered the Kotlin Multiplatform Testing ecosystem before. But I'll try to summarize it briefly here.

Coming from Android, we're a little spoiled when it comes to testing frameworks. The default is JUnit 4, but we also have JUnit 5 which are very mature frameworks. On Kotlin Multiplatform, we can't leverage JUnit features like parameterized tests and nested test classes. By default, Kotlin Multiplatorm uses the kotlin.test framework, which unfortunately is not as feature rich as JUnit.

There are alternatives frameworks like the Kotest, which does offer parameterized tests, but has some limitations with Kotlin Multiplatform like the Kotest plugin not being able to run tests from commonTest, so they always need to be executed from the command line.

However, in this article I'd like to focus on the standard testing framework, because it comes out of the box with Kotlin and has good IDE support, and also has a similar API as JUnit.

Parameterized tests

I tried to keep the test examples simple and self-explanatory, the last one is more complicated, but I hope it's still easy to follow.

Parsing a string to an Enum

We have an Enum class representing Card (Suite), and an extension function that parses a string and returns the corresponding card or null.

enum class Card {
    HEARTS,
    DIAMONDS,
    SPADES,
    CLUBS
}

fun String.parseToCard(): Card? =
    when (this) {
        "Hearts" -> Card.HEARTS
        "Diamonds" -> Card.DIAMONDS
        "Spades" -> Card.SPADES
        "Clubs" -> Card.CLUBS
        else -> null
    }

class CardParsingTest {

    @Test
    fun `'Hearts' is a card`() = validTestCase("Hearts", Card.HEARTS)

    @Test
    fun `'Diamonds' is a card`() = validTestCase("Diamonds", Card.DIAMONDS)

    @Test
    fun `'Spades' is a card`() = validTestCase("Spades", Card.SPADES)

    @Test
    fun `'Clubs' is a card`() = validTestCase("Clubs", Card.CLUBS)

    @Test
    fun `'Heart' is not a card`() = invalidTestCase("Heart")

    @Test
    fun `'Diamons' is not a card`() = invalidTestCase("Diamons")

    @Test
    fun `'Spade' is not a card`() = invalidTestCase("Spade")

    @Test
    fun `'Club' is not a card`() = invalidTestCase("Club")

    private fun validTestCase(stringCard: String, expectedCard: Card) {
        assertEquals(actual = stringCard.parseToCard(), expected = expectedCard)
    }

    private fun invalidTestCase(stringCard: String) {
        assertNull(actual = stringCard.parseToCard())
    }
}

There are two helper functions validTestCase and invalidTestCase , depending on the expected outcome the respective "TestCase" is called. Having one function could also work in this case, but I personally think that having this distinction makes the test class more readable.

Formatting names

We have a Person class which we want to format depending on the available data.

data class Person(
    val firstName: String,
    val lastName: String,
    val secondName: String? = null,
    val secondLastName: String? = null
)

fun Person.formatToString(): String {
    val secondName = if (secondName == null) "" else " $secondName"
    val secondLastName = if (secondLastName == null) "" else "-$secondLastName"
   return "$firstName$secondName $lastName$secondLastName"
}

class PersonFormattingTest {

    @Test
    fun `Full name is correctly formatted`() = testCase(
        Person(firstName = "John", lastName = "Doe"),
        "John Doe"
    )

    @Test
    fun `Full name with second name is correctly formatted`() = testCase(
        Person(firstName = "John", secondName = "Bob", lastName = "Doe"),
        "John Bob Doe"
    )

    @Test
    fun `Full name with second last name is correctly formatted`() = testCase(
        Person(firstName = "John", lastName = "Doe", secondLastName = "Dilly"),
        "John Doe-Dilly"
    )

    @Test
    fun `Full name with second name and last name is correctly formatted`() =
        testCase(
            Person(
                firstName = "John",
                secondName = "Bob",
                lastName = "Doe",
                secondLastName = "Dilly"
            ),
            "John Bob Doe-Dilly"
        )

    private fun testCase(person: Person, expectedString: String) {
        assertEquals(actual = person.formatToString(), expected = expectedString)
    }
}

Searching through keywords

We have a UseCase which filters available keywords for a given query. The keywords come from a repository, which is replaced with a test double during testing.

interface KeywordRepository {
    suspend fun getKeywords(): List<String>
}

class FakeDelayingKeywordRepository : KeywordRepository {
    var keywords: List<String> = emptyList()

    override suspend fun getKeywords(): List<String> {
        delay(500) // Simulate some I/O operation
        return keywords
    }
}

class SearchForKeyword(
    private val keywordRepository: KeywordRepository,
    private val dispatcher: CoroutineDispatcher,
) {

    sealed class SearchResult {
        object Empty : SearchResult()
        object InvalidQuery : SearchResult()
        object Error : SearchResult()
        data class Success(val keywords: List<String>) : SearchResult()
    }

    suspend fun execute(query: String): SearchResult = withContext(dispatcher) {
        if (query.count() < 3) return@withContext InvalidQuery

        val keywords = keywordRepository.getKeywords()

        if (keywords.isEmpty()) return@withContext Error

        val matches = keywords.filter { keyword -> keyword.contains(query) }
        if (matches.isEmpty()) {
            Empty
        } else {
            Success(matches)
        }
    }
}

class SearchTest {

    private lateinit var fakeKeywordRepository: FakeDelayingKeywordRepository
    private lateinit var dispatcher: TestDispatcher
    private lateinit var systemUnderTest: SearchForKeyword

    @BeforeTest
    fun setUp() {
        fakeKeywordRepository = FakeDelayingKeywordRepository()
        dispatcher = UnconfinedTestDispatcher()
        systemUnderTest = SearchForKeyword(fakeKeywordRepository, dispatcher)
    }

    @Test
    fun `When query is empty then InvalidQuery is returned`() =
        testCase(query = "", expectedResult = InvalidQuery)

    @Test
    fun `When query has 2 characters then InvalidQuery is returned`() =
        testCase(query = "fi", expectedResult = InvalidQuery)

    @Test
    fun `When query valid the expected Success result is returned`() =
        testCase(
            query = "fir",
            keywords = listOf("first", "second", "Fire", "sound"),
            expectedResult = Success(listOf("first")),
        )

    @Test
    fun `When query valid but does not match any keywords then Empty is returned`() =
        testCase(
            query = "asd",
            keywords = listOf("second", "Fire", "sound"),
            expectedResult = Empty,
        )

    @Test
    fun `When query valid but keyword repository is empty then Error is returned`() =
        testCase(
            query = "asd",
            keywords = emptyList(),
            expectedResult = Error,
        )

    private fun testCase(
        query: String,
        expectedResult: SearchForKeyword.SearchResult,
        keywords: List<String> = emptyList()
    ) =
        runTest(dispatcher) {
            fakeKeywordRepository.keywords = keywords

            val result = systemUnderTest.execute(query)

            assertEquals(actual = result, expected = expectedResult)
        }
}

This test is more complicated compared to the last ones, because it requires some Arrangement, before the test Action and Assertions. It also resembles more of a "real" thing that happens during app development.

The added benefit of having a "TestCase" function is that the systemUnderTest could also be created inside of it, without repeating the same boilerplate in every test. This can be helpful if a Test Double or System Under Test take in different constructor parameters depending on the test.

Grouping tests in Kotlin Multiplatform

Another topic I talked about in the introduction was JUnit 5 nested classes used for grouping test cases. This is not available in the standard Kotlin testing library, but there is another way of grouping test cases.

Instead of nested classes, they could be normal classes in different files. The problem with this is that the System Under Test creation has to be repeated in every test class.

To illustrate this problem, I refactored the Search UseCase to be more complicated by extracting out some classes:

class QueryValidator {

    fun isValid(query: String): Boolean = query.count() < 3
}

class KeywordFilter {

    fun execute(query: String, keywords: List<String>): List<String> {
        return keywords.filter { keyword -> keyword.contains(query) }
    }
}

The constructor of the UseCase is now the following:

class SearchForKeyword(
    private val keywordRepository: KeywordRepository,
    private val queryValidator: QueryValidator,
    private val keywordFilter: KeywordFilter,
    private val dispatcher: CoroutineDispatcher,
)

System Under Test creation

The instantiation of the system under test is now more involved:

private lateinit var keywordRepository: FakeDelayingKeywordRepository
private lateinit var dispatcher: TestDispatcher
private lateinit var systemUnderTest: SearchForKeyword

@BeforeTest
fun setUp() {
    keywordRepository = FakeDelayingKeywordRepository()
    dispatcher = UnconfinedTestDispatcher()
    systemUnderTest = SearchForKeyword(
        keywordRepository,
        QueryValidator(),
        KeywordFilter(),
        dispatcher
    )
}

Repeating this in every test class will cause the test class to be more complex and harder to maintain every time a constructor parameters changes. To help with that, a helper Object Mother function can be created:

fun createSearchForKeyword(
    dispatcher: CoroutineDispatcher,
    keywordRepository: KeywordRepository = FakeDelayingKeywordRepository(),
): SearchForKeyword {
    return SearchForKeyword(
        keywordRepository,
        QueryValidator(),
        KeywordFilter(),
        dispatcher
    )
}

The QueryValidator and KeywordFilter are implementation details from the perspective of the test, so their creation is hidden here. However, the dispatcher and repository are used inside the test class, so they are created in the test class and passed in here.

Different Test classes

The test cases for the Search UseCase remain the same because the behavior did not change, however the test class will be split into two: SearchInvalidKeywordTest and SearchValidKeywordTest

class SearchInvalidKeywordTest {

    private lateinit var dispatcher: TestDispatcher
    private lateinit var systemUnderTest: SearchForKeyword

    @BeforeTest
    fun setUp() {
        dispatcher = UnconfinedTestDispatcher()
        systemUnderTest = createSearchForKeyword(dispatcher)
    }

    @Test
    fun `When query is empty then InvalidQuery is returned`() =
        testCase(query = "")

    @Test
    fun `When query has 2 characters then InvalidQuery is returned`() =
        testCase(query = "fi")

    private fun testCase(query: String) =
        runTest(dispatcher) {
            val result = systemUnderTest.execute(query)

            assertEquals(actual = result, expected = InvalidQuery)
        }
}

The keyword repository is removed from here, because it is not used by the tests. The default parameter in createSearchForKeyword function creates the repository.

class SearchValidKeywordTest {

    private lateinit var fakeKeywordRepository: FakeDelayingKeywordRepository
    private lateinit var dispatcher: TestDispatcher
    private lateinit var systemUnderTest: SearchForKeyword

    @BeforeTest
    fun setUp() {
        fakeKeywordRepository = FakeDelayingKeywordRepository()
        dispatcher = UnconfinedTestDispatcher()
        systemUnderTest = createSearchForKeyword(dispatcher, fakeKeywordRepository)
    }

    @Test
    fun `When query valid the expected Success result is returned`() =
        testCase(
            query = "fir",
            expectedResult = Success(listOf("first")),
            keywords = listOf("first", "second", "Fire", "sound")
        )

    @Test
    fun `When query valid but does not match any keywords then Empty is returned`() =
        testCase(
            query = "asd",
            expectedResult = Empty,
            keywords = listOf("second", "Fire", "sound")
        )

    @Test
    fun `When query valid but keyword repository is empty then Error is returned`() =
        testCase(
            query = "asd",
            expectedResult = Error,
            keywords = emptyList()
        )

    private fun testCase(
        query: String,
        expectedResult: SearchForKeyword.SearchResult,
        keywords: List<String>
    ) =
        runTest(dispatcher) {
            fakeKeywordRepository.keywords = keywords

            val result = systemUnderTest.execute(query)

            assertEquals(actual = result, expected = expectedResult)
        }
}

In this test class, the keyword repository is a property because it is used to Arrange the correct return value before calling the System Under Test.

This method of grouping tests, is more verbose and complicated which for simple cases might be an overkill, but when the test cases keep growing (like when there are a lot of edge cases), this grouping is definitely better than having one 600+ line test class.

Summary

Although the standard Kotlin testing framework lacks some JUnit features, we are able to implement them by hand. They are more verbose, but we have to work with what we got.

If you have your own strategies for writing Kotlin Multiplatform tests, feel free to share them in the comments 😁

Modularizing a Kotlin Multiplatform Mobile Project

Aleksander Jaworski — Tue, 05 Oct 2021 15:45:08 +0000

This article was originally posted on my blog, for better viewing experience try it out there.

Introduction

In this article I'll tackle the topic of Modularization in a Kotlin Multiplaform project. I wasn't able to find any up-to-date material on this subject, so I thought I would share the approach that we're using at FootballCo.

The project

For this article I've created a simple modularized Kotlin Multiplatform Mobile project which can be found on GitHub (it uses the KaMPKit starter). It consists of two screens, one shows a list of todos and another one which shows the number of todos. On both screens the todos can be added with a button.

The apps

The list screen

The count screen

Please excuse the lackluster UI, as it was not the focus of this article.

The modules

The Android and iOS platform use the shared module as an umbrella framework/library. The blue modules are the ones which will be exported through the shared module and the white ones are implementation details.

Modules like core-common or todos-list-api should be treated as part of the shared module API, because these modules are not used directly. The reason for that will be explained later.

There are two main groups of modules in the shared module:

core modules - contain common classes, functions etc. which might are used in a lot of different modules
feature modules - correspond to a feature of the app. In this example they are prefixed with todos, one for the list and one for the count

Each feature module can be broken down even further into two types:

api module (blue - exported) - contains the interfaces and data structures of the given features. It contains the API that the clients (Android and iOS) use
dependency module (white - internal) - contains the implementations for the corresponding api module. This module is basically the implementation details of the api module

The core modules

In this example there are three core modules:

core-common - all the common entities which are used throughout the app. In this example it contains an interface for providing the current timestamp (with an internal implementation)
core-ios - this module is only used by the iOS platform. It contains functions that help the Swift-Kotlin interop like the iOS wrappers (on which I've touched on in my previous article) or Koin helpers.
core-test - contains the BaseTest class, and might contain other common text fixtures like API / Database fakes etc. More information about Testing can be found in my Testing on Kotlin Multiplatform article

The feature modules

As mentioned in the introduction, the app has two main features: showing a list of todos; and their count.

The features are contained in four modules (two api and two dependency modules):

todos-list: retrieves the list of todos and adds random todo
todos-count: retrieves the number of todos

Implementing gradle project modules

For the most part gradle project dependencies are used in the same way as in normal JVM projects with the difference that the dependencies are attached (implemented) in commonMain source set.

sourceSets["commonMain"].dependencies {
    implementation(project(":kmm:todos:todos-count-api"))
    implementation(project(":kmm:todos:todos-list-api"))
    implementation(project(":kmm:core:core-common"))
    implementation(Deps.Coroutines.common)
    implementation(Deps.kotlinxDateTime)
    implementation(Deps.koinCore)
    implementation(Deps.kermit)
}

The build.gradle file for todos-count-dependency

Project dependencies can also be added to other source sets besides commonMain. For example the core-ios module should only be used on the iOS platform. Which means that it has to be added to the iosMain source set.

sourceSets["iosMain"].dependencies {
    implementation(project(":kmm:core:core-ios"))
    implementation(Deps.koinCore)
    implementation(Deps.Coroutines.common) {
        version {
            strictly(Versions.coroutines)
        }
    }
}

The build.gradle file for todos-count-api

The iOS side of Kotlin modularization

Why do the API modules have a dependency on core-ios?

This is a small detour to explain the reasoning behind the aforementioned statement. Here's the module graph for reference:

The graph shows that the api modules use the core-ios module indicated by the yellow arrows. To make the life of the iOS developers easier, suspending functions and functions with a flow return type are wrapped to make their usage from swift easier.

There are multiple places to create these wrappers, however the one used in the example project is the following: the *-api modules contain and expose the wrappers. Doing it this way makes the interface implementation irrelevant, because the wrapper doesn't have to change when the interface implementation changes.

For example: the todos-counts-api module contains the interface for retrieving the todos counts inside the commonMain source set:

package co.touchlab.kmm.todos.count.api.domain

interface GetTodoCount {

    operator fun invoke(): Flow<TodoCount>
}

The above use case uses a Flow which is hard to use in swift. Because of this the following wrapper exists in iosMain (details about the wrappers can be found here):

package co.touchlab.kmm.todos.count.api.domain

class GetTodoCountIos(
    private val getTodoCount: GetTodoCount
){

    fun invoke(): FlowWrapper<TodoCount> =
        FlowWrapper(
            scope = CoroutineScope(SupervisorJob() + Dispatchers.Main),
            flow = getTodoCount()
        )
}

The FlowWrapper offers functions which make collecting the flow much easier on iOS.

How are dependencies exposed to the iOS platform

Kotlin Multiplatform creates an Obj-C Framework which can be then used on the iOS platform. In this project, the framework is generated based on the shared module.

The shared module is the entry point for both the iOS and Android platform. It contains dependencies to all other modules, and dependency injection set up (explained in the following section).

To export the modules and regular Kotlin libraries, the build.gradle file has to attach the dependencies as api:

sourceSets["commonMain"].dependencies {
    api(project(":kmm:core:core-common"))
    api(project(":kmm:todos:todos-list-api"))
    implementation(project(":kmm:todos:todos-list-dependency"))
    api(project(":kmm:todos:todos-count-api"))
    implementation(project(":kmm:todos:todos-count-dependency"))
    ...
}

sourceSets["iosMain"].dependencies {
    api(project(":kmm:core:core-ios"))
    ...
}

The shared module dependencies

For iOS to see the exported modules and libraries, the framework configuration has to be updated:

cocoapods {
    framework {
        isStatic = false
        export(project(":kmm:core:core-common"))
        export(project(":kmm:core:core-ios"))
        export(project(":kmm:todos:todos-list-api"))
        export(project(":kmm:todos:todos-count-api"))
        export(Deps.Coroutines.common)
        export(Deps.koinCore)
    }
}

The shared module framework

Exposing multiple KMM frameworks

This is one of the biggest limitation of Kotlin Multiplatform currently, the iOS platform can't have granular access to Kotlin Modules. KMM generates a single umbrella framework which contains all the exported Kotlin classes (In this subsection when referring to classes I mean classes, objects, functions etc.).

It is possible to generate multiple KMM frameworks, but this will come with a lot of overhead in the form of a bigger binary because each framework will have duplicate Kotlin standard library classes.

If that wasn't bad enough, all the shared dependencies in the Kotlin modules will also be duplicated. In the example from this article, exporting the list and count modules as separate frameworks would duplicate all classes of the core-common module.

The biggest problem with this is that on iOS, the core-common classes in each framework are treated as different classes. This means that, for example, a shared data structure from core-common can't be used interchangeably between the list and count framework.

Creating a Swift class which uses MyString as a parameter would only be compatible only within the same framework. Passing in a MyString argument from a different framework would result in an incompatible type compilation error even though in Kotlin it is the same class.

Long story short, it might be possible to export multiple KMM frameworks, granted that they don't have/use the same modules. The following resources go more in-depth about the topic:

https://touchlab.co/multiple-kotlin-frameworks-in-application/?ref=akjaw.com

https://www.youtube.com/watch?v=hrRqX7NYg3Q&t=1763s&ref=akjaw.com

Testing

Because Kotlin Multiplatform lacks the support for mock framework, Test Doubles will need to be created by implementing interfaces. These Fake/Mock implementations will usually reside in the core-test module.

This approach increases maintainability and re-usability across the whole project. The Fake implementation details are contained in one class instead of spread out across multiple test files like it happens with mock frameworks.

Testing the shared module is even more important than tests for platform specific code. Because the code is used by multiple clients (platforms) it needs to work correctly, and what better way to do it than tests. If you'd like to learn more, checkout my Testing on Kotlin Multiplatform article.

Koin dependency injection

The Koin dependency graph is initialized inside the entry gradle module of Kotlin Multiplatform (the shared module). The initialization of the graph is done inside this function:

fun initKoin(appModule: Module): KoinApplication {
    val koinApplication = startKoin {
        modules(
            appModule,
            commonModule,
            todoListDependencyModule,
            todoCountDependencyModule
        )
    }

    return koinApplication
}

The appModule is the Koin module from the platforms (iOS and Android), for multiple modules, a vararg can be used.

For iOS there is an additional function to make providing dependencies easier:

fun initKoinIos(
    appInfo: AppInfo,
): KoinApplication = initKoin(
    module {
        single { appInfo }
    }
)

From Swift the dependencies are passed in as parameters to this function, and then a Koin module is created from them and passed into the main initialization function.

Attaching gradle module classes to the dependency graph

The *-dependency gradle modules can just expose one Koin module which is then attached in the initKoin function.

val todoCountDependencyModule = module {
    factory<GetTodoCount> { GetTodoCountFromList(get(), get()) }
}

There is however one problem with this, the iOS platform uses a wrapper for the GetTodoCount class. This means that the wrapper also has to be introduced into the dependency graph.

As it was explained earlier, the api modules contain the iOS wrapper meaning that the *-api modules should add the wrappers to the dependency graph.

Either they are added to the initKoin function:

modules(
    appModule,
    commonModule,
    todoListDependencyModule,
    todoListApiModule,
    todoCountDependencyModule
    todoCountApiModule
)

Or they can be added to their corresponding dependency module:

// commonMain
expect fun Module.countApiPlatformModule()

// androidMain
actual fun Module.countApiPlatformModule() { /* Empty */ }

// iosMain
actual fun Module.countApiPlatformModule() {
    factory { GetTodoCountIos(get()) }
}

The todos-count-api Koin module

val todoCountDependencyModule = module {
    factory<GetTodoCount> { GetTodoCountFromList(get(), get()) }
    countApiPlatformModule()
}

The todos-count-dependency Koin module

There are definitely more ways to do this, but this example project uses the latter approach.

Injecting Fake / Mock implementations

Integration and UI tests should be as predictable as possible, that's why instead of making a real API call, a Fake implementation can be used.

I've written several articles about his topics, all of these approaches can be used on Kotlin Muliplatform (Ktor, Apollo GraphQL, SQLDelight).

The compilation speed

One of the biggest benefits of modularizing a project is faster compilation speed, because unchanged modules can be cached. On paper everything looks good, the Android app builds much faster when changing only some modules.

The issue is however with building the Kotlin/Native part of KMM, caused by the linkDebugFrameworkIos and linkReleaseFrameworkIos gradle tasks. These two tasks take up a lot of time, no matter if the change is in one or multiple module.

Here's an example, adding a todo in the app uses a predefined list:

private val tasks = listOf(
    "Cook a cuisine from a different country",
    ...
    "Paint a plant pot",
)

Changing the elements in the list results in the following compilation speeds:

Running the Android app (:app:assembleDebug)

Building the shared module for both platforms

There is a significant difference when comparing the two times, the Android build is 20+ times faster.

However, I've noticed that the shared module doesn't have to be built every time. When making small changes, building the Android app or running iOS tests in the changed module (maybe tests in a different module will work too) results in the changes being present in the iOS app.

I don't have this down to a science, but this definitely speeds up the feedback loop when building the iOS App. However, I still think that automated tests for the KMM logic will result in the best and fastest feedback loop, compared to running the Android / iOS app on every change.

Update: the compileKotlinIosArm64 and compileKotlinIosX64 speed up the compilation time a lot more.

Summary

I hope this article was helpful in explaining some Kotlin Multiplatform Mobile caveats and showing an example modularization strategy.

If you have used a different modularization strategy, or have some additional insights about the topic, please feel free to leave a comment about it.

Implementing a Stopwatch with Kotlin Coroutines and Flow Part 1 - a Single Stopwatch

Aleksander Jaworski — Wed, 16 Jun 2021 13:49:01 +0000

Currently, I'm working on a Jetpack Compose Android app which amongst other things allows the user to start multiple stopwatches.

This is the first part where I show a simplified version of the implementation which will only handle one stopwatch. The second part will include the full implementation for multiple stopwatches along with testing.

State

To represent the stopwatch state I'm using a sealed class with two sub-types:

sealed class StopwatchState {

    data class Paused(
        val elapsedTime: Long
    ) : StopwatchState()

    data class Running(
        val startTime: Long,
        val elapsedTime: Long
    ) : StopwatchState()
}

The Paused state contains the elapsed time used in order to preserve the time between stopwatch state changes.

The Running state contains information about when the stopwatch was started and what the current elapsed time is. At the beginning the elapsed time will be 0, but every time the stopwatch is paused and started this value changes.

The Stopped state is not required because if the stopwatch is stopped then the state cannot be further changed. The final time can be calculated from either the Paused or Running state.

The current timestamp of the system is provided with the TimestampProvider interface:

interface TimestampProvider {

    fun getMilliseconds(): Long
}

State changes between Running and Paused are calculated in this class:

class StopwatchStateCalculator(
    private val timestampProvider: TimestampProvider,
    private val elapsedTimeCalculator: ElapsedTimeCalculator,
) {

    fun calculateRunningState(oldState: StopwatchState): StopwatchState.Running =
        when (oldState) {
            is StopwatchState.Running -> oldState
            is StopwatchState.Paused -> {
                StopwatchState.Running(
                    startTime = timestampProvider.getMilliseconds(),
                    elapsedTime = oldState.elapsedTime
                )
            }
        }

    fun calculatePausedState(oldState: StopwatchState): StopwatchState.Paused =
        when (oldState) {
            is StopwatchState.Running -> {
                val elapsedTime = elapsedTimeCalculator.calculate(oldState)
                StopwatchState.Paused(elapsedTime = elapsedTime)
            }
            is StopwatchState.Paused -> oldState
        }
}

If the state remains unchanged, the parameter is just returned.

Paused -> Running:Saves the current timestamp as the stopwatch start time. The elapsed time is reused from the previous state because in the paused state the stopwatch should not be "running".

Running -> Paused:Calculates the elapsed time based on the stopwatch start time and the current elapsed time. This calculation is explained in the next section

Calculating the elapsed time

class ElapsedTimeCalculator(
    private val timestampProvider: TimestampProvider,
) {

    fun calculate(state: StopwatchState.Running): Long {
        val currentTimestamp = timestampProvider.getMilliseconds()
        val timePassedSinceStart = if (currentTimestamp > state.startTime) {
            currentTimestamp - state.startTime
        } else {
            0
        }
        return timePassedSinceStart + state.elapsedTime
    }
}

The condition check (currentTimestamp > state.startTime) should always be true, but you never know. Calculating the elapsed time consists of subtracting the stopwatch start time from the current timestamp and then adding the result to the existing elapsed time. This elapsed time is responsible for preserving the time between the stopwatch state changes.

Here's an accompanying test showing how the diagram looks in code, the TimestampProvider is a mock however the ElapsedTimeCalculator is the real implementation:

@Test
fun `Article example test`() {
    val timestampProvider: TimestampProvider = mockk()
    val elapsedTimeCalculator = ElapsedTimeCalculator(timestampProvider)
    val stopwatchStateCalculator = StopwatchStateCalculator(
        timestampProvider = timestampProvider,
        elapsedTimeCalculator = elapsedTimeCalculator
    )

    every { timestampProvider.getMilliseconds() } returns 0
    val initialState = StopwatchState.Paused(0L)
    val firstStart = stopwatchStateCalculator.calculateRunningState(initialState)
    expectThat(firstStart.startTime).isEqualTo(0L)
    expectThat(firstStart.elapsedTime).isEqualTo(0L)

    every { timestampProvider.getMilliseconds() } returns 100
    val firstPause = stopwatchStateCalculator.calculatePausedState(firstStart)
    expectThat(firstPause.elapsedTime).isEqualTo(100L)

    every { timestampProvider.getMilliseconds() } returns 1000
    val secondStart = stopwatchStateCalculator.calculateRunningState(firstPause)
    expectThat(secondStart.startTime).isEqualTo(1000L)
    expectThat(secondStart.elapsedTime).isEqualTo(100L)

    every { timestampProvider.getMilliseconds() } returns 1500
    val secondPause = stopwatchStateCalculator.calculatePausedState(secondStart)
    expectThat(secondPause.elapsedTime).isEqualTo(600L)
}

Formatting the stopwatch time

The formatter takes in a timestamp and produces a human-readable time for the UI:

internal class TimestampMillisecondsFormatter() {

    companion object {
        const val DEFAULT_TIME = "00:00:000"
    }

    fun format(timestamp: Long): String {
        val millisecondsFormatted = (timestamp % 1000).pad(3)
        val seconds = timestamp / 1000
        val secondsFormatted = (seconds % 60).pad(2)
        val minutes = seconds / 60
        val minutesFormatted = (minutes % 60).pad(2)
        val hours = minutes / 60
        return if (hours > 0) {
            val hoursFormatted = (minutes / 60).pad(2)
            "$hoursFormatted:$minutesFormatted:$secondsFormatted"
        } else {
            "$minutesFormatted:$secondsFormatted:$millisecondsFormatted"
        }
    }

    private fun Long.pad(desiredLength: Int) = this.toString().padStart(desiredLength, '0')
}

The initial hour in the stopwatch is more dynamic, because the milliseconds are shown but after one hour the milliseconds are omitted in favor of showing the hour. Additionally, the numbers are padded with one or two leading zeros.

Managing the stopwatch state

Because the states are self-contained and do not contain any behavior, an additional class is needed for managing the state changes:

internal class StopwatchStateHolder(
    private val stopwatchStateCalculator: StopwatchStateCalculator,
    private val elapsedTimeCalculator: ElapsedTimeCalculator,
    private val timestampMillisecondsFormatter: TimestampMillisecondsFormatter,
) {

    var currentState: StopwatchState = StopwatchState.Paused(0)
        private set

    fun start() {
        currentState = stopwatchStateCalculator.calculateRunningState(currentState)
    }

    fun pause() {
        currentState = stopwatchStateCalculator.calculatePausedState(currentState)
    }

    fun stop() {
        currentState = StopwatchState.Paused(0)
    }

    fun getStringTimeRepresentation(): String {
        val elapsedTime = when (val currentState = currentState) {
            is StopwatchState.Paused -> currentState.elapsedTime
            is StopwatchState.Running -> elapsedTimeCalculator.calculate(currentState)
        }
        return timestampMillisecondsFormatter.format(elapsedTime)
    }
}

This class provides an API for managing the stopwatch state. For convenience, this class also exposes a method for retrieving the formatted elapsed time of the stopwatch.

Using Kotlin Coroutines with Flow

The StopwatchStateHolder provides all the required functions for interacting with the stopwatch, however the stopwatch updates should not be running on the main thread. Doing so would result in an unusable UI where the only thing happening would be the stopwatch changes.

An additional abstraction needs to be created which offloads the stopwatch updates to a background thread:

internal class StopwatchListOrchestrator(
    private val stopwatchStateHolder: StopwatchStateHolder,
    private val scope: CoroutineScope,
) {

    private var job: Job? = null
    private val mutableTicker = MutableStateFlow("")
    val ticker: StateFlow<String> = mutableTicker

    fun start() {
        if (job == null) startJob()
        stopwatchStateHolder.start()
    }

    private fun startJob() {
        scope.launch {
            while (isActive) {
                mutableTicker.value = stopwatchStateHolder.getStringTimeRepresentation()
                delay(20)
            }
        }
    }

    fun pause() {
        stopwatchStateHolder.pause()
        stopJob()
    }

    fun stop() {
        stopwatchStateHolder.stop()
        stopJob()
        clearValue()
    }

    private fun stopJob() {
        scope.coroutineContext.cancelChildren()
        job = null
    }

    private fun clearValue() {
        mutableTicker.value = ""
    }
}

Keep in mind that this StopwatchListOrchestrator implementation was simplified for this article. The real implementation is able to handle multiple stopwatches at the same time. The reasoning for injecting a CoroutineScope is related to testing, but it will be explained more in-depth in the next part.

The start function creates a coroutine job which will be responsible for updating the stopwatch time. It consists of a while loop with a condition that checks whether the coroutine job is still active. Inside the loop the stopwatch time is updated in a 20 milliseconds interval. The time update happens through a StateFlow which ends up being collected in the UI.

The pause and stop functions stop the coroutine job because the stopwatch time will not be updated anymore. Additionally, the stop function resets the stopwatch and sets the default value for the stopwatch time (an empty strings prevents the stopwatch from being shown in the UI).

Please note that the coroutine job is stopped using cancelChildren() instead of cancel(). Canceling the children preserves the scope and makes it possible to launch other coroutines. Using the cancel method would prevent the stopwatch from working after pausing or stopping it. The reason for this is that cancel() cancels the whole coroutine scope, preventing any new coutine from being launched in that scope.

How it looks in the App

Summary

The code shown here and the rest of the application is available on my GitHub.

Kotlin coroutines provide an easy way of starting and stopping background operations, provided all the coroutine gotchas are taken care of (like using cancelChildren instead of cancel).

Flows provide a nice and simple API for creating and consuming asynchronous flows which play nicely with the rise of declarative UIs.

Combining these concepts shows how easy it is to implement a simple stopwatch (A timer could also be implemented in a similar way). No need for working with bare threads or creating RxJava streams with an interval.

The next article will build upon what was described here and add support for multiple simultaneous stopwatches.

Using Dagger 2 Multibindings to Avoid Coupling in a Multi Flavor Android Project

Aleksander Jaworski — Mon, 19 Apr 2021 15:34:27 +0000

This article was originally posted on my website.

Introduction

Adding flavor dependent features on a shared screen can be troublesome. The problem gets even worse when you don't want to couple app flavors to features they don't use. In this article I'll show you how we do in FootballCo using Dagger 2 Multibinding, AdapterDelegates and some abstractions.

This example will focus on injecting feature specific RecyclerView items and a concept of "customOrDefault" that we use in our codebase. Multibindings however have a lot more uses than shown here. If you know of other use cases please feel free to share them in the comments below.

The apps

There will be two app flavors: a basic and a premium one.

The basic flavor shows 3 football matches

The premium flavor has additional 3 basketball matches

I tried to keep the app simple while still tackling the Android flavor coupling problem.

Gradle modules

A diagram of the project gradle modules and their dependencies

The app module

Contains the Activity, RecyclerView Adapter and most importantly it contains the entry point for the dagger modules.

Additionally, the premium package contains an implementation which is used to override the default app implementation using the customOrDefault concept (which will be explained later).

The gradle dependencies for the app module are as follows:

implementation project(":framework")
implementation project(":dependency:football")

premiumImplementation project(":dependency:bastketball")

The Football and Basketball modules

Contain:

their corresponding match data structure
an AdapterDelegate which are used for extending the capabilities of the RecyclerView Adapter (shown later)
a MatchProvider which just returns a list of matches either Football or Basketball depending on the module.

To keep the example simple the modules implementations are mirrored with slight changes. But multibindings can be used in much more complicated situations where the flavor features are much different.

The Framework module

This module includes classes which are not implementation details but rather the things that are used by multiple modules, for example:

Interfaces and other abstractions
Data structures
Utilities

Flavor based RecyclerView extension without coupling modules

In the first part of this section I will be showing how the AdapterDelegates library works. If that does not interest you please read the summary below and navigate to the second part

Summary:
AdapterDelegates are mini RecyclerView Adapters which can be added to the Main Adapter in order to extend the supported types.

In the first solution the Main Adapter is extended by injecting a concrete class. This means that changing the supported types of the Main Adapter requires changes in the constructor. Multibinding solves the problem by providing an abstraction in the form of a set. Thanks to this set, the constructor requires no changes when a type is added/removed/changed.

How AdapterDelegates work

"Favor composition over inheritance" for RecyclerView Adapters

AdapterDelegates could be thought of like mini RecyclerView Adapters which can be plugged in into the main Adapter in order to support more item types. This means that adding an additional type to a list only requires an additional AdapterDelegate without needing to add extra logic to the main Adapter.

The AdapterDelegate for football matches in this project:

The data structure:

data class FootballMatch(
    val homeTeamName: String,
    val awayTeamName: String,
) : DisplayableItem

DisplayableItem is just a marker interface to indicate that this data structure is used as a RecyclerView Adapter item

interface DisplayableItem

Taking all of this into account, an AdapterDelegate for a football match looks like this:

internal class FootballMatchAdapterDelegate @Inject constructor() :
    AdapterDelegate<List<DisplayableItem>>() {

    override fun isForViewType(items: List<DisplayableItem>, position: Int): Boolean =
        items[position] is FootballMatch

    override fun onCreateViewHolder(parent: ViewGroup): RecyclerView.ViewHolder =
        FootballMatchViewHolder(
            parent.inflateLayout(R.layout.item_football_match)
        )

    override fun onBindViewHolder(
        items: List<DisplayableItem>,
        position: Int,
        holder: RecyclerView.ViewHolder,
        payloads: MutableList<Any>
    ) {
        val match = items[position] as FootballMatch
        (holder as FootballMatchViewHolder).bind(match)
    }
}

The FootballMatchAdapterDelegate will be responsible for showing any FootballMatch that is present in the DisplayableItem list. The ViewHolder implemented in the same way as any other ViewHolder, so I won't show it. The basketball implementation is just a mirror to this implementation is also omitted.

The main RecyclerView Adapter for the FootballMatchAdapterDelegate:

class MatchListAdapter(
    footballMatchAdapterDelegate: FootballMatchAdapterDelegate
) : RecyclerView.Adapter<RecyclerView.ViewHolder>() {

    private val delegatesManager = AdapterDelegatesManager<List<DisplayableItem>>()
    private var items = listOf<DisplayableItem>()

    init {
        delegatesManager.addDelegate(footballMatchAdapterDelegate)
    }

    override fun getItemViewType(position: Int): Int {
        return delegatesManager.getItemViewType(items, position)
    }

    override fun onCreateViewHolder(
        parent: ViewGroup, 
        viewType: Int
    ): RecyclerView.ViewHolder =
        delegatesManager.onCreateViewHolder(parent, viewType)

    override fun onBindViewHolder(holder: RecyclerView.ViewHolder, position: Int) {
        delegatesManager.onBindViewHolder(items, position, holder)
    }

    override fun getItemCount(): Int = items.count()

    fun setItems(newItems: List<DisplayableItem>) {
        items = newItems
    }
}

The main Adapter basically delegates all of its calls to the registered AdapterDelegates. If a suitable delegate is found then it will handle the item, in the case no appropriate delegate is found, a RunTimeException is thrown.

Side note: Behind the scenes I used an additional abstraction for the AdapterDelegate superclass to make injections more readable:

abstract class MatchAdapterDelegate : AdapterDelegate<List<DisplayableItem>>()

Using Dagger 2 Multibinds to extend RecyclerView Adapter functionality

Extending the solution from the previous section would require adding an extra constructor parameter along with its addition to the delegatesManager property. To make matters worse, it uses the concrete AdapterDelegate implementation instead of an abstraction. This means that adding a basketball AdapterDelegate would require a dependency on the basketball module for both the basic flavor and the premium flavor, even though the basic flavor will not use it.

Injecting a common supertype (AdapterDelegate or the MatchAdapterDelegate mentioned earlier) and the help of Multibinds allows extending the main Adapter without the need to change the code inside it. The added bonus is that the basic flavor does not need a dependency on the basketball module.

The dagger module for adding the FootballMatchAdapterDelegate into the dependency graph:

@Module
abstract class FootballModule {

    @Binds
    @IntoSet
    internal abstract fun bindFootballMatchAdapterDelegate(
        footballMatchAdapterDelegate: FootballMatchAdapterDelegate
    ): MatchAdapterDelegate
}

Thanks to the @IntoSet annotation the AdapterDelegate is not bound as a single class in the dagger graph, but as Set. If that sounds confusing I encourage you to read more about dagger multibindings in the official documentation.

In order for the Set to work correctly, a @Multibinds declaration needs to exist in a module that both flavors use:

@Multibinds
abstract fun multibindMatchAdapterDelegate(): Set<MatchAdapterDelegate>

And now instead of injecting a concrete implementation into the main Adapter, the multibound Set can be injected instead:

class MatchListAdapter(
    matchAdapterDelegates: Set<@JvmSuppressWildcards MatchAdapterDelegate>
) : RecyclerView.Adapter<RecyclerView.ViewHolder>() {
    //...
    init {
        matchAdapterDelegates.forEach { delegate ->
            delegatesManager.addDelegate(delegate)
        }
    }
    //...
}

Adding another RecyclerView type now only requires creating an AdapterDelegate and adding it to the dagger dependency graph as a set. The @JvmSuppressWildcards is used because of the way that Kotlin defines Set. Sometimes without the annotation dagger won't recognize the generic type.

Extending the main Adapter with the basketball type, only requires a dagger declaration with an @IntoSet annotation:

@Binds
@IntoSet
internal abstract fun bindBasketballMatchAdapterDelegate(
    basketballMatchAdapterDelegate: BasketballMatchAdapterDelegate
): MatchAdapterDelegate

Flavor based custom implementation

In our project we commonly encounter a situation where we need to implement custom behavior in one of the flavors, but the rest should remain as is. To allow this we use a function called customOrDefault:

fun <Type> customOrDefault(
    defaultImplementation: Type, 
    customImplementationsSet: Set<Type>
): Type {
    require(customImplementationsSet.size <= 1) {
        "Multiple (${customImplementationsSet.size}) custom implementations bound in $customImplementationsSet"
    }
    return customImplementationsSet.firstOrNull() ?: defaultImplementation
}

The basic idea is that if there is one custom implementation in the set then the custom implementation is used, otherwise the default implementation is used.

Providing the default implementation

The basic flavor only provides a list of football matches
A list of only football matches

These three items come from the default (basic flavor) implementation of the MatchesProvider interface:

interface MatchesProvider {

    fun get(): List<DisplayableItem>
}

class FootballMatchesProvider @Inject constructor() : MatchesProvider {

    override fun get(): List<DisplayableItem> {
        return listOf(
            FootballMatch("Burnley", "Leicester"),
            FootballMatch("Leipzig", "Wolfsburg"),
            FootballMatch("Chelsea", "Atlético Madrid"),
        )
    }
}

This MatchesProvider interface is used to provide items to the main Adapter:

@Inject
lateinit var  matchesProvider: MatchesProvider
//...
    adapter.setItems(matchesProvider.get())
//...

The MatchesProvider interface is introduced to the dagger dependency graph in the following way:

@Provides
fun provideDefaultOrCustomMatchesProvider(
    default: FootballMatchesProvider,
    custom: Set<@JvmSuppressWildcards MatchesProvider>
): MatchesProvider =
    customOrDefault(default, custom)

If the Set does not exist in the dagger graph then the default FootballMatchesProvider is used. Because the basic flavor does not introduce any additional MatchesProvider it uses the default implementation.

Side note: This declaration resides in the main package of the app module, meaning that both flavors use it.

Providing a custom implementation

The basketball module provides a MatchesProvider for basketball matches:

class BasketballMatchesProvider @Inject constructor() : MatchesProvider {

    override fun get(): List<DisplayableItem> {
        return listOf(
            BasketballMatch("Denver Nuggets", "Boston Celtics"),
            BasketballMatch("Atlanta Hawks", "Charlotte Hornets"),
            BasketballMatch("Orlando Magic", "Washington Wizards"),
        )
    }
}

However binding this as a Set with @IntoSet would mean that this implementation is the custom one thus making the premium flavor only show basketball matches.

To overcome this issue an additional MatchesProvider is defined in the app module within the package of the premium flavor:

class ConcatenatedMatchesProvider @Inject constructor(
    private val footballMatchesProvider: FootballMatchesProvider,
    private val basketballMatchesProvider: BasketballMatchesProvider,
): MatchesProvider {

    override fun get(): List<DisplayableItem> {
        return footballMatchesProvider.get()
            .zip(basketballMatchesProvider.get()) { a, b ->
                listOf(a, b)
        }.flatten()
    }
}

It basically merges the football and basketball matches together and returns the result. This implementation is bound in the following way:

@Binds
@IntoSet
abstract fun bindMatchesProvider(
    concatenatedMatchesProvider: ConcatenatedMatchesProvider
): MatchesProvider

Because the ConcatenatedMatchesProvider implementation is bound as a set, it will be used as the custom implementation in the customOrDefault function:

@Provides
fun provideDefaultOrCustomMatchesProvider(
    default: FootballMatchesProvider,
    custom: Set<@JvmSuppressWildcards MatchesProvider>
): MatchesProvider =
    customOrDefault(default, custom)

The list of matches from ConcatenatedMatchesProvider

Summary

Dagger2 Multibindings add even more complexity to the dependency injection in Android, but they can be used to solve even more complex problems. The example project for this article is available on GitHub, I hope it can be used as learning material for using Dagger 2 Multibindings in Android apps with multiple flavors.

Some things we used Multibindings for:

New RecyclerView types
Additional screens (e.g. Authentication)
Analytics
Custom views

If you have any questions, or you want to share how you used Multibindings to solve a complex problem please write about it below.