Husi Testing

Husi Testing

Husi tests its Kotlin code from composeApp/src/commonTest/ against the desktop JVM target. There is no Android instrumented test suite. Tests follow a strong inject seams + fake them style: the existing suite uses mockk almost nowhere despite it being on the classpath — every reusable test dependency is a hand-rolled Fake* registered through Koin or passed via constructor.

Before writing tests, answer two questions:

1. Does the code under test touch Koin-resolved singletons (Repository, HttpClientFactory, DataStore)? → extend one of the Koin-aware base classes below.
2. Does it use viewModelScope / Dispatchers.IO / delay? → you need a StandardTestDispatcher and runTest(dispatcher.scheduler) { ... advanceUntilIdle() }.

The answers determine the base class and the boilerplate. Don't roll your own.

Toolchain & where things live

Test files mirror the package of the file under test: fr.husi.ui.tools.SpeedTestScreenViewModel → commonTest/kotlin/fr/husi/ui/tools/SpeedTestScreenViewModelTest.kt.

Function names use backticked sentences describing the behaviour, e.g. `setServer with blank value sets urlError`. Match the existing style — see MainViewModelTest.kt, ProfileEditorViewModelTest.kt, the fmt/ tests.

Base class cheat sheet

All three live in composeApp/src/commonTest/kotlin/fr/husi/test/.

The hooks preStartKoin / postStartKoin / preStopKoin / postStopKoin (suspend, all open) are the extension points. HusiHttpKoinTest exposes its own postStartKoinWithHttp() because it already finalises postStartKoin.

Why fakes, not mockk

The codebase uses Fake* classes that implement the production interfaces (FakeRepository, FakeHttpClientFactory, FakeHTTPClient, FakeHTTPRequest, FakeHTTPResponse, FakeURL). They:

• compile-check against the real interface so renaming/refactoring stays sound,
• can be reused across many tests with no per-test setup boilerplate,
• read like a recorder — you assert on lastClient?.lastRequest?.headers["Referer"] instead of decoding verify { … } blocks,
• never require mockkStatic against gobind classes, which is fragile on the desktop JVM.

If you find yourself reaching for mockk, first check whether a fake already exists, or whether the right move is to extract an interface and add a fake to commonTest/kotlin/fr/husi/test/. Treat each new fake as infrastructure for future tests, not just the one you're writing.

Refactoring for testability

When the code you want to test calls a global static (Libcore.xxx) or an internal Kotlin object (DataStore), introduce a DI seam instead of working around it in the test:

1. Interface in commonMain (e.g. fr.husi.libcore.HttpClientFactory) wrapping the static.
2. Default object impl (e.g. LibcoreHttpClientFactory) that just delegates.
3. Koin binding in commonUiModule() (or a new module if domain-specific).
4. Constructor injection on the consumer, with the Koin singleton as the default.
5. Fake in commonTest implementing the same interface; recording inputs, replaying canned outputs. Register it via loadKoinModules(module { single<T> { fake } }) in a base class.

Worked example: HttpClientFactory.kt + LibcoreHttpClientFactory + FakeHttpClientFactory + HusiHttpKoinTest. DataStore itself is not abstracted — it's a Kotlin object backed by DataStore-Preferences, and DataStore.configurationStore.reset() (in postStartKoin) is enough for tests to start clean. Don't replicate that level of plumbing unless you need to.

Inject CoroutineDispatcher (default Dispatchers.IO) on ViewModels that use it explicitly — otherwise advanceUntilIdle() can't drive the background work. Don't inject viewModelScope itself; let StandardTestDispatcher + Dispatchers.setMain (handled by MainDispatcherTest) control it.

