# Android App — Test Coverage Plan **Goal:** clear the SonarQube coverage quality gate (`new_coverage ≥ 50%`) for `Runic-Gateway-Android-app`, and leave a durable unit-test culture behind it. Companion to [`PLAN.md`](./PLAN.md) §12.1 (the JaCoCo wiring that made coverage measurable). ## 1. Current state (2026-07-22, post `Android-app#26`) The JaCoCo→Sonar wiring is live on `main`, so coverage is now real — and the gate is **failing**: | Metric | Value | |---|---| | Quality gate | **ERROR** (one condition) | | `new_coverage` | **16.4%** (threshold ≥ 50%) | | overall `coverage` | 16.3% | | lines to cover | 3,188 | | covered | 542 | Everything else on the gate is green (reliability/security/maintainability **A**, duplication 0%). Because this is the *first* measured version, Sonar's "new code" window is essentially the whole codebase, so `new_coverage ≈ overall coverage` — to pass we need to roughly **triple** covered lines, from 542 to ~1,600. ### Where the uncovered lines are Bucketed from Sonar's per-file `uncovered_lines` (exclusions from #26 already applied, so `*Screen.kt` is absent): | Bucket | Files | Lines to cover | Covered % | Verdict | |---|--:|--:|--:|---| | **ViewModels** | 28 | 1,153 | **0.1%** | **Test** — the dominant lever; no ViewModel has any test | | **DTOs** | 12 | 648 | 26.7% | **Test** — trivial (serialization); a pattern already exists | | **Repositories** | 11 | 274 | 11.3% | **Test** — fake the API interface | | **core/\* (logic)** | 21 | 365 | 56.2% | **Test** — top up the partially-covered ones | | UI composables (`*Components.kt`, `BlockRenderer`, …) | 7 | 255 | 3.9% | **Exclude** — not JVM-unit-testable, and `*Screen.kt`'s exclusion missed them | | core/push (Android services) | 4 | ~191 | ~0% | **Exclude** (or Robolectric later) — foreground service / notifications | | core/auth `Encrypted*` stores | 3 | 76 | 0% | **Exclude** — Android Keystore / EncryptedSharedPreferences | | framework glue (`di/`, `RunicGatewayApp`, `LocalAssetResolver`) | 3 | ~17 | 0% | **Exclude** | **Two levers, applied together:** (a) stop *counting* code a JVM unit test physically cannot execute, and (b) actually *test* the logic — ViewModels, DTOs, repositories, core utilities. ## 2. Strategy & projected math Numbers below are line-coverage projections against Sonar's `lines_to_cover`. They are estimates, but grounded in the current per-bucket totals. ### Phase 0 — Broaden coverage exclusions (no tests; ~½ day) Move non-unit-testable code out of the **coverage** denominator (it stays in *analysis* — bugs and smells are still reported). Extend `sonar.coverage.exclusions` in `sonar-project.properties`: ```properties sonar.coverage.exclusions=\ app/src/main/java/**/ui/**/*Screen.kt,\ app/src/main/java/**/ui/**/*Screen*.kt,\ app/src/main/java/**/ui/**/*Components.kt,\ app/src/main/java/**/ui/page/BlockRenderer.kt,\ app/src/main/java/**/ui/components/**,\ app/src/main/java/**/ui/shard/FrameFields.kt,\ app/src/main/java/**/ui/theme/**,\ app/src/main/java/**/ui/LocalAssetResolver.kt,\ app/src/main/java/**/RunicApp.kt,\ app/src/main/java/**/MainActivity.kt,\ app/src/main/java/**/*Application.kt,\ app/src/main/java/**/RunicGatewayApp.kt,\ app/src/main/java/**/di/**,\ app/src/main/java/**/core/push/PushService.kt,\ app/src/main/java/**/core/push/PushManager.kt,\ app/src/main/java/**/core/push/PushNotifier.kt,\ app/src/main/java/**/core/push/NtfyStreamClient.kt,\ app/src/main/java/**/core/auth/Encrypted*.kt ``` > Verify each glob targets composable-only / framework-only files before committing (e.g. confirm > `FrameFields.kt` holds no testable logic). Keep the *pure-logic* push files in coverage > (`PushPreferences`, `PushTickle`, `NtfyTopic`, `PushStreams`) — they already have tests. Effect: denominator ~3,188 → ~2,650; covered ~542 → ~532. **Coverage ≈ 20%.** (Removing ~540 lines that were ~2% covered.) ### Phase 1 — DTO serialization tests (highest ROI; ~1 day) → ~34% DTOs are `@Serializable` data classes; test them with kotlinx-serialization round-trips against representative backend JSON. The pattern already exists (`AccountDtoTest`, `AuthDtoTest`, `NotificationsDtoTest`, `PlayerShardDtoTest`, `ShardDtoTest`). Add/extend: - **New:** `AdminDto` (111 uncov — biggest single file), `WikiDto` (51), `PublicDto` (32), `PageDto` (16), `PostDto` (12), `ContactDto` (11), `SsoDto`, `PageDto`. - **Extend to ~85%:** `PlayerShardDto` (30.8%), `ShardDto` (35.6%), `AccountDto` (50.7%), `AuthDto` (47.4%). Target DTOs to ~85%: **+~380 covered lines** → covered ~912 / ~2,650 ≈ **34%**. ### Phase 2 — ViewModel tests (the big one; ~3–4 days) → clears the gate 28 ViewModels, ~1,153 lines, currently 0%. This is where the gate is won. Requires a small test harness (§3). Each test drives the VM with fake collaborators and asserts `UiState` transitions (loading → success/error, form validation, actions). Priority by uncovered lines: 1. `LoginViewModel` (116), `AccountViewModel` (104), `CharactersViewModel` (77), `AdminContentViewModel` (74), `NotificationsViewModel` (66), `TrustedDevicesViewModel` (63), `ShardViewModel` (59) 2. `HousesViewModel` (51), `GovernorsViewModel` (47), `AdminDashboardViewModel` (43), `AdminSupportViewModel` (41), `ChampsViewModel` (40), `AdminModerationViewModel` (40), `GuildsViewModel` (39), `RecoveryCodesViewModel` (38), `ConnectViewModel` (37), `ContactViewModel` (36), `VendorsViewModel` (32), `AppViewModel` (29) 3. The small ones (`PostViewModel`, `NewsViewModel`, `WikiViewModel`, `CharacterViewModel`, `MyHousesViewModel`, `WikiPageViewModel`, `PageViewModel`, `HomeViewModel`, `SessionViewModel`) Target ViewModels to ~70%: **+~800 covered lines** → covered ~1,712 / ~2,650 ≈ **65%. ✅ Gate passes.** > Phases 0 + 2 alone (skipping DTOs) already reach ~50.5% — but DTOs are cheap insurance and Phase 1 > lands first because it de-risks the harness work. ### Phase 3 — Repository tests (~1–2 days) → margin Repositories map API `Response`/exceptions to `ApiResult`; test with a fake `*Api` interface (or OkHttp `MockWebServer`). Priority: `AuthRepository` (89), `ConnectionRepository` (43), `ShardRepository` (27), `AdminRepository` (21), then the small content/wiki/player repos. Target ~70%: **+~160 lines** → buffer well above 50% and resilience as the new-code window narrows. ### Phase 4 — core/net + core/auth top-up (~½–1 day) → durability Fill the partially-covered utilities: `TokenAuthenticator` (31), `ShardStreamClient` (36), `HostSelectionInterceptor` (9), `ApiResult` (6), `WebHandoff`, `WebsiteUrls`, `DeviceNameProvider`, `ServerPreferences`, `AppConfig`. ### Trajectory | After | Denominator | Covered | Coverage | |---|--:|--:|--:| | Today | 3,188 | 542 | 16.3% | | Phase 0 (exclusions) | ~2,650 | ~532 | ~20% | | Phase 1 (DTOs) | ~2,650 | ~912 | ~34% | | **Phase 2 (ViewModels)** | ~2,650 | ~1,712 | **~65% ✅** | | Phase 3 (repos) | ~2,650 | ~1,872 | ~71% | | Phase 4 (core) | ~2,650 | ~2,000+ | ~75%+ | ## 3. Test infrastructure to add The existing suite tests pure-logic classes only; ViewModel/coroutine testing needs a little scaffold. `kotlinx-coroutines-test` is already a `testImplementation` dependency. **`MainDispatcherRule`** (JUnit4) — swaps `Dispatchers.Main` (used by `viewModelScope`) for a test dispatcher: ```kotlin // app/src/test/java/com/runicgateway/app/util/MainDispatcherRule.kt @OptIn(ExperimentalCoroutinesApi::class) class MainDispatcherRule( private val dispatcher: TestDispatcher = StandardTestDispatcher(), ) : TestWatcher() { override fun starting(d: Description) = Dispatchers.setMain(dispatcher) override fun finished(d: Description) = Dispatchers.resetMain() } ``` **ViewModel test pattern** — hand-written fakes (matches the repo's existing no-mock convention; no new dependency): ```kotlin class LoginViewModelTest { @get:Rule val mainDispatcher = MainDispatcherRule() private class FakeAuthRepository(var result: LoginResult) : AuthRepository { /* stub the seam */ } @Test fun `blank credentials surface INVALID_CREDENTIALS without a network call`() = runTest { val vm = LoginViewModel(FakeAuthRepository(LoginResult.Success), /* … */) vm.submit() assertEquals(LoginError.INVALID_CREDENTIALS, vm.state.value.error) } } ``` - Assert on `viewModel.state.value` after `advanceUntilIdle()`; or collect the `StateFlow` in a background `launch` when you need to see intermediate (loading) states. - **Optional deps (decide once):** `mockk` would cut fake-writing for wide interfaces, and `turbine` simplifies Flow assertions. Recommendation: **stay with hand fakes** to match convention; revisit only if VM tests get boilerplate-heavy. ## 4. Execution notes - CI already runs `./gradlew testDebugUnitTest jacocoTestReport` before the scan (`sonarqube.yml`), so new tests count automatically on merge to `main`. Locally on this machine: JDK 21 needs `-Pksp.incremental=false`. - Sonar recomputes the gate on the post-merge scan; there's no way to fully confirm the number pre-merge. Land phases as separate PRs (0, 1, 2, …) so coverage climbs visibly and reviews stay small. - `sonar.coverage.exclusions` removes files from **coverage only** — analysis still flags bugs/smells in them, so excluding UI/framework code is safe. - **Android-framework code deferred, not abandoned:** push services and `Encrypted*` stores are excluded now; if we want them covered later, add Robolectric (`testImplementation`) and a `RobolectricTestRunner` suite rather than instrumented tests, to keep it in the fast JVM `test` source set the scan already consumes. ## 5. Definition of done - `new_coverage ≥ 50%` and the SonarQube quality gate is **green**. - `MainDispatcherRule` + a documented ViewModel test pattern exist and are reused. - Coverage exclusions list only genuinely non-unit-testable files (UI composables, Android-framework glue) — no ViewModel, repository, DTO, or pure core-logic file is excluded.