Setup test application

For example, let’s create the following controller:

import com.pohorelov.medium.response.ResourceData;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequiredArgsConstructor
public class BaseController {

  @GetMapping("/resources/{resourceId}")
  public ResponseEntity<ResourceData> getAccountData(
      @AuthenticationPrincipal Jwt principal,
      @PathVariable String resourceId
  ) {
    if (!resourceId.equals(principal.getClaimAsString("resourceId"))) {
      return ResponseEntity
          .status(HttpStatus.FORBIDDEN)
          .body(AccountData.builder()
              .errorMessage("Search resource id is not associated with current user")
              .build());
    }
    return ResponseEntity
        .status(HttpStatus.OK)
        .body(ResourceData.builder()
            .resourceId(accountId)
            .name("Oleksandr Pohorelov")
            .build());
  }

}

We want to verify that authenticated users asks for their own details, and not for another user’s details. We can do that by extracting resource identifier from JWT token (of course, we assume that our token issuer service is set up to put this id as a claim while generating a new token).

Of course, this is ultra-simplified example and probably cannot be an example of real production code and logic. However, I am pretty sure that reader of this story has faced some real-life scenarios with similar logic, and that is the reason why you are here.

Few words about security configuration of our test project. Let’s assume that our organization follows OAuth2 standard and uses Keycloack as a solution. However, this story is not about Keycloack only, its goal is to cover testing of application with any 3rd party identity and access management tool.

So, our pom.xml contains few dependencies related to security:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

We have basic security configuration as the following:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfiguration {

  @Bean
  public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .csrf().disable()
        .cors()
        .and()
        .authorizeRequests()
        .anyRequest()
        .authenticated()
        .and()
        .oauth2ResourceServer()
        .jwt();
    return http.build();
  }

}

And to connect to OAuth2 resource we use application properties. For Keycloack JWKS url will look like the following:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwkSetUri: http://auth-server:9000/auth/realms/myrealm/protocol/openid-connect/certs

That’s it. Everything else is Spring Boot magic of auto-configurations. Of course, in real life application we might have more configurations, may custom JwtDecoder or custom provider configuration. We can map claims from token to some POJO to be used as a Principal in an application. Finally, all these logic can be extracted to an internal library, which will be imported by all services in an organization. In fact — more complex logic you have related to security — more useful you will find this story.

Controller layer test

Developers usually prefer not to mess up with security, and often disable security in WebMvcTests because of that reason. This can be easily done with the following test configuration:

@WebMvcTest(controllers = BaseController.class)
@AutoConfigureMockMvc(addFilters = false)

But this approach brings a lot of limitations:

1. What if there is a custom request filter that we would like to test?
2. What if we put @PreAutorize annotation on controller class or method and would like to test only users with required roles/permissions can access our API?
3. And finally — how to test our controller with @AuthenticationPrincipal?

Most probably, it is not the best approach to disable security in your tests. Moreover, for the first and second scenarios there are ready-to-go annotations provided by Spring.

We just need to add test dependency:

<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-test</artifactId>
    <scope>test</scope>
</dependency>

And we will be able to use annotations like @WithMockUser to pass Authentication and put requires roles/authorities to SecurityContext.

However, this still doesn’t address the issue with mocking Principal. We can always fall back to mocking interfaces manually with Mockito. This article describes this process. Author mocks Authentication, mocks Principal and manually set it to SecurityContext. This approach might be sufficient for your service. But let’s imagine the following scenarios:

• there is custom logic in common organization library related to security you would like to test
• you are writing acceptance or E2E tests that require fully operational application context without any mocked beans
• you DO want to test authentication flow of your service

Well, to achieve this, let’s first recollect how authorization and authentication with JWT token usually work.

Basic overview of authorization and authentication

