In this guide (20 items)

Testing Strategy

MANDATORY FOR ALL AI AGENTS: Every new feature MUST include tests at the appropriate layer. You MUST write tests BEFORE implementation when possible (TDD). Unit tests for domain and use cases are NON-NEGOTIABLE. Architecture tests (ArchUnit) MUST pass before any PR is merged. Do NOT skip testing under any circumstance.

This guide details the testing strategies and tools used to ensure quality in our hexagonal architecture, covering everything from isolated unit tests to end-to-end integration tests with Karate and Testcontainers.

1. Testing Strategy by Layer

Following the principles of hexagonal architecture, tests are divided according to the layer and its responsibility:

Layer	Test Type	Tools	Focus
Domain	Unit Test	JUnit 5	Pure business logic, entities, and Value Objects. No mocks in domain – use real instances.
Application	Unit Test	JUnit 5, MockK / Mockito	Use case orchestration. Mocking of outbound ports.
Infrastructure – Driven (outbound) Adapters	Integration Test	JUnit 5, Testcontainers	Verification of technical implementations (DB, Kafka, API Clients).
Infrastructure – Entry Points (driving/inbound adapters)	Functional / E2E Test	Karate DSL	Entry points (REST/GraphQL) are driving adapters inside `infrastructure.entry.points` (see §6 ArchUnit), not a separate layer. Full flows from entry points to persistence/messaging.

2. TDD Workflow for Hexagonal Architecture

Test-Driven Development follows the Red-Green-Refactor cycle. In a hexagonal architecture, the workflow is:

Step 1: RED – Write a failing test for the port interface

Kotlin:

1
class CreateOrganizationUseCaseTest {
2
    private val repository = mockk<OrganizationRepositoryPort>()
3
    private val useCase = CreateOrganizationUseCase(repository)
4

5
    @Test
6
    fun `should create organization with ACTIVE status`() {
7
        // Given
8
        val command = CreateOrganizationCommand(
9
            name = "Acme Corp",
10
            contactName = "John",
11
            contactLastName = "Doe",
12
            contactEmail = "john@acme.com",
13
            contactPhone = "+1234567890"
14
        )
15
        every { repository.save(any()) } answers { firstArg() }
16

17
        // When
18
        val result = useCase.execute(command)
19

20
        // Then
21
        assertEquals("Acme Corp", result.name)
22
        assertEquals(OrganizationStatus.ACTIVE, result.status)
23
        verify(exactly = 1) { repository.save(any()) }
24
    }
25
}

Java:

1
class CreateOrganizationUseCaseTest {
2
    private final OrganizationRepositoryPort repository = mock(OrganizationRepositoryPort.class);
3
    private final CreateOrganizationUseCase useCase = new CreateOrganizationUseCase(repository);
4

5
    @Test
6
    @DisplayName("should create organization with ACTIVE status")
7
    void shouldCreateOrganizationWithActiveStatus() {
8
        // Given
9
        var command = new CreateOrganizationCommand(
10
            "Acme Corp", "John", "Doe", "john@acme.com", "+1234567890"
11
        );
12
        when(repository.save(any())).thenAnswer(invocation -> invocation.getArgument(0));
13

14
        // When
15
        var result = useCase.execute(command);
16

17
        // Then
18
        assertEquals("Acme Corp", result.getName());
19
        assertEquals(OrganizationStatus.ACTIVE, result.getStatus());
20
        verify(repository, times(1)).save(any());
21
    }
22
}

Step 2: GREEN – Implement the use case to pass the test

Write the minimal use case implementation that makes the test pass.

Step 3: REFACTOR – Clean up while keeping tests green

Improve code structure, naming, and remove duplication without changing behavior.

3. Unit Testing

Unit tests must be fast and should not depend on frameworks like Spring.

Domain Layer

Focus on business rules in entities and domain services.

No mocks in domain: If an entity depends on another, use real instances.
State: Verify that the entity state changes correctly.

