0Pricing
Spring Boot 4 Complete Guide · レッスン

モジュール統合テストとシナリオ

Modulithのシナリオ機能とテストスライスサポートを使い、モジュール間の相互作用を分離してテストします。

「モジュール統合テストとシナリオ」はCoddyKit上の無料Spring Boot 4 Complete Guideレッスンです。 これはレッスン4/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはSpring Boot 4 Complete Guide学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Spring Boot 4 Complete Guideコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

Why Module Integration Tests?

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 @ApplicationModuleTest Slice

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.

package com.example.shop.order;

import org.springframework.modulith.test.ApplicationModuleTest;

@ApplicationModuleTest
class OrderModuleIntegrationTests {

    // Only the 'order' module's beans are bootstrapped here.
    // Other modules (inventory, shipping) are NOT loaded.
}

Bootstrap Modes

@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.

import org.springframework.modulith.test.ApplicationModuleTest;
import org.springframework.modulith.test.ApplicationModuleTest.BootstrapMode;

@ApplicationModuleTest(BootstrapMode.DIRECT_DEPENDENCIES)
class OrderModuleIntegrationTests {
    // 'order' + every module it directly depends on are loaded.
}

Capturing Published Events

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.

@ApplicationModuleTest
class OrderModuleIntegrationTests {

    @Autowired OrderService orders;

    @Test
    void publishesEventOnCompletion(PublishedEvents events) {
        orders.complete(new OrderId("4711"));

        var completed = events.ofType(OrderCompleted.class)
                .matching(OrderCompleted::orderId, new OrderId("4711"));

        assertThat(completed).hasSize(1);
    }
}

AssertablePublishedEvents

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.

@Test
void completionPublishesExactlyOnce(AssertablePublishedEvents events) {
    orders.complete(new OrderId("4711"));

    assertThat(events)
            .contains(OrderCompleted.class)
            .matching(OrderCompleted::orderId, new OrderId("4711"));
}

The Scenario API

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.

Stimulus Triggered by a Method Call

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.

@ApplicationModuleTest
class OrderModuleIntegrationTests {

    @Autowired OrderService orders;

    @Test
    void completingOrderTriggersFollowUp(Scenario scenario) {
        scenario.stimulate(() -> orders.complete(new OrderId("4711")))
                .andWaitForEventOfType(OrderCompleted.class)
                .matchingMappedValue(OrderCompleted::orderId, new OrderId("4711"))
                .toArrive();
    }
}

Stimulus Triggered by Publishing an Event

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.

@Test
void inventoryReservesStockOnOrder(Scenario scenario) {
    scenario.publish(new OrderCompleted(new OrderId("4711")))
            .andWaitForEventOfType(StockReserved.class)
            .matchingMappedValue(StockReserved::orderId, new OrderId("4711"))
            .toArrive();
}

Verifying State, Not Just Events

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.

@Test
void reservationPersistsState(Scenario scenario) {
    scenario.publish(new OrderCompleted(new OrderId("4711")))
            .andWaitForEventOfType(StockReserved.class)
            .toArriveAndVerify(event ->
                assertThat(reservations.findByOrderId(event.orderId()))
                        .isPresent());
}

Customising Timeouts and State Changes

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.

@Test
void statusFlipsToShipped(Scenario scenario) {
    scenario.stimulate(() -> orders.complete(new OrderId("4711")))
            .customize(it -> it.atMost(Duration.ofSeconds(2)))
            .andWaitForStateChange(() -> orders.statusOf(new OrderId("4711")))
            .andVerify(status ->
                assertThat(status).isEqualTo(OrderStatus.SHIPPED));
}

Mocking Out-of-Module Collaborators

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.

@ApplicationModuleTest
class OrderModuleIntegrationTests {

    @MockitoBean PricingClient pricingClient; // bean from another module

    @Autowired OrderService orders;

    @Test
    void usesQuotedPrice(Scenario scenario) {
        when(pricingClient.quote(any())).thenReturn(Money.of(42));
        scenario.stimulate(() -> orders.place(new Cart("4711")))
                .andWaitForEventOfType(OrderPlaced.class)
                .toArrive();
    }
}

Quick Check

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?

Recap

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.

よくある質問

「モジュール統合テストとシナリオ」レッスンは無料ですか？

はい。「モジュール統合テストとシナリオ」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Spring Boot 4 Complete Guideコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Spring Boot 4 Complete Guideコースには全4レッスンが含まれています。

「モジュール統合テストとシナリオ」で何を学びますか？

Modulithのシナリオ機能とテストスライスサポートを使い、モジュール間の相互作用を分離してテストします。 ブラウザで直接実行するハンズオンコードでSpring Boot 4 Complete Guideを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Spring Boot 4 Complete Guideを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのSpring Boot 4 Complete Guideは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン4/4です。

「モジュール統合テストとシナリオ」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このSpring Boot 4 Complete Guideレッスンでコードを書いて実行できますか？

はい。すべてのSpring Boot 4 Complete Guideレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. アプリケーションモジュールと境界検証
  2. アプリケーション内部イベントとリスナー
  3. トランザクショナルイベント発行とOutbox
  4. モジュール統合テストとシナリオ
← Spring Boot 4 Complete Guideに戻る