chore: make the test harness loud and rewrite the testing guidance [skip size]

[andresmr]

Draft, and deliberately so. Everything below is done and verified. It is held as a
draft because the coverage work it was originally bundled with went out separately as
#5087, and because the follow-ups in Next are worth doing under the same theme.
Agents picking this up later: read State and Next — they are written for you.

Why

The test harness failed silently in several places, and its testing guidance existed
in three copies that disagreed with the repo.

• useJUnitPlatform() is set nowhere, so a JUnit Jupiter @Test was not "run and
  failed" — it was never collected. The class compiled, the build went green, and no
  result file was written.
• jacoco was pinned to 0.8.10, overriding the catalog.
• There was no single command that meant "what CI runs".
• The guidance taught androidUnitTest/, androidInstrumentedTest/ and
  testAndroidDebugUnitTest — none of which exist in this repository. A test placed
  in one of them is never compiled and never run, and nothing says so.

What changed

One test framework: JUnit4 + kotlin.test

• 3 org.junit.jupiter.api.assertThrows call sites in DataSetTableViewModelTest →
  kotlin.test.assertFailsWith.
• libs.junit.jupiter removed from the androidHostTest sets of login, sync,
  tracker, aggregates; unused koin-test-junit5 removed; both aliases dropped from
  the catalog. koin-test-junit4 kept — GetDataValueInputTest genuinely uses
  KoinTestRule with @get:Rule.
• New guard: org.junit.jupiter is excluded from every configuration whose name
  contains "test".

Verified by making it fail: junit-jupiter was re-added to login's androidHostTest
with a scratch Jupiter test. The exclusion strips it and the build fails with
Unresolved reference 'jupiter'. Scratch reverted.

One command for humans and CI

New verifyAll lifecycle task covering ktlintCheck, testDebugUnitTest,
testDhis2DebugUnitTest, testAndroidHostTest and jacocoReport across every project.
run_tests.sh calls it.

ci.yml is deliberately untouched — its unit-tests job already needs the separate
lint-check job, so swapping the step would run ktlint twice.

The first version of this task was itself a silent-success bug. It resolved to
zero dependencies and still reported BUILD SUCCESSFUL, because
org.gradle.configureondemand=true means the subprojects are not configured while the
root script runs, so eager findByName found nothing. Caught with --dry-run. It now
resolves through a Provider at task-graph time, with a check(resolved.isNotEmpty())
so an empty resolution fails loudly instead of passing vacuously.

JaCoCo unpin

useVersion("0.8.10") removed, and the plugin's toolVersion wired to
libs.versions.jacoco. All 8 modules verified on 0.8.15.

Guidance collapsed into one source of truth

• .github/agents/testing.agent.md → a 30-line pointer stub (was 337 lines).
• AGENTS.md: task names corrected (app → testDhis2DebugUnitTest, other AGP →
  testDebugUnitTest, KMP → testAndroidHostTest for both source sets); tracker
  marked KMP and dhis2-mobile-program-rules a plain com.android.library; the three
  missing modules added; androidUnitTest → androidHostTest; the Repository "required
  imports" snippet replaced with withDomainErrors { }; launchUseCase scoped with the
  140 legacy viewModelScope.launch sites explicitly excluded; Testing section reduced
  to five invariants plus a pointer.
• .claude/skills/android-testing/ — one 441-line SKILL.md became a 122-line router
  plus references/unit-testing.md (new, 11 sections, each citing a real file in this
  repo) and references/instrumented-testing.md (verbatim move).
• Stale tokens cleared from sentry-fix, sentry-triage/repo-map.md,
  test-flow-architect.md and test-flow-planner.

The UseCase example was teaching a bug. It caught Exception, but DomainError
is sealed class DomainError : Throwable(), so that catch does not match and the error
escapes the try. It now catches Throwable and rethrows CancellationException.

The grep gate is self-contradictory, and how that was resolved