In simple words, JWT is an “encrypted” JSON. It contains useful data about its expiration time, issuer, it can also contain custom key-value pair (called claims). What makes JWT token secured is signature — made with encryption key using particular algorithm. One of the popular algorithms — RS256 — uses RSA key’s private part. You might be familiar with RSA key concept and might use them already in your developer’s life, for example, to clone git projects with SSH.

Public part of RSA key is stored along with its identifier in JWKS — JSON Web Key Set. JWKS is managed by 3rd parties (in our case — Keycloack) and used by services with security support to verify incoming JWT token. Security request filters fetch JWT token from request headers, validate expiration date, extract key id and algorithm. Further authentication depends on your configuration, but in our case with OAuth2 and JWKS URL specified in properties — service is going to call 3rd party (Keycloack) to fetch JWKS. Then from this set it gets corresponding public key (by id) and verifies token signature. After successful verification — authentication is completed successfully.

Considering this schema, we can notice that there is only one part which breaks “fully operational flow” — JWKS provider.

Fully operational security with mock server

What we can actually do — we can start a mock server, which will return predefined key set. In this key set we will put public part of generated RSA key. With private part of the key we will sign our test JWT with all custom data we want. Exactly as it is working in real life!

First let’s assure that we have required test dependencies — on Spring Boot starter and mock server:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

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

Now let’s implement test class itself:

import static org.hamcrest.Matchers.is;
import static org.mockserver.model.HttpRequest.request;
import static org.mockserver.model.HttpResponse.response;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import com.nimbusds.jose.jwk.RSAKey;
import com.pohorelov.medium.configuration.SecurityConfiguration;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.interfaces.RSAPublicKey;
import java.util.Date;
import java.util.List;
import java.util.Map;
import lombok.SneakyThrows;
import org.json.JSONObject;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockserver.client.MockServerClient;
import org.mockserver.springtest.MockServerTest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.context.annotation.Import;
import org.springframework.http.HttpHeaders;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.servlet.MockMvc;

@ActiveProfiles("test")
@MockServerTest
@WebMvcTest(controllers = BaseController.class)
class BaseControllerTest {

  private MockServerClient mockServerClient;

  @Autowired
  private MockMvc mockMvc;

  private static String jwks;
  private static String jwt;

  @BeforeAll
  public static void setUp() {
    final var keyPair = generateKeyPair();
    jwks = generateJwksJson(keyPair);
    jwt = authorize(keyPair);
  }

  @BeforeEach
  public void setUpServer() {
    mockServerClient
        .when(
            request()
                .withMethod("GET")
                .withPath("/auth/realms/test-realm/protocol/openid-connect/certs"))
        .respond(response().withStatusCode(200).withBody(jwks));
  }

  @SneakyThrows
  @Test
  void shouldReturnAccountData() {
    final var headers = new HttpHeaders();
    headers.setBearerAuth(jwt);
    mockMvc.perform(get("/resources/1").headers(headers))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.name", is("Oleksandr Pohorelov")));
  }

  @SneakyThrows
  @Test
  void shouldReturnForbidden() {
    final var headers = new HttpHeaders();
    headers.setBearerAuth(jwt);
    mockMvc.perform(get("/resources/2").headers(headers))
        .andExpect(status().isForbidden())
        .andExpect(jsonPath("$.errorMessage",
            is("Search account id is not associated with current user")));
  }

  @SneakyThrows
  private static KeyPair generateKeyPair() {
    final var keyGenerator = KeyPairGenerator.getInstance("RSA");
    keyGenerator.initialize(1024);
    return keyGenerator.generateKeyPair();
  }

  private static String generateJwksJson(KeyPair keyPair) {
    final var rsaKey = new RSAKey.Builder((RSAPublicKey) keyPair.getPublic()).build();
    final var jwk =
        Map.of(
            "kid", "test",
            "kty", "RSA",
            "alg", "RS256",
            "n", rsaKey.getModulus().toString(),
            "e", rsaKey.getPublicExponent().toString());
    final var responseSet = Map.of("keys", List.of(jwk));
    final var jsonObj = new JSONObject(responseSet);
    return jsonObj.toString();
  }

