werkator/docs/adrs/0001-2026-06-09.test-framework.md

Test Framework Selection

Status:

• proposed: 2026-06-09
• accepted: 2026-06-09
• rejected: -
• superseded: -

Decision [accepted]: Kotest — Kotlin-native test runner with richer DSL than JUnit 5; paired with MockK, WireMock, and Testcontainers.

Context and Problem Statement

GitTally is a greenfield Kotlin/Spring Boot project. A test framework must be chosen before writing any tests.

The framework shapes how tests are structured, how readable they are, and how well they integrate with the Spring Boot test slice infrastructure.

Technical Background

The JVM test ecosystem offers multiple runners for Kotlin projects. The main candidates are

• JUnit 5 (the de-facto standard on the JVM),

• Kotest (a Kotlin-native framework built on the JUnit 5 platform),

• and Spek 2 (a Kotlin BDD framework).

• All three can coexist with MockK for mocking and WireMock / Testcontainers for integration-level stubs.

Considered Options

• JUnit 5
• Kotest
• Spek 2

JUnit 5

The standard JVM test runner, included transitively via spring-boot-starter-test.

Advantages

• Zero additional dependencies — already on the classpath.
• Universal IDE and tooling support.
• Extensive documentation and community resources.
• Native support for all Spring Boot test slices (@SpringBootTest, @WebMvcTest, etc.).
• No learning curve for developers already familiar with it.

Disadvantages

• Test structure is class-/method-based; nesting requires @Nested inner classes, which is verbose in Kotlin.
• Assertion style (assertEquals, assertThrows) is less expressive than Kotlin-idiomatic alternatives.

Kotest

A Kotlin-native test framework that runs on the JUnit 5 platform engine. Provides multiple spec styles (e.g. DescribeSpec, BehaviorSpec, FunSpec).

Advantages

• Expressive, Kotlin-idiomatic DSL with clean nesting — no @Nested boilerplate.
• Rich built-in assertion library (shouldBe, shouldThrow, etc.) with good error messages.
• Multiple spec styles allow choosing the right level of formality per test type.
• kotest-extensions-spring enables @SpringBootTest and all Spring slices natively.
• Pairs naturally with MockK (both are Kotlin-first).
• Actively maintained with a large community.

Disadvantages

• Additional dependency (kotest-runner-junit5, kotest-assertions-core, kotest-extensions-spring).
• Slightly steeper learning curve if the team is new to it.
• Spring context caching behavior requires awareness of how Kotest manages lifecycle.

Spek 2

A Kotlin BDD framework with a describe/it DSL inspired by RSpec.

Advantages

• Clear BDD-style specification structure.

Disadvantages

• Development has stalled; no meaningful releases in several years.
• Spring Boot integration is not maintained.
• Smaller community; risk of abandonment.

Decision Outcome

Kotest is chosen as the primary test runner and assertion library, supplemented by MockK for mocking, WireMock for HTTP stubbing (Gitea API), and Testcontainers for Docker-based integration tests.

The main reasons:

• Kotest's nested DSL fits Kotlin's concise style better than @Nested inner classes, and its assertion library produces clearer failure messages. The Spring extension covers all Spring Boot test slices, so there is no capability regression compared to JUnit 5. The additional dependency cost is low.
• Spek 2 is excluded due to its abandoned state.

JUnit 5 remains on the classpath (as a transitive dependency and as Kotest's engine), so any JUnit 5 tests can coexist if needed.