This article is a continuation of my previous Kotlin Multiplatform CI article the code can be found in the repository and changes for this article are in this Pull Request.

Reminder

The Code Review workflow runs the jobs based on the Pull Request labels, so the Android label only runs Android related Gradle tasks and the KMP label runs everything.

jobs:
  SetUp:
    runs-on: ubuntu-latest
    steps:
      - id: setVariables
        name: Set variables
        run: ...
    outputs:
      shouldRunKmp: ${{ steps.setVariables.outputs.shouldRunKmp }}
      shouldRunAndroid: ${{ steps.setVariables.outputs.shouldRunAndroid }}
      shouldRunIos: ${{ steps.setVariables.outputs.shouldRunIos }}
      shouldRunDesktop: ${{ steps.setVariables.outputs.shouldRunDesktop }}

  Build:
    needs: SetUp
    uses: ./.github/workflows/build.yml
    with:
      shouldRunKmp: ${{ needs.SetUp.outputs.shouldRunKmp }}
      shouldRunAndroid: ${{ needs.SetUp.outputs.shouldRunAndroid }}
      shouldRunIos: ${{ needs.SetUp.outputs.shouldRunIos }}
      shouldRunDesktop: ${{ needs.SetUp.outputs.shouldRunDesktop }}

  UnitTests:
    needs: SetUp
    uses: ./.github/workflows/test.yml
    with:
      shouldRunKmp: ${{ needs.SetUp.outputs.shouldRunKmp }}
      shouldRunAndroid: ${{ needs.SetUp.outputs.shouldRunAndroid }}
      shouldRunIos: ${{ needs.SetUp.outputs.shouldRunIos }}
      shouldRunDesktop: ${{ needs.SetUp.outputs.shouldRunDesktop }}

  AllowMerge:
    ...

Thanks to this, the CI only builds things which are needed and allows for skipping unrelated jobs. There's no point in running the iOS build if there are only Android changes.

AllowMerge, will pass if the dependent jobs passed or were skipped, in case of failure it will fail, thus blocking merging. Additionally, when the PR is opened without any label, then it will also fail.

AllowMerge:
  if: always()
    runs-on: ubuntu-latest
    needs: [ Build, UnitTests ]
    steps:
      - run: |
          if [ ${{ github.event_name }} == pull_request ] && [ ${{ join(github.event.pull_request.labels.*.name) == '' }} == true ]; then
            exit 1
          elif [ ${{ (contains(needs.Build.result, 'failure')) }} == true ] || [ ${{ (contains(needs.UnitTests.result, 'failure')) }} == true ]; then
            exit 1

The above logic will prevent a broken main branch, however, the Pull Request author needs to be diligent and apply the correct labels, which might be problematic if the changes start including other platforms and the author forgets to update them.

Automatic Labeling

The action for labeling is Labeler v5, which is configured as follows:

KMP:
- changed-files:
    - any-glob-to-any-file:
      - shared/**
      - konsist/**

Android:
- changed-files:
    - any-glob-to-any-file:
      - androidApp/**

iOS:
- changed-files:
    - any-glob-to-any-file:
      - iosApp/**

Desktop:
- changed-files:
    - any-glob-to-any-file:
      - desktopApp/**

The repository for this project is a fork, and because of this Labeler requires additional permissions, to work correctly:

jobs:
  SetUp:
    permissions:
      contents: read
      pull-requests: write
    ...

The set-up outputs, which control which platform is run, are now based on the labeler output:

SetUp:
  ...
  steps:
    - id: labeler
      if: ${{ !contains(github.event.pull_request.labels.*.name, 'Ignore') }}
      uses: actions/labeler@v5
    - id: setVariables
      name: Set variables
      run: |
        ...
        hasKmpLabel=${{ contains(steps.labeler.outputs.all-labels, 'KMP') }}
        ...
  outputs:
    shouldRunKmp: ${{ steps.setVariables.outputs.shouldRunKmp }}
    shouldRunAndroid: ${{ steps.setVariables.outputs.shouldRunAndroid }}
    shouldRunIos: ${{ steps.setVariables.outputs.shouldRunIos }}
    shouldRunDesktop: ${{ steps.setVariables.outputs.shouldRunDesktop }}
    all-labels: ${{ steps.labeler.outputs.all-labels }}

Additionally, if the PR already has a label called 'Ignore' then the labeler does not apply any labels, allowing the PR to be merged without any checks which might be useful for Tooling, Documentation, Codeowner etc. changes. (More on this in the next section)

The AllowMerge job has one additional dependency to SetUp to access the labeler output:

AllowMerge:
  if: always()
  runs-on: ubuntu-latest
  needs: [ SetUp, Build, UnitTests ]
  steps:
    - run: |
        if [ ${{ github.event_name }} == pull_request ] && [ ${{ join(github.event.pull_request.labels.*.name) == '' }} == true ] && [ ${{ join(needs.SetUp.outputs.all-labels) == '' }} == true ]; then
          exit 1
        elif [ ${{ (contains(needs.Build.result, 'failure')) }} == true ] || [ ${{ (contains(needs.UnitTests.result, 'failure')) }} == true ]; then
          exit 1
        else
          exit 0
        fi

This output is used in the empty label condition to ensure that labels which were added automatically are also checked, preventing false positives.

How it works

When the PR is created, then the labeler adds the corresponding labels, which then dictate what jobs are run:

Ignoring the labeling

There are some cases where there are no code changes, like tooling or documentation updates. In such cases, opening the PR with no matching directory changes will fail, because there are no labels.

However, the workflow logic has a special case for the Ignore label, which prevents labeler from being run (and accidentally adding labels when it shouldn't):

SetUp:
  ...
  steps:
    - id: labeler
      if: ${{ !contains(github.event.pull_request.labels.*.name, 'Ignore') }}
      uses: actions/labeler@v5
  ...

AllowMerge will pass because there is the Ignore label, allowing the PR to merge.

Summary

Having automated labels makes the Code Review process much safer by preventing merges for broken Pull Requests, ensuring that the main branch is stable (The only exception being adding the Ignore label by accident).

Additionally, the PR authors don't need to remember which labels to add or even add them at all, labeler takes care of this when creating a Pull Request.

Testing is an important part of software development, a good automated test suite can catch bugs in a matter of minutes. Automated tests are usually run as part of a Continuous Integration, which runs on a separate machine without much involvement of the developer.

Comparing that with manual testing, which usually: builds the whole app, requires clicking through it, sometimes even changing network responses to test edge cases (e.g. errors, missing data). All those manual steps performed through the day add up pretty quickly (not to mention the whole lifetime of the project) costing developers a lot of time which could be spent elsewhere.

However, to have a good automated test suite, it needs to cover all edge cases for the important parts of the code. Important code could be just complex logic which everyone is scared to touch in fear of breaking it. It might also be code which is often changed, and with a little bit of oversight might introduce regressions (i.e. bugs).

Unfortunately, having a good test suite isn't easy, every developer must be diligent and add tests for every logic condition. When the Author forgets to do so, then a Code Reviewer should catch this and raise the missing test cases.

The good news is, that Mutation Testing is an approach which allows for quickly catching missing test cases.

What's mutation testing

In simple terms, Mutation Testing involves changing the production code and then running the tests. If there's a failure after this change, then usually this condition is covered by tests*. However, if all tests pass, then most likely there is a missing test case for this condition.

* Sometimes even if some test fails after the "mutation" it's good to double-check if the test fails for the correct reasons. For example, the test focuses on some other part of the production code, but fails as a side effect of this mutation.

Boundary values example

Take a look at this example production code:

enum class Priority {
    LOW,
    HIGH,
}

fun convertToPriority(value: Int): Priority? {
    if (value !in 0..100) return null

    return if (value <= 100 && value > 50) {
        Priority.HIGH
    } else {
        Priority.LOW
    }
}

The logic could be simplified, but I wanted to keep it this way to simulate logic with a lot of conditions which might be tricky to test. There are some bugs hidden in the above code, which the current test suite does not detect:

@Test
fun `When value is -1 then null is returned`() {
    convertToPriority(-1) shouldBe null
}

@Test
fun `When value is 101 then null is returned`() {
    convertToPriority(101) shouldBe null
}

@Test
fun `When value is 51 then High priority is returned`() {
    convertToPriority(51) shouldBe Priority.HIGH
}

@Test
fun `When value is 50 then Low priority is returned`() {
    convertToPriority(50) shouldBe Priority.LOW
}

Looking at the test cases above, it might seem that everything is covered, however when it comes to boundary values it's really important to test all of them. In the function above, the boundary values are 100, 50 and 0.

To catch the missing test cases, it's as easy as changing the upper boundary value to something smaller, like 99:

The production code treats 100 as a High priority, so that's probably the requirement. However, after this change, all tests still pass, meaning that there's a missing test case for checking it:

@Test
fun `When value is 100 then High priority is returned`() {
    convertToPriority(100) shouldBe Priority.HIGH
}

Another missing test case is for the lower boundary in the first condition:

All tests still pass, so the following test needs to be added:

@Test
fun `When value is 0 then Low priority is returned`() {
    convertToPriority(0) shouldBe Priority.LOW
}

Mutation testing Cheat Sheet

Every condition like ifs, filters or anything which uses a boolean can be easily mutated by:

• Commenting it out altogether (removing a condition branch)
• Changing boundary values in comparisons (like in the example above)
• Negating the condition (e.g. using !, .not(), or switching from any to all)

Other code mutations could be returning a hard-coded value intentionally (e.g. an empty list, error or null)

Why Code Coverage doesn't tell the whole truth

Code coverage is a misleading metric, look at this example:

Looking at the above result it seems that everything is covered, however as previously pointed out, the above code has issues with the boundary values. So even though every line is covered, the test suite is not complete and is missing some cases.

Coverage could be used for just checking untested lines, however, for complex conditions it can be misleading and give false confidence that every case is covered.

Writing Code

When I'm writing code, most of the time I'm using Test Driven Development, which in practice should mean that there is no production code that doesn't have a corresponding test.

There are cases where I don't use TDD, or that the logic is so complex that I wasn't able to figure out all test cases for it. When that happens, Mutation Testing comes in handy, because it quickly allows me to find missing cases.

Reviewing Code

When reviewing code which has tests, I usually open both the production code and the tests side by side in a split view. I first read through the test cases and try to understand the requirements of the class.

After I'm done checking the existing code, I try to find any missing cases through mutation testing. Thanks to this, I don't need to spend a lot of time scanning through all test cases and checking the corresponding production code.

Besides finding missing test cases, mutation testing can also find tests which are passing for the wrong reason. For example, the production code uses condition A and B. The test verifies that when condition A is met, it passes. However, through mutation testing, condition A is removed but the test still passes. This means that the test passes for the wrong reason and needs to be changed.

Summary

To ensure that something is properly tested you first have to fully understand the code, mutation testing is kind of shortcut for this. The rule of thumb is that, if the changed code doesn't cause the test to fail, then some test case is missing.

This technique is helpful for driving good test coverage, it doesn't need to be used every time. There are less important classes which don't need to have perfect test coverage.

The main focus for using mutation testing should be on code which:

• Is changed a lot (because changes can introduce regressions, and automated tests help with catching them)
• Is critical for the functionality of the software (having tests for stuff which is only used for development might be overkill)
• Has really complex logic, making it hard to change without braking anything. In such situations, tests can act like a guiding lighthouse, if everything is green, then proceed.

If you're interested in learning more about testing in-general, checkout my article series on this topic:

5 Beginner Testing Mistakes I Noticed While Working with Less Experienced Developers

Having a good test suite helps with catching regressions / bugs a lot faster, and gives developers more confidence when merging / releasing their product. In this series, I’ll share my recommendations for improving your tests.

Aleksander JaworskiAKJAW

21 Testing Mistakes - Part 2

The second part of my Testing Mistakes series which is only available to Members / Subscribers

Aleksander JaworskiAKJAW

21 Testing Mistakes - Part 3

The third part of my Testing Mistakes series which is only available to Members / Subscribers

Aleksander JaworskiAKJAW

21 Testing Mistakes - Part 4

The fourth part of my Testing Mistakes series which is only available to Members / Subscribers

Aleksander JaworskiAKJAW

This article will focus on adding linter and code checks to a GitHub Actions Code Review workflow. The examples here are based on my Kotlin Multiplatform GitHub Actions repository, but all workflows and jobs are applicable to any Kotlin / Android project.

GitHub - AKJAW/kotlin-multiplatform-github-actions: Repository showcasing GitHub Actions for Kotlin Multiplatform

Repository showcasing GitHub Actions for Kotlin Multiplatform - GitHub - AKJAW/kotlin-multiplatform-github-actions: Repository showcasing GitHub Actions for Kotlin Multiplatform

AKJAWGitHub

However, before diving into the implementation, I'd like to provide some arguments why it's a good idea to do this.

Why are such automations needed?

Enforcing formatting and guidelines usually happens at the Code Review stage. You open a Pull Request, and a teammate informs you that a something is formatted incorrectly, or that the codebase uses a different convention for naming or packaging.

Verifying this manually takes more time, as the person doing the Code Review needs to pay extra attention to these things. While additionally trying to understand the changes in the PR. This leads to increased Code Review time and then additional time for fixing all the issues pointed out.

Besides the increased feedback loop, there is still a reliance on the human memory, the Reviewer might just forget about the conventions or be in a hurry, thus allowing the introduction of these "inconsistencies" into the codebase.

Automating such steps in the Continuous Integration pipeline should result in a healthier codebase, where every Pull Request follows the project guidelines. This eliminates the human forgetfulness aspect and also cuts down the feedback loop, because as soon as the PR is opened the verification is run and the author knows that some things need to be fixed.

Konsist

I've recently started playing around Konsist, and I was blown away by its ease of use and power. You basically write tests which asserts something on your Kotlin files / classes / properties. The added benefit is that the tests are debuggable, meaning that it's easy to create the test inside the debugger evaluation window.

I won't go into the details of how to set up Konsist, because the official documentation is a much better resource for that. I can just say that I put Konsist into a separate module to decrease the build / configuration time.

As for calling Konsist inside GitHub Actions, it's as simple as running all tests inside the Konsist module:

name: Konsist

on:
  workflow_call:

jobs:
  Konsist:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-java@v3
        with:
          distribution: "adopt"
          java-version: "11"
  
      - name: Setup Gradle
        uses: gradle/gradle-build-action@v2

      - run: ./gradlew :konsist:testDebugUnitTest

Ktlint

While Konsist focuses on more Architectural / Structural guidelines, Ktlint focuses on code style conventions / standards. Both of them can work together to create a more predictable and healthy codebase.

In the example repository, Ktlint is added through a Gradle plugin, meaning that it is installed alongside the project and can be run through a Gradle Task:

name: Ktlint

on:
  workflow_call:

jobs:
  Ktlint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-java@v3
        with:
          distribution: "adopt"
          java-version: "11"
  
      - name: Setup Gradle
        uses: gradle/gradle-build-action@v2

      - run: ./gradlew ktlintCheck

If your project doesn't use a Gradle plugin, but the Ktlint CLI, then it can be used on the GitHub machine like this:

...
jobs:
  Ktlint:
    runs-on: ubuntu-latest

    steps:
      ...

      - name: Ktint set up
        run: curl -sSLO https://github.com/pinterest/ktlint/releases/download/0.50.0/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/

      - run: ktlint '!**/build/**'

Running Konsist and Ktlint before other verifications

As you might've noticed, both the above workflows are declared as workflow_call, allowing them to be called from other workflows. If the other verifications like UnitTests or Builds ale also workflow_calls, then they can be set up in the following way:

name: Code review

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:
    types: [opened, ready_for_review, synchronize]
    branches:
      - main

jobs:
  Konsist:
    uses: ./.github/workflows/konsist.yml

  Ktlint:
    uses: ./.github/workflows/ktlint.yml

  Build:
    needs: [ Konsist, Ktlint ]
    uses: ./.github/workflows/build.yml

  UnitTests:
    needs: [ Konsist, Ktlint ]
    uses: ./.github/workflows/test.yml

Using needs inside the Build and UnitTests jobs forces both of them to wait for Konsist and Ktlint to complete successfully before starting. So for example if Konsist passes, but Ktlint fails then Build and UnitTests are not started, thus saving precious billing minutes and gives faster feedback to the PR author.

Summary

Having a good automation for these types of checks:

• Enforces good practices across the whole codebase by blocking incorrect Pull Requests
• Makes reviewing code easier and faster, because less attention needs to be given to the naming / packaging / styling etc
• Speeds up Pull Request merges, because the CI gives fast feedback about what should be fixed
• They are run automatically, so there's no need to manually check them before opening a PR

If you'd like to learn more about good GitHub Actions practices for actions and workflows, feel free to check out my previous article:

GitHub Actions Reducing Duplication / Boilerplate

YAML files, which are not that easy to maintain, changes are usually copied and pasted across multiple files. This article shows that there’s a better way.

Aleksander JaworskiAKJAW

Kotlin Multiplatform Bonus

Because Kotlin Multiplatform PRs can be iOS only, it makes no sense to run Ktlint or Konsist on them. So if there are no Kotlin changes, then both of the jobs should just be skipped. However, GitHub Actions treats skipped jobs as failed thus blocks merging, this means that the approach needs to be different.

The changes which add the Kotlin Multiplatform Label logic (From my previous article) can be found inside this Pull Request. The basic idea is that the labels are passed in from the Code Review workflow (I'll omit Ktlint because it's the same).

...

jobs:
  ...

  Konsist:
    needs: SetUp
    uses: ./.github/workflows/konsist.yml
    with:
      shouldRunKmp: ${{ needs.SetUp.outputs.shouldRunKmp }}
      shouldRunAndroid: ${{ needs.SetUp.outputs.shouldRunAndroid }}
      shouldRunDesktop: ${{ needs.SetUp.outputs.shouldRunDesktop }}

  ...

Then used like this

name: Konsist

on:
  workflow_call:
    inputs:
      shouldRunKmp:
        required: true
        type: string
      shouldRunAndroid:
        required: true
        type: string
      shouldRunDesktop:
        required: true
        type: string

jobs:
  Konsist:
    runs-on: ubuntu-latest

    steps:
      ...

      - run: |
          if ${{ inputs.shouldRunKmp == 'true' || inputs.shouldRunAndroid == 'true' || inputs.shouldRunDesktop == 'true' }}; then
            ./gradlew :konsist:testDebugUnitTest
          else 
            exit 0
          fi

Another approach could be using an if for the run step:

    steps:
      ...

      - if: ${{ inputs.shouldRunKmp == 'true' || inputs.shouldRunAndroid == 'true' || inputs.shouldRunDesktop == 'true' }}
        run: ./gradlew :konsist:testDebugUnitTest

So in cases when it doesn't make sense, Konsist and Ktlint are not executed:

However, for iOS there is SwiftLint which could be used when the iOS label is applied to the PR, thus ensuring iOS style guidelines. Adding a SwiftLint job to the above workflow would be pretty much the same as for the Konsist job, just the command, parameters and condition would be different.

If you want to learn more about using GitHub Actions for a Kotlin Multiplatform repository, you can read my other article on this topic:

Kotlin Multiplatform GitHub Actions CI Verification using Labels

Having automatic verifications is an important part of Software Development, as the project and team grows it becomes crucial that no regressions are introduced into the “main” branch by mistake.

Aleksander JaworskiAKJAW

In my previous article, I've shown how to set up a CI for a Kotlin Multiplatform repository. In this post, I'll focus on how to remove GitHub Actions boilerplate.

The CI verification consists of building the project and running tests on: the main branch and PRs. However, for PRs depending on what label the PR has only selected targets will be run, which saves time and costs (for paid plans).

The repository (which is a Kotlin Multiplatform project for Android, Desktop and iOS) used in this article is available in this repository:

GitHub - AKJAW/kotlin-multiplatform-github-actions: Repository showcasing GitHub Actions for Kotlin Multiplatform

Repository showcasing GitHub Actions for Kotlin Multiplatform - GitHub - AKJAW/kotlin-multiplatform-github-actions: Repository showcasing GitHub Actions for Kotlin Multiplatform

AKJAWGitHub

The Workflows

Without going into the implementation details of what is called where, here's a broad overview of the workflow structure:

name: Code review

on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:
    types: [opened, ready_for_review, synchronize]
    branches:
      - main

jobs:
  Build:
    uses: ./.github/workflows/build.yml

  UnitTests:
    uses: ./.github/workflows/test.yml

  AllowMerge:
    if: always()
    runs-on: ubuntu-latest
    needs: [ Build, UnitTests ]
    steps:
      - run: |
          if [ ${{ github.event_name }} == pull_request ] && [ ${{ join(github.event.pull_request.labels.*.name) == '' }} == true ]; then
            exit 1
          elif [ ${{ (contains(needs.Build.result, 'failure')) }} == true ] || [ ${{ (contains(needs.UnitTests.result, 'failure')) }} == true ]; then
            exit 1
          else
            exit 0
          fi

This is the main workflow which will be called by GitHub directly. It calls two other workflows that run the builds and tests. The last job is used for the GitHub PR status check, which fails if there is no PR label or when any of the Build / Tests jobs fail (which is needed because GitHub treats skipped jobs as failed).

This workflow doesn't really contain any repetition / boilerplate which can be improved. The problems lie in the two "sub-workflows" (Don't worry, you don't need to read the whole things):

name: Build

on:
  workflow_call:

jobs:
  Android:
    if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false && (contains(github.event.pull_request.labels.*.name, 'KMP') || contains(github.event.pull_request.labels.*.name, 'Android'))) }}
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-java@v3
        with:
          distribution: "adopt"
          java-version: "11"

      - name: Setup Gradle
        uses: gradle/gradle-build-action@v2

      - run: ./gradlew :androidApp:assemble

  Desktop:
    if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false && (contains(github.event.pull_request.labels.*.name, 'KMP') || contains(github.event.pull_request.labels.*.name, 'Desktop'))) }}
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-java@v3
        with:
          distribution: "adopt"
          java-version: "11"

      - name: Setup Gradle
        uses: gradle/gradle-build-action@v2

      - run: ./gradlew :desktopApp:assemble

  iOS:
    if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false && (contains(github.event.pull_request.labels.*.name, 'KMP') || contains(github.event.pull_request.labels.*.name, 'iOS'))) }}
    runs-on: macos-12

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-java@v3
        with:
          distribution: "adopt"
          java-version: "11"

      - name: Setup Gradle
        uses: gradle/gradle-build-action@v2

      - run: ./gradlew :shared:generateDummyFramework

      - name: Set up cocoapods
        uses: maxim-lobanov/setup-cocoapods@v1
        with:
          version: latest

      - name: Install Dependencies
        run: |
          cd iosApp
          pod install --verbose

      - run: xcodebuild build -workspace iosApp/iosApp.xcworkspace -configuration Debug -scheme iosApp -sdk iphoneos -destination name='iPhone 14' -verbose

The basic idea is as follows for both the Builds and UnitTests workflows. The jobs should only run when

• Started manually through workflow_dispatch
• From a push on the main branch
• When a PR is opened or pushed to (It's important that the PR is not a draft as to not waste billing minutes)

Additionally, PR labels control for which platforms the jobs will run:

For example, if the PR changes are only for the Android codebase, then the PR should have the Android label. The KMP label should be used when the shared codebase changes and because it is used by all platforms, all jobs should be run.

Boilerplate

In this article I'll only focus on the Build workflow, however the same steps should be applied to the UnitTests workflow, as both of them have the following boilerplate:

• All of the above jobs have the same two set-up steps
  • Java
  • Gradle
• Repeated if statements
  • For the GitHub event (workflow_dispatch, push, pull_request)
  • For the PR label (github.event.pull_request.labels.*.name)

Extracting steps to a separate file

Steps can be moved to a composite action, which can be then re-used multiple times across all jobs.

The Java and Gradle composite action could look like this:

name: Job set up
description: Sets up Java and Gradle
runs:
  using: "composite"
  steps:
    - uses: actions/setup-java@v3
      with:
        distribution: "adopt"
        java-version: "11"

    - name: Setup Gradle
      uses: gradle/gradle-build-action@v2

The name of the composite action becomes the name of the parent folder, which in this case is job-set-up.

And then it can be re-used in all the jobs like this:

Android:
    if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false && (contains(github.event.pull_request.labels.*.name, 'KMP') || contains(github.event.pull_request.labels.*.name, 'Android'))) }}
  runs-on: ubuntu-latest

  steps:
    - uses: actions/checkout@v3

    - name: Job set up
      uses: ./.github/actions/job-set-up

    - run: ./gradlew :androidApp:assemble

Extracting the GitHub event condition

As shown previously, the if statement is pretty complex, which leads to it being hard to understand. To make the matter worse, it is scattered through all the jobs, making it hard to change.

As we all know, developers are lazy creatures, instead of changing all of them separately, they'll for sure copy and paste the if statement, which will sooner or later lead to bugs and typos.

What can be done is to move the if statement to an additional job that runs before Build and UnitTests workflows:

# ...

jobs:
  SetUp:
    runs-on: ubuntu-latest
    steps:
      - id: setVariables
        name: Set variables
        run: |
          if [ ${{ github.event_name }} == workflow_dispatch ] || [ ${{ github.event_name }} == push ] || ([ ${{ github.event_name }} == pull_request ] && [ ${{ github.event.pull_request.draft }} == false ]); then
            exit 0
          else
            exit 1
          fi

  Build:
    needs: SetUp
    uses: ./.github/workflows/build.yml

  UnitTests:
    needs: SetUp
    uses: ./.github/workflows/test.yml

The SetUp job checks if the workflow was started in the right conditions, if yes then it completes successfully, allowing the Build and UnitTests workflows to start. Otherwise, SetUp fails, causing Build and UnitTests to also fail, thus reducing the duplication inside the workflows while behaving in the same way.

Here's what the Android build job looks after this change:

Android:
  if: ${{ github.event_name != 'pull_request' || (github.event_name == 'pull_request' && (contains(github.event.pull_request.labels.*.name, 'KMP') || contains(github.event.pull_request.labels.*.name, 'Android'))) }}
  # ...

The if statement is better but still complex, the first condition (!= 'pull_request') is required because without it, manual or main branch runs would always result in skipped jobs, but for PRs, the labels are checked just like before.

Reducing Label Boilerplate

The previous if statement was the same for all jobs, however label logic differs between jobs. This means that the if statement cannot be completely removed, however it can be improved using some bash logic and by passing variables between jobs:

# ...

jobs:
  SetUp:
    runs-on: ubuntu-latest
    steps:
      - id: setVariables
        name: Set variables
        run: |
          echo "shouldRunKmp=${{ contains(github.event.pull_request.labels.*.name, 'KMP') }}" >> "$GITHUB_OUTPUT"
          echo "shouldRunAndroid=${{ contains(github.event.pull_request.labels.*.name, 'Android') }}" >> "$GITHUB_OUTPUT"
          # ...
    outputs:
      shouldRunKmp: ${{ steps.setVariables.outputs.shouldRunKmp }}
      shouldRunAndroid: ${{ steps.setVariables.outputs.shouldRunAndroid }}
      
  Build:
    needs: SetUp
    uses: ./.github/workflows/build.yml
    with:
      shouldRunKmp: ${{ needs.SetUp.outputs.shouldRunKmp }}
      shouldRunAndroid: ${{ needs.SetUp.outputs.shouldRunAndroid }}

The above set-up logic reads the PR labels and passes them to other jobs, which can be used like this:

name: Build

on:
  workflow_call:
    inputs:
      shouldRunKmp:
        required: true
        type: string
      shouldRunAndroid:
        required: true
        type: string
      # ...

jobs:
  Android:
    if: ${{ github.event_name != 'pull_request' || (github.event_name == 'pull_request' && (inputs.shouldRunKmp == 'true' || inputs.shouldRunAndroid == 'true')) }}
    # ...

This improves the if statement, but it can still be improved further. The SetUp job already has an early return based on the event_name, but here it is duplicated. Instead of duplicating it, the logic can be included as part of the output variables logic:

SetUp:
  runs-on: ubuntu-latest
  steps:
    - id: setVariables
      name: Set variables
      run: |
        isFromMain=${{ github.ref == 'refs/heads/main' }}
        isManual=${{ github.event_name == 'workflow_dispatch' }}
        hasKmpLabel=${{ contains(github.event.pull_request.labels.*.name, 'KMP') }}
        shouldRunKmp=false
        if $isFromMain || $isManual || $hasKmpLabel ; then
          shouldRunKmp=true
        fi
        echo "shouldRunKmp=$shouldRunKmp" >> "$GITHUB_OUTPUT"
        echo "shouldRunAndroid=${{ contains(github.event.pull_request.labels.*.name, 'Android') }}" >> "$GITHUB_OUTPUT"
        # ...
  outputs:
    shouldRunKmp: ${{ steps.setVariables.outputs.shouldRunKmp }}
    shouldRunAndroid: ${{ steps.setVariables.outputs.shouldRunAndroid }}

In case the PR run on the main branch or started manually, the shouldRunKmp is set to true, meaning that all jobs will be started, and for PRs, the labels decide what is run. This change, reduces the job if statements to just using the input variables:

jobs:
  Android:
    if: ${{ inputs.shouldRunKmp == 'true' || inputs.shouldRunAndroid == 'true' }}
  # ...

Workflow Reusability

As you may have noticed, the Build and UnitTests workflows were specified as separate workflows using workflow_call. Thanks to this, they can be used in other workflows.

For example, if the project had a nightly verification, both of these workflows could be re-used to make sure that nothing broke the main branch. Please note, that with the above logic, the nightly would need to pass in the correct variables for the jobs to run (Or just the KMP one).

Summary

• Composite actions - help with repeated steps, like common set-up logic
• Set-up jobs - can contain early returns for workflow starts in the wrong conditions
• Output variables - can be used to reduce the number of conditions in jobs
• Reusable workflows - can be re-used across multiple workflows, eliminating copying and pasting logic throughout different files

All the changes discussed in this article can be seen in this PR.

Course

If you found this helpful, you might be interested in the Android Next Level course I'm a co-author of. It goes more in-depth into CI/CD for Android, e.g. Code Review, Manual builds for testers, Release builds, Nightly verification and more. Currently, the course is only available in Polish, but there is a waitlist for those interested in an English version of it, so feel free to check it out if you're interested!

Android Next Level

A course about processes outside of coding like: CI/CD, scaling your project, good git hygiene or how to cooperate with your teammates

Aleksander JaworskiAKJAW

In this article, I'll show how to set up a Continuous Integration for a Kotlin Multiplatform repository. This CI will verify that the code changes don't break the main branch. The tool used for this is GitHub Actions which I use for every personal project because it is integrated with GitHub, and it is free for open source projects.

The CI verification consists of building the project and running tests both on PRs and on the main branch. However, depending on what label is selected for the PR only selected targets will be run, which saves time and costs (for paid plans).

The repository (which includes an Android, Desktop and iOS target) used in this article is available here:

GitHub - AKJAW/kotlin-multiplatform-github-actions

Contribute to AKJAW/kotlin-multiplatform-github-actions development by creating an account on GitHub.

GitHubAKJAW

Keep in mind that this article shows a version of the repository which contains boilerplate. How to remove this boilerplate is the topic of my other article.

Why is such verification needed?

Such a Continuous Integration will give us confidence, that changes made in the project don't break anything. It offloads the verification to an automated process, which doesn't forget and runs with little manual input.

If you'd like to fully automate this verification, checkout out my follow-up article on setting up automated labels.

Steps

Before delving into the details, I just want to show the steps which will be used in the workflow. Every job contains the same set-up steps, so they will be omitted for brevity in the examples, the full code is available in the repository.

steps:
  - uses: actions/checkout@v3

  - uses: actions/setup-java@v3
    with:
      distribution: "adopt"
      java-version: "11"

  - name: Setup Gradle
    uses: gradle/gradle-build-action@v2

Build

The Android and Desktop jobs are pretty much the same, with only the module being different. Both can be run on Ubuntu machines (which are the cheapest):

Android:
  if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false) }}
  runs-on: ubuntu-latest

  steps:
    # ...
    - run: ./gradlew :androidApp:assemble

Desktop:
  if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false) }}
  runs-on: ubuntu-latest

  steps:
    # ...
    - run: ./gradlew :desktopApp:assemble

iOS requires a macOS machine and is more involved as besides Gradle it also needs to set up CocoaPods and pods installation before running the build:

iOS:
  if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false) }}
  runs-on: macos-12

  steps:
    # ...
    - run: ./gradlew :shared:generateDummyFramework

    - name: Set up cocoapods
      uses: maxim-lobanov/setup-cocoapods@v1
      with:
        version: latest

    - name: Install Dependencies
      run: |
        cd iosApp
        pod install --verbose

    - run: xcodebuild build -workspace iosApp/iosApp.xcworkspace -configuration Debug -scheme iosApp -sdk iphoneos -destination name='iPhone 14' -verbose

Test

These jobs are pretty much the same, the only difference being the last Gradle / Xcode command

./gradlew clean testDebugUnitTest -p shared/

./gradlew clean desktopTest -p shared

Because now Macs with M1/M2 have a different architecture than Intel, they require a different command. The if statement launches the correct command depending on the system architecture (As of now every GitHub runner has Intel, but this future proofs the CI and allows for self-hosted runners using M1).

if [[ $(uname -m) == 'arm64' ]]; then ./gradlew clean iosSimulatorArm64Test -p shared/; else ./gradlew clean iosX64Test -p shared/; fi

./gradlew clean testDebug -p androidApp/

./gradlew clean jvmTest -p desktopApp/

xcodebuild build test -workspace iosApp/iosApp.xcworkspace -configuration Debug -scheme iosApp -sdk iphoneos -destination name='iPhone 14' -verbose

With native iOS tests I've run into a problem caused by Compose Multiplatform which I was not able to solve, so for now they are just skipped.

Uncaught Kotlin exception: kotlin.IllegalStateException: Metal is not supported on this system

Maybe someone will be able to show me a different way of running tests which works on GHA 😄 (Comment below if you have any ideas).

Code Review Workflow

Both the Build and UnitTests workflows are called from the main Code Review workflow:

name: Code review

on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:
    types: [opened, ready_for_review, synchronize]
    branches:
      - main

jobs:
  Build:
    uses: ./.github/workflows/build.yml

  UnitTests:
    uses: ./.github/workflows/test.yml

This is the workflow which will be run on opened PRs and on the main branch after merging.

Running the verification only when it makes sense

You may have noticed, that all the build jobs share the same if statement (along with UnitTests):

if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false) }}

This is because the jobs should only run on certain conditions

• When a PR is opened
• When a commit is pushed (but only on the main branch or on an opened PR)
• When stared manually on GitHub

The jobs shouldn't run when the PR is a draft, because these PRs are still a Work In Progress, so it makes no sense to waste resources on verifying them.

Running only the required jobs

The current solution runs every target / job regardless of what was changed. This can be improved by introducing labels to the project

Then these labels can be used on GHA to decide if something should be run or not:

Android:
  if: ${{ contains(github.event.pull_request.labels.*.name, 'KMP') || contains(github.event.pull_request.labels.*.name, 'Android')}}
  runs-on: ubuntu-latest

  steps:
    # ...
    - run: ./gradlew :androidApp:assemble    

The Android build job will be only run when the PR contains either a KMP or an Android label.

Please note that the above if statement for labels needs to be combined with the if statement from the previous section, which results in this pretty thing:

${{ github.event_name == 'workflow_dispatch' || github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false && (contains(github.event.pull_request.labels.*.name, 'KMP') || contains(github.event.pull_request.labels.*.name, 'Android'))) }}

This can be improved, by creating a set-up job and moving the labels to variables, however this will be explained more in-depth in my next article as stated in the beginning.

Blocking merging when the CI fails

Unfortunately, GitHub treats skipped jobs as failed, meaning that with status checks, only the KMP label would work correctly, all other labels would result in a blocked merge option, because some jobs were skipped.

This can be fixed by adding another job which runs after all other jobs complete:

jobs:
  SetUp: # ...
  Build: # ...
  UnitTests: # ...
  AllowMerge:
    if: always()
    runs-on: ubuntu-latest
    needs: [ Build, UnitTests ]
    steps:
      - run: |
          if [ ${{ github.event_name }} == pull_request ] && [ ${{ join(github.event.pull_request.labels.*.name) == '' }} == true ]; then
            exit 1
          if [ ${{ (contains(needs.Build.result, 'failure')) }} == true ] || [ ${{ (contains(needs.UnitTests.result, 'failure')) }} == true ]; then
            exit 1
          else
            exit 0
          fi

After this change, the GitHub repository can block merging when the AllowMerge doesn't pass.

The first if statement ensures that any PR has at least one label, when it's missing a label, the run will fail. Thanks to this, the problem of human forgetfulness is out of the CI equation. When someone forgets to add the label, the PR won't be allowed to merge.

The second if statement verifies that there were no failures on any of the previous jobs. In case there was at least one failure, the PR will be blocked from merging. This should guarantee that no regressions can be introduced into the main branch (unless someone puts a wrong label on the PR).

Static analysis tools

Using these types of tools as part of the Code Review workflow will keep the codebase more predictable and healthy. If you're interested in this topic, checkout my article on it:

Adding Konsist and Ktlint to a GitHub Actions Continuous Integration

Automating code and architecture checks in the Continuous Integration pipeline can significantly reduce Code Review time and prevent human forgetfulness.

AKJAWAleksander Jaworski

Extras

Automated Labels

Depending on human memory isn't always the best way of doing things. Adding labels can be automated using the Labeler actions, to learn more click here:

Kotlin Multiplatform GitHub Actions Automated Pull Request Labels

Having automated labels makes the Code Review process much safer by preventing merges for broken Pull Requests, ensuring that the main branch is stable

AKJAWAleksander Jaworski

Gradle Caching

Caching can be achieved using the official gradle-build-action, which has a built-in caching system. The default behavior only saves the cache on the main branch, and other branches can only read from the cache.

This behavior can be customized, so the cache can be saved on multiple branches as specified in the documentation.

Concurrency

A lot of time was spent optimizing the CI, to not run when not needed, e.g. when only changing Android, the iOS jobs shouldn't run. However, there is one more optimization which cancels any unneeded jobs.

By unneeded I mean a Code Review run which is not valid anymore, for example when a new commit was pushed on an opened PR. In that case, the currently running CI on the old commit should be stopped.

Fortunately, this functionality is supported in GitHub Actions:

name: Code review

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

These 3 lines, will automatically cancel any jobs which will be replaced by new ones, potentially saving a lot of unnecessary "billing minutes".

Course

I'm a co-author of an Android course which goes more in-depth into CI/CD for Android like, the above Code Review, Manual builds for testers, Release builds, Nightly verification and more. Currently, the course is only available in Polish, but there is a waitlist for those interested in an English version of it, so feel free to check it out if you're interested!

Android Next Level

A course about processes outside of coding like: CI/CD, scaling your project, good git hygiene or how to cooperate with your teammates

AKJAWAleksander Jaworski

This is a write-up for a talk I gave at Droidcon Berlin 2023, the video version can be found here:

Calling Kotlin Multiplatform Coroutines from Swift with the help of KMP-NativeCoroutines - droidcon

The official way of using Coroutines from Swift is awkward and has a lot of limitations. These limitations can be addressed by creating handwritten wrappers, but that includes a lot of boilerplate.

droidcondroidcon

The presentations / decks can be found here:
Async / Await
Combine

TL;DR KMP-NativeCoroutines allows the use Native Swift solutions (Async await, Combine or RxSwift) for asynchronous Kotlin code (Suspend functions and Flows). The library is also one of the Kotlin Grant winners.

The code used in the deck and in this write-up is available on GitHub, it uses the Touchlab KaMP Kit Starter. The main implementation is for Async Await, but there is also a commented out Combine implementation:

GitHub - AKJAW/Swift-Coroutines-With-KMP-NativeCoroutines

Contribute to AKJAW/Swift-Coroutines-With-KMP-NativeCoroutines development by creating an account on GitHub.

GitHubAKJAW

View Model

The starter screen which uses the three coroutine approaches calls the following ViewModel:

class BreedViewModel() : ViewModel() {

   val breedState: StateFlow<BreedViewState> // Data stream

   suspend fun refreshBreeds(): Boolean // Suspend function

   fun updateBreedFavorite(breed: Breed): Job // Ordinary function
}

Which also has a super class that has access to a CoroutineScope and a function for cancelling all child coroutines:

actual abstract class ViewModel {

   actual val viewModelScope = MainScope()

   fun clear() {
       viewModelScope.coroutineContext.cancelChildren()
   }
}

Normal / Ordinary function

The easiest way to call a suspend function is to call a normal function, which launches a coroutine:

fun updateBreedFavorite(breed: Breed): Job {
   return viewModelScope.launch {
       breedRepository.updateBreedFavorite(breed)
   }
}

And in Swift, it's just a normal function call:

func onBreedFavorite(breed: Breed) {
    viewModel?.updateBreedFavorite(breed: breed)
}

However, this approach comes with drawbacks:

• There is no way to get a return value from it, the only way to achievie it to modify some internal state which is exposed to the UI
• A CoroutineScope is required in order to launch the coroutine from Kotlin
• It's not so easy to be notified when the coroutine completes

Suspend functions

For cases where the return value is needed or there needs to be a callback for when the suspension completes, then a suspending function needs to be called directly from Swift.

suspend fun refreshBreeds(): Boolean {
   return try {
       breedRepository.refreshBreeds()
       true
   } catch (exception: Exception) {
       handleBreedError(exception)
       false
   }
}

If you're just interested in the best approach, skin on over to the KMP-NativeCoroutines section.

Official generated code

This is the simplest form of calling suspend functions from Swift, which comes out of the box with Kotlin. However, it is also the worst one... Calling it is pretty straight forward, every suspend function will take in a lambda from Swift:

viewModel?.refreshBreeds { wasRefreshed, error in
  print("refresh: \(wasRefreshed), \(error)")
}

However, the return value is Optional, which means that it can exist or not (like Nullable):

refresh: Optional(1), error: nil

Even though there is an error parameter, it only represents CancellationExceptions all Other uncaught Kotlin exceptions are fatal causing the App to crash:

/**
 * @note This method converts instances of CancellationException to errors.
 * Other uncaught Kotlin exceptions are fatal.
*/
- (void)refreshBreedsWithCompletionHandler:(void (^)(SharedBoolean * _Nullable, NSError * _Nullable))completionHandler __attribute__((swift_name("refreshBreeds(completionHandler:)")));

