DEV Community: KMP Bits

Clean Lap: UI Testing in Compose Multiplatform

KMP Bits — Fri, 22 May 2026 18:33:50 +0000

In qualifying, the data engineer doesn't wait for Sunday to find out something was wrong. By the time the driver comes back to the garage, every sector time is already on the screen, every corner apex mapped against the reference lap. If the front left is locking under braking at Turn 3, it shows up immediately, not three hours later when the car is fighting for position and has no margin to fix anything.

I spent a long time treating UI tests the same way I treated the race result: something I'd look at after the damage was done. If a screen broke, someone filed a bug, I fixed it. But the first time I caught a regression in a CMP project because a test failed before the PR merged, I understood what the data engineer already knew. You want the telemetry before race day, not after.

Compose Multiplatform 1.11 (currently in beta) brings runComposeUiTest v2 support for non-Android targets. Writing a test in commonTest and running it on Android, desktop, and iOS is no longer an experimental workaround. This article walks through the setup, the API, and the one coroutine change in 1.11 that will break your existing tests if you upgrade without knowing about it.

A quick note on versions: Everything in this article uses 1.11.0-beta02. The APIs work as described, but beta means things can still shift before the final release. If you're on a stable version, stick with what you have — the stable runComposeUiTest API is available from 1.6.x onwards, but the v2 surface and the dispatcher change covered here are 1.11-specific.

Note on Navigation: To keep the focus on testing, this sample uses a manual state-switching approach. While simplified, this mirrors the state-driven philosophy of Navigation 3. For production apps—especially when implementing Shared Element Transitions as discussed in this Navigation 3 CMP article, the formal Navigation 3 library is recommended to handle the transition orchestration and back-stack management effectively.

What you're actually testing here

Before touching Gradle, it's worth being precise about what compose.uiTest is for. It tests composable UI: the layout, the interaction flow, the visual states. It is not a replacement for unit tests on your ViewModel or business logic.

In a clean CMP project, your ViewModel lives in commonMain, your Compose UI lives in commonMain, and your tests live in commonTest. The tests invoke the composable directly, interact with it through semantic queries, and assert what the user sees. No emulator needed for desktop and iOS targets. No platform ceremony.

(If you're testing ViewModels and Flows in isolation without a UI, those tests can also live in commonTest without compose. I covered how Flows behave across platforms in the StateFlow and SharedFlow article.)

That context set, here is what the setup actually looks like.

Setting up the dependencies

Start with libs.versions.toml. Every new library goes here first.

# gradle/libs.versions.toml
[versions]
compose-multiplatform = "1.11.0-beta02"
kotlin = "2.1.20"
androidx-compose-ui-test = "1.8.0"

[libraries]
# Android instrumented test support — not needed for desktop or iOS
androidx-compose-ui-test-junit4 = { module = "androidx.compose.ui:ui-test-junit4-android", version.ref = "androidx-compose-ui-test" }
androidx-compose-ui-test-manifest = { module = "androidx.compose.ui:ui-test-manifest", version.ref = "androidx-compose-ui-test" }

Then in build.gradle.kts:

// composeApp/build.gradle.kts
kotlin {
    androidTarget {
        @OptIn(ExperimentalKotlinGradlePluginApi::class)
        // Without this, commonTest won't link to the Android instrumented variant
        instrumentedTestVariant.sourceSetTree.set(KotlinSourceSetTree.test)
    }

    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test"))
            @OptIn(org.jetbrains.compose.ExperimentalComposeLibrary::class)
            implementation(compose.uiTest)
        }

        // Android instrumented tests need this additional dependency
        androidInstrumentedTest.dependencies {
            implementation(libs.androidx.compose.ui.test.junit4)
        }
    }
}

dependencies {
    // Manifest injection for Android debug builds
    debugImplementation(libs.androidx.compose.ui.test.manifest)
}

The instrumentedTestVariant.sourceSetTree.set(KotlinSourceSetTree.test) line is the one that trips people up. Without it, your commonTest source set won't link to the Android instrumented test variant, and you'll get missing class errors on device. I spent two hours staring at that error before I found it buried in a JetBrains issue tracker thread.

With that in place, the pit lane work is done. Everything else happens in commonTest.

Writing your first common test

runComposeUiTest is a top-level function. You call it, get a ComposeUiTest receiver, set your content, and query the semantic tree. No TestRule, no JUnit class-level annotation.

// commonTest/kotlin/ui/HomeScreenTest.kt
import androidx.compose.ui.test.ExperimentalTestApi
import androidx.compose.ui.test.assertIsDisplayed
import androidx.compose.ui.test.onNodeWithText
import androidx.compose.ui.test.v2.runComposeUiTest
import kotlin.test.Test

@OptIn(ExperimentalTestApi::class)
class HomeScreenTest {

    @Test
    fun homeScreen_titleIsVisible() = runComposeUiTest {
        setContent {
            HomeScreen()
        }

        onNodeWithText("Home").assertIsDisplayed()
    }
}

