Module Integration Testing and Scenarios

In an event-driven Modulith, modules talk to each other by publishing and consuming application events rather than calling each other directly. A unit test of a single bean can verify the publishing side, but it cannot prove that the other module actually reacts correctly.

• Unit test — one bean, everything else mocked.
• Module integration test — one module's Spring context, its real beans, but neighbours stubbed.
• Full integration test — the whole application context.

Spring Modulith gives you the middle layer: spin up exactly one module, exercise its event flow, and assert what it publishes — all in isolation.

The core annotation is @ApplicationModuleTest from spring-modulith-test. It bootstraps only the module that contains the test class, not the entire application.

• It auto-detects the module from the test's package.
• Beans from other modules are not loaded — their events are captured instead of really handled.
• It behaves like a Spring Boot test slice (similar to @DataJpaTest), so it is fast and focused.

Place the test in the same base package as the module under test so Modulith can resolve module boundaries correctly.

@ApplicationModuleTest accepts a bootstrap mode that controls how many neighbouring modules are pulled in:

• STANDALONE (default) — only the current module.
• DIRECT_DEPENDENCIES — the current module plus the modules it directly depends on.
• ALL_DEPENDENCIES — the current module and its entire transitive dependency tree.

Start with STANDALONE for the tightest isolation; widen the mode only when a test genuinely needs a real collaborator bean instead of a captured event.

The simplest assertion is: did my module publish the right event? Modulith injects a PublishedEvents instance that records every event published during the test.

• Inject it as a test parameter or autowire it.
• Filter by type with ofType(...).
• Refine with matching(...) on a field or predicate.

This lets you verify the publishing module's contract without loading any consumer.

For a more fluent, AssertJ-style API, inject AssertablePublishedEvents instead. It exposes assertThat() directly so you can chain expressive assertions.

• contains(Type.class) — at least one event of that type.
• matching(...) — narrow to events whose field equals a value.
• Great for readability in larger scenarios.

Both PublishedEvents and AssertablePublishedEvents are populated by the same event-capturing infrastructure.

Captured events tell you what was published, but event-driven flows are often asynchronous: a stimulus triggers a listener that publishes a follow-up event. The Scenario API models exactly this stimulus → expectation shape, and it transparently waits for async work to settle.

• stimulate(...) — the action that kicks off the flow.
• andWaitForEventOfType(...) — block until that event appears (with a timeout).
• toArrive() / toArriveAndVerify(...) — the terminal assertion.

Inject Scenario as a test-method parameter; you do not construct it yourself.

The most common scenario starts with a bean method invocation. Pass a lambda receiving the Scenario, call your service inside stimulate(...), then declare what event you expect downstream.

Modulith polls until the event arrives or the timeout expires — no manual Thread.sleep needed.

To test the consuming side of a module in isolation, make the stimulus an incoming event rather than a method call. The module's listener reacts to it and (typically) publishes its own result event.

• stimulate(event) publishes the inbound event into the context.
• You then wait for the module's own outbound event.

This is how you verify one module's reaction to another module's event without loading that other module at all.

Sometimes the assertion you really care about is a state change — a repository row, a counter, a status flag — rather than another event. toArriveAndVerify(...) runs your assertion once the awaited event has arrived.

You can also use andVerify(...) after waiting for state to stabilise. This bridges the gap between async event delivery and synchronous database checks.

Async tests need sensible timeouts. The Scenario API lets you tune the wait and even wait on arbitrary state instead of an event:

• customize(c -> c.atMost(Duration.ofSeconds(2))) — cap the wait.
• andWaitForStateChange(() -> repo.findStatus(id)) — poll a supplier until it returns a non-null / truthy value.

Prefer waiting for the concrete signal you care about; a generous-but-bounded timeout avoids flaky CI without masking real hangs.

In STANDALONE mode, beans from other modules are absent. If your module under test directly autowires a collaborator that lives in another module (not an event-based dependency), the context cannot start. Two clean options:

• Provide a @MockitoBean (formerly @MockBean) for that collaborator in the test.
• Or widen the bootstrap mode to DIRECT_DEPENDENCIES so the real bean loads.

Favour the mock when you only need to stub a response; favour widening when the real collaboration is the point of the test.

You want to test that the inventory module reserves stock when it receives an OrderCompleted event — without loading the order module that normally publishes it. Which approach fits best?

You learned how Spring Modulith tests cross-module event flows in isolation:

• @ApplicationModuleTest bootstraps a single module; bootstrap modes (STANDALONE, DIRECT_DEPENDENCIES, ALL_DEPENDENCIES) control how many neighbours load.
• PublishedEvents / AssertablePublishedEvents capture and assert what a module publishes.
• The Scenario API models stimulus → expectation for async flows: stimulate(...) or publish(...), then andWaitForEventOfType(...) and toArrive() / toArriveAndVerify(...).
• andWaitForStateChange(...) plus customize(...atMost...) handle state assertions and bounded timeouts.
• Stub out-of-module collaborators with @MockitoBean, or widen the bootstrap mode when the real collaboration matters.

Together these let you prove module contracts hold without spinning up the entire application.