Adapter / Wrapper

This approach gives more control over our suspend functions from Swift, but requires some additional boilerplate for every function. The SuspendAdapter is the class which is used from Swift to call any suspending function:

class SuspendAdapter<T : Any>(
   private val scope: CoroutineScope,
   private val suspender: suspend () -> T
)

In order to use the Adapter, the iOS target requires an additional ViewModel class, which delegates all calls to the common ViewModel:

@Suppress("Unused") // It's used from Swift
class AdapterBreedViewModel {
  
  val viewModel = BreedViewModel()

  fun refreshBreeds() =
    SuspendAdapter(viewModel.scope) {
      viewModel.refreshBreeds()
    }
}

The SuspendAdapter has a subscribe function is used to launch the coroutine from Swift:

class SuspendAdapter<T : Any>(
   private val scope: CoroutineScope,
   private val suspender: suspend () -> T
) {

 fun subscribe(
     onSuccess: (item: T) -> Unit,
     onThrow: (error: Throwable) -> Unit
 ) = scope.launch {
     try {
         onSuccess(suspender())
     } catch (error: Throwable) {
         onThrow(error)
     }
 }
}

From the iOS App perspective, the contract is definitely much easier to use and understand:

viewModel.refreshBreeds().subscribe(
    onSuccess: { value in
        print("completion \(value)")
    },
    onThrow: { error in
        print("error \(error)")
    }
)

