feat(testing): add shared Compose UI dispatcher handling

(cherry picked from commit 852700df057f1d3c7c564304880439fa0df9aa1f)

Author: wmontwe

core/ui/contract/build.gradle.kts

@@ -16,6 +16,7 @@ kotlin {
 
         commonTest.dependencies {
             implementation(projects.core.testing)
+            implementation(projects.core.ui.testing)
         }
 
         jvmTest.dependencies {

core/ui/contract/src/commonTest/kotlin/net/thunderbird/core/ui/contract/mvi/UnidirectionalViewModelKtTest.kt

@@ -1,7 +1,6 @@
 package net.thunderbird.core.ui.contract.mvi
 
 import androidx.compose.ui.test.ExperimentalTestApi
-import androidx.compose.ui.test.runComposeUiTest
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import assertk.assertThat
@@ -18,13 +17,14 @@ import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.launch
-import kotlinx.coroutines.test.UnconfinedTestDispatcher
+import kotlinx.coroutines.test.StandardTestDispatcher
 import net.thunderbird.core.testing.coroutines.MainDispatcherHelper
+import net.thunderbird.core.ui.testing.ComposeUiTestHarness
 
-class UnidirectionalViewModelKtTest {
+@OptIn(ExperimentalCoroutinesApi::class)
+class UnidirectionalViewModelKtTest : ComposeUiTestHarness() {
 
-    @OptIn(ExperimentalCoroutinesApi::class)
-    val mainDispatcher = MainDispatcherHelper(UnconfinedTestDispatcher())
+    private val mainDispatcher = MainDispatcherHelper(StandardTestDispatcher())
 
     @BeforeTest
     fun setUp() {
@@ -38,7 +38,9 @@ class UnidirectionalViewModelKtTest {
 
     @OptIn(ExperimentalTestApi::class)
     @Test
-    fun `observe should emit state changes, allow event dispatch and expose effects`() = runComposeUiTest {
+    fun `observe should emit state changes, allow event dispatch and expose effects`() = runComposeTest(
+        effectContext = mainDispatcher.testDispatcher,
+    ) {
         val viewModel = TestViewModel()
         val effects = mutableListOf<TestEffect>()
         lateinit var stateDispatch: StateDispatch<TestState, TestEvent>
@@ -56,12 +58,14 @@ class UnidirectionalViewModelKtTest {
 
         // Dispatch an event
         dispatch(TestEvent("Event 1"))
+        waitForIdle()
 
         assertThat(state.value.data).isEqualTo("TestState: Event 1")
         assertThat(effects.last().result).isEqualTo("TestEffect: Event 1")
 
         // Dispatch another event
         dispatch(TestEvent("Event 2"))
+        waitForIdle()
 
         assertThat(state.value.data).isEqualTo("TestState: Event 2")
         assertThat(effects.last().result).isEqualTo("TestEffect: Event 2")

core/ui/testing/README.md

@@ -0,0 +1,96 @@
+# Core UI Testing
+
+This module provides shared test utilities for Compose UI tests.
+
+## Compose UI Test Harness
+
+Use `ComposeUiTestHarness` for tests that exercise Compose UI from common test code.
+
+```kotlin
+class ExampleTest : ComposeUiTestHarness() {
+
+    @Test
+    fun `content is shown`() = runComposeTest {
+        setContent {
+            ExampleContent()
+        }
+
+        onNodeWithText("Example").assertExists()
+    }
+}
+```
+
+The harness wraps the platform-specific `runComposeUiTest` implementation and exposes a common
+`ComposeUiTestScope`.
+
+## Dispatcher Handling
+
+`runComposeTest` mirrors Compose's `runComposeUiTest` dispatcher API:
+
+```kotlin
+fun runComposeTest(
+    effectContext: CoroutineContext = EmptyCoroutineContext,
+    runTestContext: CoroutineContext = EmptyCoroutineContext,
+    testTimeout: Duration = 60.seconds,
+    block: suspend ComposeUiTestScope.() -> Unit,
+)
+```
+
+The harness passes these values to Compose unchanged:
+
+- `effectContext` is used for composition, `LaunchedEffect`, `rememberCoroutineScope`, and the main test clock.
+- `runTestContext` is used for the test block.
+- `testTimeout` controls the timeout for the Compose test.
+
+Do not pass the same `TestDispatcher` or scheduler to both `effectContext` and `runTestContext`. Compose requires these
+contexts to not share a `TestCoroutineScheduler`.
+
+## Standard Dispatcher
+
+Use `StandardTestDispatcher` when the test needs explicit scheduler control. Work is queued, so call `waitForIdle()`
+before asserting results that depend on queued coroutine or Compose work.
+
+```kotlin
+@Test
+fun `event updates state`() = runComposeTest(
+    effectContext = StandardTestDispatcher(),
+) {
+    setContent {
+        Screen()
+    }
+
+    onNodeWithText("Submit").performClick()
+    waitForIdle()
+
+    onNodeWithText("Submitted").assertExists()
+}
+```
+
+## Unconfined Dispatcher
+
+Use `UnconfinedTestDispatcher` when the test benefits from eager execution and does not require explicit scheduler
+control. With this dispatcher, immediate assertions may not need `waitForIdle()`.
+
+```kotlin
+@Test
+fun `event updates state eagerly`() = runComposeTest(
+    effectContext = UnconfinedTestDispatcher(),
+) {
+    setContent {
+        Screen()
+    }
+
+    onNodeWithText("Submit").performClick()
+
+    onNodeWithText("Submitted").assertExists()
+}
+```
+
+## Verification
+
+Run the narrow module checks after changing this module:
+
+```shell
+./gradlew :core:ui:testing:jvmTest :core:ui:testing:testAndroidHostTest
+```
+

core/ui/testing/src/androidMain/kotlin/net/thunderbird/core/ui/testing/ComposeUiTestHarness.android.kt

@@ -2,22 +2,34 @@ package net.thunderbird.core.ui.testing
 
 import androidx.compose.ui.test.ExperimentalTestApi
 import androidx.compose.ui.test.v2.runComposeUiTest
+import kotlin.coroutines.CoroutineContext
+import kotlin.time.Duration
 import org.junit.runner.RunWith
 import org.robolectric.RobolectricTestRunner
 
 /**
  * Android implementation of [ComposeUiTestHarness].
  *
- * It uses Robolectric to run the tests and pro.
+ * It runs Compose UI tests with Robolectric.
  */
 @OptIn(ExperimentalTestApi::class)
 @RunWith(RobolectricTestRunner::class)
 public actual abstract class ComposeUiTestHarness actual constructor() {
 
+    /**
+     * Runs [block] inside `runComposeUiTest`.
+     */
     public actual fun runComposeTest(
-        block: ComposeUiTestScope.() -> Unit,
+        effectContext: CoroutineContext,
+        runTestContext: CoroutineContext,
+        testTimeout: Duration,
+        block: suspend ComposeUiTestScope.() -> Unit,
     ) {
-        runComposeUiTest {
+        runComposeUiTest(
+            effectContext = effectContext,
+            runTestContext = runTestContext,
+            testTimeout = testTimeout,
+        ) {
             AndroidComposeUiTestScope(this).block()
         }
     }

core/ui/testing/src/commonMain/kotlin/net/thunderbird/core/ui/testing/ComposeUiTestHarness.kt

@@ -1,18 +1,34 @@
 package net.thunderbird.core.ui.testing
 
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
+import kotlin.time.Duration
+import kotlin.time.Duration.Companion.seconds
+
 /**
  * Platform-agnostic test harness for Compose UI tests.
  *
- * It wraps the platform-specific implementation of the test harness to allow for consistent testing across platforms.
+ * The harness wraps the platform-specific [androidx.compose.ui.test.v2.runComposeUiTest] implementation and exposes a
+ * common [ComposeUiTestScope].
  */
 public expect abstract class ComposeUiTestHarness() {
 
     /**
-     * Run a compose UI test harness with the provided block.
+     * Runs a Compose UI test.
+     *
+     * The parameters mirror [androidx.compose.ui.test.v2.runComposeUiTest]. [effectContext] is used for composition,
+     * `LaunchedEffect`, `rememberCoroutineScope`, and the main test clock. [runTestContext] is used for the test block.
+     * Compose requires these contexts to not share a [kotlinx.coroutines.test.TestCoroutineScheduler].
      *
+     * @param effectContext The [CoroutineContext] to use for the [androidx.compose.ui.test.v2.runComposeUiTest] implementation.
+     * @param runTestContext The [kotlinx.coroutines.test.StandardTestDispatcher] to use for the [androidx.compose.ui.test.v2.runComposeUiTest] implementation.
+     * @param testTimeout The timeout for the test, defaults to 60 seconds.
      * @param block The block of code to execute within the Compose UI test harness.
      */
     public fun runComposeTest(
-        block: ComposeUiTestScope.() -> Unit,
+        effectContext: CoroutineContext = EmptyCoroutineContext,
+        runTestContext: CoroutineContext = EmptyCoroutineContext,
+        testTimeout: Duration = 60.seconds,
+        block: suspend ComposeUiTestScope.() -> Unit,
     )
 }

core/ui/testing/src/jvmMain/kotlin/net/thunderbird/core/ui/testing/ComposeUiTestHarness.jvm.kt

@@ -2,19 +2,31 @@ package net.thunderbird.core.ui.testing
 
 import androidx.compose.ui.test.ExperimentalTestApi
 import androidx.compose.ui.test.v2.runComposeUiTest
+import kotlin.coroutines.CoroutineContext
+import kotlin.time.Duration
 
 /**
  * JVM implementation of [ComposeUiTestHarness].
  *
- * It uses JUnit to run the tests.
+ * It runs Compose UI tests with JUnit.
  */
 @OptIn(ExperimentalTestApi::class)
 public actual abstract class ComposeUiTestHarness actual constructor() {
 
+    /**
+     * Runs [block] inside `runComposeUiTest`.
+     */
     public actual fun runComposeTest(
-        block: ComposeUiTestScope.() -> Unit,
+        effectContext: CoroutineContext,
+        runTestContext: CoroutineContext,
+        testTimeout: Duration,
+        block: suspend ComposeUiTestScope.() -> Unit,
     ) {
-        runComposeUiTest {
+        runComposeUiTest(
+            effectContext = effectContext,
+            runTestContext = runTestContext,
+            testTimeout = testTimeout,
+        ) {
             JvmComposeUiTestScope(this).block()
         }
     }