Kotlin:

1
class OrganizationTest {
2
    @Test
3
    fun `should change status with withStatus`() {
4
        val org = Organization(
5
            id = UUID.randomUUID(),
6
            name = "Acme",
7
            contactName = "John",
8
            contactLastName = "Doe",
9
            contactEmail = "john@acme.com",
10
            contactPhone = "+1234567890",
11
            status = OrganizationStatus.ACTIVE
12
        )
13

14
        val updated = org.withStatus(OrganizationStatus.INACTIVE)
15

16
        assertEquals(OrganizationStatus.INACTIVE, updated.status)
17
    }
18

19
    @Test
20
    fun `should throw when changing to same status`() {
21
        val org = Organization(
22
            id = UUID.randomUUID(),
23
            name = "Acme",
24
            contactName = "John",
25
            contactLastName = "Doe",
26
            contactEmail = "john@acme.com",
27
            contactPhone = "+1234567890",
28
            status = OrganizationStatus.ACTIVE
29
        )
30

31
        assertThrows<IllegalStateException> {
32
            org.withStatus(OrganizationStatus.ACTIVE)
33
        }
34
    }
35
}

Java:

1
class OrganizationTest {
2
    @Test
3
    @DisplayName("should change status with withStatus")
4
    void shouldChangeStatusWithWithStatus() {
5
        var org = new Organization(
6
            UUID.randomUUID(), "Acme", "John", "Doe",
7
            "john@acme.com", "+1234567890", OrganizationStatus.ACTIVE
8
        );
9

10
        var updated = org.withStatus(OrganizationStatus.INACTIVE);
11

12
        assertEquals(OrganizationStatus.INACTIVE, updated.getStatus());
13
    }
14

15
    @Test
16
    @DisplayName("should throw when changing to same status")
17
    void shouldThrowWhenChangingToSameStatus() {
18
        var org = new Organization(
19
            UUID.randomUUID(), "Acme", "John", "Doe",
20
            "john@acme.com", "+1234567890", OrganizationStatus.ACTIVE
21
        );
22

23
        assertThrows(IllegalStateException.class, () ->
24
            org.withStatus(OrganizationStatus.ACTIVE)
25
        );
26
    }
27
}

Application Layer (Use Cases)

Test orchestration. Mocks are used for ports (interfaces).

Kotlin:

1
class CreateInvoiceUseCaseTest {
2
    private val transaction = mockk<TransactionPort<Invoice>>()
3
    private val repository = mockk<InvoiceRepositoryPort>()
4
    private val outbox = mockk<OutboxRepositoryPort>(relaxed = true)
5
    private val events = OutboxEventFactory("test-service", EventMessageFactory("test-service"))
6
    private val useCase = CreateInvoiceUseCase(transaction, repository, outbox, events)
7

8
    @Test
9
    fun `should save aggregate and enqueue outbox event in same transaction`() {
10
        // Given
11
        val command = CreateInvoiceCommand(/* params */, traceId = "t-1")
12
        every { transaction.run(any()) } answers { firstArg<() -> Invoice>().invoke() }
13
        every { repository.save(any()) } returns mockInvoice
14

15
        // When
16
        val result = useCase.execute(command)
17

18
        // Then
19
        verify { repository.save(any()) }
20
        verify { outbox.save<OutboxMessage<EventMessage<InvoiceCreatedPayload>>>(match { it.topic == "platform.invoices" }) }
21
        assertNotNull(result)
22
    }
23
}

Java:

