Testing an application on Spring Boot, part 2

Mock beans and spy beans

When running tests, you sometimes need to mock certain components in the application context. For example, you might have a facade for some remote service that is not accessible during development. Mocking can also be useful if you need to simulate crashes that are difficult to cause in a real environment.

Spring Boot contains a @MockBean annotation that can be used to define a Mockito mock for a bean inside ApplicationContext. You can use an annotation to add new beans or replace one existing bean definition. The annotation can be used directly on test classes, on fields within a test, or on classes and fields with the @Configuration annotation. When used with a field, an instance of the created mock object is also injected. Mock beans are automatically reset after each test method is executed.

import org.springframework.boot.test.mock.mockito.MockitoTestExecutionListener;
import org.springframework.boot.test.mock.mockito.ResetMocksTestExecutionListener;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.TestExecutionListeners;
@ContextConfiguration(classes = MyConfig.class)
@TestExecutionListeners({ MockitoTestExecutionListener.class, ResetMocksTestExecutionListener.class })
class MyTests {
    // ...
}

import org.springframework.boot.test.mock.mockito.MockitoTestExecutionListener
import org.springframework.boot.test.mock.mockito.ResetMocksTestExecutionListener
import org.springframework.test.context.ContextConfiguration
import org.springframework.test.context.TestExecutionListeners
@ContextConfiguration(classes = [MyConfig::class])
@TestExecutionListeners(
    MockitoTestExecutionListener::class,
    ResetMocksTestExecutionListener::class
)
class MyTests {
    // ...
}

The following example replaces an existing RemoteService bean with a mock implementation:

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.BDDMockito.given;
@SpringBootTest
class MyTests {
    @Autowired
    private Reverser reverser;
    @MockBean
    private RemoteService remoteService;
    @Test
    void exampleTest() {
        given(this.remoteService.getValue()).willReturn("spring");
        String reverse = this.reverser.getReverseValue(); // Calls injected RemoteService
        assertThat(reverse).isEqualTo("gnirps");
    }
}

import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.mockito.BDDMockito.given
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.boot.test.mock.mockito.MockBean
@SpringBootTest
class MyTests(@Autowired val reverser: Reverser, @MockBean val remoteService: RemoteService) {
    @Test
    fun exampleTest() {
        given(remoteService.value).willReturn("spring")
        val reverse = reverser.reverseValue // Calls injected RemoteService
        assertThat(reverse).isEqualTo("gnirps")
    }
}

Alternatively, you can use the @SpyBean annotation to wrap any existing bean with a spy object from Mockito.

Auto-configuring tests

Spring Boot's auto-configuration system works great with applications, but can sometimes be too redundant for tests. It is often practical to load only those parts of the configuration that are needed to test the "layer" of the application. For example, you might want to ensure that Spring MVC controllers render URLs correctly, but don't want to involve database calls in those tests, or you might want to test JPA entities, but the web tier isn't interested in running those tests. .

The spring-boot-test-autoconfigure module contains a number of annotations that can be used to automatically configure such "layers". Each of them works the same way, representing an annotation of the form @...​Test, which loads ApplicationContext, and one or more annotations of the form @AutoConfigure...​ , which can be used to configure auto-configuration parameters.

Auto-configured JSON tests

To ensure that JSON serialization and deserialization -objects works as expected, you can use the @JsonTest annotation. The @JsonTest annotation automatically configures an available supported JSON mapper, which can be one of the following libraries:

• ObjectMapper from Jackson, any beans with the @JsonComponent annotation and any Modules from Jackson

• Gson

• Jsonb

If you need to configure autoconfig elements, you can use the @AutoConfigureJsonTesters annotation.

Spring Boot contains AssertJ-based helper classes that work with the JSONAssert and JsonPath libraries, designed to check that the intended JSON mapping is correct. The classes JacksonTester, GsonTester, JsonbTester and BasicJsonTester can be used for the Jackson, Gson, Jsonb and Strings libraries, respectively. Any auxiliary fields of the test class can be marked with the @Autowired annotation when using the @JsonTest annotation. The following example shows a test class for the Jackson library:

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.json.JsonTest;
import org.springframework.boot.test.json.JacksonTester;
import static org.assertj.core.api.Assertions.assertThat;
@JsonTest
class MyJsonTests {
    @Autowired
    private JacksonTester<VehicleDetails> json;
    @Test
    void serialize() throws Exception {
        VehicleDetails details = new VehicleDetails("Honda", "Civic");
        // Assertion for a ".json" file in the same package as the test
        assertThat(this.json.write(details)).isEqualToJson("expected.json");
        // Or use assertions based on the JSON path
        assertThat(this.json.write(details)).hasJsonPathStringValue("@.make");
        assertThat(this.json.write(details)).extractingJsonPathStringValue("@.make").isEqualTo("Honda");
    }
    @Test
    void deserialize() throws Exception {
        String content = "{\"make\":\"Ford\",\"model\":\"Focus\"}";
        assertThat(this.json.parse(content)).isEqualTo(new VehicleDetails("Ford", "Focus"));
        assertThat(this.json.parseObject(content).getMake()).isEqualTo("Ford");
    }
}

