@rosetears/aili-pi 0.1.0

package/skills/android-native-dev/references/testing.md

@@ -0,0 +1,554 @@
+# Testing
+
+Detailed examples and patterns for each Android test layer. Read the section relevant to the layer you're working with.
+
+## Table of Contents
+
+1. [Local Unit Tests (JUnit + Robolectric)](#1-local-unit-tests-junit--robolectric)
+2. [Instrumentation Tests (Espresso)](#2-instrumentation-tests-espresso)
+3. [UI Automator (Cross-App & System UI)](#3-ui-automator-cross-app--system-ui)
+4. [Compose UI Testing](#4-compose-ui-testing)
+5. [Gradle Managed Devices](#5-gradle-managed-devices)
+
+---
+
+## 1. Local Unit Tests (JUnit + Robolectric)
+
+Local tests live in `src/test/` and run on the JVM — no emulator needed, so they're fast (milliseconds each). Use them for ViewModels, Repositories, mappers, validators, and any pure logic.
+
+### Basic ViewModel Test
+
+```kotlin
+class CounterViewModelTest {
+    @get:Rule
+    val mainDispatcherRule = MainDispatcherRule()  // see below
+
+    private lateinit var viewModel: CounterViewModel
+
+    @Before
+    fun setup() {
+        viewModel = CounterViewModel()
+    }
+
+    @Test
+    fun `increment updates count`() = runTest {
+        viewModel.increment()
+        assertEquals(1, viewModel.uiState.value.count)
+    }
+}
+```
+
+### Testing Coroutines (Critical)
+
+The Main dispatcher doesn't exist on the JVM. Replace it with `TestDispatcher` or tests crash with `IllegalStateException`.
+
+```kotlin
+// Reusable rule — put in a shared test-util module
+class MainDispatcherRule(
+    private val dispatcher: TestDispatcher = UnconfinedTestDispatcher()
+) : TestWatcher() {
+    override fun starting(description: Description) {
+        Dispatchers.setMain(dispatcher)
+    }
+    override fun finished(description: Description) {
+        Dispatchers.resetMain()
+    }
+}
+```
+
+```kotlin
+// ❌ Wrong: No Main dispatcher replacement → crash
+@Test
+fun `load data`() = runTest {
+    val vm = MyViewModel(repo)
+    vm.load()  // launches on Dispatchers.Main → IllegalStateException
+}
+
+// ✅ Correct: Use MainDispatcherRule
+@get:Rule
+val mainDispatcherRule = MainDispatcherRule()
+
+@Test
+fun `load data`() = runTest {
+    val vm = MyViewModel(repo)
+    vm.load()
+    assertEquals(UiState.Success, vm.uiState.value)
+}
+```
+
+### Testing StateFlow with Turbine
+
+```kotlin
+@Test
+fun `loading then success states`() = runTest {
+    val vm = MyViewModel(fakeRepo)
+
+    vm.uiState.test {   // Turbine extension
+        assertEquals(UiState.Idle, awaitItem())
+        vm.load()
+        assertEquals(UiState.Loading, awaitItem())
+        assertEquals(UiState.Success(data), awaitItem())
+        cancelAndIgnoreRemainingEvents()
+    }
+}
+```
+
+### Mocking with MockK
+
+```kotlin
+@Test
+fun `repository calls api and caches`() = runTest {
+    val api = mockk<UserApi>()
+    coEvery { api.getUser("42") } returns User("42", "Alice")
+
+    val repo = UserRepository(api)
+    val user = repo.getUser("42")
+
+    assertEquals("Alice", user.name)
+    coVerify(exactly = 1) { api.getUser("42") }
+}
+```
+
+| MockK Function | Purpose                |
+|----------------|------------------------|
+| `mockk<T>()`  | Create mock instance   |
+| `every { }`   | Stub synchronous calls |
+| `coEvery { }` | Stub suspend functions |
+| `verify { }`  | Verify call happened   |
+| `coVerify { }` | Verify suspend call   |
+| `slot<T>()`   | Capture argument value |
+
+### Robolectric — When You Need Android Classes
+
+Robolectric simulates the Android framework on the JVM, so tests stay fast while accessing `Context`, `SharedPreferences`, resources, etc.
+
+```kotlin
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class PreferencesManagerTest {
+
+    private lateinit var context: Context
+
+    @Before
+    fun setup() {
+        context = ApplicationProvider.getApplicationContext()
+    }
+
+    @Test
+    fun `saves and reads theme preference`() {
+        val prefs = PreferencesManager(context)
+        prefs.setDarkMode(true)
+        assertTrue(prefs.isDarkMode())
+    }
+}
+```
+
+### Common Local Test Mistakes
+
+```kotlin
+// ❌ Wrong: Testing implementation details (fragile)
+@Test
+fun `check internal cache map size`() {
+    repo.load()
+    assertEquals(1, repo.cacheMap.size)  // breaks if cache strategy changes
+}
+
+// ✅ Correct: Test observable behavior
+@Test
+fun `second call returns cached result without network`() = runTest {
+    coEvery { api.fetch() } returns data
+
+    repo.load()
+    repo.load()
+
+    coVerify(exactly = 1) { api.fetch() }  // only one network call
+}
+```
+
+---
+
+## 2. Instrumentation Tests (Espresso)
+
+Instrumentation tests live in `src/androidTest/` and run on a real device or emulator. Slower than local tests, but they exercise the actual Android stack — use them for UI flows, database integration, and cross-component interaction.
+
+### Test Runner Setup
+
+In `app/build.gradle.kts`:
+
+```kotlin
+android {
+    defaultConfig {
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+}
+```
+
+### Espresso Basics
+
+Espresso's API follows a consistent pattern: **find → act → assert**.
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class LoginScreenTest {
+
+    @get:Rule
+    val activityRule = ActivityScenarioRule(LoginActivity::class.java)
+
+    @Test
+    fun validLogin_navigatesToHome() {
+        // Find and act
+        onView(withId(R.id.email_input))
+            .perform(typeText("user@example.com"), closeSoftKeyboard())
+        onView(withId(R.id.password_input))
+            .perform(typeText("secret123"), closeSoftKeyboard())
+        onView(withId(R.id.login_button))
+            .perform(click())
+
+        // Assert
+        onView(withId(R.id.home_container))
+            .check(matches(isDisplayed()))
+    }
+}
+```
+
+| Category   | Common Matchers / Actions                                                          |
+|------------|------------------------------------------------------------------------------------|
+| **Find**   | `withId(R.id.x)`, `withText("x")`, `withContentDescription("x")`, `withHint("x")` |
+| **Act**    | `click()`, `typeText("x")`, `clearText()`, `scrollTo()`, `swipeUp()`              |
+| **Assert** | `isDisplayed()`, `withText("x")`, `isEnabled()`, `isChecked()`, `doesNotExist()`  |
+
+### Testing Intents
+
+Espresso-Intents lets you verify outgoing Intents and stub responses (e.g., camera, file picker).
+
+```kotlin
+@get:Rule
+val intentsRule = IntentsRule()
+
+@Test
+fun shareButton_launchesShareIntent() {
+    onView(withId(R.id.share_button)).perform(click())
+
+    intended(allOf(
+        hasAction(Intent.ACTION_SEND),
+        hasType("text/plain")
+    ))
+}
+
+@Test
+fun cameraButton_handlesResult() {
+    val resultData = Intent().apply { putExtra("photo_uri", "content://mock") }
+    intending(hasAction(MediaStore.ACTION_IMAGE_CAPTURE))
+        .respondWith(Instrumentation.ActivityResult(RESULT_OK, resultData))
+
+    onView(withId(R.id.camera_button)).perform(click())
+    onView(withId(R.id.photo_preview)).check(matches(isDisplayed()))
+}
+```
+
+### IdlingResource for Async Operations
+
+Espresso waits for the UI thread and AsyncTask by default, but not for custom async work (Retrofit, coroutines, etc.). `IdlingResource` tells Espresso when your app is busy.
+
+```kotlin
+// In production code (thin wrapper)
+object NetworkIdlingResource {
+    private val counter = CountingIdlingResource("Network")
+    fun increment() = counter.increment()
+    fun decrement() = counter.decrement()
+    fun get(): IdlingResource = counter
+}
+
+// In test setup
+@Before
+fun registerIdling() {
+    IdlingRegistry.getInstance().register(NetworkIdlingResource.get())
+}
+
+@After
+fun unregisterIdling() {
+    IdlingRegistry.getInstance().unregister(NetworkIdlingResource.get())
+}
+```
+
+---
+
+## 3. UI Automator (Cross-App & System UI)
+
+UI Automator can interact with any visible UI — system dialogs, notifications, other apps. Use it when Espresso can't reach outside your app's process.
+
+| Use Case                     | Why UI Automator                       |
+|------------------------------|----------------------------------------|
+| Runtime permission dialogs   | System UI, outside app process         |
+| Notification actions         | System notification shade              |
+| Device settings interaction  | Settings app                           |
+| Multi-app workflows          | e.g., share to another app and return  |
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class PermissionFlowTest {
+
+    private lateinit var device: UiDevice
+
+    @Before
+    fun setup() {
+        device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
+    }
+
+    @Test
+    fun grantsCameraPermission_andOpensCamera() {
+        // Trigger permission request from within your app
+        onView(withId(R.id.camera_button)).perform(click())
+
+        // Handle the system permission dialog via UI Automator
+        val allowButton = device.findObject(
+            By.res("com.android.permissioncontroller:id/permission_allow_foreground_only_button")
+        )
+        allowButton?.click()
+
+        // Back in Espresso territory — verify the camera view appeared
+        onView(withId(R.id.camera_preview)).check(matches(isDisplayed()))
+    }
+
+    @Test
+    fun notificationTap_opensDetail() {
+        // Open notification shade
+        device.openNotification()
+        device.wait(Until.hasObject(By.textStartsWith("New message")), 5000)
+
+        // Tap the notification
+        val notification = device.findObject(By.textStartsWith("New message"))
+        notification.click()
+
+        // Verify deep-link target
+        onView(withId(R.id.message_detail)).check(matches(isDisplayed()))
+    }
+}
+```
+
+---
+
+## 4. Compose UI Testing
+
+Compose has its own testing framework that works with the semantic tree rather than the view hierarchy. Tests can run as local tests (with Robolectric) or instrumentation tests — the API is the same.
+
+### Basic Setup
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class GreetingScreenTest {
+
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun displaysGreeting_andRespondsToClick() {
+        composeTestRule.setContent {
+            MyAppTheme {
+                GreetingScreen(name = "World")
+            }
+        }
+
+        composeTestRule.onNodeWithText("Hello, World!")
+            .assertIsDisplayed()
+
+        composeTestRule.onNodeWithText("Say Hi")
+            .performClick()
+
+        composeTestRule.onNodeWithText("Hi back!")
+            .assertIsDisplayed()
+    }
+}
+```
+
+### Finders, Assertions & Actions
+
+| Category   | API                                          | Example                         |
+|------------|----------------------------------------------|---------------------------------|
+| **Find**   | `onNodeWithText("x")`                       | Matches visible text            |
+|            | `onNodeWithTag("x")`                        | Matches `Modifier.testTag("x")` |
+|            | `onNodeWithContentDescription("x")`         | Matches semantics label         |
+|            | `onAllNodesWithTag("x")`                    | Returns list of matches         |
+| **Assert** | `assertIsDisplayed()`                        | Node is visible                 |
+|            | `assertTextEquals("x")`                     | Exact text match                |
+|            | `assertIsEnabled()` / `assertIsNotEnabled()` | Enabled state                  |
+|            | `assertDoesNotExist()`                       | Node not in tree               |
+|            | `assertCountEquals(n)`                       | For `onAllNodes`               |
+| **Act**    | `performClick()`                             | Tap                             |
+|            | `performTextInput("x")`                     | Type into text field            |
+|            | `performScrollTo()`                          | Scroll node into view          |
+|            | `performTouchInput { swipeUp() }`           | Gestures                        |
+
+### Using testTag for Reliable Selectors
+
+Text-based finders break with localization or copy changes. Use `testTag` for stable selectors:
+
+```kotlin
+// ❌ Fragile: breaks if text changes or app is localized
+composeTestRule.onNodeWithText("Submit Order").performClick()
+
+// ✅ Stable: testTag doesn't change with locale
+composeTestRule.onNodeWithTag("submit_order_button").performClick()
+```
+
+```kotlin
+// In production Composable
+Button(
+    onClick = { /* ... */ },
+    modifier = Modifier.testTag("submit_order_button")
+) {
+    Text(stringResource(R.string.submit_order))
+}
+```
+
+### Testing with Activity Context
+
+When your Composable needs a `ComponentActivity` (e.g., for `viewModel()` or navigation), use `createAndroidComposeRule`:
+
+```kotlin
+@get:Rule
+val composeTestRule = createAndroidComposeRule<MainActivity>()
+
+@Test
+fun fullScreen_endToEnd() {
+    // Activity is already launched — interact with the real content
+    composeTestRule.onNodeWithTag("login_email")
+        .performTextInput("user@test.com")
+    composeTestRule.onNodeWithTag("login_password")
+        .performTextInput("pass123")
+    composeTestRule.onNodeWithTag("login_submit")
+        .performClick()
+
+    composeTestRule.waitUntil(timeoutMillis = 5000) {
+        composeTestRule.onAllNodesWithTag("home_screen")
+            .fetchSemanticsNodes().isNotEmpty()
+    }
+
+    composeTestRule.onNodeWithTag("home_screen")
+        .assertIsDisplayed()
+}
+```
+
+### Testing Navigation
+
+```kotlin
+@Test
+fun navigatesToDetail_onItemClick() {
+    val navController = TestNavHostController(ApplicationProvider.getApplicationContext())
+
+    composeTestRule.setContent {
+        navController.navigatorProvider.addNavigator(ComposeNavigator())
+        MyAppNavHost(navController = navController)
+    }
+
+    // Click item on list screen
+    composeTestRule.onNodeWithTag("item_0").performClick()
+
+    // Verify navigation destination
+    assertEquals("detail/0", navController.currentBackStackEntry?.destination?.route)
+}
+```
+
+### Common Compose Test Mistakes
+
+```kotlin
+// ❌ Wrong: Asserting immediately after async operation
+composeTestRule.onNodeWithTag("submit").performClick()
+composeTestRule.onNodeWithText("Success").assertIsDisplayed()  // may fail — UI hasn't updated yet
+
+// ✅ Correct: Wait for the UI to settle
+composeTestRule.onNodeWithTag("submit").performClick()
+composeTestRule.waitForIdle()
+composeTestRule.onNodeWithText("Success").assertIsDisplayed()
+
+// ✅ Also correct: waitUntil for longer async work
+composeTestRule.onNodeWithTag("submit").performClick()
+composeTestRule.waitUntil(timeoutMillis = 3000) {
+    composeTestRule.onAllNodesWithText("Success")
+        .fetchSemanticsNodes().isNotEmpty()
+}
+```
+
+---
+
+## 5. Gradle Managed Devices
+
+Define emulator profiles in `build.gradle.kts` so anyone (including CI) can run instrumentation tests without manually creating AVDs. Gradle downloads the system image, creates the emulator, runs tests, and tears it down automatically.
+
+### Device Configuration
+
+In `app/build.gradle.kts`:
+
+```kotlin
+android {
+    testOptions {
+        managedDevices {
+            localDevices {
+                create("pixel6Api34") {
+                    device = "Pixel 6"
+                    apiLevel = 34
+                    systemImageSource = "aosp-atd"  // ATD = faster, headless
+                }
+                create("pixel4Api30") {
+                    device = "Pixel 4"
+                    apiLevel = 30
+                    systemImageSource = "aosp-atd"
+                }
+                create("smallTabletApi34") {
+                    device = "Nexus 7"
+                    apiLevel = 34
+                    systemImageSource = "google"     // full Google APIs image
+                }
+            }
+
+            // Group devices for matrix testing
+            groups {
+                create("phoneTests") {
+                    targetDevices.add(devices["pixel6Api34"])
+                    targetDevices.add(devices["pixel4Api30"])
+                }
+                create("allDevices") {
+                    targetDevices.add(devices["pixel6Api34"])
+                    targetDevices.add(devices["pixel4Api30"])
+                    targetDevices.add(devices["smallTabletApi34"])
+                }
+            }
+        }
+    }
+}
+```
+
+### System Image Sources
+
+| Source         | Description                                       | Best For                     |
+|----------------|---------------------------------------------------|------------------------------|
+| `"aosp-atd"`   | Automated Test Device — minimal, no Play Services | Fast CI, pure logic tests    |
+| `"google-atd"` | ATD with Google APIs                              | Tests needing Maps, Firebase |
+| `"aosp"`       | Full AOSP image                                   | Standard emulator testing    |
+| `"google"`     | Full image with Google Play Services              | Play Services integration    |
+
+ATD images boot faster and consume less memory because they strip out UI chrome and preinstalled apps irrelevant to testing. Prefer `aosp-atd` or `google-atd` for CI pipelines.
+
+### Running Tests
+
+```bash
+# Run on a single managed device
+./gradlew pixel6Api34DebugAndroidTest
+
+# Run on a device group (all devices in parallel if hardware allows)
+./gradlew phoneTestsGroupDebugAndroidTest
+./gradlew allDevicesGroupDebugAndroidTest
+
+# With specific flavor
+./gradlew pixel6Api34DevDebugAndroidTest
+
+# Enable test sharding across devices (speeds up large suites)
+./gradlew allDevicesGroupDebugAndroidTest \
+    -Pandroid.experimental.androidTest.numManagedDeviceShards=2
+
+# Generate HTML test report
+./gradlew pixel6Api34DebugAndroidTest \
+    --continue   # don't stop on first failure
+```
+
+Test results are written to `app/build/reports/androidTests/managedDevice/`.