Import correct: Use androidx.compose.ui.test.v2.runComposeUiTest, not androidx.compose.ui.test.runComposeUiTest. The package without .v2 is the old version (and it's deprecated on 1.11-beta02).

The @OptIn(ExperimentalTestApi::class) is required for every file until the API fully graduates. In 1.11.0-beta02, the v2 APIs are available for non-Android targets but the annotation is still needed on the common surface — expect it to drop when 1.11 goes stable.

For interaction flows:

// commonTest/kotlin/ui/LoginScreenTest.kt
import androidx.compose.ui.test.ExperimentalTestApi
import androidx.compose.ui.test.assertIsDisplayed
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.onNodeWithText
import androidx.compose.ui.test.performClick
import androidx.compose.ui.test.performTextInput
import androidx.compose.ui.test.v2.runComposeUiTest
import kotlin.test.Test
import kotlin.test.assertTrue

@OptIn(ExperimentalTestApi::class)
class LoginScreenTest {

    @Test
    fun loginScreen_showsErrorWhenEmailIsEmpty() = runComposeUiTest {
        setContent {
            LoginScreen(onLoginSuccess = {})
        }

        // User taps submit without filling anything in
        onNodeWithTag("submit_button").performClick()

        onNodeWithText("Email cannot be empty").assertIsDisplayed()
    }

    @Test
    fun loginScreen_navigatesOnValidInput() = runComposeUiTest {
        var navigated = false

        setContent {
            LoginScreen(onLoginSuccess = { navigated = true })
        }

        onNodeWithTag("email_field").performTextInput("test@example.com")
        onNodeWithTag("password_field").performTextInput("hunter2")
        onNodeWithTag("submit_button").performClick()

        assertTrue(navigated)
    }
}

The test annotation is kotlin.test.Test, not org.junit.Test. That's what makes the test run across all targets, including iOS via the Kotlin/Native runner. If you accidentally import the JUnit annotation in a common file, the iOS and desktop targets will not pick it up at all — the test silently won't exist on those platforms.

The coroutine dispatcher change in CMP 1.11

This is the part you need to know before you upgrade.

Before v2, runComposeUiTest used UnconfinedTestDispatcher internally. Coroutines ran eagerly — side effects triggered immediately, states updated without you doing anything. Tests passed without any manual clock advancement. It felt convenient.

In CMP 1.11, the default switches to StandardTestDispatcher. Coroutines no longer run automatically. If your composable launches a coroutine on composition, such as a LaunchedEffect triggering a data fetch, you need to advance the test scheduler to see the result.

// commonTest/kotlin/ui/FeedScreenTest.kt
import androidx.compose.ui.test.ExperimentalTestApi
import androidx.compose.ui.test.assertIsDisplayed
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.v2.runComposeUiTest
import kotlin.test.Test

@OptIn(ExperimentalTestApi::class)
class FeedScreenTest {

    @Test
    fun feedScreen_showsLoadingIndicator() = runComposeUiTest {
        setContent {
            FeedScreen(state = FeedUiState.Loading)
        }

        onNodeWithTag("loading_indicator").assertIsDisplayed()
    }

    @Test
    fun feedScreen_showsContentItems() = runComposeUiTest {
        setContent {
            FeedScreen(state = FeedUiState.Content(listOf("Article 1", "Article 2")))
        }

        onNodeWithTag("feed_list").assertIsDisplayed()
    }

    @Test
    fun feedScreen_showsLoadingThenContent() = runComposeUiTest {
        var state by mutableStateOf<FeedUiState>(FeedUiState.Loading)

        setContent {
            LaunchedEffect(Unit) {
                delay(500)
                state = FeedUiState.Content(listOf("Article 1", "Article 2", "Article 3"))
            }
            FeedScreen(state = state)
        }

        // Check initial state
        onNodeWithTag("loading_indicator").assertIsDisplayed()

        // Wait until the list appears (this handles the clock advancement internally)
        waitUntil(timeoutMillis = 1000) {
            // Returns true when the node exists
            onAllNodesWithTag("feed_list").fetchSemanticsNodes().isNotEmpty()
        }

        onNodeWithTag("feed_list").assertIsDisplayed()
    }
}

While waitForIdle() pumps the event queue until the current UI state is stable, waitUntil actively advances the virtual clock to bridge gaps created by delay() or asynchronous tasks, ensuring the test stays paused until your specific UI condition is met.

When I upgraded a CMP project from 1.9 to 1.11-beta02, five tests that were passing started failing. Every single one was relying on the eager dispatcher to hide an async gap in the UI. The tests were wrong before. The new dispatcher just finally showed it.

Running across platforms

Three targets, three commands:

# Android instrumented (emulator or connected device required)
./gradlew :composeApp:connectedAndroidTest

# Desktop (JVM, no emulator needed — fast)
./gradlew :composeApp:desktopTest

# iOS (Kotlin/Native, runs via XCTest wrapper)
./gradlew :composeApp:iosSimulatorArm64Test

The desktop run is the fastest feedback loop. I use it constantly during development — the round trip is under 30 seconds on a warm build. If the desktop test passes, Android and iOS almost always do too, unless there's a platform-specific composable in the mix.

A quick note: iOS tests require a Mac with an iOS Simulator available. On CI, that means a macOS runner for the iOS command. Linux runners will handle desktop and Android.

The goal on CI is to run all three in parallel. You want the qualifying data from every target before the PR merges, not just one.

Gotchas

A few things that cost me time:

Semantic tags must be added explicitly. onNodeWithTag() only works if you've added Modifier.testTag("your_tag") to the composable. Don't rely on text content for interactive elements — button labels change, tags don't. Add tags from the start, not after the test breaks.
The @OptIn annotation is per file. You can't declare it once at module level and have it propagate. Every test file using runComposeUiTest needs its own @OptIn(ExperimentalTestApi::class).
System dialogs are invisible to tests. If your composable triggers a permission dialog or a system-level sheet, the test runner won't see it. Mock the permission state at the ViewModel level and test the resulting composable state, not the dialog.
@Preview composables are not tests. They don't run in commonTest. If you want to test a state-dependent screen, you're testing the real composable with injected state — that's a different thing, and it's the right thing.

Where this fits with everything else

commonTest UI tests are fast and platform-agnostic. They cover layout, interactions, and state transitions. They don't cover the full integration with real network, real databases, or real OS behaviour.

The way I think about it: common UI tests confirm the qualifying lap. The composable is doing the right thing in isolation. Integration tests on a real device confirm the race pace: does the real data layer, real network, and real platform behave together as expected?

Both matter. The qualifying lap is just considerably cheaper to run before the team heads out to the grid.

(For Android-specific UI testing on the JVM without a CMP setup, I covered Robolectric in an earlier article: Testing Jetpack Compose UI on the JVM. It's a different approach and worth knowing about if you're working on an Android-only module alongside your KMP code.)

Compose Multiplatform 1.11.0-beta02 makes runComposeUiTest a first-class citizen on non-Android targets. The setup is a handful of Gradle lines, the API keeps itself minimal, and the desktop feedback loop is fast enough to use on every save. The one thing to account for before upgrading is the dispatcher change: if your tests depended on eager coroutine execution, add waitForIdle() or waitUntil() (Depending on what you need) and treat the failures as the API finally telling you the truth.

The telemetry was always available. The only question is whether you check it before the race starts or after something goes wrong on track. 🏁

The full demo for this article is available on GitHub.

The KMP Bits app is available on App Store and Google Play — built entirely with KMP.

KMP Splash: How I Stopped Opening Xcode for Splash Screens

KMP Bits — Thu, 21 May 2026 16:02:03 +0000

Every Formula 1 driver knows. You don't change your own tyres. You don't adjust the front wing yourself. You pull in, the crew handles it in under three seconds, and you're back at racing speed before you've had time to think about it. The driver's job is to drive.

I kept changing my own tyres.

Every new Compose Multiplatform project came with the same ritual. Open Xcode, find the LaunchScreen storyboard, set the background color add the logo to the asset catalog, patch Info.plist, go back to Android Studio, generate themes.xml and add the theme to the manifest. I always ended up copying the setup from the last project because I never remembered all the steps. Sometimes I forgot one file and only found out on device. The race was already running and I was still in the garage.

So I built the pit crew. KMP Splash is a Gradle plugin that handles the entire splash screen setup for both Android and iOS from a single config block. This is about why I built it and how it evolved. The README has the full setup. This is the story behind it.

The storyboard era

The standard iOS splash screen approach for years was LaunchScreen.storyboard. You created a storyboard, set a background color, added an image view, connected it to the asset catalog, and referenced it in Info.plist. Xcode's tooling made it manageable, if you were working in Xcode.

In a Compose Multiplatform project, you are not in Xcode, you're in Android Studio, and Xcode is a separate application you open only when something native needs touching. Any change, a color tweak, a new logo, means switching contexts entirely. Then switching back.

What finally got to me was the copy-paste cycle. Every new project, I'd go back to the last one, try to remember which files I needed, copy them over, adjust the names, miss something, and only discover the miss when the app launched wrong on a real device. It wasn't a hard problem. It was a repetitive one. And repetition compounds.

Apple introduced UILaunchScreen, on iOS 14, as a plist-based alternative. Instead of a storyboard, you define a dictionary in Info.plist with your background color name and optional logo. No storyboard, no Interface Builder, no Xcode required for changes. The OS reads it directly.

That was the door. The pit lane was always there. I just needed to build a crew.

One config block

The idea was simple: describe the splash screen once, in Kotlin, in the build file you already have open. Let the plugin generate whatever the platforms need.

The first version was rough. Background color was a plain hex string. Logo was a full file path. It worked, but it was fragile. A typo in the color string generated wrong assets with no error until the app ran. A wrong path gave you a cryptic Gradle message that pointed nowhere useful.

// composeApp/build.gradle.kts — first version, don't do this
splashScreen {
    backgroundColor = "#FFFFFF"
    logoFile = "src/commonMain/composeResources/drawable/logo.png"
}

I shipped the alpha that way because it was functional. But I knew it was wrong. Strings give you no help. The crew hands you a tyre and you have to figure out if it's the right compound yourself.

The API learned to talk back

The second iteration introduced typed wrappers. SplashColor replaced the hex string and validates the format immediately, telling you exactly what's wrong if the input is malformed. SplashLogo replaced the full path and resolves the location from composeResources/drawable/ automatically. You just name the file.

The config went from something you had to get right to something that tells you when you haven't:

// composeApp/build.gradle.kts
splashScreen {
    backgroundColor = SplashColor.hex("#FFFFFF")
    backgroundColorNight = SplashColor.hex("#1A1A2E")
    logo = SplashLogo.resource("logo.png")
    logoDark = SplashLogo.resource("logo_dark.png") // optional
}

SplashColor also accepts RGB values with SplashColor.rgb(26, 26, 46) and named constants like SplashColor.white. Both backgroundColorNight and logoDark are optional. If you don't set them, the plugin uses the light values for both modes.

The difference feels small in a snippet. In practice, the config stopped being a source of bugs. I stopped thinking about it. That's the goal. The driver manages the tyres, but he doesn't fit them himself. That part stays in the pit lane.

The gap nobody talks about

Splash screens on mobile have two distinct phases. First, the OS renders something while your app loads. Then your Compose UI takes over.

The problem is the transition between them. On iOS especially, there's a moment after the native launch screen disappears but before Compose has initialized where the screen flashes its default background. On a cold start on a slower device, that flash is visible. It feels rough even when everything else about the app is polished.

KMP Splash bridges it. On Android, SplashActivity extends the native splash by holding the screen until your initialization is done. On iOS, SplashConfig renders a Compose screen that's visually identical to the native launch, using the same colors and logo, and holds it until the app is ready.

The Compose side reads the config from your Gradle block automatically. You don't pass colors or logos at the call site. You configured them once, and everything is already wired.

Using it

On Android, you extend SplashActivity in your MainActivity:

// androidMain/MainActivity.kt
class MainActivity : SplashActivity() {

    override suspend fun isReady(): Boolean {
        delay(1000) // load data, check auth, etc.
        return true
    }

    override fun onFinished() {
        setContent { App() }
    }
}

On iOS, you call SplashConfig from your MainViewController:

// iosMain/MainViewController.kt
fun MainViewController() = ComposeUIViewController {
    var isAppReady by remember { mutableStateOf(false) }

    if (!isAppReady) {
        SplashConfig(
            isReady = {
                delay(1500)
                true
            },
            onFinished = { isAppReady = true }
        )
    } else {
        App()
    }
}

Both tasks run automatically before compilation. You never call them manually.

The first time I used it on a new project and didn't open Xcode once, I sat back for a second. The right color, the right logo, no flash. The app looked exactly right from the first pixel. And I hadn't touched a storyboard.

One limitation worth knowing

There's one thing no library can fix. The native splash screen reads the system dark mode setting, not your app's dark mode setting. If your app has its own appearance toggle and the user has set it to dark while the phone is in light mode, the native launch screen will still show the light version.

This isn't a bug in the library. The OS renders the native splash before any of your code runs. There's no way to communicate an app-level preference at that point. The Compose layer can respond to it, but the brief native phase cannot.

The options are: use a background color that works in both modes, or accept that the native splash matches the system and the Compose layer corrects to the app preference immediately after. For most apps, neither is a real problem. But it's worth knowing before you spend time debugging it.

Wrapping up

The frustration that started this was trivial on any individual project. It's the repetition that wears you down. The same ritual, the same files to remember, the same context switch to Xcode. Automating it didn't require anything exotic. It just required sitting down and building the crew.

KMP Splash is published on Maven Central at io.github.kmpbits:splash-runtime. The README has the full setup guide. Source is on GitHub.

Pull into the pits, let the crew handle it, and get back on track. 🏁

The library is available on GitHub.

The KMP Bits app is available on App Store and Google Play, built entirely with KMP.

Drop the Clutch: Three Metro DI Patterns Every KMP Developer Should Know

KMP Bits — Wed, 20 May 2026 14:32:46 +0000

In a GT3 car, you have a choice. You can drive with a traditional manual gearbox: clutch pedal, H-pattern shifter, full control over every gear change. Or you can switch to the sequential paddle shifters that most modern GT3 cars run. The car is still yours to drive. The racing line, the braking points, the tyre management. All of that stays with you. The only thing that changes is that you stop managing something that was never really the point.

I've been running Koin in a multi-module Compose Multiplatform project for a while, and for a long time it felt like the manual gearbox. Not painful exactly, just present. Every new dependency meant another module { } block somewhere, another get() in the factory lambda, another place where the compiler had nothing to say if I forgot to wire something. The error came at runtime, and usually in a context that made it harder to trace than it should have been.

Metro is the paddle shifters. You annotate your classes, define a graph interface, and the Kotlin compiler plugin generates the wiring at build time. If something is missing from the graph, the build fails. Not the app launch. The build.

I already covered Koin Annotations in a previous article. What follows isn't a migration guide. It's a look at three specific patterns that come up in every real KMP project and where Metro's behaviour changed how I think about dependency injection.

What Metro is

Metro is a compile-time dependency injection framework for Kotlin Multiplatform. It ships as a Kotlin compiler plugin, not an annotation processor or a KSP plugin. Code generation happens in the compiler's FIR/IR pipeline directly.

The mental model draws from three places: @Inject, @Provides, and the scope system come from Dagger; the interface-based graph definition comes from kotlin-inject; and the contribution aggregation system comes from Anvil. If you've worked with any of those three, the ideas transfer quickly.

Metro, Koin Annotations, and Dagger

Before getting into the patterns, it's worth placing Metro relative to the tools you've probably already used.

Koin Annotations

The comparison people reach for first is Koin Annotations, because both claim compile-time safety. I want to be clear about something: these are not competing answers to the same question. They solve the same problem, both do it well, and the choice comes down to what your project actually needs.

Koin Annotations uses KSP to generate source files during the build. It catches graph errors in the KSP phase, which is earlier than runtime, but the Koin service locator container still exists underneath. If something slips through, the app can still throw on startup. The generated .kt files land in build/generated/ksp/, and you need KSP configured and on the right classpath. For most projects, that's no trouble at all. Koin is mature, widely used, and well documented.

Metro works at a different level. It's a compiler plugin operating on the IR representation of your code, the same layer where kotlinx.serialization and the Compose compiler plugin live. There are no generated source files, no build/generated/ directory, no KSP classpath to manage. The output is direct constructor calls baked into bytecode. Metro has no runtime container. If the graph is invalid, the build doesn't produce a binary.

The trade-offs are real on both sides. Metro is strictly static, so dynamic or conditional bindings that Koin handles without friction are outside Metro's scope. And Metro is a newer library, primarily maintained by one person. Koin has years of production use behind it.

My take: if your team already knows Koin, or you need dynamic binding flexibility, stick with Koin Annotations. If you want the strictest compile-time guarantee with no runtime container underneath, Metro is the right call.

If you know Dagger

If you've used Dagger before, Metro will feel familiar in the right places. @Inject, @Provides, scope annotations, and compile-time graph validation are all there. The graph interface replaces Dagger's @Component, @DependencyGraph.Factory replaces @Component.Builder, and @ContributesBinding replaces the manual @Binds plus module wiring you'd write by hand in Dagger.

Metro is a compiler plugin rather than an annotation processor, so no KAPT, no KSP, no generated source files to track. The interface-based graph definition is cleaner than Dagger's abstract class components. And Metro supports Kotlin Multiplatform natively. Dagger never did. If you've used Hilt, the @ContributesBinding aggregation pattern will look familiar: Metro borrows it from Anvil, which is what Hilt builds on.

Where Dagger still has an edge: it's been used in large Android codebases for over a decade, the tooling is more mature, and the error messages are better when something goes wrong. If you're on a large Android-only project with an existing Dagger graph, there's rarely a reason to migrate.

The demo

The three patterns I want to show are easier to understand in context than in isolation. To make them concrete, I built a fake real-time chat app: a conversations list, a notification permission screen, and a chat room with a scoped WebSocket. No server, no real backend. Just hardcoded data and coroutine timers. Each screen demonstrates one Metro concept, and together they cover the situations you'll hit in almost any real KMP project.

The article focuses entirely on the DI wiring. The UI is minimal by design.

Setup

# gradle/libs.versions.toml
[versions]
metro = "1.0.0"

[plugins]
metro = { id = "dev.zacsweers.metro", version.ref = "metro" }

[libraries]
metro-viewmodel = { module = "dev.zacsweers.metro:metrox-viewmodel", version.ref = "metro" }
metro-viewmodel-compose = { module = "dev.zacsweers.metro:metrox-viewmodel-compose", version.ref = "metro" }

// build.gradle.kts (root)
plugins {
    alias(libs.plugins.metro) apply false
}

Apply the plugin to every module that contains Metro annotations and add the ViewModel extensions to the modules that need them:

// composeApp/build.gradle.kts
plugins {
    alias(libs.plugins.metro)
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.metro.viewmodel)
            implementation(libs.metro.viewmodel.compose)
        }
    }
}

