Kora Testing Junit Kotlin

Kora Testing JUnit (Kotlin)

Kora sub-skill — obey the kora-v1 meta rules on every task: R0 ensure .kora-agent/ docs+examples are cloned · R1 read this sub-skill before writing code · R2 Kora APIs only — no Spring/Micronaut/Quarkus, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

In-process JUnit 5 tests that build a real Kora application Graph at compile time and inject its components into the test. @KoraAppTest reads a @KoraApp interface, builds only the slice of the Graph reachable from the requested @TestComponents, and hands those components to the test. There is no reflection-based runtime container — the same generated *Graph code used in production runs in the test.

Read this first when:

• writing the first component test for a Kora Kotlin service,
• mocking a graph dependency with @MockK + @TestComponent,
• overriding config via KoraAppTestConfigModifier,
• adding or replacing a component via KoraAppTestGraphModifier,
• adding test-only repositories through the TestApplication submodule pattern,
• wiring a PostgreSQL Testcontainer into a @KoraAppTest.

Quick Start

1. Dependencies (build.gradle.kts)

All Kora artifacts inherit their version from the kora-parent BOM — never pin a ru.tinkoff.kora:* version individually.

dependencies {
    // BOM already applied in the project (ru.tinkoff.kora:kora-parent)
    ksp("ru.tinkoff.kora:symbol-processors")

    testImplementation(platform("org.junit:junit-bom:5.13.4"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testImplementation("ru.tinkoff.kora:test-junit5")

    // Kotlin-idiomatic mocking
    testImplementation("io.mockk:mockk:1.13.11")
}

tasks.test {
    useJUnitPlatform()
    testLogging {
        showStandardStreams = true
        events("passed", "skipped", "failed")
        exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
    }
}

ksp("ru.tinkoff.kora:symbol-processors") is mandatory in the main source set — without it no @KoraApp Graph is generated and @KoraAppTest has nothing to load.

2. Component test with a real Graph

@KoraAppTest(Application::class)
class UserServiceComponentTest {

    @TestComponent
    lateinit var userService: UserService

    @Test
    fun createUserWithRealGraph() {
        val result = userService.createUser(UserRequest("John", "john@example.com"))

        assertNotNull(result)
        assertEquals("John", result.name)
    }
}

@KoraAppTest(Application::class) names the @KoraApp interface to build from. @TestComponent on userService both injects the component and makes it a root of the test Graph, so Kora builds UserService and only the dependencies it needs.

3. Component test with a MockK mock

@KoraAppTest(Application::class)
class UserServiceMockTest {

    @MockK
    @TestComponent
    lateinit var userRepository: UserRepository

    @TestComponent
    lateinit var userService: UserService

    @Test
    fun getUserUsesRepositoryMock() {
        val expected = UserResponse("1", "John", "john@example.com", LocalDateTime.now())
        every { userRepository.findById("1") } returns expected

        val result = userService.getUser("1")

        assertEquals(expected, result)
        verify { userRepository.findById("1") }
    }
}

@MockK creates the mock; @TestComponent registers it in the Graph in place of the real UserRepository. The same mock instance is injected into the test field and into every graph component that depends on UserRepository, so userService stays real while its repository is the mock.

Do not add = mockk() next to a @MockK field — the annotation already creates the mock. Do not combine @KoraAppTest with MockKExtension/@ExtendWith(MockKExtension::class); @KoraAppTest owns the mock lifecycle.

References and assets

When to use vs NOT

@KoraAppTest is the strongest in-process signal; black-box tests over the packaged artifact remain the primary source of truth for full-application correctness.

Core patterns

Injection styles

@TestComponent works on fields, the test constructor, and test-method parameters.

// Field
@KoraAppTest(Application::class)
class FieldTest {
    @TestComponent lateinit var userService: UserService
}

// Constructor
@KoraAppTest(Application::class)
class CtorTest(@TestComponent val userService: UserService)

// Method parameter
@KoraAppTest(Application::class)
class MethodTest {
    @Test
    fun example(@TestComponent userService: UserService) { /* ... */ }
}

Inject a tagged component by repeating its @Tag next to the parameter:

@Test
fun example(@Tag(Supplier::class) @TestComponent supplier: Supplier<String>) {
    assertEquals("tag1", supplier.get())
}

Config overrides — KoraAppTestConfigModifier

Implement the interface on the test class (not via the constructor — the modifier must run before injection).

@KoraAppTest(Application::class)
class ConfigTest : KoraAppTestConfigModifier {

    override fun config(): KoraConfigModification =
        KoraConfigModification
            .ofSystemProperty("POSTGRES_JDBC_URL", "jdbc:postgresql://localhost:5432/postgres")
            .withSystemProperty("POSTGRES_USER", "postgres")
            .withSystemProperty("POSTGRES_PASS", "postgres")
}

Other factories: KoraConfigModification.ofResourceFile("application-test.conf") (loads a classpath config) and KoraConfigModification.ofString("""...""") (replaces all config with the given HOCON text). ofSystemProperty/withSystemProperty only substitute ${VAR} placeholders in the default config.

Graph modification — KoraAppTestGraphModifier

Add or replace components that are not declared in the @KoraApp. Implement the interface on the class, never via the constructor.

@KoraAppTest(Application::class)
class GraphAddTest : KoraAppTestGraphModifier {

    override fun graph(): KoraGraphModification =
        KoraGraphModification.create()
            .addComponent(TypeRef.of(Supplier::class.java, Int::class.java), Supplier { Supplier { 1 } })

    @Test
    fun example(@TestComponent supplier: Supplier<Int>) {
        assertEquals(1, supplier.get())
    }
}

Replace a component, optionally deriving the new value from the existing one:

override fun graph(): KoraGraphModification =
    KoraGraphModification.create()
        .replaceComponent(TypeRef.of(Supplier::class.java, Int::class.java)) { graph ->
            @Suppress("UNCHECKED_CAST")
            val existing = graph.getFirst(TypeRef.of(Supplier::class.java, Int::class.java)) as Supplier<Int>
            Supplier { 1 + existing.get() }
        }

addComponent registers a new type; replaceComponent swaps an existing one. graph.getFirst(TypeRef.of(...)) resolves the original component. Prefer @MockK + @TestComponent for plain mock-replacement; reach for the Graph modifier when the replacement type is generic, tagged, or must wrap the real component.

Coroutines

Use runTest for suspend tests and the co* MockK DSL for suspend mocks. See references/coroutines-testing-reference.md.

@KoraAppTest(Application::class)
class UserServiceCoroutineTest {

    @MockK @TestComponent lateinit var userRepository: UserRepository
    @TestComponent lateinit var userService: UserService

    @Test
    fun createUserAsync() = runTest {
        coEvery { userRepository.save(any()) } returns "1"

        val result = userService.createUser(UserRequest("John", "john@example.com"))

        assertNotNull(result)
        coVerify { userRepository.save(any()) }
    }
}

Once-per-class initialization

By default the Graph is rebuilt for every test method. Build it once per class with the standard JUnit annotation:

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@KoraAppTest(Application::class)
class FastTests { /* one Graph for all @Test methods */ }

TestApplication submodule pattern

When tests need components the production @KoraApp does not declare — e.g. a repository with deleteAll() for cleanup — extend the application graph in the test source set. Mark added components @Root so they are not pruned.

@KoraApp
interface TestApplication : Application {

    @Repository
    interface TestUserRepository : JdbcRepository {

        @Query("SELECT id, name, email, created_at FROM users ORDER BY id")
        fun findAll(): List<UserDAO>

        @Query("DELETE FROM users")
        fun deleteAll()
    }

    @Tag(TestApplication::class)
    @Root
    fun testRoot(ignored: TestUserRepository): String = "test-root"
}

Enable submodule generation and run the symbol processor over the test source set in build.gradle.kts:

ksp {
    arg("kora.app.submodule.enabled", "true")
}

dependencies {
    kspTest("ru.tinkoff.kora:symbol-processors")
}

tasks.test {
    exclude("**/\$*") // generated classes start with $ and confuse JUnit discovery
}

Then point the test at the extended graph: @KoraAppTest(TestApplication::class).

Testcontainers integration

Combine @Testcontainers with @KoraAppTest and feed container coordinates through KoraAppTestConfigModifier. Full templates: references/testcontainers-kotlin-reference.md.

@Testcontainers
@KoraAppTest(TestApplication::class)
class UserServiceIntegrationPostgresTest : KoraAppTestConfigModifier {

    companion object {
        @Container
        @JvmStatic
        val POSTGRES = PostgreSQLContainer("postgres:16-alpine")
    }

    @TestComponent lateinit var userService: UserService
    @TestComponent lateinit var testUserRepository: TestApplication.TestUserRepository

    override fun config(): KoraConfigModification =
        KoraConfigModification.ofString(
            """
            db {
              jdbcUrl = ${'$'}{POSTGRES_JDBC_URL}
              username = ${'$'}{POSTGRES_USER}
              password = ${'$'}{POSTGRES_PASS}
              poolName = "kora-test"
            }
            flyway { locations = "db/migration" }
            """.trimIndent()
        )
            .withSystemProperty("POSTGRES_JDBC_URL", POSTGRES.jdbcUrl)
            .withSystemProperty("POSTGRES_USER", POSTGRES.username)
            .withSystemProperty("POSTGRES_PASS", POSTGRES.password)

    @BeforeEach
    fun cleanup() = testUserRepository.deleteAll()

    @Test
    fun createUserShouldPersistUserInDatabase() {
        userService.createUser(UserRequest("John", "john@example.com"))
        assertEquals(1, testUserRepository.findAll().size)
    }
}

Test dependencies for this pattern:

testImplementation("org.testcontainers:postgresql:1.20.4")
testImplementation("org.testcontainers:junit-jupiter:1.20.4")

Mocking framework choice

Both are driven by @TestComponent; the mock is injected into the Graph the same way regardless of framework. Pick one per module and stay consistent.

Common pitfalls