There is also a way to integrate it with Native solutions (like Combine):

createFuture(suspendAdapter: adapter)
    .sink { completion in
        print("completion \(completion)")
    } receiveValue: { value in
        print("recieveValue \(value)")
    }.store(in: &cancellables)

KMP-NativeCoroutines

This is my recommended approach of handling suspend functions from Swift. The library basically generates code similar to the Adapter (but a lot better) from the previous section. Additionally, it also has Swift libraries / packages which allow the use of Native Swift solutions, which in this case it will be Async/Await.

To generate the Adapter, all that needs to be done from Kotlin is to add the correct annotation:

@NativeCoroutines
suspend fun nativeRefreshBreeds(): Boolean =
   refreshBreeds()

And from Swift, once the correct library is imported, there is access to helper functions which for this call is asyncFunction that takes in the Kotlin suspend function call:

func refresh() async {
  let suspend = viewModel.nativeRefreshBreeds()
  do {
      let value = 
          try await asyncFunction(for: suspend)
      print("Async Success: \(value)")
  } catch {
      print("Async Failed with error: \(error)")
  }
}

There exists also another helper function asyncResult which eliminates the need for error handling because it returns enum values representing either success or error values:

func refresh() async {
  let suspend = viewModel.nativeRefreshBreeds()
  let value = await asyncResult(for: suspend)
  switch value {
  case .success(let result):
      print("Async Success: \(result)")
  case .failure(let error):
      print("Async Failed with error: \(error)")
  }
}

Internals of the generated code

If you're interested in what the library generates, here's my own, non-complete and simplified version.

The generated Kotlin function, which is called from Swift, looks as follows:

@ObjCName(name = "nativeRefreshBreeds")
public fun BreedViewModel.nativeRefreshBreedsNative(): NativeSuspend<Boolean> =
    nativeSuspend(viewModelScope) { nativeRefreshBreeds() }

The body of the function does a similar thing to what happened in the handwritten Adapter, it just delegates the call to the common ViewModel.

The return value NativeSuspend is type alias for a lambda that takes in three other lambdas:

typealias NativeCallback<T> = (T, Unit) -> Unit

typealias NativeSuspend<T> = (
    onResult: NativeCallback<T>,
    onError: NativeCallback<NativeError>,
    onCancelled: NativeCallback<NativeError>
) -> NativeCancellable

And in the generated code ObjC it looks like this:

@interface SharedBreedViewModel (Extensions)
- (SharedKotlinUnit *(^(^)(SharedKotlinUnit *(^)(SharedBoolean *, SharedKotlinUnit *), SharedKotlinUnit *(^)(NSError *, SharedKotlinUnit *), SharedKotlinUnit *(^)(NSError *, SharedKotlinUnit *)))(void))nativeRefreshBreeds __attribute__((swift_name("nativeRefreshBreeds()")));
@end

I personally cannot decipher the code above, but fortunately the library author can and provides this on the Swift side:

public typealias NativeCallback<T, Unit> = (T, Unit) -> Unit

public typealias NativeSuspend<Result, Failure: Error, Unit> = (
    _ onResult: @escaping NativeCallback<Result, Unit>,
    _ onError: @escaping NativeCallback<Failure, Unit>,
    _ onCancelled: @escaping NativeCallback<Failure, Unit>
) -> NativeCancellable<Unit>

Which is then used for the asyncFunction:

public func asyncFunction<Result, Failure: Error, Unit>(
    for nativeSuspend: @escaping NativeSuspend<Result, Failure, Unit>
) async throws -> Result {
    try await AsyncFunctionTask(nativeSuspend: nativeSuspend).awaitResult()
}

A lot of more internal magic is done, which allows the following Async/Await call:

let result =
    await asyncResult(for: viewModel.nativeRefreshBreeds())

Flows

It is possible to collect flows using the Official way and with the Adapter as well, however I won't dive into their implementations. They are briefly shown in the deck on page 63 and 65 respectively.

KMP-NativeCoroutines

The approach is the same as with suspending functions, just adding an annotation will generate the necessary code on the Kotlin/Native side:

@NativeCoroutinesState
val nativeBreedState: StateFlow<BreedViewState> =
   breedState

This time, the asyncSequence is used for transforming the Flow into a Sequence:

func activate() async {
  let nativeFlow = viewModel.nativeBreedStateFlow
  do {
    let sequence = asyncSequence(for: nativeFlow)
    for try await dogsState in sequence {
        self.loading = dogsState.isLoading
        self.breeds = dogsState.breeds
        self.error = dogsState.error
    }
  } catch {
    print("Async Failed with error: \(error)")
  }
}

Which is caused by the internal state updates:

self.loading = dogsState.isLoading
self.breeds = dogsState.breeds
self.error = dogsState.error

The fix for the warning is to update the state on the main thread, which shown in the next section.

Controlling the Scope

To define the scope / dispatcher which KMP-NativeCoroutines uses needs to be available in the Kotlin class and have the following annotation:

@NativeCoroutineScope
actual val viewModelScope = MainScope()

MainScope is a standard library function which creates a Scope for the "UI Thread":

public fun MainScope(): CoroutineScope = 
    ContextScope(SupervisorJob() + Dispatchers.Main)

Keep in mind that the @NativeCoroutineScope only controls the Kotlin side of the coroutine.

• In Combine, the above scope makes the Swift "collection" happen on the main thread. Thanks to this, the .receive(on: DispatchQueue.main) is not required.
• In Async / Await, this scope won't apply to the Swift side. The thread still needs to be specified in Swift, like in the example below.

@MainActor
func activate() async { ... }

Without this @MainActor annotation, the values are "collected" in Kotlin using the Main thread, but once they are received by Swift, the Task is responsible for specifying the threading.

Exception / Error Handling

It's good to know how Kotlin Coroutines exceptions affect the iOS app and how to guard against them.

Suspend functions

The function which will be called is as follows, it delays for 1 second and the throws an exception:

@NativeCoroutines
suspend fun throwException() {
   delay(1000)
   throw IllegalStateException()
}

On The Swift side, it is called like this:

print("async exception start")
do {
    let result = try await asyncFunction(for: suspend)
    print("async exception success \(result)")
} catch {
    print("async exception failure \(error)")
}

And the result is as follows:

18:07:03 async exception start
18:07:04 async exception failure (ErrorDomain=KotlinExcepton Code=0 "(null)" UserInfo={KotlinException=kotlin.IllegalStateException})

Flows

For flows, the stream emits 3 values and then throws an exception:

@NativeCoroutines
val errorFlow: Flow<Int> = flow {
   repeat(3) { number ->
       emit(number)
       delay(1000)
   }
   throw IllegalStateException()
}

do {
    let sequence = asyncSequence(for: viewModel.errorFlow)
    for try await number in sequence {
        print("sequence exception n: \(number)")
    }
} catch {
    print("sequence exception error: \(error)")
}

2023-06-28 18:14:24 sequence exception number 0
2023-06-28 18:14:25 sequence exception number 1
2023-06-28 18:14:26 sequence exception number 2
2023-06-28 18:14:27 sequence exception error 
(Error Domain=KotlinException Code=0 "(null)"
UserInfo={KotlinException=kotlin.IllegalStateException})

There is also an option to just ignore errors:

func throwException() async throws {
    let sequence = asyncSequence(for: viewModel.errorFlow)
    for try await number in sequence {
        print("sequence exception n: \(number)")
    }
}

try? await observableModel.throwException()

Exception handling summary

In Async / Await the error handling is pretty straight forward with the do catch statement so no surprises here. However, handling these Kotlin exceptions on the Swift side is pretty awkward.

I'm personally not a fan of throwing exceptions (and neither is the Kotlin team), it's much better to define a value which represents the error state. Which could a null or a sealed class, both of these approaches will be a lot easier and safer to handle on the Swift side.

Cancellation

The following Flow will be used to demonstrate cancellation on the iOS App:

@NativeCoroutines
val numberFlow: Flow<Int> = flow {
   var i = 0
   while (true) {
       emit(i++)
       delay(1000)
   }
}.onEach { number ->
   log.i("numberFlow onEach: $number")
}.onCompletion { throwable ->
   log.i("numberFlow onCompletion: $throwable")
}

There are two ways of cancelling coroutines in the iOS App:

• Manual, which happens when a button is pressed or when the onDisappear callback is called.
• Automatic when SwiftUI deems the screen as not needed (No callbacks required).

I tried making the code in such a way that both these ways are possible using Async / Await. However, at the moment Swift lacks structured concurrency for Tasks meaning, that only one is possible at the same time.

Manual

In order to manually cancel the number sequence, a new Task needs to be created and assigned to a field:

func listenToNumbers() async {
  numberTask = Task {
      let sequence =
        asyncSequence(for: viewModel.numberFlow)
      for try await number in sequence {
        self.number = number.intValue
      }
  }
}

When the button is pressed, or onDisappear happens, then the cancellation happens:

func cancel() {
    numberTask?.cancel()
    numberTask = nil
}

Resulting in these logs:

2023-06-30 12:21:30 numberFlow onEach: 0
2023-06-30 12:21:31 numberFlow onEach: 1
2023-06-30 12:21:32 numberFlow onEach: 2
2023-06-30 12:21:33 numberFlow onCompletion: kotlinx.coroutines.JobCancellationException: …

Automatic

In order for SwiftUI to automatically cancel, the screen needs to be fully closed. In the Playground screen, it is achieved by opening a new "nested" screen and then closing it:

In order to achieve this automatic cancellation, the numberTask cannot be created, because nested Tasks are not cancelled by the parent (no structured concurrency). When the async function is executed directly:

func listenToNumbers() async {
    let sequence =
        asyncSequence(for: viewModel.numberFlow)
    for try await number in sequence {
      self.number = number.intValue
    }
}

Then SwiftUI is in control of the Task, thus allowing automatic cancellation:

var body: some View {
    ...
}.task {
    await observableModel.listenToNumbers()
}

No additional callbacks are required (like onDisappear), because SwiftUI takes care of everything. When the class calling the coroutine is de-initialized, then the coroutine is cancelled:

2023-03-24 12:28:13 init 0x00006000024be000
2023-03-24 12:28:13 numberFlow onEach: 0
2023-03-24 12:28:14 numberFlow onEach: 1
2023-03-24 12:28:15 numberFlow onEach: 2
2023-03-24 12:28:16 numberFlow onEach: 3
2023-03-24 12:28:16 deinit 0x00006000024be000
2023-03-24 12:28:16 numberFlow onCompletion: kotlinx.coroutines.JobCancellationException: ...

Cancellation summary

I won't go into depth into this topic, because there are better resources for it. Basically correct cancellation results in:

• Freeing up the users resources like data transfer
• Avoiding Memory leaks
• Fewer unnecessary API calls

Ending

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:

1. Using the Native programming language, (e.g. Swift implementation that is passed in from the iOS platform to the shared code)
2. 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:

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.

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.

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

Keeping Kotlin Multiplatform tests clean while using the standard kotlin.test framework

AKJAWAleksander Jaworski

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.

Mocks Aren’t Stubs

Explaining the difference between Mock Objects and Stubs (together with other forms of Test Double). Also the difference between classical and mockist styles of unit testing.

martinfowler.comMartin Fowler

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).

bliki: TestDouble

Test Double is generic term for fakes, mocks, stubs, dummies and spies.