1
class CreateInvoiceUseCaseTest {
2
    private final TransactionPort<Invoice> transaction = mock();
3
    private final InvoiceRepositoryPort repository = mock();
4
    private final OutboxRepositoryPort outbox = mock();
5
    private final OutboxEventFactory events =
6
        new OutboxEventFactory("test-service", new EventMessageFactory("test-service"));
7
    private final CreateInvoiceUseCase useCase =
8
        new CreateInvoiceUseCase(transaction, repository, outbox, events);
9

10
    @Test
11
    @DisplayName("should save aggregate and enqueue outbox event in same transaction")
12
    void shouldEnqueueOutboxEvent() {
13
        var command = new CreateInvoiceCommand(/* params */);
14
        when(transaction.run(any())).thenAnswer(i -> ((Supplier<Invoice>) i.getArgument(0)).get());
15
        when(repository.save(any())).thenReturn(mockInvoice);
16

17
        var result = useCase.execute(command);
18

19
        verify(repository).save(any());
20
        verify(outbox).save(argThat(msg -> msg.getTopic().equals("platform.invoices")));
21
        assertNotNull(result);
22
    }
23
}

4. Integration Testing with Testcontainers

Testcontainers is used for testing infrastructure adapters with real instances of databases, brokers, or external services, ensuring that our technical implementations work against the actual technology.

Database Integration Test (PostgreSQL)

Kotlin:

1
@Testcontainers
2
class InvoiceRepositoryAdapterTest {
3

4
    companion object {
5
        @Container
6
        val postgres = PostgreSQLContainer("postgres:17-alpine")
7
            .withDatabaseName("testdb")
8
            .withUsername("user")
9
            .withPassword("password")
10

11
        @JvmStatic
12
        @DynamicPropertySource
13
        fun properties(registry: DynamicPropertyRegistry) {
14
            registry.add("spring.datasource.url", postgres::getJdbcUrl)
15
            registry.add("spring.datasource.username", postgres::getUsername)
16
            registry.add("spring.datasource.password", postgres::getPassword)
17
        }
18
    }
19

20
    @Test
21
    fun `should save and find invoice`() {
22
        // Test logic using the real database
23
    }
24
}

Java:

1
@Testcontainers
2
class InvoiceRepositoryAdapterTest {
3

4
    @Container
5
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17-alpine")
6
            .withDatabaseName("testdb")
7
            .withUsername("user")
8
            .withPassword("password");
9

10
    @DynamicPropertySource
11
    static void properties(DynamicPropertyRegistry registry) {
12
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
13
        registry.add("spring.datasource.username", postgres::getUsername);
14
        registry.add("spring.datasource.password", postgres::getPassword);
15
    }
16

17
    @Test
18
    @DisplayName("should save and find invoice")
19
    void shouldSaveAndFindInvoice() {
20
        // Test logic using the real database
21
    }
22
}

Messaging Integration Test (Kafka)

Kotlin:

1
@Testcontainers
2
class KafkaPublisherAdapterTest {
3

4
    companion object {
5
        @Container
6
        val kafka = KafkaContainer("apache/kafka:3.8.0")
7

8
        @JvmStatic
9
        @DynamicPropertySource
10
        fun registerKafkaProperties(registry: DynamicPropertyRegistry) {
11
            registry.add("spring.kafka.bootstrap-servers", kafka::getBootstrapServers)
12
        }
13
    }
14

15
    // Test logic...
16
}

Java:

1
@Testcontainers
2
class KafkaPublisherAdapterTest {
3

4
    @Container
5
    static KafkaContainer kafka = new KafkaContainer("apache/kafka:3.8.0");
6

7
    @DynamicPropertySource
8
    static void registerKafkaProperties(DynamicPropertyRegistry registry) {
9
        registry.add("spring.kafka.bootstrap-servers", kafka::getBootstrapServers);
10
    }
11

12
    // Test logic...
13
}

5. Functional Testing with Karate

Karate is used for black-box testing over entry-points (REST/GraphQL). These tests validate that the complete system works as expected.

Folder Structure

Karate tests usually reside in the bootstrap module or a dedicated acceptance-tests module.

1
src/test/resources/karate/
2
  +-- features/
3
  |   +-- create-invoice.feature
4
  +-- karate-config.js

