testing-strategies

name	testing-strategies
description	Testing patterns for Micronaut/Kotlin backend including repository tests, integration tests, and test data builders. Use when writing tests, setting up test infrastructure, or improving coverage.
allowed_tools	["Read","Write","Edit","Glob","Grep","Bash"]

Testing Strategies — Quick Reference

See integration-test-setup.md for @MicronautTest configuration, Retrofit client setup, and connection pool tuning.

See examples.md for complete code patterns including MockK, test data builders, and assertions.

Integration Tests

Every endpoint needs an integration test. Extend AbstractControllerTest, use Retrofit clients from module-client, and clean up with truncateAllTables() in @AfterEach.

Key rules:

• Always use Retrofit clients — never raw HttpRequest
• Generate real JWT tokens via accessToken()
• Test full HTTP stack end-to-end, no mocking managers

Test Naming

@Test
fun `{action} - {expected outcome}`() = runBlocking { }

// Examples:
fun `getEmployee - returns employee by id`() = runBlocking { }
fun `getEmployee - returns 404 when not found`() = runBlocking { }
fun `createEmployee - fails with 401 when not authenticated`() = runBlocking { }

Required Test Coverage Per Endpoint

1. Happy path — basic success case
2. Not found — 404 for missing resource
3. Auth failure — 401 without token
4. Soft delete — deleted records not returned

@Test
fun `getById - returns 404 when not found`() = runBlocking {
  val token = accessToken(prepareUser())
  assertThrows<HttpException> {
    runBlocking {
      client.getById(authorization = token, id = UUID.randomUUID())
    }
  }.also {
    assertThat(it.code()).isEqualTo(404)
  }
}

Repository Tests

Extend AbstractRepositoryTest. Every repository needs these tests at minimum:

class DefaultEmployeeRepositoryTest : AbstractRepositoryTest() {

  private val repository = DefaultEmployeeRepository(database)

  @BeforeEach
  fun cleanup() { database.primary.truncateAllTables() }

  @Test
  fun `insert - happy path`() { }

  @Test
  fun `byId - returns entity when exists`() { }

  @Test
  fun `byId - returns null when not exists`() { }

  @Test
  fun `byId - returns null when soft deleted`() { }

  @Test
  fun `deleteById - soft deletes entity`() { }

  @Test
  fun `update - updates selected fields`() { }
}

MockK Rules

• mockk<T>() for creating mocks
• coEvery / coVerify for suspend functions (not every/verify)
• slot<T>() + capture() to verify what arguments were passed
• runTest { } from kotlinx.coroutines.test — NOT runBlocking. runTest handles virtual time and catches coroutine issues.
• AAA pattern with comments: // Given, // When, // Then
• Use @Nested + @DisplayName to group related tests

See examples.md for full MockK code examples, @Nested patterns, test data builders, and AssertJ assertions.

Gotchas

Connection pool exhaustion: If parallel tests fail with "cannot acquire connection", bump maxPoolSize to 20. See integration-test-setup.md for the config snippet.

MockK + coroutines: Always use coEvery/coVerify for suspend functions. Plain every/verify won't work and gives confusing errors.

Run Tests

./gradlew test                                                    # All tests
./gradlew test --tests "com.yourcompany.EmployeeControllerTest"   # One class
./gradlew :app:module-repository:test                             # One module