How to test any HTTP Client of your Spring Boot Application with MockServer

In an integration test, we want to test the interaction of several components of our application. However, as soon as one of these components communicates with a 3rd party service via HTTP, this can present us with a challenge. To be independent of this service, we have to mock it. In this blog post, I will show you how to do that with the help of MockServer.

What is MockServer?

MockServer is a tool to mock any service that communicates via HTTP(S). In integration tests, we can use it to decouple our code from the real service we want to integrate with. By doing so, our tests will be independent of the availability of the real service, and we can test the behavior of our code in different success or error scenarios. To configure the MockServer we set expectations containing a request matcher and an action. When MockServer receives a request, it checks for a matching request matcher, by comparing properties like HTTP method, request path, headers, cookies, etc. If there is a match, it will respond according to the action. For example a success response or an error.

The Example

In this blog post, we will extend the test suite of my previous post “How to test the REST Clients of your Spring Boot Application with @RestClientTest”. There we created a client for the Star Wars API by using Spring’s RestClient. We also tested this client in isolation by leveraging the @RestClientTest test slice. Today we want to write an integration test, that spans the complete application from the controller to the repository.

Here is an overview of the involved classes:

@Repository
public class StarWarsCharacterRepository {

    private final RestTemplate restTemplate;

     public StarWarsCharacterRepository(RestTemplateBuilder restTemplateBuilder,
                                       @Value("${swapi.baseUrl}") String baseUrl) {
        this.restTemplate = restTemplateBuilder.rootUri(baseUrl).build();
    }

    public Optional<Character> findById(Long id) {
        //...
    }
}

@RestController
@RequestMapping("/characters")
public class CharacterController {

    private final StarWarsCharacterRepository repository;

    public CharacterController(StarWarsCharacterRepository repository) {
        this.repository = repository;
    }

    @GetMapping(value = "/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
    public Character findById(@PathVariable Long id) {
        return repository.findById(id).orElseThrow(() -> new CharacterNotFoundException(id));
    }
}

Test Setup

Before we can start to implement the test, we first need to add MockServer as a dependency to the project.

<dependency>
    <groupId>org.mock-server</groupId>
    <artifactId>mockserver-spring-test-listener</artifactId>
    <version>5.14.0</version>
</dependency>
...

The Test

Let’s start by implementing the skeleton of our test class:

@SpringBootTest
@AutoConfigureMockMvc
@MockServerTest({"swapi.baseUrl=http://localhost:${mockServerPort}"})
class CharacterControllerIT {

    @Autowired
    private MockMvc mockMvc;

    private MockServerClient mockServerClient;

    // tests
}

With our prepared test class, we can now start to implement the test:

@Test
void requestingAKnownCharacter_Returns200() throws Exception {

        final var resource = new ClassPathResource("luke.json");
        final var mockedResponse = Files.readString(Path.of(resource.getURI()));

        mockServerClient
                .when(request().withPath("/people/1"))
                .respond(response()
                                 .withStatusCode(HttpStatusCode.OK_200.code())
                                 .withContentType(org.mockserver.model.MediaType.APPLICATION_JSON)
                                 .withBody(mockedResponse));

        mockMvc.perform(get("/characters/1"))
               .andExpect(status().isOk())
               .andExpect(content().contentType(MediaType.APPLICATION_JSON_VALUE))
               .andExpect(jsonPath("$.name", equalTo("Luke Skywalker")));
    }

Conclusion

As you could see in the example, MockServer enables us to test our fully integrated application. In combination with @RestClientTests, this gives us a well-rounded test suite for our HTTP clients. The fact that it comes in one package containing all dependencies makes it easy to add to your project. With MockServerClient’s easy-to-learn API, you can start writing your expectations in no time. The TestExecutionListener integrates well into Spring Boot and allows you to configure your application dynamically. On top of that, it will also reset the MockServer after each test. This way the expectations set in one test won’t be carried over to the next, which means each one runs in isolation.

Resources

• You can find the code of this blog post in this GitHub repository
• Want to learn more about MockServer? Have a look at the official page
• You didn’t know about @RestClientTest yet? Have a look at “How to test the REST Clients of your Spring Boot Application with @RestClientTest”
• Do you need help with the usage of MockMvc? Look here: “How to test the Web Layer of your Spring Boot Application with @WebMvcTest”