martinfowler.comMartin Fowler

Mocking is not practical — Use fakes

This article talks about the benefits fakes provide over mocks in testing software. Fakes lead to better API and readable/robust tests.

MediumPravin Sonawane

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.

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.

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:

bliki: ContractTest

Test Doubles avoid non-deterministic errors, but you need Contract Tests to ensure they remain consistent with the real services.

martinfowler.comMartin Fowler

Outside-In TDD - Search Functionality 6 (The Contract Tests)

In this video, we are leveraging a fake test-double to emerge contract tests that we could use later on to make sure that every new shipping implementation a...

YouTube

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

Unit Tests are focused on small parts of a code-base, defined in regular programming tools, and fast. There is disagreement on whether units should be solitary or sociable.

martinfowler.comMartin Fowler

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.

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.

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!

I've been a big fan of testing ever since I was introduced to it, most of the code I write is written with Test Driven Development. Having a good test suite helps with catching regressions / bugs a lot faster, and gives developers more confidence when merging / releasing their product.

That's why I encourage / expect my teammates to write tests for the important parts of the code (In our case, it's the shared KMM codebase for Android and iOS). When reviewing PRs, I sometimes see testing approaches which could be better, in this series, I'll share my recommendations for improving your tests.

A lot of these tips are related with each other, and sometimes they complement each other. However, I'll try to keep every point straight forward and make it easy to understand without dragging additional information into them.

This series was completed as part of my Members only content, here's the full list of topics which I wrote about:

These parts are available here:

If you're interested and like have access to them subscribe to my newsletter or sign up right here on my website (No passwords required).

Note: All the examples here, are written with Kotlin, however, I believe that the tips presented here, could be applied in most modern programming languages.

1. Not using the Arrange Act Assert (Triple A) Convention

Often times I see developers group the test code like they would on production code, i.e. based on what logic is related. In tests, however, there exists a common convention / pattern which splits the code into three distinct groups separated by a new line:

@Test
fun something() {
   givenApiReturnsSuccess() // arrange / set up
   
   val result = systemUnderTest.fetchDetail("1") // act / action
   
   assertEquals(Detail("1"), result) // assert / verify
}

These groups don't have to be one-liners, but it would be best to keep the Act group as small as possible (preferably one line). Keeping the AAA convention in all the tests helps with understanding:

• What set-up is needed
• What action is taken to achieve the outcome
• What is verified by the test.

2. Not creating helper functions

Tests almost always include some boilerplate, be it set up code, verification and sometimes even the action. Helper functions help address this issue

• Help with test readability by hiding irrelevant implementation details. With a readable test, it is much easier to understand what the system under test does
• Protects from code changes, e.g: instead of changing a parameter in every test case, it only needs to be changed in the helper function

Take a look at the following test:

@Test
fun storageItemsAreReturnedWithTimestamp() {
    val item1 = StorageItem(id = 1, name = "")
    val item2 = StorageItem(id = 2, name = "")
    fakeStorage.items = listOf(item1, item2)
    val timestamp = 123
    fakeTimestampProvider.value = timestamp

    val result = systemUnderTest.fetchFromStorage()

    val result1 = result.first { item -> item.id == 1 }
    assertEquals(timestamp, result1.timestamp)
    val result2 = result.first { item -> item.id == 2 }
    assertEquals(timestamp, result2.timestamp)
}

In this example, we have a systemUnderTest (SUT) which retrieves items from a storage and adds the current timestamp to them. However, the code includes some boilerplate that will most likely be present in other test cases, an improved version could look like this:

@Test
fun storageItemsAreReturnedWithTimestamp() {
    fakeStorage.items = listOf(createStorageItem(1), createStorageItem(2))
    val timestamp = 123
    fakeTimestampProvider.value = timestamp

    val result = systemUnderTest.fetchFromStorage()

    verifyItemHasCorrectTimestamp(result, id = 1, expectedTimestamp = timestamp)
    verifyItemHasCorrectTimestamp(result, id = 2, expectedTimestamp = timestamp)
}

private fun createStorageItem(id: String): StorageItem {
    return StorageItem(id = 1, name = "")
}

private fun verifyItemHasCorrectTimestamp(
    items: List<Item>,
    id: Int,
    expectedTimestamp: Int
) {
    val item = result.first { item -> item.id == id }
    assertEquals(expectedTimestamp, item.timestamp)
}

The above code is more verbose judging just by the number of lines, however the more test cases we have, the more we benefit from such helper functions.

Other examples:

fun givenApiReturnsSuccess(id: String, result: Detail) {
   mockk { fetchDetail(id) } returns result
}

fun givenDatabaseContainsItemWithId(id: String) {
   val item = ComplexItem(id = id, name = "", timestamp = 0L)
   fakeStorage.items = listOf(item)
}

fun executeAndAdvanceTime() {
   systemUnderTest.execute()
   advanceTimeBy(milliseconds = 2000)
}

One additional example I like to use is a "testCase" helper function. From time to time you will have a behavior which requires a lot of tests, with slightly different set-up / assertions:

@Test
fun `Timestamp of 0 becomes "00 00 000"`() {
    formatTestCase(0, "00:00:000")
}

@Test
fun `Timestamp of 500 becomes "00 00 500"`() {
    formatTestCase(500, "00:00:500")
}

@Test
fun `Timestamp of 59999 becomes "00 59 999"`() {
    formatTestCase(59999, "00:59:999")
}

private fun formatTestCase(
    timestamp: Long,
    expectedString: String
) {
    val result = systemUnderTest.format(timestamp)

    result shouldBe expectedString
}

These types of helper functions can be even more complex, as long as they help with the readability and maintainability of the test.

However, there is one important point I'd like to address before going to the next point. Don't force out these helper functions, as the name suggests, they should help you and not make your life harder.

There are cases where it's better to leave the code inline without any helper functions. Like with everything in programming, this knowledge comes with experience, as long as the helper functions make the tests easier to understand and maintain, go for it.

3. Unnecessary set up / Arrangement

Sometimes when creating a new test case, we copy an existing one, and change it to fit a new test case. When doing, so we sometimes copy more than we need, tests should only contain code which is relevant to that particular test case. More code in the tests, means it will be harder to understand, and sometimes even confuse the reader because some parts are irrelevant.

Imagine, we have a function which always retrieves something from a database cache (the function never calls the API):

@Test
fun databaseIsUsedToRetrieveCachedValue() {
   val item = Item(...)
   givenDatabaseContainsItem(item)
   givenApiReturnsSuccess(item)
   
   val result = systemUnderTest.fetchFromStorage()
   
   assertEquals(item, result)
}

The above test is confusing for two reasons: looking at the set-up we can take a guess that the action uses both the database and the API, additional confusion is added, because we're not sure if the item comes from the database or from the API. Only inspecting / debugging the production code would give us the answer.

Keeping our test code focused on only the relevant things will make our test cases easier to understand. In this case, removing the givenApiReturnsSuccess would reduce the confusion by a lot:

@Test
fun databaseIsUsedToRetrieveCachedValue() {
   val item = Item(...)
   givenDatabaseContainsItem(item)
   
   val result = systemUnderTest.fetchFromStorage()
   
   assertEquals(item, result)
}

4. Testing multiple things instead of focusing on one

Most tests should focus on one particular behavior of the system under test. However, sometimes tests are created in ways that verify multiple things. At first sight it might seem beneficial, because less code should make it easier to understand, right?

@Test
fun stateAfterInitializingIsCorrect() {
    givenApiReturns(listOf(1, 2, 3))

    systemUnderTest.initialize()
    
    assertEquals(false, systemUnderTest.isLoading)
    assertEquals(listOf(), systemUnderTest.selectedItems)
    assertEquals(listOf(1, 2, 3), systemUnderTest.items)
}

Well not exactly, the problems arise, when the tests stop passing. Then you have to first look at the test code, and if that doesn't suffice you'll have to debug it, which is not ideal... That's why it's better to break it up into more test cases:

@Test
fun isLoadingIsFalseAfterInitializing() {
    systemUnderTest.initialize()
    
    assertEquals(false, systemUnderTest.isLoading)
}

@Test
fun selectedItemsAreEmptyAfterInitializing() {
    systemUnderTest.initialize()
    
    assertEquals(listOf(), systemUnderTest.selectedItems)
}

@Test
fun itemsAreRetrievedFromTheApiOnInitialization() {
    givenApiReturns(listOf(1, 2, 3))
    
    systemUnderTest.initialize()
    
    assertEquals(listOf(1, 2, 3), systemUnderTest.items)
}

Having separate test cases for the verification involves more code, but the tests should be easier to understand, because they focus only on one aspect of the SUT. The benefit of that is, that if the test fails, the name should be more than enough to understand what's wrong with the SUT (As long as the test name is descriptive...)

It's important to understand and separate things that are different in each test case.

5. Not using explicit set-up values in tests, but depending on default or global values

Tests should be as explicit as possible (while not hindering its readability).

Sometimes when we define a test double, we might be tempted to put default values in order to reduce the amount of code we need to write in our tests. In my opinion this is not the best approach, test doubles should not have hidden values which make the tests pass, takes this for example:

interface Config {
    val numberOfRepetitions: Int
}

class FakeConfig : Config {
    override var numberOfRepetitions: Int = 3
}

class SomeTest {
    // ...

    @Test
    fun apiCallOnFailShouldBeRepeatedTheCorrectAmountOfTimes() {
        mockApi.shouldReturnError()

        systemUnderTest.fetch()

        assertEquals(3, mockApi.fetchCallCount)
    }
}

In the example above, we have a hidden default value in inside FakeConfig. This value is not set explicitly in the tests, so without delving into the implementation details, we won't know where the magic number 3 comes from. Of course, we could rename the test to be even more wordy, but it's better to let the test code speak for itself:

class FakeConfig : Config {
    override var numberOfRepetitions: Int = 0
}

class SomeTest {
    ...

    @Test
    fun apiCallOnFailShouldBeRepeatedTheCorrectAmountOfTimes() {
        mockApi.shouldReturnError()
        val repetitionAmount = 3
        fakeConfig.numberOfRepetitions = repetitionAmount

        systemUnderTest.fetch()

        assertEquals(repetitionAmount, mockApi.fetchCallCount)
    }
}

In my opinion, the above test is much easier to understand and the systemUnderTest behavior is much more explicit, even if it takes up more lines.

If you'd like to see more:

All the code described in the article is available here

GitHub - AKJAW/ApolloDataBuilders

Contribute to AKJAW/ApolloDataBuilders development by creating an account on GitHub.

GitHubAKJAW

API

The GraphQL API used for this article is called Countries and returns simple information about continents, countries and languages.

GitHub - trevorblades/countries: 🌎 Public GraphQL API for information about countries

🌎 Public GraphQL API for information about countries - GitHub - trevorblades/countries: 🌎 Public GraphQL API for information about countries

GitHubtrevorblades

Sandbox: https://studio.apollographql.com/public/countries/explorer

The Query we will be testing:

query Country($code: ID!) {
    country(code: $code) {
        name
        languages {
            ...LanguageFragment
        }
    }
}

fragment LanguageFragment on Language {
    name
}

Response for CountryQuery("GB"):

{
  "data": {
    "country": {
      "name": "United Kingdom",
      "languages": [
        {
          "name": "English"
        }
      ]
    }
  }
}

Apollo

Based on the query above, Apollo generates something along these lines:

public data class CountryQuery(
  public val code: String,
) : Query<CountryQuery.Data> {

  public data class Data(
    public val country: Country?,
  ) : Query.Data

  public data class Country(
    public val name: String,
    public val languages: List<Language>,
  )

  public data class Language(
    public val __typename: String,
    public val languageFragment: LanguageFragment,
  )
}

public data class LanguageFragment(
  public val name: String?,
) : Fragment.Data

The Country data class can be instantiated manually

CountryQuery.Country(
    name = "United Kingdom",
    languages = listOf(
        CountryQuery.Language(
            __typename = "Language",
            languageFragment = LanguageFragment("English")
        )
    )
)

However, this involves a lot of boilerplate because there are no default values. Additionally, whenever the query changes the compilation will break (all constructor calls need to be updated)

To mitigate this, Apollo provides Data builders, which provides a nice DSL for the class creation.

Data Builders

The main benefit of builders is that they provide default values for any known types (Unknown custom scalars will be explained later) and they don't care about fragments. Meaning that they don't break so easily when the query is updated.

Unit tests

Usually the Query data will be converted to a domain data structure, in this case it could be:

data class Country(
    val name: String,
    val language: List<Language>,
)

data class Language(
    val name: String
)

Given we have a correctly implemented converter, we could have a test that verifies that the country name is correctly converted:

@Test
fun `The country name is correctly converted`() {
    val schema = CountryQuery.Data {
        country = buildCountry {
            name = "Poland"
        }
    }.country!!

    val result = systemUnderTest.convert(schema)

    result.name shouldBe "Poland"
}

The data builder creates the whole Query "Data" that's why we need to access the nullable .country!! at the end.

To avoid repeating the same boilerplate every time, a helper function can be extracted:

@Test
fun `The country name is correctly converted`() {
    val schema = createCountry {
        name = "Poland"
    }

    val result = systemUnderTest.convert(schema)

    result.name shouldBe "Poland"
}

private fun createCountry(
    block: CountryBuilder.() -> Unit
): CountryQuery.Country =
    CountryQuery.Data {
        country = buildCountry {
            block()
        }
    }.country!!

Thanks to this, the boilerplate is mitigated while still allowing the full usage like:

createCountry {
    name = "Poland"
    languages = listOf(
        buildLanguage {
            name = "Polish"
        },
    )
}

The full converter test is available in the repository.

Custom Scalars

When the data builder encounters a field which was not set inside the DSL, it will use a Resolver to put a default value there. For numbers, it starts at 0 and increments every time it is used, for strings the field name is used.

However, sometimes the GraphQL schema contains a type which Apollo cannot resolve