import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.json.JsonTest
import org.springframework.boot.test.json.JacksonTester
@JsonTest
class MyJsonTests(@Autowired val json: JacksonTester<VehicleDetails>) {
    @Test
    fun serialize() {
        val details = VehicleDetails("Honda", "Civic")
        // Assertion for a ".json" file in the same package as the test
        assertThat(json.write(details)).isEqualToJson("expected.json")
        // Or use assertions based on JSON path
        assertThat(json.write(details)).hasJsonPathStringValue("@.make")
        assertThat(json.write(details)).extractingJsonPathStringValue("@.make").isEqualTo("Honda")
    }
    @Test
    fun deserialize() {
        val content = "{\"make\":\"Ford\",\"model\":\"Focus\"}"
        assertThat(json.parse(content)).isEqualTo(VehicleDetails("Ford", "Focus"))
        assertThat(json.parseObject(content).make).isEqualTo("Ford")
    }
}

If you use the AssertJ-based Spring Boot helper classes to add an assertion for a number value in a given JSON path, you may not need to use isEqualTo depending on the type. Instead, you can use the satisfies function in AssertJ to add an assertion that a value satisfies a given condition. For example, the following example adds a statement that the actual number is a float value close to 0.15 within offset 0.01.

@Test
void someTest() throws Exception {
    SomeObject value = new SomeObject(0.152f);
    assertThat(this.json.write(value)).extractingJsonPathNumberValue("@.test.numberValue")
            .satisfies((number) -> assertThat(number.floatValue()).isCloseTo(0.15f, within(0.01f)));
}

            @Test
fun someTest() {
    val value = SomeObject(0.152f)
    assertThat(json.write(value)).extractingJsonPathNumberValue("@.test.numberValue")
        .satisfies(ThrowingConsumer { number ->
            assertThat(number.toFloat()).isCloseTo(0.15f, within(0.01f))
        })
}

Spring MVC auto-configurable tests

To test Spring MVC controllers for intended functionality, use the @WebMvcTest annotation. The @WebMvcTest annotation automatically configures the Spring MVC framework and limits scanned beans to @Controller, @ControllerAdvice, @JsonComponent, Converter, GenericConverter, Filter, HandlerInterceptor, WebMvcConfigurer, WebMvcRegistrations and HandlerMethodArgumentResolver. Regular beans with @Component and @ConfigurationProperties annotations are not scanned when using the @WebMvcTest annotation. To add beans marked with the @ConfigurationProperties annotation, you can use the @EnableConfigurationProperties annotation.

Often the @WebMvcTest is limited to a single controller and is used in conjunction with the @MockBean annotation to pass mock implementations for the required communicating objects.

@WebMvcTest also automatically configures MockMvc. Mock MVC provides an efficient way to quickly test MVC controllers without having to run a full HTTP server.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import static org.mockito.BDDMockito.given;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@WebMvcTest(UserVehicleController.class)
class MyControllerTests {
    @Autowired
    private MockMvc mvc;
    @MockBean
    private UserVehicleService userVehicleService;
    @Test
    void testExample() throws Exception {
        given(this.userVehicleService.getVehicleDetails("sboot"))
            .willReturn(new VehicleDetails("Honda", "Civic"));
        this.mvc.perform(get("/sboot/vehicle").accept(MediaType.TEXT_PLAIN))
            .andExpect(status().isOk())
            .andExpect(content().string("Honda Civic"));
    }
}