Feature Example (REST)

1
Feature: Invoice Management
2

3
  Background:
4
    * url baseUrl
5
    * def payload = read('classpath:json/invoice-request.json')
6

7
  Scenario: Create an invoice successfully
8
    Given path '/api/v1/invoices'
9
    And request payload
10
    When method post
11
    Then status 201
12
    And match response.id == '#present'
13
    And match response.status == 'CREATED'

6. Architecture Testing with ArchUnit

To ensure that hexagonal architecture rules are not violated (e.g., domain depending on infrastructure), we use ArchUnit. These tests run as part of the regular test suite and enforce architectural boundaries at build time.

Concrete Example (from this project)

The following tests are implemented and enforced in this project at bootstrap/src/test/kotlin/com/example/platform/architecture/HexagonalArchitectureTest.kt. Every new module MUST pass all 6 tests.

Kotlin (actual project implementation):

1
class HexagonalArchitectureTest {
2
    companion object {
3
        private lateinit var importedClasses: JavaClasses
4

5
        @JvmStatic
6
        @BeforeAll
7
        fun setup() {
8
            importedClasses =
9
                ClassFileImporter()
10
                    .withImportOption(ImportOption.DoNotIncludeTests())
11
                    .importPackages("com.example.platform")
12
        }
13
    }
14

15
    @Test
16
    @DisplayName("Driven adapters (outbound) should not depend on domain commands")
17
    fun `driven adapters should not depend on domain commands`() {
18
        noClasses()
19
            .that()
20
            .resideInAPackage("..infrastructure.driven.adapters..")
21
            .should()
22
            .dependOnClassesThat()
23
            .resideInAPackage("..domain.command..")
24
            .because(
25
                "Commands are application-layer DTOs that should flow from entry points to use cases. " +
26
                    "Driven adapters should only work with domain entities, not commands."
27
            ).check(importedClasses)
28
    }
29

30
    @Test
31
    @DisplayName("Driven adapters should not access use case implementations directly")
32
    fun `driven adapters should not access use case implementations directly`() {
33
        noClasses()
34
            .that()
35
            .resideInAPackage("..infrastructure.driven.adapters..")
36
            .should()
37
            .accessClassesThat()
38
            .resideInAPackage("..usecase..")
39
            .andShould()
40
            .notBeInterfaces()
41
            .because(
42
                "Driven adapters should only implement port interfaces, " +
43
                    "not access use case implementation classes directly."
44
            ).allowEmptyShould(true)
45
            .check(importedClasses)
46
    }
47

48
    @Test
49
    @DisplayName("Domain should not depend on infrastructure")
50
    fun `domain should not depend on infrastructure`() {
51
        noClasses()
52
            .that()
53
            .resideInAPackage("..domain..")
54
            .should()
55
            .dependOnClassesThat()
56
            .resideInAPackage("..infrastructure..")
57
            .because(
58
                "The domain layer is the core of the application and should be completely independent. " +
59
                    "It should not have any dependencies on infrastructure concerns."
60
            ).check(importedClasses)
61
    }
62

63
    @Test
64
    @DisplayName("Domain should not depend on application use cases")
65
    fun `domain should not depend on application use cases`() {
66
        noClasses()
67
            .that()
68
            .resideInAPackage("..domain..")
69
            .should()
70
            .dependOnClassesThat()
71
            .resideInAPackage("..usecase..")
72
            .because(
73
                "The domain layer should not depend on application-specific use case orchestration. " +
74
                    "Use cases orchestrate domain entities, not the other way around."
75
            ).check(importedClasses)
76
    }
77

78
    @Test
79
    @DisplayName("Application use cases should not depend on infrastructure")
80
    fun `application use cases should not depend on infrastructure`() {
81
        noClasses()
82
            .that()
83
            .resideInAPackage("..usecase..")
84
            .should()
85
            .dependOnClassesThat()
86
            .resideInAPackage("..infrastructure..")
87
            .because(
88
                "Use cases should depend only on domain entities and port interfaces, " +
89
                    "not on concrete infrastructure implementations."
90
            ).check(importedClasses)
91
    }
92

93
    @Test
94
    @DisplayName("Entry points should not depend on driven adapters")
95
    fun `entry points should not depend on driven adapters`() {
96
        noClasses()
97
            .that()
98
            .resideInAPackage("..infrastructure.entry.points..")
99
            .should()
100
            .dependOnClassesThat()
101
            .resideInAPackage("..infrastructure.driven.adapters..")
102
            .because(
103
                "Entry points (driving adapters) should only depend on use case ports. " +
104
                    "They should not have direct dependencies on driven adapters."
105
            ).check(importedClasses)
106
    }
107
}

Java equivalent:

1
class HexagonalArchitectureTest {
2
    private static JavaClasses importedClasses;
3

4
    @BeforeAll
5
    static void setup() {
6
        importedClasses = new ClassFileImporter()
7
                .withImportOption(new ImportOption.DoNotIncludeTests())
8
                .importPackages("com.example.platform");
9
    }
10

11
    @Test
12
    @DisplayName("Driven adapters should not depend on domain commands")
13
    void drivenAdaptersShouldNotDependOnDomainCommands() {
14
        noClasses()
15
            .that().resideInAPackage("..infrastructure.driven.adapters..")
16
            .should().dependOnClassesThat().resideInAPackage("..domain.command..")
17
            .because("Commands are application-layer DTOs that should flow from entry points to use cases.")
18
            .check(importedClasses);
19
    }
20

21
    @Test
22
    @DisplayName("Domain should not depend on infrastructure")
23
    void domainShouldNotDependOnInfrastructure() {
24
        noClasses()
25
            .that().resideInAPackage("..domain..")
26
            .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
27
            .because("The domain layer should be completely independent of infrastructure.")
28
            .check(importedClasses);
29
    }
30

31
    @Test
32
    @DisplayName("Domain should not depend on application use cases")
33
    void domainShouldNotDependOnUseCases() {
34
        noClasses()
35
            .that().resideInAPackage("..domain..")
36
            .should().dependOnClassesThat().resideInAPackage("..usecase..")
37
            .because("Use cases orchestrate domain entities, not the other way around.")
38
            .check(importedClasses);
39
    }
40

41
    @Test
42
    @DisplayName("Application use cases should not depend on infrastructure")
43
    void useCasesShouldNotDependOnInfrastructure() {
44
        noClasses()
45
            .that().resideInAPackage("..usecase..")
46
            .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
47
            .because("Use cases should depend only on domain entities and port interfaces.")
48
            .check(importedClasses);
49
    }
50

51
    @Test
52
    @DisplayName("Entry points should not depend on driven adapters")
53
    void entryPointsShouldNotDependOnDrivenAdapters() {
54
        noClasses()
55
            .that().resideInAPackage("..infrastructure.entry.points..")
56
            .should().dependOnClassesThat().resideInAPackage("..infrastructure.driven.adapters..")
57
            .because("Entry points should only depend on use case ports.")
58
            .check(importedClasses);
59
    }
60

61
    @Test
62
    @DisplayName("Driven adapters should not access use case implementations directly")
63
    void drivenAdaptersShouldNotAccessUseCaseImplementations() {
64
        noClasses()
65
            .that().resideInAPackage("..infrastructure.driven.adapters..")
66
            .should().dependOnClassesThat().resideInAPackage("..usecase..")
67
            .because("Driven adapters implement output ports; they must not reach into use case implementations.")
68
            .check(importedClasses);
69
    }
70
}

Running ArchUnit Tests

# Run only architecture tests
./gradlew :bootstrap:test --tests "com.example.platform.architecture.*"

# Run all bootstrap tests (includes architecture tests)
./gradlew :bootstrap:test

Rules Enforced

Rule	What It Prevents
Domain must not depend on Infrastructure	Database, Kafka, or HTTP imports in domain classes
Domain must not depend on Use Cases	Reverse dependency from domain to application layer
Use Cases must not depend on Infrastructure	Spring, JDBC, or Kafka imports in use case classes
Entry Points must not depend on Driven Adapters	REST controllers accessing repository implementations directly
Driven Adapters must not depend on Commands	Infrastructure working with application-layer DTOs
Driven Adapters must not access Use Cases	Infrastructure coupling to application logic

7. Testing the Chain of Responsibility (Decorators)

When testing decorator adapters (cache, metrics, logging), test each decorator in isolation and verify delegation.

Kotlin:

1
class CreateUserMetricsAdapterTest {
2
    private val meterRegistry = SimpleMeterRegistry()
3
    private val delegate = mockk<CreateUserPort>()
4
    private val metricsAdapter = CreateUserMetricsAdapter(meterRegistry)
5

6
    @BeforeEach
7
    fun setup() {
8
        metricsAdapter.setDelegate(delegate)
9
    }
10

11
    @Test
12
    fun `should record metric and delegate execution`() {
13
        // Given
14
        val command = CreateUserCommand(/* params */)
15
        val expectedUser = User(/* params */)
16
        every { delegate.execute(command) } returns expectedUser
17

18
        // When
19
        val result = metricsAdapter.execute(command)
20

21
        // Then
22
        assertEquals(expectedUser, result)
23
        verify(exactly = 1) { delegate.execute(command) }
24
        // Verify metric was recorded
25
        val timer = meterRegistry.find("usecase.create.user").timer()
26
        assertNotNull(timer)
27
        assertEquals(1, timer?.count())
28
    }
29
}

Java:

1
class CreateUserMetricsAdapterTest {
2
    private final MeterRegistry meterRegistry = new SimpleMeterRegistry();
3
    private final CreateUserPort delegate = mock(CreateUserPort.class);
4
    private final CreateUserMetricsAdapter metricsAdapter = new CreateUserMetricsAdapter(meterRegistry);
5

6
    @BeforeEach
7
    void setup() {
8
        metricsAdapter.setDelegate(delegate);
9
    }
10

11
    @Test
12
    @DisplayName("should record metric and delegate execution")
13
    void shouldRecordMetricAndDelegateExecution() {
14
        // Given
15
        var command = new CreateUserCommand(/* params */);
16
        var expectedUser = new User(/* params */);
17
        when(delegate.execute(command)).thenReturn(expectedUser);
18

19
        // When
20
        var result = metricsAdapter.execute(command);
21

22
        // Then
23
        assertEquals(expectedUser, result);
24
        verify(delegate, times(1)).execute(command);
25
        // Verify metric was recorded
26
        var timer = meterRegistry.find("usecase.create.user").timer();
27
        assertNotNull(timer);
28
        assertEquals(1, timer.count());
29
    }
30
}

8. Best Practices

Naming: Use descriptive names for tests (e.g., `should return error when stock is empty` in Kotlin, shouldReturnErrorWhenStockIsEmpty in Java).
Independence: Each test must be able to run on its own, without depending on the state left by another.
Real Containers: For database or messaging adapters, use Testcontainers instead of H2 or mocks whenever possible to avoid false positives.
Data Builders: Create utility classes or extension functions to build domain objects in tests to reduce boilerplate code.
Given-When-Then: Structure every test with clear Given (setup), When (action), Then (assertions) sections.
No Spring in Unit Tests: Domain and use case tests MUST NOT load the Spring context. Use plain JUnit 5 + MockK/Mockito.

JUnit 5 (Jupiter) only; JUnit 4 / @RunWith / vintage forbidden.
Test Coverage: Aim for high coverage in domain and application layers. Infrastructure adapter tests focus on correct integration, not exhaustive coverage.