WebTestClient

WebTestClient is an HTTP client designed for testing server applications. It wraps Spring's WebClient and uses it to make requests, but exposes a testing façade to test responses. WebTestClient can be used to perform end-to-end HTTP tests. It can also be used to test Spring MVC and Spring WebFlux applications without a running server by simulating server request objects and response objects.

Settings

To configure WebTestClient, you must select a server setting for the binding. This can be one of several settings for the simulated server or a connection to a real server.

Controller binding

This setup allows you to test a specific controller(s) using simulated request and response objects without a running server.

For WebFlux applications, use the following configuration, which loads the infrastructure equivalent to WebFlux Java Configurations, registers the given controller(s) and creates a WebHandler chain to process requests:

WebTestClient client =
        WebTestClient.bindToController(new TestController()).build();

val client = WebTestClient.bindToController(TestController()).build()

For Spring MVC, use the following configuration which delegates StandaloneMockMvcBuilder authority to load infrastructure equivalent to Java-WebMvc configuration, registers the given controller(s) and creates an instance of MockMvc to handle requests:

WebTestClient client =
        MockMvcWebTestClient.bindToController(new TestController()).build();

val client = MockMvcWebTestClient.bindToController(TestController()).build()

Binding to ApplicationContext

This setup allows you to load a Spring configuration with infrastructure from Spring MVC or Spring WebFlux and controller declarations, and use it to process requests using mock request and response objects without a running server.

For WebFlux, use the following configuration, where ApplicationContext from Spring is passed WebHttpHandlerBuilder to create WebHandler chain for processing requests:

@SpringJUnitConfig(WebConfig.class) 
class MyTests {
    WebTestClient client;
    @BeforeEach
    void setUp(ApplicationContext context) { 
        client = WebTestClient.bindToApplicationContext(context).build(); 
    }
}

1. Specify the configuration to load
2. Implement the configuration
3. Create a WebTestClient

@SpringJUnitConfig(WebConfig::class) 
class MyTests {
    lateinit var client: WebTestClient
    @BeforeEach
    fun setUp(context: ApplicationContext) { 
        client = WebTestClient.bindToApplicationContext(context).build() 
    }
}

1. Specify the configuration to load
2. Implement the configuration
3. Create a WebTestClient

For Spring MVC, use the following configuration, where the ApplicationContext from Spring is passed to MockMvcBuilders.webAppContextSetup to instantiate MockMvc for processing requests:

@ExtendWith(SpringExtension.class)
@WebAppConfiguration("classpath:META-INF/web-resources") 
@ContextHierarchy({
    @ContextConfiguration(classes = RootConfig.class),
    @ContextConfiguration(classes = WebConfig.class)
})
class MyTests {
    @Autowired
    WebApplicationContext wac; 
    WebTestClient client;
    @BeforeEach
    void setUp() {
        client = MockMvcWebTestClient.bindToApplicationContext(this.wac).build(); 
    }
}

1. Specify the configuration to load
2. Implement the configuration
3. Create a WebTestClient

@ExtendWith(SpringExtension.class)
@WebAppConfiguration("classpath:META-INF/web-resources") 
@ContextHierarchy({
    @ContextConfiguration(classes = RootConfig.class),
    @ContextConfiguration(classes = WebConfig.class)
})
class MyTests {
    @Autowired
    lateinit var wac: WebApplicationContext; 
    lateinit var client: WebTestClient
    @BeforeEach
    fun setUp() { 
        client = MockMvcWebTestClient.bindToApplicationContext(wac).build() 
    }
}

1. Specify the configuration to load
2. Implement the configuration
3. Create a WebTestClient

Binding to a router function

This setup allows you to test functional endpoints using simulated request and response objects without running server.

For WebFlux, use the following configuration, which delegates to RouterFunctions.toWebHandler the authority to create a server configuration to handle requests:

RouterFunction<?> route=...
client = WebTestClient.bindToRouterFunction(route).build();

val route: RouterFunction<*> = ...
val client = WebTestClient.bindToRouterFunction(route).build()

There are currently no testing options for WebMvc functional endpoints for Spring MVC.

Binding to the server

This setup connects to a running server to perform full end-to-end HTTP tests:

client = WebTestClient.bindToServer().baseUrl("http://localhost:8080").build();

client = WebTestClient.bindToServer().baseUrl("http://localhost:8080").build()

Client configuration

In addition to the server settings described earlier, you can also configure client settings, including base URL, default headers, client filters, and more. These options can be easily accessed after executing bindToServer(). For all other configuration options, you must use configureClient() to move from server configuration to client configuration, as shown below:

client = WebTestClient.bindToController(new TestController())
        .configureClient()
        .baseUrl("/test")
        .build();

client = WebTestClient.bindToController(TestController())
        .configureClient()
        .baseUrl("/test")
        .build()