liveBook · Manning

WebTestClient

As explained in Testing Spring Boot Applications

WebTestClient is Spring's HTTP testing client for exercising web applications, including reactive applications, without requiring a browser.

WebTestClient exercises WebFlux applications with a fluent HTTP-style API. Because WebFlux does not provide the mock MVC stack, MockMvcTester is unavailable; WebTestClient fills that role for reactive web tests. Add the test-scoped `spring-boot-starter-webflux-test` dependency if it is not already in the project. section 4.2.2

Listing 4.10 A WebTestClient-based test
@SpringBootTest
@AutoConfigureWebTestClient #1
class ApiWebClientTests {

  @Autowired
  private WebTestClient client; #2

  @Test
  void indexPageHasSelectedCity() {
    selectCity("Paris");

    client.get()
      .uri("/")
      .exchange() #3
      .expectStatus() #4
      .isOk() #4
      .expectBody(String.class) #4
      .value(body -> #4
        assertThat(body).contains("Paris (France)") #4
      );
  }

}

A typical test combines `@SpringBootTest` and `@AutoConfigureWebTestClient`, injects the client, then exchanges a GET request and checks its status and body. With the default mock web environment, the reactive server does not start. section 4.2.2

Status and body checks have dedicated assertion methods. A body-value callback can also use AssertJ. For a fully AssertJ-style response chain, Spring Framework 7 in Spring Boot 4 provides `WebTestClientResponse.from(...)`; using that bridge is a style choice, not a requirement. section 4.2.2

Listing 4.11 Bridging WebTestClient and AssertJ
@Test
void indexPageHasSelectedCityAssertJ() {
  selectCity("Paris");

  var webClientResponse = client.get().uri("/").exchange(); #1
  var response = WebTestClientResponse.from(webClientResponse); #2
  assertThat(response).hasStatusOk() #3
    .bodyText()
    .contains("Paris (France)");
}

The bridge converts the exchanged response for fluent AssertJ assertions on status and body text. section 4.2.2

Use `@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)` when a test needs an actual web server, such as for server-level error dispatch or session handling. An autoconfigured WebTestClient receives the running application's base URL, so requests need not specify its changing port. Full-server tests load more components and can run more slowly. For browser behavior, use a browser-oriented tool instead. section 4.3 section 4.6

How Testing Spring Boot Applications covers it

How deep it goes
Shows dependency, autoconfiguration, request and assertion code, then contrasts mock execution with full-server tests.
Examples
Tests a GET response for a selected city and converts another response for fluent AssertJ assertions.
What it assumes
Assumes a Spring Boot WebFlux application; specifies the test dependency and annotations needed to configure the client.
What you can do after
Apply it via WebTestClient to check response status and body in mock or random-port web tests.
How it connects
Connects WebTestClient to WebFlux, WebClient, AssertJ, Spring Boot integration tests, and random-port server testing.

Also explained in

Compare how 2 books explain WebTestClient →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Testing Spring Boot Applications. The section links point to the parts of the book it draws on.