"""
A custom scalar for presentation purposes
"""
scalar CustomScalar

query CountryWithCustomScalar {
    country(code: "GB") {
        name
        customScalar
    }
}

Because Apollo does not know what to do with this type, an error will be thrown if it is not set in the DSL

java.lang.IllegalStateException: Don't know how to instantiate leaf CustomScalar

To help with this, we can define our own resolver

class MyFakeResolver : FakeResolver {

    private val delegate = DefaultFakeResolver(__Schema.all)

    override fun resolveLeaf(context: FakeResolverContext): Any {
        return if (context.mergedField.type.leafType().name == "CustomScalar") {
            return ""
        } else {
            delegate.resolveLeaf(context)
        }
    }

    override fun resolveListSize(context: FakeResolverContext): Int {
        return delegate.resolveListSize(context)
    }

    override fun resolveMaybeNull(context: FakeResolverContext): Boolean {
        return delegate.resolveMaybeNull(context)
    }

    override fun resolveTypename(context: FakeResolverContext): String {
        return delegate.resolveTypename(context)
    }
}

This resolver uses an empty string for every CustomScalar field and delegates to the default behavior in every other case.

Verification test:

@Test
fun `Does not throw exception with resolver`() {
    shouldNotThrowAny {
        CountryWithCustomScalarQuery.Data(MyFakeResolver()) {
            country = buildCountry {
                name = "Custom"
            }
        }
    }
}

@Test
fun `Throws an exception without resolver`() {
    shouldThrow<IllegalStateException> {
        CountryWithCustomScalarQuery.Data {
            country = buildCountry {
                name = "Custom"
            }
        }
    }
}

The Resolver and verification test can be found in the repository.

Integration / UI tests

In cases where we want to test our logic along with the network layer, for example through Mock HttpInterceptor or MockServerHandler. The data builder can be used to provide the JSON string.

object Responses {

// {"data":{"country":{"name":"United Kingdom","languages":[{"__typename":"Language","name":"English"}]}}}
    val SUCCESS =
        CountryQuery.Data {
            country = buildCountry {
                name = "United Kingdom"
                languages = listOf(
                    buildLanguage {
                        name = "English"
                    }
                )
            }
        }.toDataJson()

// {"data":{"country":null}}
    val SUCCESS_NULL_SCHEMA = CountryQuery.Data {
        country = null
    }.toDataJson()

    private fun Operation.Data.toDataJson() =
        """{"data":${this.toJsonString()}}"""

    private fun CountryQuery.Data.toDataJsonKmm() =
        """{"data":${CountryQuery_ResponseAdapter.Data.obj().toJsonString(this)}}"""
}

The main benefit of using the builder here is that the JSON will always be up-to-date with the latest Query changes and is more resilient to parsing issues.

Sidenote: the JVM Apollo implementation provides a generic Operation.Data.toJsonString() function however on KMM, every query requires its own function (like in the snippet above).

The full integration test code is available here.

Besides Apollo I've also covered Mocking Ktor network requests and In-Memory SQLDelight testing which might interest you. Additionally, I have an article series about what testing mistakes you should avoid if you want to improve your test suite.

GraphQL testing course

Recently I had the pleasure of recording a couple of GraphQL testing course videos which will be a part of the KotlinTesting Unit testing course. Unfortunately, the course is currently only available in Polish, but we're planning to expand it to a more world-wide audience. If you're interested in the English version or have any questions, please let me know.

In the course, I discuss things like:

• How Apollo can be used for building apps using a GraphQL API
• Pros and Cons of different data creation Manual instantiation vs Builders
• Sanity tests for quick prototyping and learning how an API works
• Verifying the system correctness through integration tests which include the network layer
• Different ways of creating Integration tests in Apollo

All the course videos are recorded using a Test Driven Development approach which some might find interesting, along the way I also share some information about my approach to testing.

More information about the course can be found here:

Webinar | Praktycznie o testach na Androidzie

Praktycznie o testach na Androidzie

I'm using the non-modal commit interface, however a lot of the stuff described here should work in the modal interface too.

Changelists - Temporarily saving for the next commit

Sometimes you're deep in your code and you notice something that can be improved, or something that needs to be added. But you want to keep you commits granular, more focused on a single thing. To help with this I use Changelists:

• Default changelists (Changes) - The work that I want to commit now
• next changelist - Stuff I want to commit at a later point, it is usually a TODO comment, but sometimes it's even initial code changes. However beware, that keeping refactor changes in the next changelist can break compilation, because of broken imports split into two changelists
• remove changelist - Temporary changes which should not be commited. For example, some experiments with gradle, code, or some hacky workarounds to fix some temporary issues.

Shelf - Permamently saving something for later (Like stashing but in the IDE)

When you're in the middle of working on your code, but have to quickly look something up on the main branch, or change to another, shelving the changes might be your best option. The shelf works like the built in git stash, but it is friendlier to work with, it's also simmilair to the next changelist, but more permament.

Keep in mind that they are not saved in the repository and only in the .idea directory, so they can be lost.

File history

Sometines you need to see what changes happened to a file, this is where the Show History function can be used. It lists all of the commits which included changes for this file.

Honorable mentions:

Resolve Git conflicts | IntelliJ IDEA

IntelliJ IDEA Help

Investigate changes in Git repository | IntelliJ IDEA

IntelliJ IDEA Help

Generic tips

If you'd like to improve your overall IDE workflow, checkout this article

17 IntelliJ IDEA/Android Studio shortcuts and features for a faster development cycle

A list of IDE shortcuts and features that I use on an almost daily basis

AKJAWAleksander Jaworski

Command line

TL;DR

My build is broken and I don't know why, get me out of here I don't care about losing my progress:  git reset HEAD --hard

I needed to quickly change branches, but I forgot what branch I was on earlier:  git switch -

I want to make a complex commit but I only have the command line: git add -i

My last commit has some issues (code / commit message): git commit --amend

I don't want to write so much: git config --global alias.<alias_name> "<alias_command>"

User friendly file staging

git add -i interactive mode which allows adding, removing, diffing, patching and more

Interactive mode provides a much more user friendly staging management. If you don't have your IDE open and need to do a quick commit, add -i might be your best option. Besides adding there are a lot more useful features, feel free to explore them.

Undoing current or previous work

git reset HEAD - reset staging "I added some file to staging by accident, let me redo it"

git reset HEAD --hard - reset all staged and unstaged files "I want to throw away all my current changes and start from scratch"

git reset HEAD~ - undo the last commit and reset staging but keep them them in the working directory "I want to clean up something in the last commit / I committed to the wrong branch and want to keep this change for later"

git reset HEAD~ --hard - remove the last commit "The last commit makes no sense, let me throw it away"

* Beware that resetting something that was already pushed might create conflicts if someone else is working with that branch. If you are sure you're the only one, feel free to force push.

** HEAD~ allows specifying a number, for example: git reset HEAD~3 --hard would remove the last 3 commits

Git - Reset Demystified

Reset Demystified

Looking at the commit history / Searching for something

git log -S 'code content' - search through commits based on code content

git log -p -S 'code content' - the same but also shows the commit diff

git log --grep='commit message content' - search through commits based on the commit message

git log --pretty=oneline - shows a shortened log

Rewriting history

git commit --amend - "I want to clean up the last commit"

git rebase -i HEAD~n - rebase the last n commits.

Interactive rebase is a powerful tool for cleaning up the commit history. Here are my most used features:

• r, reword - "I want to clean up a commit message further into history"
• e, edit - "I want to clean up some code further into history"
• s, squash - "The fix took 5 commits, but it would be cleaner as one. let me squash them into one singular commit"
• d, drop - "Some previous commit is irrelevant, and it is not referenced in newer commits, I can safely remove it"

* Beware that rebasing or amending changes the commit hashes, which can cause conflicts if the work was already pushed. If you are sure you're the only one working on that branch, feel free to force push.

Git - Rewriting History

Rewriting History

Squash commits into one with Git

A nice way to group some changes together, especially before sharing them with others.

Internal PointersMonocasual Laboratories

A Branch in Time (a story about revision histories)

A talk about software maintainability and the power of our revision histories. I gave this talk at Brighton Ruby and RubyConf in 2018 as well as RubyConf AU in 2019.

tekin.co.ukTekin Süleyman

Telling stories through your commits

A short talk sharing the key practices to make your commit history usefully document your code

Cherry picking

There are situation where:

• You or a colleague did a fix for an issue that's bothering you, but the fix is on a branch which can't be yet merged
• There is some really nasty merge conflicts, god knows why, but the problematic commit is in a middle of the PR

This is where you can cherry-pick one or multiple commits onto a different branch. I use it rarely, but when I need it, it is really helpful.

What Does Git Cherry Pick Do, And When Should You Use It?

git cherry-pick is a simple but powerful tool that allows you to selectively transfer commits from one branch to another. You can use it when you don’t want to merge an entire branch into master, but would still like to include changes from a feature branch.

How-To GeekAnthony Heddings

Git Cherry Pick | Atlassian Git Tutorial

Learn about git cherry-pick, including usage, benefits, and examples using the cherry pick command.

AtlassianAtlassian

Branch navigation

• git checkout <existing-branch>
• git switch <existing-branch>
• git checkout -b <new-branch> - create branch and check out
• git switch -c <new-branch> - create branch and check out
• "git switch -" - checkout as previous branch

Switch is basically a newer version of checkout, but with a less action-packed and confusing functionality.

Git 2.23 Adds Switch and Restore Commands

Git 2.23 introduces two new commands meant to replace two common uses of git checkout: git switch to switch to a new branch after creating it if necessary, and git restore to restore changes from a given commit.

InfoQSergio De Simone

Aliases

git config --get-regexp alias - listing existing aliases

git config --global alias.<alias_name> "<alias_command>" - setting an alias

My aliases:

alias.ss status -s
alias.ai add -i
alias.logone log --pretty=oneline
alias.s- switch -
alias.sc switch -c

Git hooks

Git hooks are a powerful tool for automating some part of your workflow, in my case it usually is:

• Formatting code using a linter before committing (pre-commit hook)
• Ensuring that the commit message is formatted according to Conventional Commits guidelines (commit-msg hook)

My workflow

Is a mix of both IDE and the command line.

IDE:

• Managing changed files
• Diffing / Viewing changes
• Committing
• Resolving conflicts

Command line:

• Pushing and Force pushing
• Pulling and Fetching
• Cleaning up commit history
• Changing and deleting branches
• Searching through commits
• Resetting the workspace or the last commit
• Cherry picking

Git book

Most of my knowledge about how git works comes from the free Pro Git book. It contains a lot details, but you can focus only on stuff you need and then use it later as a reference when working with git.

Git - Book

Book

Course

If you'd like to improve your git hygiene, or learn about more outside-coding processes, checkout the Android Next Level course which I'm a co-author of.

Android Next Level

A course about processes outside of coding like: CI/CD, scaling your project, good git hygiene or how to cooperate with your teammates

AKJAWAleksander Jaworski

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 😁

Databases are an integral part of almost every mobile application, in this post I'll cover how to use SQLDelight to provide an in-memory database for test environments.

Why use in-memory databases?

Tests should be predictable, and the execution order of the tests should change the test results. If we were to use a real database for tests, then this database would need to be cleared before (or after) every test case execution.

Even if a real database is cleared between tests, it is not guaranteed.  Sometimes the test can crash, or  be aborted, this can result in the database being persisted between test runs, which might change the outcome of the next test.

In-memory databases have the advantage of being discarded after every test case, so the next test execution should have no way of re-using an old in-memory database instance.

App features

The application shown in this article is available on GitHub. It has three features which we will be testing:

• Adding new items
• Updating existing items
• Showing the list of items

The functionality is pretty basic, but it is enough to show how you can verify correct app behavior using an in-memory database.

The App Architecture

I tried keeping the code as simple as possible because it is not a main focus of the article. Basically, there are 3 UseCases corresponding to the app features:

• GetTimestampItems
• AddTimestampItem
• UpdateTimestampItem

The basic idea is that the Add and Update UseCases insert / update items in the database with the current timestamp:

internal class AddTimestampItem(
    private val tableQueries: TableQueries,
    private val timestampProvider: TimestampProvider,
) {

    suspend fun execute() = withContext(Dispatchers.Default) {
        tableQueries.insertItem(timestampProvider.getTimestampMilliseconds())
    }
}

Getting the items boils down to retrieving them from the database and converting them to a more UI friendly format.

internal class GetTimestampItems(
    private val tableQueries: TableQueries,
) {

    fun execute(): Flow<List<TimestampItem>> =
        tableQueries.selectAll()
            .asFlow()
            .mapToList()
            .map { items -> ... }
	
    ...
}

The two important things in this article is TableQueries and TimestampProvider. The TableQueries is an object that is generated by SQLDelight, in tests we will replace the production database with an in-memory one. TimestampProvider returns the current system timestamp, but in tests we will replace it with a test doubles that allows controlling the returned value (relying on real system time makes the test unpredictable).

Database Schema

CREATE TABLE TimestampItemEntity (
    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    time INTEGER NOT NULL,
    version INTEGER AS Int NOT NULL
);

selectAll:
SELECT * FROM TimestampItemEntity;

insertItem:
INSERT OR IGNORE INTO TimestampItemEntity(time, version)
VALUES (?, 1);

updateTimestamp:
UPDATE TimestampItemEntity SET time = ?, version = version + 1 WHERE id = ?;

Every item has:

• An auto-generated ID
• The timestamp which will be shown in the UI
• A version which is increased when the item is updated

Integration tests

Before diving into the tests, I just want to point out that all tests use Koin for replacing the production dependencies and retrieving classes used in the test.

In this article I won't get into the details of using Koin in tests, if  you want to learn more about this topic I invite you to my other article focused around this topic. All the test code is also available in the GitHub Repository if you want to just look at the source code.

Testing added items

class AddTimestampItemTest : KoinComponent {