The plan wanted zero occurrences of the three dead names repo-wide, while the skill has
to carry an explicit list stating they do not exist — and you cannot write
"androidUnitTest does not exist" without writing androidUnitTest.

The negative list is kept, because naming the wrong token is what makes the warning
usable. The gate is scoped to allow denials and lives in
.claude/skills/android-testing/check-stale-tokens.sh — deliberately a .sh, because
the scan covers .md/.kts/.yml, so keeping the patterns out of a scanned file stops
the gate matching its own source. (The first version documented the command inline in
SKILL.md and promptly flagged itself.)

OK: no document teaches a nonexistent source set or task.

Four claims in the original plan that did not survive checking

1. jacocoReport does not need mustRunAfter. Its dependsOn loop runs inside the
   task's registration action, which Gradle realises after AGP has created the
   unit-test tasks, so findByName resolves them even though apply(from=) precedes the
   android { } block. --dry-run puts testDhis2DebugUnitTest ahead of jacocoReport.
2. Unpinning does not give 0.8.15. libs.jacoco is only on the buildscript classpath;
   the report engine follows the plugin's toolVersion, which falls through to Gradle
   9.5.1's bundled 0.8.14. Hence the explicit wiring.
3. Turbine: login and aggregates declare it in commonTest directly, not "by
   inheritance". The real gaps are sync (only androidHostTest) and commonskmm
   (nowhere).
4. UseCase<R,T> is not confined to login/sync/commonskmm. 33 implementations,
   and app has the most (14).

A correction worth recording

An earlier revision of this PR claimed SonarCloud imported 0% coverage, stated as
"confirmed, not suspected". That was wrong and has been withdrawn. Coverage was being
imported all along. Two bad inferences caused it: reading SonarTask.properties from a
doFirst, which is before the scanner's own property computer fills the map; and reading
six identical warning strings as "all thirteen modules failed" when only the six modules
without a report emit them. The real coverage problems were different, and are fixed in
#5087.

Verification

./gradlew ktlintFormat && ./run_tests.sh
BUILD SUCCESSFUL
Total Tests Run: 1570 | Passed: 1570 | Failed: 0 | Skipped: 0
Modules: all 13

1570 vs the 1267 of a coverage-only run: verifyAll pulls in the five KMP modules'
testAndroidHostTest, which jacocoReport alone never triggered.

State

Everything above is complete, verified and pushed. Nothing here is half-finished. The
coverage work that was originally in this branch is now #5087 and is independent.

Next — for whoever picks this up

Roughly in order of value:

1. ForgotPinUseCase and SavePinUseCase (login) catch Exception, which does not
   match DomainError : Throwable(), so a mapped SDK error escapes uncaught instead of
   becoming Result.failure. AGENTS.md now documents the correct shape while these two
   still violate it. Note mockito's doThrow rejects DomainError — stub with
   thenAnswer { throw error }.
2. Adopt verifyAll in ci.yml, restructuring the lint/unit-test jobs so ktlint is
   not run twice. Deliberately out of scope here.
3. Add Turbine to sync's commonTest and to commonskmm, which has it nowhere.
4. KMP coverage — the 5 KMP modules produce no coverage at all; jacoco is applied to
   the 8 AGP modules only. Kover is the usual answer.
5. Remove continue-on-error: true / if-no-files-found: warn from ci.yml, now
   that coverage genuinely works (fix: [ANDROAPP-7775] report the project's real test coverage #5087). They currently hide exactly the failure this
   whole effort was about.
6. A conventions grep job in CI running check-stale-tokens.sh, so the guidance
   cannot drift back.
7. Longer term: a :testing module for shared fixtures, test-bundle collapse, a new-code
   coverage gate, build-logic.

Working agreement for this branch: if a test problem costs more than ~30 minutes, add
a row to the troubleshooting table in references/unit-testing.md in the same PR. That
rule is written into the skill; it is the mechanism that keeps this from rotting again.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud