En esta guía (8 elementos)

Claude Code Guide — Bug Fixing & Testing Patterns

Project-agnostic. Part of the Claude Code Guide suite. Covers: bug-fix workflow (identify layer, failing test first, fix, verify), unit test patterns (use case), integration test patterns (repository with Testcontainers).

Replace com.example.platform / platform-service placeholders with your project’s actual package and service name when applying patterns.

Companion files:

claude-code-guide.md — index + required reading order.
ccg-domain-and-ports.md — Steps 1-3 (domain, ports, use case).
ccg-adapters-and-wiring.md — Step 4 (adapters) + Step 5 (wiring).
ccg-reference.md — common tasks, anti-patterns, checklists.
testing.md — full testing strategy.

🐛 When Fixing Bugs

1. Identify the Layer

Ask: Where does the bug occur?

Domain logic bug → Fix in domain entity methods
Use case orchestration bug → Fix in use case
Data mapping bug → Fix in mapper
API validation bug → Fix in REST request DTO
Database query bug → Fix in repository adapter
Kafka publishing bug → Fix in Kafka adapter

2. Write a Failing Test First

1
@Test
2
fun `should rollback both business write and outbox row when one fails`() {
3
    // Given - outbox save throws inside the TX
4
    val outboxThatFails = mock<OutboxRepositoryPort> {
5
        on { save<Any>(any()) } doThrow RuntimeException("outbox table missing")
6
    }
7
    val useCase = CreateInvoiceUseCase(
8
        transaction, repository, outboxThatFails, outboxEventFactory, clock,
9
    )
10

11
    // When/Then - the TX rolls back; neither write persists
12
    assertThrows<RuntimeException> { useCase.execute(command) }
13
    verifyTransactionRolledBack(transaction)   // helper that asserts callback threw → no commit
14
}
15

16
@Test
17
fun `should write business row and outbox row inside the same transaction`() {
18
    val captured = AtomicReference<List<String>>(emptyList())
19
    whenever(transaction.run(any())).thenAnswer { inv ->
20
        val ops = mutableListOf<String>()
21
        whenever(repository.save(any())).thenAnswer { ops += "repo.save"; savedInvoice }
22
        whenever(outbox.save<Any>(any())).thenAnswer { ops += "outbox.save"; Unit }
23
        val result = inv.getArgument<() -> Invoice>(0).invoke()
24
        captured.set(ops)
25
        result
26
    }
27

28
    useCase.execute(command)
29

30
    assertThat(captured.get()).containsExactly("repo.save", "outbox.save")
31
}

Key shift: there is no publisher mock and no kafkaTemplate mock. The use case has exactly one event-emission collaborator — OutboxRepositoryPort — and the test asserts both writes belong to the same TX callback.

3. Fix the Bug

4. Verify All Tests Pass

./gradlew test
./gradlew build

🧪 Testing Patterns

Unit Test (Use Case)

1
class CreateInvoiceUseCaseTest {
2

3
    private lateinit var transaction: TransactionPort<Invoice>
4
    private lateinit var repository: InvoiceRepositoryPort
5
    private lateinit var outbox: OutboxRepositoryPort
6
    private lateinit var outboxEventFactory: OutboxEventFactory
7
    private lateinit var clock: Clock
8
    private lateinit var useCase: CreateInvoiceUseCase
9

10
    @BeforeEach
11
    fun setup() {
12
        transaction = mock()
13
        repository = mock()
14
        outbox = mock()
15
        outboxEventFactory = OutboxEventFactory("test-service", EventMessageFactory("test-service"))
16
        clock = Clock.fixed(Instant.parse("2026-01-01T00:00:00Z"), ZoneOffset.UTC)
17
        useCase = CreateInvoiceUseCase(transaction, repository, outbox, outboxEventFactory, clock)
18
    }
19

20
    @Test
21
    fun `should create invoice and enqueue outbox event`() {
22
        // Given
23
        val command = CreateInvoiceCommand(
24
            organizationId = UUID.randomUUID(),
25
            amount = BigDecimal("100.00"),
26
            currency = "USD",
27
            dueDate = LocalDate.now().plusDays(30),
28
            traceId = "trace-1",
29
        )
30
        val savedInvoice = mock<Invoice>()
31
        whenever(repository.save(any())).thenReturn(savedInvoice)
32
        whenever(transaction.run(any())).thenAnswer { it.getArgument<() -> Invoice>(0).invoke() }
33

34
        // When
35
        val result = useCase.execute(command)
36

37
        // Then
38
        assertThat(result).isEqualTo(savedInvoice)
39
        verify(repository).save(any())
40
        verify(outbox).save<EventMessage<InvoiceCreatedPayload>>(argThat { msg ->
41
            msg.topic == "platform.invoices" &&
42
            msg.message.body.eventName == "InvoiceCreated" &&
43
            msg.message.header.traceId == "trace-1"
44
        })
45
    }
46
}

Integration Test (Repository with Testcontainers)

1
@SpringBootTest
2
@Testcontainers
3
@ActiveProfiles("test")
4
class InvoiceRepositoryIntegrationTest {
5

6
    companion object {
7
        @Container
8
        @ServiceConnection
9
        val postgres: PostgreSQLContainer = PostgreSQLContainer("postgres:16-alpine")
10
    }
11

12
    @Autowired
13
    private lateinit var repository: InvoiceRepositoryPort
14

15
    @Test
16
    fun `should save and retrieve invoice`() {
17
        // Given
18
        val invoice = Invoice.issue(
19
            id = UUID.randomUUID(),
20
            organizationId = UUID.randomUUID(),
21
            amount = Money(BigDecimal("100.00"), Currency.getInstance("USD")),
22
            dueDate = LocalDate.now().plusDays(30),
23
            clock = Clock.systemUTC()
24
        )
25

26
        // When
27
        val saved = repository.save(invoice)
28
        val retrieved = repository.findById(saved.id)
29

30
        // Then
31
        assertThat(retrieved).isNotNull
32
        assertThat(retrieved?.amount?.value).isEqualByComparingTo(BigDecimal("100.00"))
33
    }
34
}