    private val tableQueries: TableQueries by inject()
    private val mockTimestampProvider: MockTimestampProvider by inject()
    private val systemUnderTest: AddTimestampItem by inject()

    @BeforeTest
    fun setUp() {
        startTestKoin()
    }

    @AfterTest
    fun tearDown() {
        stopTestKoin()
    }

    @Test
    fun `Added item uses the current timestamp as the name`() = runTest {
        mockTimestampProvider.setNextTimestamp(123)

        systemUnderTest.execute()

        val result = tableQueries.selectAll().executeAsList().first()
        result.time shouldBe 123
    }

    @Test
    fun `Added item has a version equal to 1`() = runTest {
        systemUnderTest.execute()

        val result = tableQueries.selectAll().executeAsList().first()
        result.version shouldBe 1
    }
}

The test cases set a predefined value for the TimestampProvider, then invoke the UseCase and verifies that the database is in the correct state.

TimestampProvider test double

interface TimestampProvider {

    fun getTimestampMilliseconds(): Long
}

class MockTimestampProvider : TimestampProvider {
    private var timestampValues: MutableList<Long> = mutableListOf()
    private var lastValue: Long = 0

    fun setNextTimestamp(value: Long) {
        timestampValues.add(value)
    }

    override fun getTimestampMilliseconds(): Long {
        lastValue = timestampValues.firstOrNull() ?: lastValue
        timestampValues.removeFirstOrNull()
        return lastValue
    }
}

MockTimestampProvider allows setting predefined values that are returned when the  getTimestampMilliseconds() is called. The reason for using a "Queue" for the values will be explained later, but it has to do iOS UI testing.

Setting up the in-memory database driver

The in-memory driver creation is done by an expect-actual function:

// commonMain
expect fun createInMemorySqlDriver(): SqlDriver

The Android in-memory function is pretty simple because it just uses the JVM JDBC driver:

// androidMain
actual fun createInMemorySqlDriver(): SqlDriver {
    val driver: SqlDriver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
    AppDatabase.Schema.create(driver)
    return driver
}

For iOS, it gets more complicated:

// iosMain
private var index = 0

actual fun createInMemorySqlDriver(): SqlDriver {
    index++
    val schema = AppDatabase.Schema
    return NativeSqliteDriver(
        DatabaseConfiguration(
            name = "test-$index.db",
            version = schema.version,
            create = { connection ->
                wrapConnection(connection) { schema.create(it) }
            },
            upgrade = { connection, oldVersion, newVersion ->
                wrapConnection(connection) { 
                    schema.migrate(it, oldVersion, newVersion) 
                }
            },
            inMemory = true
        )
    )
}

The base function was created by Touchlab in their KaMPKit starter. I just added the index variable, so the database name is different on each invocation. Without this, the same database is reused in each test case, making the tests unpredictable (running order changes the test outcome).

The createInMemorySqlDriver() function is then used by Koin to introduce the correct database driver to the dependency graph:

val testModule = module {
    single { MockTimestampProvider() }
    single<TimestampProvider> { get<MockTimestampProvider>() }
    single<SqlDriver> { createInMemorySqlDriver() }
}

Testing items retrieval

class GetTimestampItemsTest : KoinComponent {

    private val tableQueries: TableQueries by inject()
    private val systemUnderTest: GetTimestampItems by inject()

    @BeforeTest
    fun setUp() {
        startTestKoin()
    }

    @AfterTest
    fun tearDown() {
        stopTestKoin()
    }

    @Test
    fun `The date is correctly mapped`() = runTest {
        tableQueries.insertItem(1652980264000)
        tableQueries.insertItem(1652980224000)

        val result = systemUnderTest.execute().first()

        assertSoftly {
            result shouldHaveSize 2
            result[0].name shouldBe "2022-05-19T17:11:04"
            result[1].name shouldBe "2022-05-19T17:10:24"
        }
    }
}

In the set-up phase, two items are inserted to the database, then the UseCase retrieves the items and the test case verifies that the timestamp is correctly formatted.

Android UI Tests

Setting up the in-memory database driver

The significant difference with the in-memory database driver for Android UI tests is that the Android driver has to be used:

AndroidSqliteDriver(
    schema = AppDatabase.Schema,
    context = get(),
    name = null,
)

The Android OS does not support the JVM database driver, so the normal AndroidSqliteDriver is required, however passing null as the name of the database, makes the database an in-memory one:

/**
* @param name Name of the database file, or null for an in-memory database.
* @return This
*/
@NonNull
public Builder name(@Nullable String name) {
    mName = name;
    return this;
}

The test

The UI test cases focus on adding a new item and updating an existing one. As I stated previously, Koin usage for testing is covered in my other article.

class MatchScreenTest : KoinComponent {

    @get:Rule
    val composeTestRule = createAndroidComposeRule<MainActivity>()
    val mockTimestampProvider: MockTimestampProvider by inject()

    @Before
    fun setUp() {
        ...
    }

    @Test
    fun addingAnItemPopulatesTheListWithCurrentTimestamp() {
        mockTimestampProvider.setNextTimestamp(1653823433000)

        composeTestRule.onNodeWithText("Add").performClick()

        composeTestRule.waitUntilCatching(1000) {
            composeTestRule.onNodeWithText("2022-05-29T11:23:53").assertIsDisplayed()
        }
    }

    @Test
    fun refreshingAnItemUpdatesTheNameWithCurrentTimestamp() {
        mockTimestampProvider.setNextTimestamp(0)
        composeTestRule.onNodeWithText("Add").performClick()
        mockTimestampProvider.setNextTimestamp(1653823433000)

        composeTestRule.onNodeWithContentDescription("Refresh").performClick()

        composeTestRule.waitUntilCatching(1000) {
            composeTestRule.onNodeWithText("2022-05-29T11:23:53").assertIsDisplayed()
        }
    }

    private fun ComposeTestRule.waitUntilCatching(
        timeoutMillis: Long, assertion: () -> Unit
    ) = ...
}

The test cases set a pre-defined value for the TimestampProvider just as the integration test did, then it executes an action and verifies if the correct UI text is displayed.

iOS UI Tests

Setting up the in-memory database driver

The same createInMemorySqlDriver() can be used just like in the integration tests.

Setting up dependency injection

Using Koin in iOS UI testing is not as straight forward as for Android, so I'll quickly run through the steps.

fun setUpKoinForTesting() {
    val modules = listOf(
        *sharedModules,
        module {
            single<SqlDriver> { createInMemorySqlDriver() }
            single { MockTimestampProvider() }
            single<TimestampProvider> { get<MockTimestampProvider>() }
        }
    )
    unloadKoinModules(modules)
    loadKoinModules(modules)
}

The setUpKoinForTesting() function needs to be called between every iOS test case to "reload" the database.

object TestDoubleRetriever : KoinComponent {

    val mockTimestampProvider: MockTimestampProvider
        get() = get()
}

TestDoubleRetriever is just a helper object to make test double retrieval easier on iOS.

The test

The main difference between Android and iOS UI testing is that on iOS, we are not allowed to touch production code inside the test. So, calling setUpKoinForTesting() in the setUp function will not work.

The iOS testing framework allows sending so-called launch arguments:

app.launchArguments = ["enable-testing", "-mock-time", "0,1653823433000"]
app.launch()

These values can be used in the production code to set up the test doubles to the correct state:

#if DEBUG
if CommandLine.arguments.contains("enable-testing") {
    SetUpKoinForTestingKt.setUpKoinForTesting()
    UserDefaults.standard.string(forKey: "mock-time")?
        .split(separator: ",")
        .map { timeString in
            Int64(timeString)
        }
        .compactMap { $0 }
        .forEach { time in
            TestDoubleRetriever.shared.mockTimestampProvider
                .setNextTimestamp(value: time)
        }
}
#endif

The test cases are pretty much the same as for the Android app, just with a different test double set up:

class KaMPKitiOSUITests: XCTestCase {
    let app = XCUIApplication()

    func testAddingAnItemPopulatesTheListWithCurrentTimestamp() {
        app.launchArguments = ["enable-testing", "-mock-time", "1653823433000"]
        app.launch()
        
        app.staticTexts["Add"].tap()

        let itemExists = app.staticTexts["2022-05-29T11:23:53"].exists
        XCTAssert(itemExists)
    }
    
    func testRefreshingAnItemUpdatesTheNameWithCurrentTimestamp() {
        app.launchArguments = ["enable-testing", "-mock-time", "0,1653823433000"]
        app.launch()
        app.staticTexts["Add"].tap()
        
        app.buttons["Refresh"].tap()

        let itemExists = app.staticTexts["2022-05-29T11:23:53"].exists
        XCTAssert(itemExists)
    }
}

As you can see, the TimestampProvider values have to be defined before the app even launches. This limitation enforces that the Kotlin test doubles have to provide a way of defining multiple return values beforehand, and that is the reason for the "Queue" in the MockTimestampProvider.

Summary

I hope that this simple example shows how SQLDelight in-memory drivers can be helpful when testing the application.

Besides SQLDelight I've also covered Mocking Ktor network requests and Apollo GraphQL fake networking which might interest you. Additionally, I have an article series about what testing mistakes you should avoid if you want to improve your test suite.

The UI tests in action

Recently I reactivated my old project Timi which I used to learn Compose. This time my focus is on learning the iOS side of Kotlin Multiplatform, I'm hoping that this experience will help me better understand my colleagues on the other platform.

Working on a smaller project also allows for more experiments, in this project I'll try to share as much code as possible, and see how that integrates on both mobile platforms.

In this article, I'll share my experience making a Kotlin Multiplatform app from an Android only codebase. If you're interested in the commits of this process, they're available in the GitHub repository (starting from the 2022 commits).

The modularization used for this project is explained more in-depth in my Modularizing a Kotlin Multiplatform Mobile Project.

Adding Kotlin Multiplatform and iOS to the codebase

1. My first step was creating a new playground project based on the KaMPKit starter. I removed everything I didn't need and added a simple class resembling one feature of Timi (A stopwatch). I used this class on both Android and iOS to see if everything works.
2. In the Timi codebase, I did some gradle related clean up to make Kotlin Multiplatform integration easier (replaced Groovy with Kotlin DSL and added refreshVersions for dependency version management)
3. The next step was copying over the playground KMP module and the iOS project into the Timi codebase.
4. The first KMP integration was done o Android, and then I got it working on iOS.

After these steps, I had a working bare-bones Kotlin Multiplatform app which shares some code with both platforms.

Moving existing logic to Kotlin Multiplatform

Keep in mind that the project is pretty small, which allowed me to do the refactor in much bigger steps without fear of breaking something.

The Android codebase was modularized, which allowed me to move the logic to KMP on a module by module basis.

The core module

At the start, I focused on the "core" module of the application. This module contains interfaces and data structures which are used in many of the other modules. Fortunately, the module didn't contain any Java specific libraries, so it was easy to move it to KMP.

The problem came with Dependency Injection, the Android app used Dagger Hilt for DI, but for Kotlin Multiplatform I wanted to use Koin. In order to make the process straightforward without a lot of changes, I marked the Hilt module as a KoinComponent and used Koin to retrieve the dependencies:

@Module
@InstallIn(SingletonComponent::class)
object TimestampModule: KoinComponent {

    @Provides
    internal fun provideTimestampProvider(): TimestampProvider = get()
}

This allowed me to use Hilt in the Android app, but still retrieve the KMP dependencies from Koin.

