build: migrate to ScalaTest and Scoverage, replacing JaCoCo across modules

2026-03-22 15:28:02 +01:00
parent 5a21e57ca9
commit 551e08cef3
13 changed files with 1357 additions and 143 deletions
@@ -0,0 +1,85 @@
+# Design: Add ScalaTest + Replace JaCoCo with Scoverage
+
+**Date:** 2026-03-22
+**Status:** Approved
+
+## Summary
+
+Replace the current JUnit-only test setup and JaCoCo coverage with ScalaTest (via its JUnit 5 bridge) and Scoverage across both `modules/core` and `modules/api`.
+
+## Motivation
+
+- The CLAUDE.md working agreement prescribes `AnyFunSuite with Matchers with JUnitSuiteLike` as the unit test style, which requires ScalaTest.
+- Scoverage is the standard Scala code coverage tool and understands Scala semantics; JaCoCo's JVM bytecode instrumentation is less accurate for Scala code.
+
+## Scope
+
+Two modules are affected: `modules/core` and `modules/api`. The root `build.gradle.kts` is updated for shared dependency versions only.
+
+## Changes
+
+### Root `build.gradle.kts`
+
+Add to the `versions` map (dependency versions only — plugin version is hardcoded per module, see note below):
+- `SCALATEST` → `3.2.19`
+- `SCALATESTPLUS_JUNIT5` → `3.2.19.1`
+
+> **Note on plugin versioning:** Gradle resolves the `plugins {}` block before `rootProject.extra` is available, so the Scoverage plugin version (`8.1`) must be declared inline in each module's `plugins {}` block. It cannot be read from the root versions map.
+
+### `modules/core/build.gradle.kts` and `modules/api/build.gradle.kts`
+
+Both modules require the same set of changes. Both currently have **two separate `tasks.test {}` blocks** that must be merged into one.
+
+**Plugins block:**
+- Remove `jacoco`
+- Add `id("org.scoverage") version "8.1"`
+
+**Dependencies block:**
+- Remove `testImplementation(platform("org.junit:junit-bom:5.10.0"))`
+- Remove `testImplementation("org.junit.jupiter:junit-jupiter")`
+- Remove `testRuntimeOnly("org.junit.platform:junit-platform-launcher")`
+- Add `testImplementation("org.scalatest:scalatest_3:${versions["SCALATEST"]!!}")`
+- Add `testImplementation("org.scalatestplus:junit-5-11_3:${versions["SCALATESTPLUS_JUNIT5"]!!}")`
+
+**Task wiring — merge both `tasks.test {}` blocks into one and replace jacoco wiring:**
+
+Both `modules/core` and `modules/api` currently have two `tasks.test {}` blocks. Delete both and replace with the following single merged block placed **after** the `dependencies {}` block (conventional position):
+
+```kotlin
+tasks.test {
+    useJUnitPlatform()   // required — scalatestplus JUnit 5 bridge relies on this
+    finalizedBy(tasks.reportScoverage)
+}
+tasks.reportScoverage {
+    dependsOn(tasks.test)
+}
+```
+
+> Note: `modules/api` does not currently have `useJUnitPlatform()` — it must be **added** (not just kept) in the merged block.
+
+Remove the `jacocoTestReport` task block entirely from both modules.
+
+**Task name confirmation:** The Scoverage Gradle plugin 8.1 registers `reportScoverage` as the HTML report task.
+
+## Versions
+
+| Artifact | Version | Notes |
+|---|---|---|
+| `org.scalatest:scalatest_3` | 3.2.19 | Core ScalaTest for Scala 3 |
+| `org.scalatestplus:junit-5-11_3` | 3.2.19.1 | JUnit 5.11 runner bridge; `.1` = build 1 |
+| Scoverage Gradle plugin | 8.1 | Hardcoded inline in `plugins {}` block |
+
+## Testing the Change
+
+After applying:
+1. `./gradlew :modules:core:test` and `./gradlew :modules:api:test` must pass (green, even with zero test files).
+2. `./gradlew :modules:core:reportScoverage` must produce a coverage report.
+3. `./gradlew build` must be fully green.
+
+## Files Modified
+
+- `build.gradle.kts` (root) — add two version entries
+- `modules/core/build.gradle.kts` — plugin, deps, merge two `tasks.test` blocks, replace jacoco wiring
+- `modules/api/build.gradle.kts` — plugin, deps, merge two `tasks.test` blocks, add `useJUnitPlatform()`, replace jacoco wiring
+
+No new source files are created.