  @SneakyThrows
  private static String authorize(KeyPair keyPair) {
    return Jwts.builder()
        .setHeaderParam("kid", "test")
        .signWith(SignatureAlgorithm.RS256, keyPair.getPrivate())
        .claim("resourceId", "1")
        .claim("permissions", "test-permissions")
        .setExpiration(new Date(System.currentTimeMillis() + 5 * 60 * 1000))
        .compact();
  }

}

To get things work let’s override JWKS URL in application-test.yaml:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwkSetUri: http://localhost:${mockServerPort}/auth/realms/test-realm/protocol/openid-connect/certs

Let’s discuss what we are doing in this test class:

1. Before tests execution starts, we create 1 pair of RSA keys.
2. Public part of that key we use in JWKS creation. There is a provider’s defined JSON response structure — we follow this structure by putting values to map. Note field kid=test in this map. This is key identifier. Same identifier we are going to put in test JWT token so that Spring will be able to find required key in set.
3. We create test JWT with custom claims (required in our business logic). Finally, we sign test JWT with private part of the RSA key.
4. Final preparation — before each test we setup mock server expectations. We know that Spring is going to call URL which we have overridden in application test properties. We set created JWKS as an expected response of the mock server.

That’s it. We have fully operational application context without any mocked beans. We can play with SecurityContext as we want using test JWT.

Final note. I have seen some tests which use real Keycloack instances (in test environment) and call real authorization services (in same environment) to get real JWT token. Needless to say how fragile such tests are, as their execution depends on other development teams. Think twice if you want to have constant headache attempting to run and maintain such tests.

Testing Security Without Mocked Beans was originally published in Testing Spring Boot Java Applications Cookbook on Medium, where people are continuing the conversation by highlighting and responding to this story.

Let’s imagine that we have component, which is mainly responsible for parsing JSON string in model. For example, there is a Kafka listener component, which accept string event, parses it, and redirects to processor service.

import com.fasterxml.jackson.databind.ObjectMapper;
import com.pohorelov.medium.model.EventModel;
import com.pohorelov.medium.service.KafkaProcessor;
import lombok.RequiredArgsConstructor;
import lombok.SneakyThrows;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;

@Component
@RequiredArgsConstructor
public class KafkaTypicalListener {

  private final ObjectMapper objectMapper;
  private final KafkaProcessor kafkaProcessor;

  @SneakyThrows
  @KafkaListener(topics = "${spring.kafka.topic.test-topic}", groupId = "${spring.kafka.groups.test-group}")
  public void processKafkaEvent(String payload) {
    final var eventModel = objectMapper.readValue(payload, EventModel.class);
    kafkaProcessor.process(eventModel);
  }

}

I also prepared simple model structure:

import java.time.LocalDateTime;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.NoArgsConstructor;
import lombok.Value;

@Value
@Builder
@NoArgsConstructor(force = true)
@AllArgsConstructor
public class EventModel {

  String name;
  LocalDateTime time;
  Type type;

  public enum Type {
    LEFT, RIGHT
  }

}

Can we make a simple unit test?

We can write simple test — create listener instance with mock objectMapper and processor. Mock object mapper response, verify processor was called with mocked object mapper response. But do we actually achieve anything with this kind of test? We will verify that listener uses ObjectMapper for parsing, and redirects it to processor. But if we have any issues with JSON mapping, are we going to know about it?

Okay, obviously, we would like to test JSON parsing itself. So instead of mock ObjectMapper — we need a real instance. Probably, we can think about something like this:

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.Mockito.doNothing;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.pohorelov.medium.model.EventModel;
import com.pohorelov.medium.service.KafkaProcessor;
import java.time.LocalDateTime;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.ArgumentCaptor;
import org.mockito.Captor;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;