metrox-viewmodel and metrox-viewmodel-compose are what give you ViewModelGraph, LocalMetroViewModelFactory, and @ContributesIntoMap for lifecycle-aware ViewModel injection. The demo uses all three.

One Gradle plugin, two extra libraries. No annotation processor configuration, no generated source directories to wire into your source sets.

The project organises code by package rather than separate Gradle modules. Metro's contribution system works at the annotation level, not the module boundary, so packages are enough. A scope marker is all you need to get started:

// commonMain/di/AppScope.kt
import dev.zacsweers.metro.Scope

@Scope
annotation class AppScope

Feature 1: Conversations list

This is the baseline. The pattern you'll use for most features in any KMP project.

The interface lives in the domain layer:

// commonMain/feature/conversations/domain/ConversationRepository.kt
interface ConversationRepository {
    suspend fun getConversations(): List<Conversation>
}

The implementation attaches itself to the graph:

// commonMain/feature/conversations/data/FakeConversationRepository.kt
import dev.zacsweers.metro.ContributesBinding
import dev.zacsweers.metro.Inject
import dev.zacsweers.metro.SingleIn
import kotlinx.coroutines.delay

@Inject
@ContributesBinding(AppScope::class)
@SingleIn(AppScope::class)
class FakeConversationRepository : ConversationRepository {