After the core module I focused on moving the feature modules which contained all the layers (Presentation, Domain, Data and UI which I didn't move).

Domain and Data layer

At first, I stared with the Domain and Data layer of the stopwatch module. This module seemed like a good start because it had the least amount of external dependencies.

Moving the stopwatch classes was pretty easy just like the core module, however there were places where Java libraries were used, so I had to replace them with a Kotlin alternative, or just "improvise" and leave a TODO comment for later 🙊

I moved the Unit tests last because I wanted to ensure that the production code was still working after moving. After everything was green (The tests passed) I had to also move them to KMP. This task was a lot more involved because I wrote these tests using JUnit5 which is not available in Common Kotlin Multiplatform. To move the tests I had to refactor them to use plain framework features (no nested classes, no parameterized tests) and then move them to KMP.

More in-depth explanation about the Kotlin Multiplatform testing can be found here:

Testing on Kotlin Multiplatform Mobile and a Strategy to Speed Up Development Time

Automated tests are an integral part of developing software, they help catch bugs before they reach the users and save developers time by cutting down manual testing.

AKJAWAleksander Jaworski

Presentation layer

After checking that the Android app stopwatch still works, I focused on the Presentation layer of the stopwatch module. This included moving the ViewModel to the shared code (I still haven't come up with a mechanism for saving the data on process death).

After moving the presentation layer successfully,  I created some basic UI for the iOS app. Once both the apps had the stopwatch feature working, I moved on to the next feature module. Every module was moved repeating these steps: moving Data and Domain, then Presentation, followed by iOS UI.

Problems

While moving logic into KMP, I've encountered some problems which I either fixed, or left for my future self to fix.

Java dependencies

When it comes to the Java standard library, Kotlin should have corresponding functionalities, although there are some exceptions (mostly related to concurrency). The official Kotlin documentation provides great information about if a given functionality is available on Kotlin/JVM as well as Kotlin Native.

Libraries might be harder to migrate, even though the Kotlin Multiplatform ecosystem is growing every day, it is still relatively young. Because of this, not every library supports KMP or has an alternative to it. Fortunately all the basic blocks of mobile development exist: Networking (Ktor or Apollo), Database (SQLDelight), Key Value Store (Settings), Dependency Injection (Koin) the list could go on and on. To help with this, there exists a curated list of Multiplatform libraries.

Compose and Swift UI color

Timi heavily focuses on colors, every task is assigned a color. This color will be then used in other screens of the app. Unfortunately, the Android app did not use a framework-agnostic color abstraction and just used the Compose Color class everywhere. As you can guess, this was problematic when moving classes from Android to KMP.

The solution that I came up with is this:

data class TaskColor(
    val red: Float,
    val green: Float,
    val blue: Float,
)

Which can be used on both the Compose and SwiftUI framework.

The database

Fortunately, the Android app used SQLDelight for the database, which has support for Kotlin Multiplatform. The transition to KMP only required changing the database path, package and the database driver. I didn't create any migration files because the database is still in its early phases and will probable change in the near future. Although, I'm pretty sure it should work with no problems as long as the database name and structure isn't altered.

The database also had integration tests which used the in-memory database driver, unfortunately this driver only exists on the JVM. For Kotlin / Native, there is an in-memory database option, but it requires some tweaking in order to work (Although this is a topic for a separate article 😄).

What's next

I'll try to move as much as I can into the shared codebase, and create a corresponding iOS screen for that feature. When it comes to the ViewModel, I'd like to come up with a way to survive process death on Android. In the meantime, I'll try to understand the iOS platform better and find out the best ways to share / consume the shared code on iOS.

Thank you for reading this, I hope my journey might be helpful for some of you wanting to try out Kotlin Multiplatform on a more "brown field" project. My migration from Android to Kotlin Multiplatform isn't as clean as I wanted it to be. But this mostly has to do with the fact that I wanted to get my hands dirty with SwfitUi as soon as possible.

Recently, I was tasked with creating a Pager screen using Compose. Because the screen had a lot of edge cases in it, I also wanted to write UI tests alongside the screen to ensure all features are covered. In this post, I'll share my experience on testing such screens.

All the working code samples can be found here on the GitHub repository testing-compose-pager.

Here's a brief overview on what will be touched in this article:

• The semantic node tree for pager layouts
• Swiping between screens
• Selecting nodes only from a specific pager layout page
• Selecting off-screen tabs

The app under test

The main screen just allows navigating to the two pager screens (It will not be tested)

The static pager screen has 3 predefined pages, the summary page has two buttons that allow changing the selected page. The other two pages just contain a simple text.

The dynamic pager screen allows for increasing and decreasing the pager layout page count. Every page has more or less the same content.

The Pager library used for this article comes from the Accompanist Utils library for Jetpack Compose.

The Static Pager Screen

Here's a simplified structure of the static pager screen composable, the full source code is available on the GitHub repository.

enum class StaticPagerScreenPage {
    Summary,
    Info,
    Details,
}

@OptIn(ExperimentalPagerApi::class)
@Composable
fun StaticPagerScreen() {
    val pages = remember {
        listOf(
            StaticPagerScreenPage.Summary,
            StaticPagerScreenPage.Info,
            StaticPagerScreenPage.Details,
        )
    }
    Column {
        TabRow() {
            ...
        }
        HorizontalPager() { index ->
            val page = pages[index]
            Box() {
                ....
            }
        }
    }
}

The Static Pager Tests

The static pager screen is easier to test because every page has unique content. Meaning that the testing framework won't be confused when selecting nodes (The next and previous pages don't interfere).

Set up

@Before
fun setUp() {
    composeTestRule.setContent {
        TestingComposePagerTheme {
            StaticPagerScreen()
        }
    }
}

Pager semantic node tree

Before showing the tests, I want to explain how compose interprets the pager content in its semantic node tree.

By default, the pager works by "placing" the current, previous and next page in the tree. This means that at the same time, three pages can exist in the semantic node tree. Here's a simplified tree when opening the static pager screen:

|-Node #5 at (l=0.0, t=303.0, r=1080.0, b=2148.0)px
   CollectionInfo = 'androidx.compose.ui.semantics.CollectionInfo@bf668a0'
   Actions = [IndexForKey, ScrollBy, ScrollToIndex]
    |-Node #18 at (l=0.0, t=303.0, r=1080.0, b=2148.0)px
    |  |-Node #19 at (l=241.0, t=675.0, r=840.0, b=768.0)px
    |  | Text = '[The Summary page]'
    |  | Actions = [GetTextLayoutResult]
    |-Node #26 at (l=0.0, t=303.0, r=1080.0, b=2148.0)px
       |-Node #27 at (l=0.0, t=303.0, r=662.0, b=396.0)px
         Text = '[The Information page]'
         Actions = [GetTextLayoutResult]

The Node #18 and #26 represent the content of the first and second page. In tests, both of these pages are accessible, but only the first one is displayed:

@Test
fun theSecondPageIsInTheNodeTree() {
    composeTestRule.onNodeWithText("The Summary page").assertIsDisplayed()
    composeTestRule.onNodeWithText("The Information page").assertIsNotDisplayed()
}

The third page however does not exist in the node tree:

@Test
fun theThirdPageDoesNotExistInTheNodeTree() {
    composeTestRule.onNodeWithText("The Details page").assertDoesNotExist()
}

This behavior of rendering sibling pages can be problematic when dealing with pages that have content which is not unique between pages. The dynamic pager screen section goes into details on how to differentiate between these types of pages in tests.

Swiping between pages

Swiping horizontally between content is one of the most recognizable features of pagers. Fortunately, with compose, swiping gestures are really easy to perform:

@Test
fun swipingLeftOnRootTwoTimesOpensTheDetailsPage() {
    composeTestRule.onRoot().performTouchInput {
        swipeLeft()
        swipeLeft()
    }

    composeTestRule.onNodeWithText("Details").assertIsSelected()
    composeTestRule.onNodeWithText("The Details page").assertIsDisplayed()
}

The test verification ensures that the Details tab is selected, and that the details page content is displayed after swiping two times to the left.

Performing swiping onRoot works because swipes are performed in the middle of the node (which, in this case, the whole screen):

val height: Int get() = visibleSize.height

val centerY: Float get() = height / 2f

fun TouchInjectionScope.swipeLeft(
    startX: Float = right,
    endX: Float = left,
    durationMillis: Long = 200
) {
    ...
    val start = Offset(startX, centerY)
    val end = Offset(endX, centerY)
    swipe(start, end, durationMillis)
}

Changing pages by tapping the tab

Another popular way of changing pages is by tapping their corresponding tab.

@Test
fun clickingInfoTabOpensTheInfoPage() {
    composeTestRule.onNodeWithText("Info").performClick()

    composeTestRule.onNodeWithText("Info").assertIsSelected()
    composeTestRule.onNodeWithText("The Information page").assertIsDisplayed()
}

Changing pages by tapping the summary page button

There might be also additional ways of changing pages.

@Test
fun clickingGoToInfoOpensTheInfoPage() {
    composeTestRule.onNodeWithText("Go to info").performClick()

    composeTestRule.onNodeWithText("Info").assertIsSelected()
    composeTestRule.onNodeWithText("The Information page").assertIsDisplayed()
}

Static pager summary

Because all static pages have unique content, all nodes be accessed like in normal composable screens i.e. using onNodeWithText, onNodeWithTag, onNodeWithContentDescription.

The full static test source code is available on GitHub and here are the tests in action:

The Dynamic Pager Screen

This screen is more involved because the number of pages can change, and their content is not unique (The increase and decrease buttons).

Here's a simplified structure of the dynamic pager screen composable, the full source code is available on the GitHub repository.

@OptIn(ExperimentalPagerApi::class)
@Composable
fun DynamicPagerScreen() {
    var pageCount by remember { mutableStateOf(1) }
    val pages = remember(pageCount) { List(pageCount) { "Page $it" } }
    Column {
        ScrollableTabRow() {
           ...
        }
        HorizontalPager(
            count = pages.size,
            state = pagerState,
        ) { index ->
            val page = pages[index]
            Box() {
                ...
            }
        }
    }
}

In order to make the tests easier to write, some test tags can be added (a content description can also be used instead):

Column {
    ScrollableTabRow(modifier = Modifier.testTag("dynamic-pager-tab-row")) { ... }
    HorizontalPager() { index ->
        val page = pages[index]
        Box(modifier = Modifier.testTag("dynamic-pager-$index")) { ... }
    }
}

The tags can also be extracted to a companion object, to make maintenance easier:

object TestTagsDynamicPagerScreen {

    private const val pager = "dynamic-pager"
    const val tabRow = "dynamic-pager-tab-row"

    fun getPageTag(index: Int) = "$pager-$index"
}

...

Column {
    ScrollableTabRow(modifier = Modifier.testTag(TestTagsDynamicPagerScreen.tabRow)) { ... }
    HorizontalPager() { index ->
        val page = pages[index]
        Box(modifier = Modifier.testTag(TestTagsDynamicPagerScreen.getPageTag(index))) { ... }
    }
}

The Dynamic Pager Tests

Set up

@Before
fun setUp() {
    composeTestRule.setContent {
        TestingComposePagerTheme {
            DynamicPagerScreen()
        }
    }
}

Dealing with repeating page content

Because every page has the same two buttons, the tests will need to specify which page needs to be used.

For example, on entering, the dynamic pager screen only has one page available. This is the reason is why the following snipped of code works:

@Test
fun worksIfOnlyOnePageExists() {
    composeTestRule.onNodeWithText("Increase").performClick()
}

But when there are two pages (both have the Increase button) the testing framework gets confused:

@Test
fun crashesOnSecondClick() {
    composeTestRule.onNodeWithText("Increase").performClick()
    composeTestRule.onNodeWithText("Increase").performClick()
}

Reason: Expected exactly '1' node but found '2' nodes that satisfy: (Text + EditableText contains 'Increase' (ignoreCase: false))

To get around this, the selector needs to know on which screen should the button be clicked:

@Test
fun doesNotCrash() {
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()
}

private fun ComposeContentTestRule.onPagerButton(
    pageIndex: Int,
    text: String
): SemanticsNodeInteraction {
    val isOnTheCorrectPage =
        hasAnyAncestor(hasTestTag(TestTagsDynamicPagerScreen.getPageTag(pageIndex)))
    return onAllNodesWithText(text)
        .filterToOne(isOnTheCorrectPage)
}

The basic idea is, that all Increase buttons are selected (using onAllNodesWithText) and then they are filtered using a matcher. The matcher works as follows: "give me a node that has an ancestor that has a test tag with the requested page index."

In the example above, the Increase button is clicked only on the first page (index == 0).

Checking if tabs are created

The main feature of the dynamic screen is that the number of tabs can be changed on demand.

@Test
fun increaseClickedOnceTimesThenTabCountIncreases() {
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()

    composeTestRule.onNodeWithText("Page 0").assertIsDisplayed()
    composeTestRule.onNodeWithText("Page 1").assertIsDisplayed()
}

Checking off-screen tabs

When there are too many tabs, they will be added off-screen. In order to access them, the tab row will need to be scrolled horizontally.

@Test
fun increaseClickedMultipleTimesThenTabCountIncreases() {
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()

    composeTestRule.onNodeWithTag(TestTagsDynamicPagerScreen.tabRow)
        .performTouchInput {
            swipeLeft()
        }
    composeTestRule.onNodeWithText("Page 1").assertIsDisplayed()
    composeTestRule.onNodeWithText("Page 2").assertIsDisplayed()
    composeTestRule.onNodeWithText("Page 3").assertIsDisplayed()
}

Clicking increase on a different page

The increase and decrease buttons are available on every page, and they should behave in the same way regardless of the page.

@Test
fun increaseOnSecondTabClickedThenTabCountIncreases() {
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()
    composeTestRule.onNodeWithText("Page 1").performClick()

    composeTestRule.onPagerButton(pageIndex = 1, text = "Increase").performClick()

    composeTestRule.onNodeWithText("Page 0").assertIsDisplayed()
    composeTestRule.onNodeWithText("Page 1").assertIsDisplayed()
    composeTestRule.onNodeWithText("Page 2").assertIsDisplayed()
}

Swiping on page content

Instead of performing the swiping onRoot it can also be performed on one particular page.

@Test
fun swipingLeftOnPageOpensTheCorrectPage() {
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()
    composeTestRule.onPagerButton(pageIndex = 0, text = "Increase").performClick()

    composeTestRule.swipeOnPagerScreen(pageIndex = 0)
    composeTestRule.swipeOnPagerScreen(pageIndex = 1)

    composeTestRule.onNodeWithText("Page 2").assertIsSelected()
    composeTestRule.onNodeWithText("On page: 2").assertIsDisplayed()
}

private fun ComposeContentTestRule.swipeOnPagerScreen(
    pageIndex: Int
) {
    onNodeWithTag(TestTagsDynamicPagerScreen.getPageTag(pageIndex))
        .performTouchInput {
            swipeLeft()
        }
}

Dynamic pager summary

Repeating content on pages can be problematic, but compose offers a some-what elegant way of selecting content only on one particular page.

The full dynamic test source code is available on GitHub and below you can see the tests in action:

Testing screens with network or database data

This article dived deep into the Compose framework using simple examples, but what about real use cases where we need to fetch something from the API, or when we need some database rows?

These exact topics are covered in some of my other articles:

Using Ktor Client MockEngine for Integration and UI Tests

MockEngine replaces real network calls with mocked ones that use pre-defined data and status codes. The engine can be shared between Integration and UI tests.

AKJAWAleksander Jaworski

Kotlin Multiplatform In-Memory SQLDelight Database for Integration and UI Testing on iOS and Android

Databases are an integral part of mobile application development, so it’s important that these features are properly tested.

AKJAWAleksander Jaworski

Using Apollo Kotlin Data Builders for Testing

Data Builders provide an easy way for creating GraphQL response classes. In this post I’ll show how they can be used to improve your tests.

AKJAWAleksander Jaworski

Side-note: Normally when writing UI Tests it's good to use some form of pattern, like the Robot pattern:

Testing Robots – Jake Wharton

Libraries like Espresso allow UI tests to have stable interactions with your app, but without discipline these tests can become hard to manage and require frequent updating. This talk will cover how the so-called robot pattern allows you to create stable, readable, and maintainable tests with the ai…

Jake Wharton

If you have a different way of testing pager screens in compose, feel free to share them below in the comment section.