Koin registration gotcha for ViewModels with default-valued params. viewModelOf(::FooVM) uses reflection and tries to resolve every constructor parameter from Koin — it ignores Kotlin default values. If your ViewModel takes ioDispatcher: CoroutineDispatcher = Dispatchers.IO (or any other type that isn't bound), viewModelOf blows up at runtime with NoDefinitionFoundException: No definition found for type 'kotlinx.coroutines.CoroutineDispatcher'. Use an explicit factory instead and only pass the things Koin actually has:

viewModel { FooViewModel(httpClientFactory = get()) }

Reserve viewModelOf(...) for ViewModels whose constructor only takes Koin-bound types.

ViewModel test recipe

@OptIn(ExperimentalCoroutinesApi::class)
class FooViewModelTest : HusiKoinMainDispatcherTest() {

    private fun newViewModel() = FooViewModel(
        // Inject the things you faked. Defaults from constructor stay for production.
        ioDispatcher = dispatcher,
    )

    @Test
    fun `setX writes through to state`() = runTest(dispatcher.scheduler) {
        val vm = newViewModel()

        vm.setX("hello")
        advanceUntilIdle()

        assertEquals("hello", vm.uiState.value.x)
    }

    @Test
    fun `doThing emits Snackbar event`() = runTest(dispatcher.scheduler) {
        val vm = newViewModel()

        val event = backgroundScope.async { vm.uiEvent.first() }

        vm.doThing()
        advanceUntilIdle()

        assertIs<FooUiEvent.Snackbar>(event.await())
    }
}

Key points:

• Use runTest(dispatcher.scheduler) — not just runTest {}. Without passing the scheduler, the test dispatcher and viewModelScope end up driven by different clocks and advanceUntilIdle becomes a no-op.
• Collect SharedFlow events with backgroundScope.async { flow.first() } before triggering the emit. _uiEvent defaults to replay = 0; if you start collecting after the emit, you'll deadlock.
• For StateFlow you can read .value directly after advanceUntilIdle() — no collector needed.
• Reset any global object state your test mutates (e.g. DataStore.serviceState) in @AfterTest. HusiHttpKoinTest resets configurationStore; it does not reset serviceState because that's a @Volatile var outside the preference store.

Testing HTTP / Libcore code

If the code calls Libcore.newHttpClient() directly, refactor it to use HttpClientFactory first (see "Refactoring for testability"). Then in the test:

class BarUpdaterTest : HusiHttpKoinTest() {

    @Test
    fun `update issues a GET to the configured URL`() = runTest(dispatcher.scheduler) {
        fakeHttp.nextDownloadBytes = 8 * 1024
        // run code under test
        // …
        val request = assertNotNull(fakeHttp.lastClient?.lastRequest)
        assertEquals("https://example.com/list", request.url)
        assertEquals(fakeHttp.userAgent, request.userAgent)
    }

    @Test
    fun `update surfaces error when execute throws`() = runTest(dispatcher.scheduler) {
        fakeHttp.nextThrowable = IOException("boom")
        // assert the code under test emits whatever error event it should
    }
}

FakeHttpClientFactory supports:

• nextDownloadBytes — total bytes the next response reports through CopyCallback.setLength.
• nextChunkCount — how many CopyCallback.update(n) calls drive the progress callback.
• nextThrowable — when set, the next execute() throws this instead of returning a response.
• lastClient.socks5 / lastRequest.headers / lastRequest.contentZero / lastResponse.closed for assertions on what the production code configured.

Source: composeApp/src/commonTest/kotlin/fr/husi/test/FakeHttpClientFactory.kt.

DataStore in tests

DataStore is a Kotlin object backed by a real persistent file via DataStorePreferenceDataStore. Its file path is resolved through resolveRepository().resolveDatabaseFile(...), which requires Koin to be initialised — that's why ViewModel/updater tests must go through HusiKoinTest or deeper, not MainDispatcherTest alone.

The store's own coroutines (file reads, the write actor) run on Repository.preferenceStoreDispatcher — Dispatchers.IO in production, Dispatchers.Unconfined under FakeRepository, so suspending PreferenceProxy.get() / set() resumes on the calling thread and stays inside the test scheduler. Note the store is created once per process: whichever Repository is registered at the first DataStore touch supplies that dispatcher for the whole test run.

Reset between tests:

override suspend fun postStartKoin() {
    DataStore.configurationStore.reset()
}

HusiHttpKoinTest already does this. If you extend it, you don't have to reset again.

Never rely on a default value implicitly

reset() restores the defaults declared in DataStore.kt, and those defaults are product decisions that get changed. A test that asserts on behaviour gated by a setting it never wrote is asserting on today's default, not on the behaviour it names — the next chore: commit that flips that default breaks the test somewhere far from the change.

Set every setting your assertion depends on, even when the default already matches what you want:

@Test
fun `buildConfig should migrate response-based proxy DNS rules to evaluate then respond`() = runBlocking {
    disableFakeDns() // The rule shape under test only exists without fake DNS.
    // …
}

Guidelines:

• Give the premise a name when several tests share it. ConfigBuilderTest.disableFakeDns() pins enableFakeDns and fakeDNSForAll in one documented place, instead of six scattered set(false) lines that each have to be found again when a third fake-DNS switch appears.

• Pin what the assertion actually depends on, not the whole store. ConfigBuilder reads ~34 settings; pinning all of them in every test buys nothing and hides which one matters.

• Verify the dependency instead of guessing it. Temporarily flip the candidate default in postStartKoin() and run the class — the tests that fail are exactly the ones that were leaning on it:

  ./gradlew :composeApp:desktopTest --tests fr.husi.fmt.ConfigBuilderTest 2>&1 | grep -E 'FAILED$'
  

For non-preference fields (e.g. DataStore.serviceState, which is @Volatile var serviceState), restore them yourself in @AfterTest.

Common pitfalls

• Tests hang or advanceUntilIdle() does nothing. You passed runTest { ... } without dispatcher.scheduler. Use runTest(dispatcher.scheduler) { ... }.
• advanceUntilIdle() returns while the work is still running. It only drains the test scheduler; work that resumes on a real dispatcher is invisible to it, so assertions run mid-flight. DataStore used to do exactly this — Repository.preferenceStoreDispatcher now keeps the preference store on the caller's thread under FakeRepository (see below). For any other hop onto a real dispatcher, either inject the dispatcher (see "Refactoring for testability") or have the function return its Job and join() it.
• uiEvent.first() returns immediately with the wrong event (or never returns). You started collecting after the producer emitted, into a 0-replay SharedFlow. Wrap the collection in backgroundScope.async { flow.first() } before triggering the producer.
• A snapshotFlow { … } collector in the ViewModel never fires. Writing to the Compose state it reads (a TextFieldState, a mutableStateOf) lands in the global snapshot immediately, but the observers behind snapshotFlow only wake on an apply notification. In the app the recomposer sends one every frame; a unit test has no Compose runtime, so it must send its own: Snapshot.sendApplyNotifications() (from androidx.compose.runtime.snapshots) after the write and before advanceUntilIdle(). See commonTest/kotlin/fr/husi/ui/dashboard/DashboardViewModelConnectionListTest.kt.
• DataStore access throws IllegalStateException: KoinApplicationException. You extended MainDispatcherTest instead of HusiKoinMainDispatcherTest. DataStore.configurationStore's factory calls resolveRepository() which needs Koin.
• A test "passes" but only because production code silently swallowed the exception. Inspect the FakeHTTPClient / FakeHTTPRequest recorders — lastClient being null is usually the smoking gun. Treat unread recorders as a smell.
• A test that never touched a setting starts failing after an unrelated chore: commit. It was asserting on a DataStore default. Pin the setting in the test (see "Never rely on a default value implicitly") rather than rewriting the expectation to match the new default — the expectation is usually still right for the scenario the test names.
• Tests pollute each other via DataStore.serviceState or other var globals. Reset them in @AfterTest. The Koin / configurationStore lifecycle resets between tests automatically; loose vars do not.
• Reaching for mockkStatic(Libcore::class). That's a refactor-shaped problem in disguise. Add an interface seam (see the HttpClientFactory worked example) and put the fake in commonTest.
• Forgetting to register a new viewModelOf(::FooViewModel) in commonNavigationModule after switching the Composable to koinViewModel<...>(). The Compose preview will still compile (constructor has defaults) but production will throw NoDefinitionFound at runtime.
• viewModelOf(::FooViewModel) throws NoDefinitionFound for a defaulted constructor param (e.g. CoroutineDispatcher). viewModelOf resolves all params from Koin and doesn't see Kotlin defaults. Switch to viewModel { FooViewModel(httpClientFactory = get()) }.

Reference implementations

• ViewModel + flows + Koin: commonTest/kotlin/fr/husi/ui/MainViewModelTest.kt
• ViewModel without Koin (pure state): commonTest/kotlin/fr/husi/ui/AssetsScreenViewModelTest.kt
• StateFlow isDirty collector pattern: commonTest/kotlin/fr/husi/ui/profile/ProfileEditorViewModelTest.kt
• Pure logic, no base class: commonTest/kotlin/fr/husi/fmt/V2RayFmtTest.kt, commonTest/kotlin/fr/husi/ktx/MapsKtTest.kt
• HTTP-touching code with fakes: commonTest/kotlin/fr/husi/ui/tools/SpeedTestScreenViewModelTest.kt
• Background scheduling: commonTest/kotlin/fr/husi/bg/SubscriptionAutoUpdateTest.kt, RouteAssetAutoUpdateTest.kt

Source layout reminders

• Production seam: composeApp/src/commonMain/kotlin/fr/husi/libcore/HttpClientFactory.kt
• Fakes: composeApp/src/commonTest/kotlin/fr/husi/test/FakeHttpClientFactory.kt
• Base classes:
  • commonTest/kotlin/fr/husi/test/MainDispatcherTest.kt
  • commonTest/kotlin/fr/husi/test/HusiKoinTest.kt
  • commonTest/kotlin/fr/husi/test/HusiKoinMainDispatcherTest.kt
  • commonTest/kotlin/fr/husi/test/HusiHttpKoinTest.kt
• Koin module registering production singletons: composeApp/src/commonMain/kotlin/fr/husi/di/Koin.kt
• ViewModel registry: composeApp/src/commonMain/kotlin/fr/husi/di/Navigation.kt (viewModelOf(::FooViewModel) inside scope<MainScreenScope> { ... })