    override suspend fun getConversations(): List<Conversation> {
        delay(300) // fake network latency
        return listOf(
            Conversation(id = "1", name = "Garage channel", lastMessage = "Tyres are warm."),
            Conversation(id = "2", name = "Pit wall", lastMessage = "Box this lap.")
        )
    }
}

@ContributesBinding(AppScope::class) tells Metro: this class implements ConversationRepository and belongs to AppScope. The root graph never needs to declare it. Metro aggregates everything contributed to a scope automatically at compile time. @SingleIn(AppScope::class) keeps one instance alive for the app's lifetime. Remove it and Metro creates a new repository on every injection, which is almost never what you want for a repository.

This is the pattern that makes multi-feature wiring low-ceremony. Each feature declares its own contributions and the root graph stays small.

Lifecycle-aware ViewModel injection

The ViewModel follows the same constructor injection pattern, but contributing it uses a map:

// commonMain/feature/conversations/presentation/ConversationsViewModel.kt
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import dev.zacsweers.metro.ContributesIntoMap
import dev.zacsweers.metro.Inject
import dev.zacsweers.metro.ViewModelKey
import dev.zacsweers.metro.binding
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.launch

@Inject
@ContributesIntoMap(AppScope::class, binding = binding<ViewModel>())
@ViewModelKey(ConversationsViewModel::class)
class ConversationsViewModel(
    private val repository: ConversationRepository
) : ViewModel() {

    private val _conversations = MutableStateFlow<List<Conversation>>(emptyList())
    val conversations: StateFlow<List<Conversation>> = _conversations

    init {
        viewModelScope.launch {
            _conversations.value = repository.getConversations()
        }
    }
}

