@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.1

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

@@ -10,483 +10,189 @@ ViewModel tests with Turbine and TestDispatcher, and screenshot tests with
 Roborazzi/Paparazzi. Targets 2024-2025 testing libraries and Kotlin coroutines
 test APIs.
 
+Full, copyable code for every section below lives in
+[references/patterns.md](references/patterns.md). Load it when you need a
+complete example; this guide keeps the decisions and short snippets.
+
 ## Contents
 
 - [ComposeTestRule Setup](#composetestrule-setup)
 - [Finding Nodes](#finding-nodes)
+- [Test Tags from a Generated Registry](#test-tags-from-a-generated-registry)
 - [Performing Actions](#performing-actions)
 - [Assertions](#assertions)
 - [Testing State Changes](#testing-state-changes)
+- [ViewModel Test Base Class](#viewmodel-test-base-class)
 - [ViewModel Testing with Turbine](#viewmodel-testing-with-turbine)
 - [TestDispatcher and runTest](#testdispatcher-and-runtest)
 - [Screenshot Testing](#screenshot-testing)
+- [Compose Preview Screenshot Testing](#compose-preview-screenshot-testing)
 - [Do's and Don'ts](#dos-and-donts)
 - [Troubleshooting](#troubleshooting)
 - [Review Checklist](#review-checklist)
 
 ## ComposeTestRule Setup
 
-### Unit Tests (No Activity)
+Use `createComposeRule()` for pure composable tests with no activity. Use
+`createAndroidComposeRule<MainActivity>()` for instrumented tests, and pair it
+with `HiltAndroidRule` (ordered rules, `hiltRule.inject()` in `@Before`) when
+the screen needs injected dependencies.
 
 ```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()
-    }
-}
+@get:Rule
+val composeTestRule = createComposeRule()
+// composeTestRule.setContent { AppTheme { PrimaryButton(label = "Book", onClick = {}) } }
 ```
 
-### 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()
-    }
-}
-```
+Full unit and instrumented (Hilt) setups: references/patterns.md#composetestrule-setup
 
 ## Finding Nodes
 
-### Semantic Matchers
+Select nodes by semantics, never by implementation details. Set
+`Modifier.testTag("tag")` on key composables so tests find them reliably.
 
 ```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
+Combined matchers (`hasText and hasClickAction`), `onAllNodesWith*`, parent/child
+traversal, and tag placement: references/patterns.md#finding-nodes
 
-```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"),
-        )
-    }
-}
-```
+## Test Tags from a Generated Registry
 
-## Performing Actions
+Do not scatter tag strings as literals. A production rename then silently orphans
+every test that still passes the old string, and nothing fails to compile. Drive
+the `Modifier.testTag` and the matching `onNodeWithTag` from one generated
+constant so a rename is a compile error. The registry is generated from the
+shared identifier source; the codegen side lives in the
+`android-design-tokens-codegen` skill.
 
 ```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")
+Modifier.testTag(TestTags.FlightCard)
+composeTestRule.onNodeWithTag(TestTags.FlightCard).assertIsDisplayed()
+```
 
-// Scroll to node (in scrollable container)
-composeTestRule.onNodeWithText("Last Item").performScrollTo()
+Full generated-registry and usage example: references/patterns.md#test-tags-from-a-generated-registry
 
-// Scroll to index in LazyColumn
-composeTestRule.onNodeWithTag("flight_list").performScrollToIndex(15)
+## Performing Actions
 
-// Scroll to key in LazyColumn
-composeTestRule.onNodeWithTag("flight_list").performScrollToKey("flight-42")
+Actions run on a resolved node: `performClick()`, `performTextInput(text)`,
+`performTextClearance()` / `performTextReplacement(text)`, `performScrollTo()`,
+`performScrollToIndex(i)` / `performScrollToKey(k)`, and gestures via
+`performTouchInput { swipeLeft(); longClick() }`.
 
-// Swipe gestures
-composeTestRule.onNodeWithTag("card").performTouchInput {
-    swipeLeft()
-    swipeRight()
-    swipeUp()
-    swipeDown()
-}
-
-// Long click
-composeTestRule.onNodeWithTag("item").performTouchInput {
-    longClick()
-}
-```
+Full action reference: references/patterns.md#performing-actions
 
 ## Assertions
 
-```kotlin
-// Existence and visibility
-composeTestRule.onNodeWithText("Title").assertIsDisplayed()
-composeTestRule.onNodeWithText("Title").assertExists()
-composeTestRule.onNodeWithText("Hidden").assertDoesNotExist()
-composeTestRule.onNodeWithText("Hidden").assertIsNotDisplayed()
+Assert through the UI semantics, not internal state:
+`assertIsDisplayed()` / `assertExists()` / `assertDoesNotExist()`,
+`assertTextEquals(...)` / `assertTextContains(...)`,
+`assertIsEnabled()`, `assertIsSelected()`, `assertIsOn()`,
+`assertCountEquals(n)`, `assertIsFocused()`.
 
-// Text content
-composeTestRule.onNodeWithTag("price").assertTextEquals("$299")
-composeTestRule.onNodeWithTag("price").assertTextContains("299")
+Full assertion reference: references/patterns.md#assertions
 
-// Enabled/disabled state
-composeTestRule.onNodeWithText("Submit").assertIsEnabled()
-composeTestRule.onNodeWithText("Submit").assertIsNotEnabled()
+## Testing State Changes
 
-// Selection state
-composeTestRule.onNodeWithText("Economy").assertIsSelected()
-composeTestRule.onNodeWithText("Business").assertIsNotSelected()
+Drive the UI, then assert the visible result. For async updates use
+`waitUntil(timeoutMillis) { ... }` on fetched semantics nodes instead of
+`Thread.sleep`.
 
-// Toggle state
-composeTestRule.onNodeWithTag("wifi_toggle").assertIsOn()
-composeTestRule.onNodeWithTag("wifi_toggle").assertIsOff()
+Full counter and async-filter examples: references/patterns.md#testing-state-changes
 
-// Count assertions
-composeTestRule.onAllNodesWithTag("flight_card").assertCountEquals(5)
+## ViewModel Test Base Class
 
-// Focused state
-composeTestRule.onNodeWithTag("search_field").assertIsFocused()
-```
+Centralize the coroutine setup in one base class every ViewModel test extends:
+`Dispatchers.setMain(UnconfinedTestDispatcher())` in `@Before`, and
+`Dispatchers.resetMain()` plus `unmockkAll()` in `@After`. Add a
+`SavedStateHandle` helper so tests inject route arguments the same way. For a
+type-safe `@Serializable` route, back the handle with the `navigation-testing`
+artifact and read it via `savedStateHandle.toRoute<Route>()`.
 
-## Testing State Changes
+MockK inline mocking (`mockkObject`, `mockkStatic`, mocking `final` classes)
+loads a Byte Buddy agent at runtime. On JDK 21+ dynamic agent attachment is
+restricted, so self-attach fails with an opaque initialization error. Attach the
+agent explicitly with a `-javaagent` JVM arg on the `Test` task instead of
+relying on self-attach.
 
-```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)
-}
-```
+Full base class, route injection, and the `-javaagent` Gradle wiring:
+references/patterns.md#viewmodel-test-base-class
 
 ## ViewModel Testing with Turbine
 
-Turbine provides `test {}` extension on Flow for asserting emissions.
+Turbine's `test {}` extension on a `Flow`/`StateFlow` asserts emissions one at a
+time (`awaitItem()`, `skipItems(n)`, `cancelAndIgnoreRemainingEvents()`). Back
+the ViewModel with a fake repository rather than a mocking framework.
 
 ```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()
-        }
-    }
+viewModel.uiState.test {
+    assertThat(awaitItem()).isEqualTo(HomeUiState.Loading)
+    viewModel.loadFlights("IST", "JFK")
+    assertThat(awaitItem()).isInstanceOf(HomeUiState.Success::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))
-}
-```
+Full ViewModel test and fake repository: references/patterns.md#viewmodel-testing-with-turbine
 
 ## 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
+Run coroutine tests inside `runTest`. Set `Dispatchers.setMain(testDispatcher)`
+in `@Before` and `Dispatchers.resetMain()` in `@After`. Pick one dispatcher per
+test; do not mix them.
 
 | 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
-}
-```
+Dispatcher behavior examples and an injectable `TestDispatcherProvider`:
+references/patterns.md#testdispatcher-and-runtest
 
 ## Screenshot Testing
 
-### Roborazzi (JVM-based, no device required)
+Both frameworks render on the JVM with no device. Roborazzi uses Robolectric and
+captures via `captureRoboImage()`; Paparazzi uses Layoutlib and captures via
+`paparazzi.snapshot { ... }`. Screenshot both light and dark themes and commit
+the baselines.
 
-```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()
-    }
-}
+```bash
+./gradlew recordRoborazziDebug   # or recordPaparazziDebug
+./gradlew verifyRoborazziDebug   # or verifyPaparazziDebug
 ```
 
-### Paparazzi (Layoutlib-based, no device required)
+Full Roborazzi and Paparazzi test classes: references/patterns.md#screenshot-testing
 
-```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)
-            }
-        }
-    }
-}
-```
+## Compose Preview Screenshot Testing
 
-### Gradle Commands
+AGP's first-party Compose Preview screenshot-testing plugin
+(`com.android.compose.screenshot`) renders existing `@Preview` composables and
+diffs them against committed baselines, alongside Paparazzi/Roborazzi rather than
+replacing them. It is still alpha -- pin the plugin version and expect API
+changes. Enable it with `android.experimental.enableScreenshotTest=true`, mark
+previews with `@PreviewTest` under the `screenshotTest` source set, set
+`imageDifferenceThreshold` in the `screenshotTests` DSL, and keep per-flavor
+baselines under `src/<variant>ScreenshotTest/reference/`.
 
 ```bash
-# Roborazzi: record baselines
-./gradlew recordRoborazziDebug
-
-# Roborazzi: verify against baselines
-./gradlew verifyRoborazziDebug
-
-# Paparazzi: record baselines
-./gradlew recordPaparazziDebug
-
-# Paparazzi: verify against baselines
-./gradlew verifyPaparazziDebug
+./gradlew updateDebugScreenshotTest    # record/update baselines
+./gradlew validateDebugScreenshotTest  # validate against baselines
 ```
 
+Full plugin config, `@PreviewTest` previews, and threshold DSL:
+references/patterns.md#compose-preview-screenshot-testing
+
 ## Do's and Don'ts
 
 ### Do's
-- Use `Modifier.testTag()` on key composables for reliable node selection
+- Drive `testTag`/`onNodeWithTag` from a generated registry, not string literals
 - 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`
+- Extend one base class that swaps the main dispatcher and calls `resetMain()` + `unmockkAll()`
+- Attach the Byte Buddy agent via `-javaagent` when MockK does inline mocking on JDK 21+
 - 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
@@ -494,6 +200,7 @@ class FlightCardPaparazziTest {
 ### 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 hardcode `testTag` strings as literals in both production and tests
 - 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
@@ -512,15 +219,18 @@ class FlightCardPaparazziTest {
 | 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` |
+| MockK inline mock init fails on JDK 21+ | Byte Buddy self-attach restricted | Attach the agent via `-javaagent` on the `Test` task |
+| `@PreviewTest` previews not collected | `screenshotTest` source set or flag missing | Set `enableScreenshotTest=true`, place previews under `src/screenshotTest` |
 
 ## Review Checklist
 
-- [ ] Key composables have `Modifier.testTag()` for test discoverability
+- [ ] Key composables have `Modifier.testTag()` from a generated registry, not literals
 - [ ] 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
+- [ ] ViewModel tests extend a base class that swaps/resets `Dispatchers.Main` and calls `unmockkAll()`
+- [ ] MockK inline mocking has the `-javaagent` Byte Buddy wiring for JDK 21+
 - [ ] Fake implementations used for repositories and data sources
-- [ ] Screenshot tests cover light and dark themes
+- [ ] Screenshot tests cover light and dark themes (Paparazzi/Roborazzi and/or AGP `@PreviewTest`)
 - [ ] Screenshot baselines are committed to version control
 - [ ] Each test method tests one behavior/scenario
 - [ ] Test names follow `function_scenario_expected` convention