@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/compose-testing/SKILL.md

@@ -0,0 +1,527 @@
+---
+name: compose-testing
+description: "Test Jetpack Compose UI with createComposeRule, semantic matchers (onNodeWithText, onNodeWithTag, onNodeWithContentDescription), actions (performClick, performTextInput, performScrollTo), assertions (assertIsDisplayed, assertExists, assertTextEquals), screenshot testing with Roborazzi or Paparazzi, ViewModel testing with Turbine, TestDispatcher, and runTest patterns. Use when writing Compose UI tests, ViewModel tests, or screenshot tests."
+---
+
+# Compose Testing
+
+Testing patterns for Jetpack Compose covering UI tests with ComposeTestRule,
+ViewModel tests with Turbine and TestDispatcher, and screenshot tests with
+Roborazzi/Paparazzi. Targets 2024-2025 testing libraries and Kotlin coroutines
+test APIs.
+
+## Contents
+
+- [ComposeTestRule Setup](#composetestrule-setup)
+- [Finding Nodes](#finding-nodes)
+- [Performing Actions](#performing-actions)
+- [Assertions](#assertions)
+- [Testing State Changes](#testing-state-changes)
+- [ViewModel Testing with Turbine](#viewmodel-testing-with-turbine)
+- [TestDispatcher and runTest](#testdispatcher-and-runtest)
+- [Screenshot Testing](#screenshot-testing)
+- [Do's and Don'ts](#dos-and-donts)
+- [Troubleshooting](#troubleshooting)
+- [Review Checklist](#review-checklist)
+
+## ComposeTestRule Setup
+
+### Unit Tests (No Activity)
+
+```kotlin
+class ButtonComponentTest {
+
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun primaryButton_displaysLabel() {
+        composeTestRule.setContent {
+            AppTheme {
+                PrimaryButton(label = "Book Flight", onClick = {})
+            }
+        }
+
+        composeTestRule
+            .onNodeWithText("Book Flight")
+            .assertIsDisplayed()
+    }
+}
+```
+
+### Instrumented Tests (With Activity)
+
+```kotlin
+@HiltAndroidTest
+class HomeScreenTest {
+
+    @get:Rule(order = 0)
+    val hiltRule = HiltAndroidRule(this)
+
+    @get:Rule(order = 1)
+    val composeTestRule = createAndroidComposeRule<MainActivity>()
+
+    @Before
+    fun setup() {
+        hiltRule.inject()
+    }
+
+    @Test
+    fun homeScreen_showsTitle() {
+        composeTestRule
+            .onNodeWithText("Home")
+            .assertIsDisplayed()
+    }
+}
+```
+
+## Finding Nodes
+
+### Semantic Matchers
+
+```kotlin
+// By text content
+composeTestRule.onNodeWithText("Book Flight")
+composeTestRule.onNodeWithText("book flight", ignoreCase = true)
+composeTestRule.onNodeWithText("Flight", substring = true)
+
+// By test tag (set via Modifier.testTag("tag"))
+composeTestRule.onNodeWithTag("flight_list")
+
+// By content description (accessibility)
+composeTestRule.onNodeWithContentDescription("Search flights")
+
+// Multiple nodes
+composeTestRule.onAllNodesWithText("Select")
+composeTestRule.onAllNodesWithTag("flight_card")
+
+// Combined matchers
+composeTestRule.onNode(
+    hasText("Book") and hasClickAction()
+)
+
+// Parent/child traversal
+composeTestRule
+    .onNodeWithTag("flight_card")
+    .onChildren()
+    .filterToOne(hasText("IST"))
+```
+
+### Setting Test Tags
+
+```kotlin
+@Composable
+fun FlightCard(flight: Flight, modifier: Modifier = Modifier) {
+    Card(
+        modifier = modifier.testTag("flight_card_${flight.id}"),
+    ) {
+        Text(
+            text = flight.origin,
+            modifier = Modifier.testTag("flight_origin"),
+        )
+    }
+}
+```
+
+## Performing Actions
+
+```kotlin
+// Click
+composeTestRule.onNodeWithText("Book").performClick()
+
+// Text input
+composeTestRule.onNodeWithTag("search_field").performTextInput("Istanbul")
+
+// Clear and replace text
+composeTestRule.onNodeWithTag("search_field").performTextClearance()
+composeTestRule.onNodeWithTag("search_field").performTextReplacement("Ankara")
+
+// Scroll to node (in scrollable container)
+composeTestRule.onNodeWithText("Last Item").performScrollTo()
+
+// Scroll to index in LazyColumn
+composeTestRule.onNodeWithTag("flight_list").performScrollToIndex(15)
+
+// Scroll to key in LazyColumn
+composeTestRule.onNodeWithTag("flight_list").performScrollToKey("flight-42")
+
+// Swipe gestures
+composeTestRule.onNodeWithTag("card").performTouchInput {
+    swipeLeft()
+    swipeRight()
+    swipeUp()
+    swipeDown()
+}
+
+// Long click
+composeTestRule.onNodeWithTag("item").performTouchInput {
+    longClick()
+}
+```
+
+## Assertions
+
+```kotlin
+// Existence and visibility
+composeTestRule.onNodeWithText("Title").assertIsDisplayed()
+composeTestRule.onNodeWithText("Title").assertExists()
+composeTestRule.onNodeWithText("Hidden").assertDoesNotExist()
+composeTestRule.onNodeWithText("Hidden").assertIsNotDisplayed()
+
+// Text content
+composeTestRule.onNodeWithTag("price").assertTextEquals("$299")
+composeTestRule.onNodeWithTag("price").assertTextContains("299")
+
+// Enabled/disabled state
+composeTestRule.onNodeWithText("Submit").assertIsEnabled()
+composeTestRule.onNodeWithText("Submit").assertIsNotEnabled()
+
+// Selection state
+composeTestRule.onNodeWithText("Economy").assertIsSelected()
+composeTestRule.onNodeWithText("Business").assertIsNotSelected()
+
+// Toggle state
+composeTestRule.onNodeWithTag("wifi_toggle").assertIsOn()
+composeTestRule.onNodeWithTag("wifi_toggle").assertIsOff()
+
+// Count assertions
+composeTestRule.onAllNodesWithTag("flight_card").assertCountEquals(5)
+
+// Focused state
+composeTestRule.onNodeWithTag("search_field").assertIsFocused()
+```
+
+## Testing State Changes
+
+```kotlin
+@Test
+fun counter_incrementsOnClick() {
+    composeTestRule.setContent {
+        var count by remember { mutableIntStateOf(0) }
+        Column {
+            Text(text = "Count: $count", modifier = Modifier.testTag("count"))
+            Button(onClick = { count++ }) {
+                Text("Increment")
+            }
+        }
+    }
+
+    composeTestRule.onNodeWithTag("count").assertTextEquals("Count: 0")
+    composeTestRule.onNodeWithText("Increment").performClick()
+    composeTestRule.onNodeWithTag("count").assertTextEquals("Count: 1")
+}
+
+@Test
+fun searchField_filtersResults() {
+    composeTestRule.setContent {
+        AppTheme {
+            SearchScreen(viewModel = fakeViewModel)
+        }
+    }
+
+    composeTestRule.onNodeWithTag("search_input").performTextInput("Istanbul")
+
+    // Wait for async results
+    composeTestRule.waitUntil(timeoutMillis = 5_000) {
+        composeTestRule
+            .onAllNodesWithTag("search_result")
+            .fetchSemanticsNodes()
+            .isNotEmpty()
+    }
+
+    composeTestRule
+        .onAllNodesWithTag("search_result")
+        .assertCountEquals(3)
+}
+```
+
+## ViewModel Testing with Turbine
+
+Turbine provides `test {}` extension on Flow for asserting emissions.
+
+```kotlin
+// build.gradle.kts
+// testImplementation(libs.turbine)
+
+class HomeViewModelTest {
+
+    private val fakeRepository = FakeFlightRepository()
+    private lateinit var viewModel: HomeViewModel
+
+    @Before
+    fun setup() {
+        viewModel = HomeViewModel(
+            getFlightsUseCase = GetFlightsUseCase(fakeRepository),
+        )
+    }
+
+    @Test
+    fun `loadFlights emits loading then success`() = runTest {
+        fakeRepository.setFlights(listOf(testFlight))
+
+        viewModel.uiState.test {
+            // Initial state
+            assertThat(awaitItem()).isEqualTo(HomeUiState.Loading)
+
+            // Trigger load
+            viewModel.loadFlights("IST", "JFK")
+
+            // Success state
+            val success = awaitItem()
+            assertThat(success).isInstanceOf(HomeUiState.Success::class.java)
+            assertThat((success as HomeUiState.Success).flights).hasSize(1)
+
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+
+    @Test
+    fun `loadFlights emits error on failure`() = runTest {
+        fakeRepository.setShouldFail(true)
+
+        viewModel.uiState.test {
+            skipItems(1) // skip Loading
+
+            viewModel.loadFlights("IST", "JFK")
+
+            val error = awaitItem()
+            assertThat(error).isInstanceOf(HomeUiState.Error::class.java)
+
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+}
+```
+
+### Fake Repository
+
+```kotlin
+class FakeFlightRepository : FlightRepository {
+    private val flights = MutableStateFlow<List<Flight>>(emptyList())
+    private var shouldFail = false
+
+    fun setFlights(list: List<Flight>) { flights.value = list }
+    fun setShouldFail(fail: Boolean) { shouldFail = fail }
+
+    override fun getFlights(origin: String, destination: String): Flow<List<Flight>> =
+        if (shouldFail) flow { throw IOException("Network error") }
+        else flights
+
+    override fun searchFlights(query: String, date: LocalDate): Flow<List<Flight>> =
+        flights.map { it.filter { f -> f.origin.code == query } }
+
+    override suspend fun bookFlight(flightId: String): Result<Booking> =
+        if (shouldFail) Result.failure(IOException("Booking failed"))
+        else Result.success(Booking(id = "B1", confirmationCode = "CONF", status = BookingStatus.CONFIRMED))
+}
+```
+
+## TestDispatcher and runTest
+
+Use `runTest` with `StandardTestDispatcher` or `UnconfinedTestDispatcher` to
+control coroutine execution in tests.
+
+```kotlin
+class FlightRepositoryTest {
+
+    private val testDispatcher = StandardTestDispatcher()
+
+    @Before
+    fun setup() {
+        Dispatchers.setMain(testDispatcher)
+    }
+
+    @After
+    fun tearDown() {
+        Dispatchers.resetMain()
+    }
+
+    @Test
+    fun `repository returns cached data`() = runTest {
+        val repo = FlightRepositoryImpl(
+            remoteDataSource = fakeRemote,
+            localDataSource = fakeLocal,
+            flightMapper = FlightMapper(),
+        )
+
+        val result = repo.getFlights("IST", "JFK").first()
+        assertThat(result).hasSize(2)
+    }
+}
+```
+
+### TestDispatcher Comparison
+
+| Dispatcher | Behavior | Use For |
+|------------|----------|---------|
+| `StandardTestDispatcher` | Pauses coroutines; advance manually with `advanceUntilIdle()` | Precise control over execution order |
+| `UnconfinedTestDispatcher` | Runs coroutines eagerly | Simple tests where order does not matter |
+
+```kotlin
+@Test
+fun `standard dispatcher requires manual advance`() = runTest(StandardTestDispatcher()) {
+    var value = 0
+    launch { value = 1 }
+    assertThat(value).isEqualTo(0) // not yet executed
+    advanceUntilIdle()
+    assertThat(value).isEqualTo(1) // now executed
+}
+
+@Test
+fun `unconfined dispatcher runs eagerly`() = runTest(UnconfinedTestDispatcher()) {
+    var value = 0
+    launch { value = 1 }
+    assertThat(value).isEqualTo(1) // already executed
+}
+```
+
+### Injectable DispatcherProvider for Tests
+
+```kotlin
+class TestDispatcherProvider(
+    testDispatcher: TestDispatcher = StandardTestDispatcher(),
+) : DispatcherProvider {
+    override val main: CoroutineDispatcher = testDispatcher
+    override val io: CoroutineDispatcher = testDispatcher
+    override val default: CoroutineDispatcher = testDispatcher
+}
+```
+
+## Screenshot Testing
+
+### Roborazzi (JVM-based, no device required)
+
+```kotlin
+// build.gradle.kts
+// testImplementation(libs.roborazzi)
+// testImplementation(libs.roborazzi.compose)
+
+@RunWith(RobolectricTestRunner::class)
+@GraphicsMode(GraphicsMode.Mode.NATIVE)
+@Config(sdk = [34])
+class FlightCardScreenshotTest {
+
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @get:Rule
+    val roborazziRule = RoborazziRule(
+        options = RoborazziRule.Options(
+            captureType = RoborazziRule.CaptureType.LastImage(),
+        ),
+    )
+
+    @Test
+    fun flightCard_default() {
+        composeTestRule.setContent {
+            AppTheme {
+                FlightCard(flight = previewFlight)
+            }
+        }
+
+        composeTestRule
+            .onNodeWithTag("flight_card")
+            .captureRoboImage()
+    }
+
+    @Test
+    fun flightCard_dark() {
+        composeTestRule.setContent {
+            AppTheme(darkTheme = true) {
+                FlightCard(flight = previewFlight)
+            }
+        }
+
+        composeTestRule
+            .onNodeWithTag("flight_card")
+            .captureRoboImage()
+    }
+}
+```
+
+### Paparazzi (Layoutlib-based, no device required)
+
+```kotlin
+// build.gradle.kts
+// testImplementation(libs.paparazzi)
+
+class FlightCardPaparazziTest {
+
+    @get:Rule
+    val paparazzi = Paparazzi(
+        deviceConfig = DeviceConfig.PIXEL_6,
+        theme = "android:Theme.Material3.Light",
+    )
+
+    @Test
+    fun flightCard_snapshot() {
+        paparazzi.snapshot {
+            AppTheme {
+                FlightCard(flight = previewFlight)
+            }
+        }
+    }
+}
+```
+
+### Gradle Commands
+
+```bash
+# Roborazzi: record baselines
+./gradlew recordRoborazziDebug
+
+# Roborazzi: verify against baselines
+./gradlew verifyRoborazziDebug
+
+# Paparazzi: record baselines
+./gradlew recordPaparazziDebug
+
+# Paparazzi: verify against baselines
+./gradlew verifyPaparazziDebug
+```
+
+## Do's and Don'ts
+
+### Do's
+- Use `Modifier.testTag()` on key composables for reliable node selection
+- Use `waitUntil` for async UI updates instead of `Thread.sleep`
+- Use Turbine `test {}` for StateFlow/Flow assertions in ViewModel tests
+- Use `Dispatchers.setMain(testDispatcher)` in `@Before` and `resetMain()` in `@After`
+- Use fake repositories/data sources instead of mocking frameworks for data layer tests
+- Use `createComposeRule()` (no activity) for pure composable tests
+- Screenshot test both light and dark themes
+
+### Don'ts
+- Do not use `Thread.sleep()` in Compose tests -- use `waitUntil` or `advanceUntilIdle()`
+- Do not find nodes by implementation details (view IDs, class names)
+- Do not test internal state directly -- test through the UI semantics
+- Do not use `Mockito.mock()` on final Kotlin classes without mockito-inline
+- Do not forget `cancelAndIgnoreRemainingEvents()` in Turbine tests
+- Do not mix `StandardTestDispatcher` and `UnconfinedTestDispatcher` in the same test
+- Do not call `setContent` more than once per test
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `ComposeNotIdleException` | Infinite animation or recomposition loop | Use `mainClock.autoAdvance = false` and advance manually |
+| Node not found | Missing `testTag` or text not rendered yet | Add `testTag`, use `waitUntil`, or check lazy loading |
+| `No compose hierarchies found` | `setContent` not called before assertions | Call `composeTestRule.setContent {}` first |
+| Turbine `No value produced` timeout | StateFlow never emitted expected value | Check that the ViewModel action was triggered and dispatcher advanced |
+| Roborazzi images differ on CI | Different JDK/platform rendering | Pin JDK version and use same SDK in CI config |
+| Paparazzi `ClassNotFoundException` | Incompatible AGP version | Check Paparazzi compatibility matrix |
+| Tests pass locally but fail on CI | Locale/timezone differences | Set locale and timezone in test setup or Gradle |
+| `Dispatchers.Main` crash in unit test | Missing `setMain` | Add `Dispatchers.setMain(testDispatcher)` in `@Before` |
+
+## Review Checklist
+
+- [ ] Key composables have `Modifier.testTag()` for test discoverability
+- [ ] No `Thread.sleep()` -- uses `waitUntil` or coroutine test APIs
+- [ ] ViewModel tests use Turbine `test {}` for Flow assertions
+- [ ] Tests set and reset `Dispatchers.Main` with TestDispatcher
+- [ ] Fake implementations used for repositories and data sources
+- [ ] Screenshot tests cover light and dark themes
+- [ ] Screenshot baselines are committed to version control
+- [ ] Each test method tests one behavior/scenario
+- [ ] Test names follow `function_scenario_expected` convention
+- [ ] Instrumented tests use `@HiltAndroidTest` with `HiltAndroidRule`