@ContributesIntoMap puts this ViewModel into a map that Metro generates for the scope. The @ViewModelKey annotation sets the key. That map feeds into MetroViewModelFactory, an abstract class from Metro's ViewModel extensions that you subclass once per scope.

Metro won't provide MetroViewModelFactory automatically. It's abstract and has no @Inject constructor. You bridge the gap with a small file that subclasses it for each scope:

// commonMain/di/ViewModelFactory.kt
@Inject
@ContributesBinding(AppScope::class)
@SingleIn(AppScope::class)
class AppViewModelFactory(
    override val viewModelProviders: Map<KClass<out ViewModel>, () -> ViewModel>,
    override val assistedFactoryProviders: Map<KClass<out ViewModel>, () -> ViewModelAssistedFactory>,
    override val manualAssistedFactoryProviders: Map<KClass<out ManualViewModelAssistedFactory>, () -> ManualViewModelAssistedFactory>,
) : MetroViewModelFactory()

@Inject
@ContributesBinding(ChatScope::class)
@SingleIn(ChatScope::class)
class ChatViewModelFactory(
    override val viewModelProviders: Map<KClass<out ViewModel>, () -> ViewModel>,
    override val assistedFactoryProviders: Map<KClass<out ViewModel>, () -> ViewModelAssistedFactory>,
    override val manualAssistedFactoryProviders: Map<KClass<out ManualViewModelAssistedFactory>, () -> ManualViewModelAssistedFactory>,
) : MetroViewModelFactory()

