android-sdd 1.0.0

package/skills/Testing/Integration Testing/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: integration-testing
+description: >
+  Integration testing for Android — testing multiple components together.
+  Load this skill when testing Repository with a real Room database,
+  testing ViewModel with real UseCases, verifying data flow across layers,
+  or using Hilt for test dependency injection.
+---
+
+# Integration Testing
+
+## Overview
+Integration tests verify that multiple components work correctly together. Common targets: Repository + Room (real DB), ViewModel + UseCase + fake Repository, or full data layer with in-memory database. These run on a device or emulator (androidTest) or on JVM with Robolectric.
+
+---
+
+## Core Principles
+
+- Integration tests sit **between unit and UI tests** — test real wiring, fake I/O
+- Use **in-memory Room databases** — fast, no disk I/O, auto-cleaned
+- Use **Hilt testing** — swap real implementations with fakes via `@TestInstallIn`
+- Run on **JVM with Robolectric** where possible — faster than device
+- Keep integration tests **focused** — one subsystem per test class
+
+---
+
+## Dependencies
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    // Instrumented tests (androidTest)
+    androidTestImplementation(libs.hilt.android.testing)
+    kspAndroidTest(libs.hilt.compiler)
+    androidTestImplementation(libs.androidx.test.runner)
+    androidTestImplementation(libs.androidx.test.rules)
+    androidTestImplementation(libs.kotlinx.coroutines.test)
+    androidTestImplementation(libs.turbine)
+
+    // JVM tests with Robolectric (test)
+    testImplementation(libs.robolectric)
+    testImplementation(libs.androidx.test.core)
+}
+```
+
+---
+
+## Repository + Room Integration Test
+
+```kotlin
+// ✅ Test Repository with real in-memory Room database
+@RunWith(AndroidJUnit4::class)
+class UserRepositoryIntegrationTest {
+
+    private lateinit var database: AppDatabase
+    private lateinit var dao: UserDao
+    private lateinit var api: UserApiService
+    private lateinit var repository: UserRepositoryImpl
+
+    @Before
+    fun setup() {
+        val context = ApplicationProvider.getApplicationContext<Context>()
+        database = Room.inMemoryDatabaseBuilder(context, AppDatabase::class.java)
+            .allowMainThreadQueries()   // ✅ allowed in tests only
+            .build()
+        dao = database.userDao()
+        api = mockk()
+        repository = UserRepositoryImpl(dao, api)
+    }
+
+    @After
+    fun teardown() {
+        database.close()
+    }
+
+    @Test
+    fun `getUser caches API response in local database`() = runTest {
+        // Arrange
+        val dto = UserDto(id = "1", name = "Ali", email = "ali@test.com", role = "member")
+        coEvery { api.getUser("1") } returns dto
+
+        // Act — first call fetches from API
+        val result = repository.getUser("1")
+
+        // Assert
+        assertThat(result.isSuccess).isTrue()
+        assertThat(result.getOrNull()?.name).isEqualTo("Ali")
+
+        // Verify cached — second call should not hit API
+        repository.getUser("1")
+        coVerify(exactly = 1) { api.getUser("1") }
+
+        // Verify in DB
+        val cached = dao.getById("1")
+        assertThat(cached).isNotNull()
+        assertThat(cached?.name).isEqualTo("Ali")
+    }
+
+    @Test
+    fun `observeUsers emits updates when database changes`() = runTest {
+        // Arrange
+        repository.observeUsers().test {
+            assertThat(awaitItem()).isEmpty()
+
+            // Act — insert directly into DB
+            dao.insert(UserEntity(id = "1", name = "Ali", email = "ali@test.com", role = "member"))
+
+            // Assert — Flow emits new value
+            val users = awaitItem()
+            assertThat(users).hasSize(1)
+            assertThat(users[0].name).isEqualTo("Ali")
+
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+}
+```
+
+---
+
+## Hilt Integration Test
+
+```kotlin
+// ✅ Replace real dependencies with fakes for specific tests
+
+// 1. Define a fake module
+@Module
+@TestInstallIn(
+    components = [SingletonComponent::class],
+    replaces = [UserRepositoryModule::class]   // replaces real binding
+)
+abstract class FakeUserRepositoryModule {
+    @Binds
+    @Singleton
+    abstract fun bindUserRepository(fake: FakeUserRepository): UserRepository
+}
+
+// 2. Inject fake into test
+@HiltAndroidTest
+class UserListViewModelIntegrationTest {
+
+    @get:Rule(order = 0)
+    val hiltRule = HiltAndroidRule(this)
+
+    @get:Rule(order = 1)
+    val mainDispatcherRule = MainDispatcherRule()
+
+    @Inject lateinit var fakeRepository: FakeUserRepository
+    @Inject lateinit var getUsersUseCase: GetUsersUseCase
+
+    private lateinit var viewModel: UserListViewModel
+
+    @Before
+    fun setup() {
+        hiltRule.inject()
+        viewModel = UserListViewModel(getUsersUseCase)
+    }
+
+    @Test
+    fun `ViewModel reflects repository data changes`() = runTest {
+        viewModel.state.test {
+            assertThat(awaitItem()).isEqualTo(UserListUiState.Loading)
+
+            val users = listOf(User(id = "1", name = "Ali", email = Email("ali@test.com")))
+            fakeRepository.emit(users)
+
+            val success = awaitItem() as UserListUiState.Success
+            assertThat(success.users).isEqualTo(users)
+
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+}
+```
+
+---
+
+## Robolectric (JVM-based Android Tests)
+
+```kotlin
+// ✅ Run Android-dependent tests on JVM — faster than emulator
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class UserRepositoryRobolectricTest {
+
+    private lateinit var database: AppDatabase
+    private lateinit var repository: UserRepositoryImpl
+
+    @Before
+    fun setup() {
+        val context = ApplicationProvider.getApplicationContext<Context>()
+        database = Room.inMemoryDatabaseBuilder(context, AppDatabase::class.java)
+            .allowMainThreadQueries()
+            .build()
+        repository = UserRepositoryImpl(database.userDao(), mockk())
+    }
+
+    @After
+    fun teardown() { database.close() }
+
+    @Test
+    fun `delete user removes from database`() = runTest {
+        // Arrange
+        database.userDao().insert(
+            UserEntity(id = "1", name = "Ali", email = "ali@test.com", role = "member")
+        )
+
+        // Act
+        repository.deleteUser("1")
+
+        // Assert
+        val result = database.userDao().getById("1")
+        assertThat(result).isNull()
+    }
+}
+```
+
+---
+
+## DAO Integration Test
+
+```kotlin
+// ✅ Test DAO queries with real Room in-memory database
+@RunWith(AndroidJUnit4::class)
+class UserDaoTest {
+
+    private lateinit var database: AppDatabase
+    private lateinit var dao: UserDao
+
+    @Before
+    fun setup() {
+        val context = ApplicationProvider.getApplicationContext<Context>()
+        database = Room.inMemoryDatabaseBuilder(context, AppDatabase::class.java)
+            .allowMainThreadQueries()
+            .build()
+        dao = database.userDao()
+    }
+
+    @After
+    fun teardown() { database.close() }
+
+    @Test
+    fun `insert and retrieve user`() = runTest {
+        val entity = UserEntity(id = "1", name = "Ali", email = "ali@test.com", role = "member")
+        dao.insert(entity)
+
+        val retrieved = dao.getById("1")
+        assertThat(retrieved).isEqualTo(entity)
+    }
+
+    @Test
+    fun `observeAll emits empty list initially`() = runTest {
+        dao.observeAll().test {
+            assertThat(awaitItem()).isEmpty()
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+
+    @Test
+    fun `delete removes entity`() = runTest {
+        val entity = UserEntity(id = "1", name = "Ali", email = "ali@test.com", role = "member")
+        dao.insert(entity)
+        dao.deleteById("1")
+
+        assertThat(dao.getById("1")).isNull()
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using real network in integration tests — mock the API layer; only test DB + logic integration
+- Not closing the in-memory database in `@After` — causes resource leaks between tests
+- `allowMainThreadQueries()` in production code — only acceptable in tests
+- Testing too many layers at once — keep each integration test focused on one boundary
+- Slow tests due to full Hilt component initialization — use `@UninstallModules` selectively
+
+---
+
+## Related Skills
+- `unit-testing` — isolated unit tests for individual classes
+- `ui-testing` — Compose UI tests on device/emulator
+- `mocking` — MockK patterns used in integration tests
+- `fake-data` — test data factories
+- `hilt` — Hilt test setup with `@HiltAndroidTest`
+- `room` — Room database under test

package/skills/Testing/Mocking/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: mocking
+description: >
+  Mocking with MockK for Android unit tests.
+  Load this skill when creating mocks, stubs, and spies with MockK,
+  stubbing suspend functions and Flows, verifying interactions,
+  using argument captors, or deciding between mocks and fakes.
+---
+
+# Mocking
+
+## Overview
+MockK is the idiomatic mocking library for Kotlin. It supports suspend functions, coroutines, extension functions, and object mocking — areas where Mockito struggles with Kotlin code. Use mocks to isolate the class under test from its dependencies and verify interactions.
+
+---
+
+## Core Principles
+
+- **Fakes over mocks** for repositories and data sources — fakes are more maintainable
+- **Mocks** for verifying interactions — "was this method called with these arguments?"
+- **Stubs** for providing return values — "when called, return this"
+- **Never mock what you don't own** — mock your own interfaces, not third-party classes
+- `coEvery` / `coVerify` for suspend functions — never use `every`/`verify` for coroutines
+
+---
+
+## Creating Mocks
+
+```kotlin
+// ✅ Create mock
+val repository = mockk<UserRepository>()
+
+// ✅ Relaxed mock — returns default values without explicit stubs
+val repository = mockk<UserRepository>(relaxed = true)
+
+// ✅ Relaxed Unit mock — only relaxes Unit-returning functions
+val repository = mockk<UserRepository>(relaxUnitFun = true)
+
+// ✅ Spy — wraps real object, overrides only stubbed methods
+val realRepository = UserRepositoryImpl(dao, api)
+val spy = spyk(realRepository)
+```
+
+---
+
+## Stubbing
+
+```kotlin
+// ✅ Stub regular function
+every { repository.getCount() } returns 5
+every { repository.getCount() } returns 5 andThen 10   // different on subsequent calls
+every { repository.getCount() } throws RuntimeException("error")
+
+// ✅ Stub suspend function
+coEvery { repository.getUser("1") } returns Result.success(user)
+coEvery { repository.getUser("1") } throws IOException("Network error")
+coEvery { repository.getUser(any()) } returns Result.failure(Exception("Not found"))
+
+// ✅ Stub Flow
+every { repository.observeUsers() } returns flowOf(listOf(user))
+every { repository.observeUsers() } returns flow {
+    emit(emptyList())
+    delay(100)
+    emit(listOf(user))
+}
+
+// ✅ Stub with argument matching
+coEvery { repository.getUser(match { it.startsWith("user_") }) } returns Result.success(user)
+coEvery { repository.getUser(any()) } returns Result.failure(Exception())
+
+// ✅ Stub with answer (access arguments)
+coEvery { repository.getUser(any()) } answers {
+    val id = firstArg<String>()
+    Result.success(User(id = id, name = "User $id", email = Email("$id@test.com")))
+}
+
+// ✅ Unit-returning suspend — use coJustRun
+coJustRun { repository.deleteUser(any()) }
+
+// ✅ Non-suspend Unit — use justRun
+justRun { analytics.log(any()) }
+```
+
+---
+
+## Verification
+
+```kotlin
+// ✅ Verify call was made
+verify { repository.getCount() }
+coVerify { repository.getUser("1") }
+
+// ✅ Verify call count
+verify(exactly = 1) { repository.getCount() }
+verify(exactly = 0) { repository.getCount() }   // never called
+verify(atLeast = 1) { repository.getCount() }
+verify(atMost = 2)  { repository.getCount() }
+
+// ✅ Verify with argument matchers
+coVerify { repository.getUser(eq("1")) }
+coVerify { repository.getUser(any()) }
+coVerify { repository.getUser(match { it.isNotEmpty() }) }
+
+// ✅ Verify order
+verifyOrder {
+    repository.getCount()
+    repository.getUser("1")
+}
+
+// ✅ Verify sequence (exactly in order, no other calls)
+verifySequence {
+    repository.getCount()
+    repository.getUser("1")
+}
+
+// ✅ Verify no interactions
+verify { repository wasNot Called }
+confirmVerified(repository)   // all interactions accounted for
+```
+
+---
+
+## Argument Captors
+
+```kotlin
+// ✅ Capture arguments for complex assertions
+val userSlot = slot<User>()
+coEvery { repository.createUser(capture(userSlot)) } returns Result.success(user)
+
+viewModel.onCreateUser("Ali", "ali@test.com")
+
+assertThat(userSlot.captured.name).isEqualTo("Ali")
+assertThat(userSlot.captured.email.value).isEqualTo("ali@test.com")
+
+// ✅ Capture multiple calls
+val capturedIds = mutableListOf<String>()
+coEvery { repository.getUser(captureMany = capturedIds) } returns Result.success(user)
+```
+
+---
+
+## Mocking Objects and Companions
+
+```kotlin
+// ✅ Mock Kotlin object
+mockkObject(DateUtils)
+every { DateUtils.now() } returns Instant.parse("2024-01-01T00:00:00Z")
+// ... test ...
+unmockkObject(DateUtils)
+
+// ✅ Mock companion object
+mockkObject(User.Companion)
+every { User.Companion.create(any()) } returns mockUser
+
+// ✅ Mock top-level functions
+mockkStatic("com.example.app.utils.ExtensionsKt")
+every { anyString().toFormattedDate() } returns "Jan 1, 2024"
+```
+
+---
+
+## Clearing Mocks
+
+```kotlin
+// ✅ Clear recorded calls (keep stubs)
+clearMocks(repository, answers = false)
+
+// ✅ Clear stubs and calls
+clearMocks(repository)
+
+// ✅ Clear all mocks in a test class
+@AfterEach
+fun teardown() {
+    clearAllMocks()
+}
+
+// ✅ Unmock objects
+@AfterEach
+fun teardown() {
+    unmockkAll()
+}
+```
+
+---
+
+## Mocks vs Fakes Decision Guide
+
+| Scenario | Use |
+|---|---|
+| Repository with simple CRUD | Fake |
+| Repository — verify specific API calls | Mock |
+| External service (Analytics, Firebase) | Mock |
+| Database layer in integration test | Real (in-memory Room) |
+| Verifying a method was called N times | Mock |
+| Controlling returned data in multiple tests | Fake |
+
+```kotlin
+// ✅ Fake — simpler, no verify needed
+class FakeUserRepository : UserRepository {
+    private val _users = MutableStateFlow<List<User>>(emptyList())
+    var shouldFail = false
+
+    override fun observeUsers() = _users.asStateFlow()
+    override suspend fun getUser(id: String) =
+        if (shouldFail) Result.failure(Exception("error"))
+        else _users.value.find { it.id == id }
+            ?.let { Result.success(it) }
+            ?: Result.failure(Exception("not found"))
+
+    fun emit(users: List<User>) { _users.value = users }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- `every` for suspend functions — use `coEvery`; `every` will not work correctly
+- `verify` for suspend functions — use `coVerify`
+- Mocking data classes — just create them directly
+- Over-verifying — only verify interactions that matter for the behavior being tested
+- Not clearing mocks between tests — stale stubs cause test pollution
+
+---
+
+## Related Skills
+- `unit-testing` — full unit test structure using MockK
+- `fake-data` — building fake implementations and test data
+- `integration-testing` — when to use fakes vs mocks