Dedicated test support for Namastack Outbox

[rolandbeisel]

Testing application code that uses the outbox currently requires users to assemble their own combination of mocks, repository access, Awaitility, and real-time delays. This becomes especially cumbersome for retry and backoff scenarios, where tests may need to wait for the scheduler even though the behavior under test is deterministic.

Would a dedicated OSS test-support module be useful?

Proposed module

testImplementation("io.namastack:namastack-outbox-test")

The module could cover two distinct testing levels.

1. Verify scheduling in unit tests

A small RecordingOutbox could implement the public Outbox API and record calls made by user code:

val outbox = RecordingOutbox()
val service = OrderService(orderRepository, outbox)

service.placeOrder(order)

assertThat(outbox.invocations()).singleElement().satisfies { invocation ->
    assertThat(invocation.payload).isEqualTo(OrderPlaced(order.id))
    assertThat(invocation.key).isEqualTo(order.id)
}

This would only verify that application code invokes Outbox.schedule(...) with the expected payload, key, and context. It would not test persistence, transaction boundaries, serialization, handler resolution, retries, or record processing. MockK and Mockito can already cover this use case, so the value of RecordingOutbox would mainly be a small, framework-independent convenience.

2. Control the real runtime in Spring Boot integration tests

Following Spring Boot conventions, an OutboxTester could be enabled explicitly on an existing application test:

@SpringBootTest
@AutoConfigureOutboxTester
class OrderServiceTest(
    @Autowired private val orderService: OrderService,
    @Autowired private val outboxTester: OutboxTester,
) {
    @Test
    fun `retries a failed notification`() {
        orderService.placeOrder()

        outboxTester.processOnce()
        assertThat(outboxTester.pendingRecords().single().failureCount).isEqualTo(1)

        outboxTester.advanceToNextRetry()
        outboxTester.processUntilIdle()

        assertThat(outboxTester.completedRecords()).hasSize(1)
    }
}

Possible operations include:

outboxTester.pendingRecords()
outboxTester.completedRecords()
outboxTester.failedRecords()

outboxTester.processOnce()
outboxTester.processUntilIdle()

outboxTester.now()
outboxTester.advanceTimeBy(duration)
outboxTester.advanceTimeTo(instant)
outboxTester.advanceToNextRetry()

The tester should use the actual configured persistence adapter and processing pipeline. It should expose immutable record snapshots rather than persistence-specific entities.

Time and processing

A mutable test Clock alone is insufficient because advancing it does not trigger Spring's scheduler. Deterministic integration tests therefore need two capabilities:

1. replace the runtime clock with a controllable test clock;
2. disable background polling and execute processing cycles explicitly.

The first version can support this without replacing the existing processing architecture. OutboxProcessingScheduler.process() already executes one complete polling cycle and waits for its batch to finish. An additive API could keep that method unchanged and expose a result-returning variant for test and operational use:

class OutboxProcessingScheduler {
    fun process() {
        processNow()
    }

    fun processNow(): OutboxProcessingResult {
        // Existing processing cycle
    }
}

OutboxTester.processOnce() would delegate to processNow(). The existing scheduled entry point, constructor, and default behavior would remain unchanged.

Background polling still needs to be disabled while the tester controls processing. This could be provided through an opt-in property such as:

namastack:
  outbox:
    polling:
      enabled: false

The default would remain true. When disabled, the scheduler lifecycle could still enter a state that permits explicit processNow() calls, but it would not register a periodic task. An alternative that requires no production property is for the test auto-configuration to provide a manual TaskScheduler that records scheduled tasks without executing them. The explicit property is likely easier to understand and also useful outside this test module.

Extracting a dedicated OutboxProcessingCycle may still improve the internal design later. It is not required for the initial test-support module and should only be done while preserving the existing public OutboxProcessingScheduler constructor and process(): Unit method.

Compatibility

The proposal can be implemented as a non-breaking addition:

• namastack-outbox-test is a new optional test-scoped artifact;
• OutboxTester, RecordingOutbox, record snapshots, and test auto-configuration are new types;
• a new polling switch defaults to the current behavior;
• a new result-returning scheduler method can be added while retaining process(): Unit;
• no methods need to be added to the existing Outbox or repository interfaces;
• no existing constructor needs to change.

Changing the return type of OutboxProcessingScheduler.process(), replacing its public constructor, or adding a property to the primary constructor of a public Kotlin configuration data class could break compiled clients and should be avoided. If a processing-cycle abstraction is introduced, the old constructor and method signatures should delegate to the new implementation.

Initial scope

An initial version could include:

• OutboxTester and @AutoConfigureOutboxTester;
• a controllable UTC-based clock;
• manual processing of one cycle or until no further progress is possible;
• immutable snapshots of pending, completed, and failed records;
• clear diagnostics when processing does not become idle;
• optionally, RecordingOutbox for plain unit tests.

It would intentionally avoid database-container management, persistence-specific assertions, a complete in-memory outbox implementation, and dependencies on a particular assertion or mocking library.

Open questions

• Is controlling the real runtime the main problem users need solved, or is verifying schedule(...) calls already a significant use case?
• Should RecordingOutbox be part of the first version, given that mocking libraries already support the same interaction tests?
• Is OutboxTester the right Spring Boot-style name?
• Should automatic processing be disabled through a general polling.enabled property, or should the test auto-configuration install a manual scheduler?
• Should the tester reject processOnce() while the test thread still has an active transaction, since production processing happens after commit?

Decision Process

• Decision owner: @rolandbeisel
• Review period ends: 2026-09-30
• Outcome: The accepted decision will be recorded in an ADR.
• Related work: #459