Both classes are @Inject, so Metro can construct them. The three maps are populated from @ContributesIntoMap contributions in the matching scope. @ContributesBinding wires AppViewModelFactory to the MetroViewModelFactory binding in AppScope, and the same pattern applies for ChatViewModelFactory in ChatScope.

ViewModelGraph then exposes metroViewModelFactory, which you provide through a CompositionLocal:

// commonMain/App.kt
@Composable
fun App(graph: RootGraph) {
    CompositionLocalProvider(LocalMetroViewModelFactory provides graph.metroViewModelFactory) {
        AppTheme { AppEntry() }
    }
}

Inside any screen below that provider, metroViewModel<ConversationsViewModel>() resolves from the map, scoped to the back stack entry, cleaned up when the screen pops. The Metro wiring doesn't touch any of that: it just provides the factory.

A quick note on metroViewModelFactory: Compose's viewModel() function uses reflection by default, which doesn't work with Metro since there's no runtime container. metroViewModel<T>() from metrox-viewmodel-compose reads LocalMetroViewModelFactory and constructs ViewModels from the contributed map instead. The MetroViewModelFactory subclass you write in ViewModelFactory.kt is the bridge: it takes the generated provider maps as constructor arguments and wires them into the factory. Everything else works exactly as you'd expect from the Jetpack ViewModel API.

The thing that clicked for me: @ContributesBinding contributes a single binding, @ContributesIntoMap contributes an entry to a map. Both are aggregated automatically. Neither requires touching the root graph.

Feature 2: Notification permission

This is where Metro in a multiplatform project gets genuinely tricky, and where the constraint that makes it correct becomes obvious.

On Android, requesting notification permission requires Context, which goes to ActivityCompat.requestPermissions. On iOS, you use UNUserNotificationCenter. Neither type exists in commonMain. The interface for the provider lives there, but the implementations are entirely platform-specific. If you want a deep dive into cross-platform notifications with KMP, I covered the full setup in a previous article.

The instinct is to put @DependencyGraph on the common interface and let platform graphs extend it:

// WRONG: fails to compile on the iOS target
// commonMain/di/AppGraph.kt
@DependencyGraph(scope = AppScope::class)
interface AppGraph {
    @DependencyGraph.Factory
    fun interface Factory {
        fun create(@Provides context: Context): AppGraph // Context is an Android type
    }
}

The iOS compiler doesn't know what Context is. The build fails with an unresolved reference. After that error, we can try @GraphExtension. Metro provides it for extending an existing graph, but @GraphExtension.Factory is a different annotation from @DependencyGraph.Factory, and createGraphFactory only accepts the second one. You end up with a graph you can't instantiate.

I went through both of those dead ends before the correct pattern became clear: the common interface is just a plain Kotlin interface with no Metro annotations. The @DependencyGraph goes only on the platform-specific implementations.

// commonMain/di/RootGraph.kt
import dev.zacsweers.metrox.viewmodel.ViewModelGraph

// Plain Kotlin interface, no @DependencyGraph
interface RootGraph : ViewModelGraph {
    val platformNotificationProvider: PlatformNotificationProvider
}

// androidMain/di/AndroidRootGraph.kt
import dev.zacsweers.metro.DependencyGraph
import dev.zacsweers.metro.Provides

@DependencyGraph(scope = AppScope::class)
interface AndroidRootGraph : RootGraph {

    @DependencyGraph.Factory
    fun interface Factory {
        fun create(@Provides context: Context): AndroidRootGraph
    }
}

// iosMain/di/IosRootGraph.kt
import dev.zacsweers.metro.DependencyGraph

@DependencyGraph(scope = AppScope::class)
interface IosRootGraph : RootGraph

Creating the graph on each platform:

// androidMain/App.kt
class App : Application() {
    val graph: RootGraph by lazy {
        createGraphFactory<AndroidRootGraph.Factory>().create(applicationContext)
    }
}

// iosMain/MainViewController.kt
fun MainViewController() = ComposeUIViewController {
    val graph = remember { createGraph<IosRootGraph>() }
    App(graph)
}

createGraph<T>() expects T to be a @DependencyGraph with no required external parameters. createGraphFactory<F>() expects F to be a @DependencyGraph.Factory inside a graph that needs those parameters. Both return a RootGraph, which is what the shared App() composable receives. The composable never needs to know which platform it's running on.

Platform implementations

The notification provider expect class lives in common:

// commonMain/core/domain/PlatformNotificationProvider.kt
import kotlinx.coroutines.flow.StateFlow