@ExtendWith(MockitoExtension.class)
class KafkaListenerTest {

  private KafkaTypicalListener kafkaListener;

  @Mock
  private KafkaProcessor kafkaProcessor;

  @Captor
  private ArgumentCaptor<EventModel> eventModelArgumentCaptor;

  @BeforeEach
  public void setUp() {
    kafkaListener = 
        new KafkaTypicalListener(new ObjectMapper(), kafkaProcessor);
  }

  @Test
  void shouldProcessEvent() {
    final var payload = "{\"name\" : \"Alex\", \"time\" : \"2022-11-12T13:01:00\", \"type\": \"LEFT\"}";

    doNothing().when(kafkaProcessor)
        .process(eventModelArgumentCaptor.capture());

    kafkaListener.processKafkaEvent(payload);

    final var actualModel = 
        eventModelArgumentCaptor.getValue();
    
    assertThat(actualModel.getName()).isEqualTo("Alex");
    assertThat(actualModel.getTime())
        .isEqualTo(LocalDateTime.of(2022, 11, 12, 13, 1, 0));
    assertThat(actualModel.getType()).isEqualTo(EventModel.Type.LEFT);
  }

}

But such test will fail:

com.fasterxml.jackson.databind.exc.InvalidDefinitionException: Java 8 date/time type `java.time.LocalDateTime` not supported by default: add Module "com.fasterxml.jackson.datatype:jackson-datatype-jsr310" to enable handling
 at [Source: (String)"{"name" : "Alex", "time" : "2022-11-12T13:01:00"}"; line: 1, column: 28] (through reference chain: com.pohorelov.medium.model.EventModel["time"])

Conclusion: we would like to test ObjectMapper which we configured for our application (i.e. ObjectMapper from real context) instead of the new instance.

Playing with Spring context…

Okay, can we ask SpringBoot to create test context of 2 beans, which we want to test?

...

@SpringBootTest(classes = {
    KafkaTypicalListener.class,
    ObjectMapper.class
})
class KafkaListenerTest {

  @Autowired
  private KafkaTypicalListener kafkaListener;

  @MockBean
  private KafkaProcessor kafkaProcessor;

...

Same exception… Why? Because plain ObjectMapper cannot deserialize LocalDateTime by default. We don’t face this issue is runtime, because Spring auto-configure default module and features of ObjectMapper for us. This is happening behind the scene, but we do need this part in out test as well.

Use bootstrap annotation

As we discussed in a previous story, there are some test annotations provided by Spring Boot Test, which can help to setup particular “slice” of application, which we want to test. In our case, all we need to do is to utilize @AutoConfigureJson annotation, which will include several JSON related auto-configurations to our test application context:

@SpringBootTest(classes = KafkaTypicalListener.class)
@AutoConfigureJson
class KafkaListenerTest {
...

Don’t forget to include customizers

If you have ObjectMapper customizer bean in your configuration:

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.databind.DeserializationFeature;
import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class JacksonConfiguration {

  @Bean
  public Jackson2ObjectMapperBuilderCustomizer customJackson2ObjectMapperBuilder() {
    return builder -> {
      builder.serializationInclusion(JsonInclude.Include.NON_NULL);
      builder.featuresToEnable(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_AS_NULL);
    };
  }

}

Don’t forget to include it to your test context as well:

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.Mockito.doNothing;

import com.pohorelov.medium.configuration.JacksonConfiguration;
import com.pohorelov.medium.model.EventModel;
import com.pohorelov.medium.service.KafkaProcessor;
import java.time.LocalDateTime;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.mockito.Captor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.json.AutoConfigureJson;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.MockBean;

@SpringBootTest(classes = {
    KafkaTypicalListener.class,
    JacksonConfiguration.class
})
@AutoConfigureJson
class KafkaListenerTest {

  @Autowired
  private KafkaTypicalListener kafkaListener;

