Testing your Spring RestTemplate with @RestClientTest

While watching Andy Wilkinson’s great talk Testing Spring Boot Applications on YouTube he brought my attention to a hidden gem for testing the Spring RestTemplate. In the past, I always wondered how to write proper tests for client classes using the RestTemplate to fetch data from external services. In his presentation, he mentioned the @RestClientTest annotation that provides everything you need to test such classes.

With this blog post, I’ll walk you through a Spring Boot 2.2 application using the  @RestClientTest annotation.

Spring RestTemplate project setup

The application is a usual Tomcat based Spring Boot Web MVC application. The RestTemplate is used to fetch data from a remote API.

In addition, I’m using Java 13, which is optional and not required for this to work. It’s included to demonstrate how the experimental text block feature benefits for preparing JSON strings.

That’s everything you need. No additional dependency required as the @RestClientTest annotation is part of the spring-boot-test-autoconfigure dependency which comes with spring-boot-starter-test.

Please note that the example uses JUnit 5, but I’ll explain what you have to change if your application is using JUnit 4.X.

Compared to using WireMock for testing your RestTemplate in isolation, this solution requires less set up as everything is part of Spring Boot.

Inside the @RestClientTest annotation

Let’s first have a look at the @RestClientTest  annotation to truly understand what is happening in behind the scenes:

The annotation is used to combine (a lot of) other annotations mostly used for auto-configuration. Together all of these annotations make sure to only bootstrap required beans to test a specific part of the application.

With @ExtendWith(SpringExtension.class) the annotation registers the Spring JUnit 5 extension. Among other things we need this annotation to autowire objects from the test’s ApplicationContext. For those of you who are using JUnit 4, make sure to always add @RunWith(SpringRunner.class) to all your tests. This is required as the SpringExtension only works with JUnit 5.

Next @AutoConfigureWebClient is used to enable and configure the auto-configuration of web clients. By default, Spring Boot configures the RestTemplateBuilder for us. If we specify @AutoConfigureWebClient(registerRestTemplate=true)  also concrete RestTemplate beans are available to inject, which you’ll see later on.

The last important annotation is @AutoConfigureMockRestServiceServer.  This ensures we can inject a bean of type MockRestServiceServer to our tests and mock the HTTP response.

Testing code using the RestTemplateBuilder

If you have used the RestTemplate in the past, the following might look familiar:

It basically returns a POJO from a remote API. For this example, I’m using a dummy API.

Testing this part of your application while mocking the RestTemplateBuilder results in a lot of setup ceremony. The benefit of just testing such code parts using only Mocktio is questionable. It would be great if we can also include HTTP semantics and test different responses from the remote server.

All of this we can solve using the setup we get with@RestClientTest. Once you annotate a test class with this, you have to specify which class you want to actually test,e.g.:@RestClientTest(UserClient.class). Next, you are able to autowire everything you need in the test:

Given this MockRestSerivceServer instance, we can now specify the result of this mock server for each test case:

The example above is using the Java 13 text block preview feature to define the JSON string response. Besides the HTTP body, you are also able to configure the content type and HTTP status of the response.

For those of you, who don’t use Java 13 yet, you can also use the injected ObjectMapper to create a proper JSON string:

You can now also test how your method behaves in case of a server error in the remote system:

The example above just propagates the exception, but your client class might handle it differently and return null or an empty Optional, which you can test with this.

Testing code using a Spring RestTemplate bean

Furthermore, some parts of your application might not directly use the RestTemplateBuilder. It’s also common to prepare different RestTemplate beans for your application inside a @Configuration class:

And the client directly injects the configured RestTemplate:

For such use cases, you have to set up your test class like the following:

Finally, the MockRestSerivceServer provides a way to reset all expectations/recorded requests and verify that every expectation was actually used. This is quite helpful and can be integrated using the JUnit test lifecycle:

This ensures to not have any side effects between tests by creating unnecessary HTTP stubs.

Unfortunately, you can’t use this whole setup if your application already uses the Spring WebClient instead of the RestTemplate. There is a different approach to have something similar for the WebClient, which I covered in another guide.

The full source code (including all tests) for this Spring Boot application example is available on GitHub.

Have fun testing your Spring RestTemplate,

Phil