expect class PlatformNotificationProvider {
    val permissionGranted: StateFlow<Boolean>
    fun requestPermission()
    fun observeNotificationServicePermission()
}

The Android implementation uses Context and an ActivityHolder, a wrapper that MainActivity updates on onCreate/onDestroy so DI-managed classes can reach the current Activity without holding a direct reference to it:

// androidMain/feature/notifications/data/PlatformNotificationProviderImpl.kt
@Inject
@SingleIn(AppScope::class)
actual class PlatformNotificationProvider(
    private val context: Context,
    private val activityHolder: ActivityHolder
) {
    companion object {
        const val REQUEST_CODE_NOTIFICATIONS = 1001
    }

    private val _permissionGranted = MutableStateFlow(false)
    actual val permissionGranted: StateFlow<Boolean> = _permissionGranted

    actual fun requestPermission() {
        val activity = activityHolder.get() ?: return
        ActivityCompat.requestPermissions(
            activity,
            arrayOf(Manifest.permission.POST_NOTIFICATIONS),
            REQUEST_CODE_NOTIFICATIONS
        )
    }

    actual fun observeNotificationServicePermission() {
        _permissionGranted.value = ContextCompat.checkSelfPermission(
            context, Manifest.permission.POST_NOTIFICATIONS
        ) == PackageManager.PERMISSION_GRANTED
    }
}

Android	iOS

Android doesn't deliver permission results to DI-managed classes. They come back to Activity.onRequestPermissionsResult. The pattern that works: MainActivity calls observeNotificationServicePermission() in the callback, the provider re-reads the system state, and the MutableStateFlow updates. Everything else observes the flow.

// androidMain/MainActivity.kt
override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String?>,
    grantResults: IntArray,
    deviceId: Int
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults, deviceId)
    if (requestCode == PlatformNotificationProviderImpl.REQUEST_CODE_NOTIFICATIONS) {
        graph.platformNotificationProvider.observeNotificationServicePermission()
    }
}

The iOS implementation uses UNUserNotificationCenter.

The error you get if you annotate the common graph isn't Metro being fussy. It's the compiler catching a design that would break the iOS build entirely. The plain interface isn't a workaround. It's the correct model.

Feature 3: Chat room

This is the pattern I wanted to understand before committing to Metro seriously. The first two features use AppScope for everything, which makes sense: repositories and providers live for the app's lifetime. But not everything does.

A WebSocket isn't a data object. It connects on creation and needs to be explicitly closed. Keeping it in AppScope means the socket stays open for the entire app lifetime, even when the user is on a completely different screen. That's almost never what you want for a real-time connection.

A scope is a lifetime, not a namespace. The ChatScope exists because the socket needs to opened when the chat screen opens and closed when it leaves. And because every chat room is a different conversation, there's a second problem to solve: the conversation ID is only known at runtime, when the user taps a row. Metro needs to receive it and make it available to anything in the scope.

Here's how the two scopes relate in the demo:

AppScope  (AndroidRootGraph / IosRootGraph)
├── ConversationRepository       singleton, lives for the app's lifetime
├── PlatformNotificationProvider singleton, lives for the app's lifetime
├── AppViewModelFactory
│
└── ChatScope  (ChatGraph) ──── created via ChatGraph.Factory at navigation time
    ├── ConversationId           runtime value, injected through the factory parameter
    ├── ChatSocket               singleton within this scope
    └── ChatViewModelFactory

ChatScope is nested inside AppScope and inherits all of its bindings. ChatGraph uses @GraphExtension for exactly that reason. Anything in ChatScope can ask for ConversationRepository or PlatformNotificationProvider and Metro will resolve them from the parent graph. The reverse isn't true: AppScope knows nothing about ChatSocket or ConversationId.

The scope and the socket

// commonMain/di/ChatScope.kt
import dev.zacsweers.metro.Scope

@Scope
annotation class ChatScope

The conversation ID is a runtime value, so it gets a proper type:

// commonMain/feature/chat/domain/ConversationId.kt
@JvmInline
value class ConversationId(val value: String)

A value class, different from a raw String, keeps the binding unambiguous. Metro identifies bindings by type, so ConversationId and String are different things in the graph.

// commonMain/feature/chat/data/ChatSocket.kt
@Inject
@SingleIn(ChatScope::class)
class ChatSocket(val conversationId: ConversationId) {

    private val _messages = MutableStateFlow<List<ChatMessage>>(emptyList())
    val messages: StateFlow<List<ChatMessage>> = _messages

    private val _isTyping = MutableStateFlow(false)
    val isTyping: StateFlow<Boolean> = _isTyping

    private var job: Job? = null

    init {
        job = CoroutineScope(Dispatchers.Default).launch {
            var lap = 1
            while (true) {
                delay(2_000)
                _isTyping.value = true
                delay(1_000)
                _isTyping.value = false
                _messages.update {
                    it + ChatMessage(sender = "Engineer", text = "Lap $lap: pace looks good.")
                }
                lap++
            }
        }
    }

    fun close() {
        job?.cancel()
        job = null
    }
}

ChatSocket declares ConversationId as a constructor parameter. Metro will inject it, no special annotation needed on the parameter itself. The binding just has to exist somewhere in the scope, and the factory is where it comes from.

@SingleIn(ChatScope::class) means one ChatSocket per ChatGraph. Not one per app, one per chat session. Navigate away and come back, and you get a fresh socket with its own conversation ID.

The graph extension

The chat graph uses @GraphExtension rather than @DependencyGraph. The difference is that @GraphExtension extends an existing parent graph and inherits all of its bindings. @DependencyGraph creates a standalone graph that knows nothing about its caller.