  @MockBean
  private KafkaProcessor kafkaProcessor;

  @Captor
  private ArgumentCaptor<EventModel> eventModelArgumentCaptor;

  @Test
  void shouldProcessEvent() {
    final var payload = "{\"name\" : \"Alex\", \"time\" : \"2022-11-12T13:01:00\", \"type\": \"INVALID\"}";

    doNothing().when(kafkaProcessor)
        .process(eventModelArgumentCaptor.capture());

    kafkaListener.processKafkaEvent(payload);

    final var actualModel =
        eventModelArgumentCaptor.getValue();

    assertThat(actualModel.getName()).isEqualTo("Alex");
    assertThat(actualModel.getTime())
        .isEqualTo(LocalDateTime.of(2022, 11, 12, 13, 1, 0));
    assertThat(actualModel.getType()).isNull();
  }

}

Summary

• Unit test is the simplest kind of tests developer can prepare. In most cases (especially, for services, where we have business logic), unit tests should be the only choice. However, some layers of application may require “component”, or “slice” testing. Such tests should include target component as well as some part of configured application context.
• Spring Boot provides us with useful tool for testing of JSON manipulations (ie. serialization and desialization). Consider utilizing @AutoConfigureJson annotation while testing Kafka listeners (with String consumer deserializer) or JSON schema validators.

Testing ObjectMapper component was originally published in Testing Spring Boot Java Applications Cookbook on Medium, where people are continuing the conversation by highlighting and responding to this story.

What is client component?

Client Component is a class which responsibility is to call other services or 3rd parties. It has an injected RestTemplate (from spring-boot-starter-web) or WebClient (from spring-boot-starter-webflux). Third party URL is usually configured in property files and is injected in the component with Spring Value annotation or via ConfigurationProperties class.

application.yaml

application:
  third-party:
    base-url: https://api.coinbase.com
    currency-endpoint: ${application.third-party.base-url}/v2/currencies

ApplicationProperties.java

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Getter
@Setter
@Configuration
@ConfigurationProperties(prefix = "application.third-party")
public class ApplicationProperties {

  private String currencyEndpoint;

}

Fetching properties via configuration class should be considered as a preferable way. Imagine situation when service needs to integrate with some amount of endpoints. Injecting each endpoint with Value can expand client’s constructor and decrease readability. Instead we can keep one configuration properties class and get any required endpoint with getter.

TypicalClient.java

import com.pohorelov.medium.configuration.ApplicationProperties;
import com.pohorelov.medium.response.CurrencyResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.client.WebClient;

@Component
@RequiredArgsConstructor
public class TypicalClient {

  private final WebClient webClient;
  private final ApplicationProperties applicationProperties;

  public CurrencyResponse getCurrencies() {
    return webClient
        .get()
        .uri(applicationProperties.getCurrencyEndpoint())
        .retrieve()
        .bodyToMono(CurrencyResponse.class)
        .block();
  }

}

WebClient should be considered as a preferable tool for a client component. RestTemplate is in maintenance mode as mentioned in its documentation.

Same client with RestTemplate will look like:

import com.pohorelov.medium.configuration.ApplicationProperties;
import com.pohorelov.medium.response.CurrencyResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;

@Component
@RequiredArgsConstructor
public class TypicalRestTemplateClient {

  private final RestTemplate restTemplate;
  private final ApplicationProperties applicationProperties;

