Mock External APIs (WireMock)

When a Spring Boot application depends on external systems such as payment gateways, SMS/email services, OAuth providers, or third-party REST APIs, testing can become:

• Slow
• Unstable
• Costly
• Unreliable

Mock External APIs solve this problem by allowing you to test your application without calling real external services.

What Is a Mock External API?

A Mock External API simulates a third-party or external service during testing.

A mock API:

• Runs like a real HTTP server
• Accepts HTTP requests
• Returns predefined responses
• Simulates success, failure, and timeout scenarios

👉 Your application believes it is calling a real API, but a mock server handles the request.

What Is WireMock?

WireMock is a popular and widely used tool for mocking HTTP/REST APIs.

It acts as a fake external server that returns predefined responses based on your configuration.

With WireMock, you can:

• Mock successful API responses
• Simulate errors (500, 404, 401)
• Add artificial delays (timeouts)
• Verify whether an API was actually called
• Test edge and failure scenarios safely

👉 WireMock is the most common choice in Spring Boot integration testing.

Why Mock External APIs?

External APIs can be:

• Slow or unreliable
• Paid or rate-limited
• Unavailable in test/CI environments
• Dangerous (real payments, real emails, real data)

Benefits of Mocking External APIs

• No dependency on third-party systems
• Faster and deterministic tests
• No cost or side effects
• Easy testing of error cases (500, timeout, invalid response)
• Stable CI/CD pipelines
• Fully offline testing support

When to Use WireMock?

Use WireMock when:

• Your service calls third-party REST APIs
• APIs have rate limits or usage costs
• You need isolated and reliable integration tests
• You want to simulate failures or timeouts
• Testing microservice-to-microservice communication
• Writing service-level or integration tests

What Can Be Mocked & Common Use Cases

In Spring Boot testing, mocking is used to simulate dependencies so your application can be tested in isolation, safely, and reliably. Both external systems and internal components can be mocked depending on the test scenario.

👉 Use WireMock for external HTTP services, MockWebServer for lightweight HTTP mocking, and Contract stubs for producer-consumer contract verification.

Tools for Mocking External APIs

👉 WireMock is the preferred choice for mocking external HTTP services because it supports request matching, response stubbing, delays, fault injection, and verification—making it ideal for integration and microservice testing.

Example Scenario

Suppose your Spring Boot service calls an external API:

GET <https://external-api.com/users/1>

Expected Response:

{
"id":1,
"name":"Alice"
}

Instead of calling the real API, we mock this response using WireMock so that:

• Tests run fast and offline
• Responses are controlled and predictable
• Error scenarios and delays can be simulated easily

Add WireMock Dependency (Maven)

<dependency>
<groupId>com.github.tomakehurst</groupId>
<artifactId>wiremock-jre8</artifactId>
<version>2.35.0</version>
<scope>test</scope>
</dependency>

Configure WireMock in Spring Boot Test

Start WireMock on a Random Port:

import com.github.tomakehurst.wiremock.junit5.WireMockTest;
import org.springframework.boot.test.context.SpringBootTest;

@WireMockTest
@SpringBootTest
class UserServiceTest {
    // WireMock starts automatically on a random port
}

• WireMock starts automatically
• Uses a random available port (recommended)

Stub External API Response

import static com.github.tomakehurst.wiremock.client.WireMock.*;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;

@Test
void shouldFetchUserFromMockApi() {

    stubFor(get(urlEqualTo("/users/1"))
        .willReturn(aResponse()
            .withStatus(200)
            .withHeader("Content-Type", "application/json")
            .withBody("""
                {
                  "id": 1,
                  "name": "Alice"
                }
            """)));

    User user = userService.getUserById(1);

    assertEquals("Alice", user.getName());
}

• No real API call
• Fully controlled response
• Fast and reliable test

Configure External API Base URL

application-test.yml

external:
  api:
    base-url: <http://localhost>:${wiremock.server.port}

Use Base URL in Service

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;

@Service
public class UserService {

    @Value("${external.api.base-url}")
    private String baseUrl;

    private final RestTemplate restTemplate = new RestTemplate();

    public User getUserById(int id) {
        return restTemplate.getForObject(
            baseUrl + "/users/" + id,
            User.class
        );
    }
}

Simulating Error Scenarios

WireMock allows you to simulate failures and delays from external APIs so you can test how your application handles errors.

External API Failure (500)

stubFor(get(urlEqualTo("/users/1"))
    .willReturn(aResponse()
        .withStatus(500)
        .withHeader("Content-Type", "application/json")
        .withBody("{\\"error\\":\\"Internal Server Error\\"}")));

• Tests how your service reacts to server errors.
• Useful for validating error handling logic.

Timeout Simulation

stubFor(get(urlEqualTo("/users/1"))
    .willReturn(aResponse()
        .withFixedDelay(3000)  // delay in milliseconds
        .withStatus(200)
        .withHeader("Content-Type", "application/json")
        .withBody("{\\"id\\":1,\\"name\\":\\"Alice\\"}")));

• Simulates slow responses from external services.
• Helps test timeout handling and retries in your service.

Testing Other Error Scenarios

You can also simulate:

• 400 – Bad Request
• 401 – Unauthorized
• 403 – Forbidden
• 404 – Not Found
• Invalid or corrupted JSON responses

Verify External API Calls

WireMock can verify whether your application actually called the external API as expected:

import static com.github.tomakehurst.wiremock.client.WireMock.*;

verify(getRequestedFor(urlEqualTo("/users/1")));

• Ensures the request was executed
• Prevents false-positive tests
• Confirms correct API usage and integration behavior

WireMock with @SpringBootTest

When you want to run full integration tests with your Spring Boot context while still mocking external APIs, use @WireMockTest alongside @SpringBootTest.

@SpringBootTest
@WireMockTest
class PaymentServiceIT {

    @Autowired
    private PaymentService paymentService;

    @Test
    void shouldProcessPaymentUsingMockApi() {
        // Stub external payment API
        stubFor(post(urlEqualTo("/payments"))
            .willReturn(aResponse()
                .withStatus(201)
                .withHeader("Content-Type", "application/json")
                .withBody("{\\"transactionId\\":\\"tx12345\\",\\"status\\":\\"SUCCESS\\"}")));

        PaymentResult result = paymentService.processPayment(new PaymentRequest(100.0, "USD"));

        assertEquals("SUCCESS", result.getStatus());
        assertNotNull(result.getTransactionId());

        // Verify that the external API was called
        verify(postRequestedFor(urlEqualTo("/payments")));
    }
}

WireMock vs Mockito

👉 Mockito: Use for internal logic/unit tests where no real HTTP calls are involved.

👉 WireMock: Use for external API mocking, testing integration, error scenarios, and API contracts.

Where Mock External APIs Fit in Testing Pyramid

Best Practices

• Mock only external systems
• Keep stub responses realistic
• Test success + failure scenarios
• Always use random ports
• Reset stubs between tests
• Combine with Testcontainers for real databases

Key Takeaways

• Mock External APIs simulate real third-party services
• WireMock is the best tool for HTTP API mocking
• Makes tests fast, stable, and independent
• Essential for Spring Boot integration testing
• Critical for microservices and CI/CD pipelines

Conclusion

Mocking External APIs using WireMock is a best practice in Spring Boot testing.

It ensures your tests are:

• Fast
• Stable
• Independent
• Cost-effective

By using WireMock, you can confidently test Spring Boot applications without relying on real external systems, making your software reliable, maintainable, and production-ready.