Mock External Services in Spring Boot Integration Tests

The Challenge of Testing External APIs

Modern Spring Boot applications frequently integrate with external services. This may include payment providers such as Stripe, SaaS platforms, or other internal microservices.

Properly integration testing these interactions is important but often difficult. Developers typically choose between two imperfect approaches:

• Mocking the Bean: Using @MockBean to mock the HTTP client is fast and simple. However, this approach bypasses real HTTP behavior, serialization, headers, and networking configuration. The test validates only the mocked behavior rather than the real integration contract.
• Manual WireMock Configuration: WireMock provides powerful and flexible HTTP mocking. However, maintaining stub mappings manually can be time-consuming. Developers must create JSON mappings, manage ports, and keep stubs aligned with evolving external APIs.

StableMock: Recording-Based API Mocking for Spring Boot

StableMock builds on top of WireMock and focuses on improving the developer workflow by automating stub creation through HTTP recording.

Instead of guessing what the API response looks like, you run your test once against the real API (or a dev instance). StableMock captures the traffic transparently and converts them into WireMock stubs.

Step 1: Record Real API Interactions

During an initial test execution, StableMock can route traffic to a real API or development environment. The HTTP request and response are recorded and stored as WireMock-compatible stubs.

@SpringBootTest
@U(urls = "https://api.stripe.com", properties = "stripe.api.url")
class OrderServiceTest extends BaseStableMockTest 

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) 
        autoRegisterProperties(registry, OrderServiceTest.class);
    

    @Test
    void shouldProcessPayment() 
        // Your test logic here
    

Step 2: Replay Interactions Deterministically

After recording, StableMock reuses the generated stubs in subsequent test executions. This enables tests to run without network dependencies while preserving realistic API behavior.

• Fast: Tests run locally without external network calls.
• Deterministic: Responses remain consistent across test runs.
• Realistic: Stubs are derived from real API interactions rather than manually written assumptions.

StableMock and WireMock: Complementary Tools

StableMock uses WireMock as its underlying HTTP mocking engine. The generated stubs remain fully compatible with WireMock and can be edited or reused manually if needed.

Capability	WireMock	StableMock
Server Lifecycle	Manual configuration	Integrated with JUnit lifecycle
Stub Creation	Manual JSON or programmatic stubs	Automatic recording into WireMock stubs
Port Management	Configured manually or programmatically	Automatically assigned and injected into Spring properties

Using Feign? Check out our guide on Mocking Feign Clients in Spring Boot.