  public CurrencyResponse getCurrencies() {
    return restTemplate.getForObject(
        applicationProperties.getCurrencyEndpoint(), 
        CurrencyResponse.class
    );
  }

}

What exactly we want to test?

To choose the best testing tool and decide on testing strategy, we should always first answer this question. In most cases, good old unit test would be the best option, but can it address all our requirements?

In case of client components we would like to test the following:

• url is configured correctly in properties or/and in @ConfigurationProperties class. In our case it means that we expect client to use application.third-party.currency-endpoint. Moreover, we would like to know that developers use base url to constuct endpoint. So that if we replace it for our test — our client should use this value.
• client is sending request to the configured url in a tested method. This point also implies configured request params and headers. There can be a situation when request is “enriched” by Spring Filters (e.g., we have microservice architecture and use distributed tracing, so our common web filter adds a correlation id header to the request).
• request body format (if present)
• verify response body is deserialised correctly

What about plain unit test?

We still can try to meet all the points with plain unit test. We can mock ApplicationProperties and verify that expected getter was called.

Mocking WebClient can be a little bit tricky. There are StackOverFlow discussions dedicated to this. One of them recommends refactoring client code with ExchangeFunction or mocking each step of WebClient call (ie. mock .get() then mock .uri(), then mock .retrieve() and so on).

Mocking RestTemplate would be much easier — when template was called for specific URI and for specific response class — then return prepared answer.

But let’s take a look at last point of our requirements. In our api response structure is the following:

{
  "data": [
    {
      "id": "AED",
      "name": "United Arab Emirates Dirham",
      "min_size": "0.01000000"
    },
    {
      "id": "AFN",
      "name": "Afghan Afghani",
      "min_size": "0.01000000"
    }
  ]
}

I prepared response object to represent it:

import java.util.List;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.NoArgsConstructor;
import lombok.Value;

@Value
@Builder
@NoArgsConstructor(force = true)
@AllArgsConstructor
public class CurrencyResponse {

  List<CurrencyData> data;

}

import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.NoArgsConstructor;
import lombok.Value;

@Value
@Builder
@NoArgsConstructor(force = true)
@AllArgsConstructor
public class CurrencyData {

  String id;
  String name;
  @JsonProperty("min_size")
  String minSize;

}

Note field minSize. I don’t want to violate Java Code Convention — so I named field in camel case. However, in JSON its name is in snake case. Returning manually built response object I will not be able to test mapping of this field.

Proposed solution — RestClientTest

Hopefully, Spring developers prepared a set of test annotation which can help to bootstrap application context in a specific way to test a particular layer (or slice) of our application.

You can check which auto-configurations are invoked for which test annotation here:

Test Auto-configuration Annotations

Let’s write test for RestTemplate client:

import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withSuccess;

import com.pohorelov.medium.configuration.ApplicationProperties;
import java.nio.charset.Charset;
import lombok.SneakyThrows;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.test.autoconfigure.web.client.AutoConfigureWebClient;
import org.springframework.boot.test.autoconfigure.web.client.RestClientTest;
import org.springframework.core.io.ClassPathResource;
import org.springframework.http.MediaType;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.client.MockRestServiceServer;
import org.springframework.util.StreamUtils;

@ActiveProfiles("test")
@RestClientTest(components = TypicalRestTemplateClient.class)
@AutoConfigureWebClient(registerRestTemplate = true)
@EnableConfigurationProperties(ApplicationProperties.class)
class TypicalRestTemplateClientTest {

  @Autowired
  private TypicalRestTemplateClient client;

  @Autowired
  private MockRestServiceServer server;