import org.junit.jupiter.api.Test
import org.mockito.BDDMockito.given
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
import org.springframework.boot.test.mock.mockito.MockBean
import org.springframework.http.MediaType
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders
import org.springframework.test.web.servlet.result.MockMvcResultMatchers
@WebMvcTest(UserVehicleController::class)
class MyControllerTests(@Autowired val mvc: MockMvc) {
    @MockBean
    lateinit var userVehicleService: UserVehicleService
    @Test
    fun testExample() {
        given(userVehicleService.getVehicleDetails("sboot"))
            .willReturn(VehicleDetails("Honda", "Civic"))
        mvc.perform(MockMvcRequestBuilders.get("/sboot/vehicle").accept(MediaType.TEXT_PLAIN))
            .andExpect(MockMvcResultMatchers.status().isOk)
            .andExpect(MockMvcResultMatchers.content().string("Honda Civic"))
    }
}

If you are using HtmlUnit and Selenium, auto-configuration also provides a WebClient bean for HtmlUnit and/or a WebDriver bean for Selenium. The following example uses HtmlUnit:

import com.gargoylesoftware.htmlunit.WebClient;
import com.gargoylesoftware.htmlunit.html.HtmlPage;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.BDDMockito.given;
@WebMvcTest(UserVehicleController.class)
class MyHtmlUnitTests {
    @Autowired
    private WebClient webClient;
    @MockBean
    private UserVehicleService userVehicleService;
    @Test
    void testExample() throws Exception {
        given(this.userVehicleService.getVehicleDetails("sboot")).willReturn(new VehicleDetails("Honda", "Civic"));
        HtmlPage page = this.webClient.getPage("/sboot/vehicle.html");
        assertThat(page.getBody().getTextContent()).isEqualTo("Honda Civic");
    }
}

import com.gargoylesoftware.htmlunit.WebClient
import com.gargoylesoftware.htmlunit.html.HtmlPage
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.mockito.BDDMockito.given
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
import org.springframework.boot.test.mock.mockito.MockBean
@WebMvcTest(UserVehicleController::class)
class MyHtmlUnitTests(@Autowired val webClient: WebClient) {
    @MockBean
    lateinit var userVehicleService: UserVehicleService
    @Test
    fun testExample() {
        given(userVehicleService.getVehicleDetails("sboot")).willReturn(VehicleDetails("Honda", "Civic"))
        val page = webClient.getPage<HtmlPage>("/sboot/vehicle.html")
        assertThat(page.body.textContent).isEqualTo("Honda Civic")
    }
}

If the classpath has the Spring Security annotation @WebMvcTest will also scan the WebSecurityConfigurer beans. Instead of completely disabling security for such tests, you can use the test support from Spring Security.

Spring WebFlux Self-Configuring Tests

To ensure that Spring WebFlux controllers work as expected, you can use the @WebFluxTest annotation. The @WebFluxTest annotation automatically configures the Spring WebFlux framework and limits scanned beans to @Controller, @ControllerAdvice, @JsonComponent, Converter, GenericConverter, WebFilter and WebFluxConfigurer. Regular beans with @Component and @ConfigurationProperties annotations are not scanned when using the @WebFluxTest annotation. To add beans marked with the @ConfigurationProperties annotation, you can use the @EnableConfigurationProperties annotation.

Often the @WebFluxTest is limited to a single controller and is used in conjunction with the @MockBean annotation to pass mock implementations for the required communicating objects.

The @WebFluxTest annotation code> also automatically configures WebTestClient, which provides an efficient means of quickly testing WebFlux controllers without the need to run a full HTTP server.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.reactive.server.WebTestClient;
import static org.mockito.BDDMockito.given;
@WebFluxTest(UserVehicleController.class)
class MyControllerTests {
    @Autowired
    private WebTestClient webClient;
    @MockBean
    private UserVehicleService userVehicleService;
    @Test
    void testExample() {
        given(this.userVehicleService.getVehicleDetails("sboot"))
            .willReturn(new VehicleDetails("Honda", "Civic"));
        this.webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN).exchange()
            .expectStatus().isOk()
            .expectBody(String.class).isEqualTo("Honda Civic");
    }
}

import org.junit.jupiter.api.Test
import org.mockito.BDDMockito.given
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest
import org.springframework.boot.test.mock.mockito.MockBean
import org.springframework.http.MediaType
import org.springframework.test.web.reactive.server.WebTestClient
import org.springframework.test.web.reactive.server.expectBody
@WebFluxTest(UserVehicleController::class)
class MyControllerTests(@Autowired val webClient: WebTestClient) {
    @MockBean
    lateinit var userVehicleService: UserVehicleService
    @Test
    fun testExample() {
        given(userVehicleService.getVehicleDetails("sboot"))
            .willReturn(VehicleDetails("Honda", "Civic"))
        webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN).exchange()
            .expectStatus().isOk
            .expectBody<String>().isEqualTo("Honda Civic")
    }
}