// commonMain/di/ChatGraph.kt
import dev.zacsweers.metro.GraphExtension
import dev.zacsweers.metro.Provides
import dev.zacsweers.metrox.viewmodel.ViewModelGraph

@GraphExtension(scope = ChatScope::class)
interface ChatGraph : ViewModelGraph {
    val chatSocket: ChatSocket

    @ContributesTo(AppScope::class)
    @GraphExtension.Factory
    fun interface Factory {
        fun create(@Provides conversationId: ConversationId): ChatGraph
    }
}

@Provides on the factory parameter is Metro's answer to runtime injection. When create(conversationId) is called, Metro takes that value and makes it available as a binding for the entire ChatScope. ChatSocket asks for ConversationId in its constructor; Metro delivers the one passed into the factory. No extra wiring, no manual passing.

ConversationId isn't being threaded through a call chain. It's a graph-level binding. Any class in ChatScope can list it as a constructor parameter and get the right one automatically. The ChatGraph instance is this specific conversation. Add a read-receipt tracker or a typing service later and they get the ID for free, for as long as the socket is alive.

@ContributesTo(AppScope::class) on the factory tells Metro to aggregate it into the root graph automatically, so the root graph exposes chatGraphFactory without needing to declare it explicitly.

The entry composable

// commonMain/feature/chat/presentation/ChatEntry.kt
@Composable
fun ChatEntry(
    factory: ChatGraph.Factory,
    conversationId: ConversationId,
    onBackClick: () -> Unit
) {
    val graph = remember { factory.create(conversationId) }

    DisposableEffect(Unit) {
        onDispose { graph.chatSocket.close() }
    }

    CompositionLocalProvider(LocalMetroViewModelFactory provides graph.metroViewModelFactory) {
        ChatScreen(onBackClick = onBackClick)
    }
}

remember { factory.create(conversationId) } creates the graph once for the lifetime of this composable. The conversationId comes from the navigation back-stack entry and is fixed for the session, which is why remember with no key is correct here. DisposableEffect with onDispose calls close() when the composable leaves the composition. CompositionLocalProvider swaps the ViewModel factory to the one backed by ChatScope, so metroViewModel() calls inside ChatScreen resolve from ChatGraph, not the root AppScope factory.

The socket starts emitting as soon as ChatEntry enters the composition. While the screen is open, a new message arrives every three seconds, preceded by a one-second typing indicator. The moment you navigate away, onDispose fires, close() cancels the coroutine, and it stops. Navigate back to a different conversation and you get a fresh ChatGraph, a fresh ChatSocket, and a new ConversationId, all from a single factory.create(newId) call.

AppScope would mean the socket survives every screen transition for the app's entire lifetime. ChatScope means it lives exactly as long as the chat screen. The @Provides on factory parameter means runtime values flow into the scope cleanly, without leaking Android lifecycle details into the graph definition.

Gotchas

Most of these I hit personally while building the demo. Metro's error messages are generally good, but a few failure modes produce errors that point at the wrong place. You see the interface in the message, not the implementation that caused the problem. That's the pattern to watch for.

internal on @ContributesBinding classes.
If a contributed class is internal (Usually on a multi module project), Metro can't aggregate it across module boundaries. The reason: Metro's compiler plugin generates glue code that references your class by name. If that class is internal, the generated code sits outside the declaring module's visibility boundary and can't see it. The build succeeds, but you'll get a MissingBinding error naming the interface, not the implementation. This one is hard to trace the first time. Keep contributed classes public (the default) or at least within the same Gradle module as every class that needs them.

@DependencyGraph cannot extend @DependencyGraph.
Metro rejects this at compile time: "Graph class may not directly extend graph class." The plain-interface pattern from Feature 2 is the correct solution: annotate only the platform-specific leaf implementations.

createGraph vs createGraphFactory.
createGraph<T>() expects T to be a @DependencyGraph with no required external parameters. createGraphFactory<F>() expects F to be a @DependencyGraph.Factory. These are different annotations; mixing them produces a compiler error that points at the right place, but the fix isn't obvious until you understand the split.

@GraphExtension vs @DependencyGraph for child graphs.
Use @GraphExtension when the child graph should inherit parent bindings, which is the right choice for a scoped feature graph like ChatGraph. Use @DependencyGraph only for the root platform graphs. Mixing them up produces a graph that either can't see parent bindings or can't be instantiated correctly.

Scope mismatch.
A class scoped to ChatScope that gets injected into something in AppScope produces a MissingBinding error at compile time. The error names the interface, not the implementation. When you see it, check whether the implementation is scoped to a graph the requester can't reach.

Manifest permissions are a separate concern.
This is more an Android issue. Metro wires up a class that calls requestPermissions correctly. But if POST_NOTIFICATIONS isn't declared in AndroidManifest.xml, the dialog won't appear and there's no error anywhere. Always check the manifest first if a permission flow does nothing.

Wrapping up

Metro moves dependency graph validation from runtime to compile time, and that shift changes how you think about DI mistakes. The patterns here cover most of the ground: binding contributions for everyday features, the platform graph split for anything that needs Android or iOS types, and child scopes for dependencies with a real lifecycle, including runtime values like a conversation ID flowing in through a factory parameter. Get those three things in place and the rest of the wiring tends to solve itself.

The paddle shifters don't make you a faster driver. But they do free up your hands for the things that actually determine where you finish.

The full demo for this article is available on GitHub.

The KMP Bits app is available on App Store and Google Play, built entirely with KMP.