  @SneakyThrows
  @Test
  void shouldReturnData() {
    final var responseStream =
        new ClassPathResource("client/response.json")
            .getInputStream();
    final var response =
        StreamUtils.copyToString(responseStream, 
            Charset.defaultCharset());
    this.server.expect(
        requestTo("http://localhost:8080/v2/currencies")
        )
        .andRespond(
            withSuccess(response, MediaType.APPLICATION_JSON)
        );

    final var actualResponse = 
        client.getCurrencies();

    assertThat(actualResponse).isNotNull();
    assertThat(actualResponse.getData()).hasSize(2);
    assertThat(actualResponse.getData().get(0).getId())
        .isEqualTo("AED");
    assertThat(actualResponse.getData().get(0).getName())
        .isEqualTo("United Arab Emirates Dirham");
    assertThat(actualResponse.getData().get(0).getMinSize())
        .isEqualTo("0.01000000");
  }

}

We use active profile to get base url from application-test.yaml:

application:
  third-party:
    base-url: http://localhost:8080

Note that MockRestServiceServer was auto-configured for us and was bound to RestTemplate present in application context.

Test structure is the following:

1. Register mock server expectations (and set response JSON string).
2. Call target method.
3. Assert deserialized response meets our expectations.

Testing component with WebClient

RestClient test cannot be used for client implementation with WebClient, because MockRestServiceServer will be not be able to find required RestTemplate for binding. Spring developers still recommend to use static server for testing in their documentation.

In order to achieve this we are going to add mock-server dependency:

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

Mock server will be started on random free port, so we should also update application-test.yaml property:

application:
  third-party:
    base-url: http://localhost:${mockServerPort}

Note that you should not specifymockServerPort, it will be defined after mock server is started.

Test class will look like the following:

import static java.nio.charset.Charset.defaultCharset;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockserver.model.HttpRequest.request;
import static org.mockserver.model.HttpResponse.response;

import com.pohorelov.medium.configuration.ApplicationProperties;
import com.pohorelov.medium.configuration.WebClientConfiguration;
import lombok.SneakyThrows;
import org.junit.jupiter.api.Test;
import org.mockserver.client.MockServerClient;
import org.mockserver.model.MediaType;
import org.mockserver.springtest.MockServerTest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.core.io.ClassPathResource;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.util.StreamUtils;

@ActiveProfiles("test")
@SpringBootTest(classes = {
    TypicalClient.class,
    WebClientConfiguration.class
})
@MockServerTest
@EnableConfigurationProperties(ApplicationProperties.class)
public class TypicalClientTest {

  private MockServerClient mockServerClient;

  @Autowired
  private TypicalClient client;

  @SneakyThrows
  @Test
  void shouldReturnData() {
    final var responseStream =
        new ClassPathResource("client/response.json")
            .getInputStream();
    final var response =
        StreamUtils.copyToString(responseStream, defaultCharset());

    this.mockServerClient.when(
        request()
            .withMethod("GET")
            .withPath("/v2/currencies"))
        .respond(response()
            .withContentType(MediaType.APPLICATION_JSON)
            .withBody(response));

    final var actualResponse = client.getCurrencies();

    assertThat(actualResponse).isNotNull();
    assertThat(actualResponse.getData()).hasSize(2);
    assertThat(actualResponse.getData().get(0).getId())
        .isEqualTo("AED");
    assertThat(actualResponse.getData().get(0).getName())
        .isEqualTo("United Arab Emirates Dirham");
    assertThat(actualResponse.getData().get(0).getMinSize())
        .isEqualTo("0.01000000");
  }

}

We changed expectation format settings, but approach and assertions remained the same.

Note that for MacOS (M1 chip) you might also need the following dependency:

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-resolver-dns-native-macos</artifactId>
    <version>4.1.84.Final</version>
    <classifier>osx-aarch_64</classifier>
</dependency>

Summary

Client Components are responsible for REST communication with 3rd parties and other micro-services. While testing such components, one should validate request configuration and serialization as well as server response deserialization (and probably, exception handling).

Unit tests may be not the best solution as one would not be able to verify some aspects of request/response structure. Loading full application context is never a good choice while testing particular application layer.

Better approach would be to bootstrap application context with client component as well as components required for REST communication (e.g., WebClient configuration, configuration properties). Spring Boot Test annotation @RestClientTest can help to setup context for clients which use RestTemplate. For WebClient one should still setup mock server manually. However, @MockServerTest from mockserver-spring-test-listener can help a little bit with it (it takes responsibility for server start and shutdown logic).

Testing Client Component was originally published in Testing Spring Boot Java Applications Cookbook on Medium, where people are continuing the conversation by highlighting and responding to this story.