WebTestClient

WebTestClient 是一个设计用于测试服务器应用程序的 HTTP 客户端。它包装了 WebClient 并使用它来执行请求，但暴露了一个测试门面（testing facade）用于验证响应。WebTestClient 可用于执行端到端 HTTP 测试。它还可以通过 mock 服务器请求和响应对象，在没有运行服务器的情况下测试 Web MVC 和 Infra WebFlux 应用程序。

设置

要设置 WebTestClient，你需要选择一个要绑定的服务器设置。这可以是几个 mock 服务器设置选项之一，也可以是连接到一个实时服务器。

绑定到控制器

此设置允许你通过 mock 请求和响应对象测试特定控制器，而无需运行服务器。

  • Java

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

对于 Web MVC，使用以下代码，它委托给 StandaloneMockMvcBuilder 来加载等同于 WebMvc Java 配置 的基础设施，注册给定的控制器，并创建一个 MockMvc 实例来处理请求：

  • Java

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

绑定到 ApplicationContext

此设置允许你加载带有 Web MVC 或 Infra WebFlux 基础设施和控制器声明的 Infra 配置，并使用它通过 mock 请求和响应对象处理请求，而无需运行服务器。

对于 Web MVC，使用以下代码，其中 Infra ApplicationContext 被传递给 MockMvcBuilders.webAppContextSetup 以创建一个 MockMvc 实例来处理请求：

@ExtendWith(InfraExtension.class)
@WebAppConfiguration("classpath:META-INF/web-resources") (1)
@ContextHierarchy({
  @ContextConfiguration(classes = RootConfig.class),
  @ContextConfiguration(classes = WebConfig.class)
})
class MyTests {

  @Autowired
  WebApplicationContext wac; (2)

  WebTestClient client;

  @BeforeEach
  void setUp() {
    client = MockMvcWebTestClient.bindToApplicationContext(this.wac).build(); (3)
  }
}
1 指定要加载的配置
2 注入配置
3 创建 WebTestClient

绑定到 Router Function

此设置允许你通过 mock 请求和响应对象测试函数式端点，而无需运行服务器。

对于 WebFlux，使用以下代码，它委托给 RouterFunctions.toWebHandler 创建服务器设置以处理请求：

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

对于 Web MVC，目前没有选项测试 WebMvc 函数式端点。

绑定到服务器

此设置连接到运行中的服务器以执行完整的端到端 HTTP 测试：

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

客户端配置

除了前面描述的服务器设置选项外，你还可以配置客户端选项，包括基础 URL、默认头、客户端过滤器等。这些选项在 bindToServer() 之后立即可用。对于所有其他配置选项，你需要使用 configureClient() 从服务器配置过渡到客户端配置，如下所示：

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

编写测试

WebTestClient 提供了一个与 WebClient 相同的 API，直到使用 exchange() 执行请求的那一点。有关如何准备包含表单数据、多部分数据等任何内容的请求的示例，请参阅 WebClient 文档。

在调用 exchange() 之后，WebTestClient 与 WebClient 分道扬镳，转而继续执行验证响应的工作流。

要断言响应状态和头，请使用以下代码：

client.get().uri("/persons/1")
  .accept(MediaType.APPLICATION_JSON)
  .exchange()
  .expectStatus().isOk()
  .expectHeader().contentType(MediaType.APPLICATION_JSON);

如果你希望即使其中一个期望失败也能断言所有期望，可以使用 expectAll(..) 代替多个链式 expect*(..) 调用。此功能类似于 AssertJ 中的 soft assertions 支持和 JUnit Jupiter 中的 assertAll() 支持。

client.get().uri("/persons/1")
  .accept(MediaType.APPLICATION_JSON)
  .exchange()
  .expectAll(
    spec -> spec.expectStatus().isOk(),
    spec -> spec.expectHeader().contentType(MediaType.APPLICATION_JSON)
  );

然后，你可以选择通过以下方式之一解码响应体：

  • expectBody(Class<T>): 解码为单个对象。

  • expectBodyList(Class<T>): 解码并收集对象到 List<T>。

  • expectBody(): 解码为 byte[] 以用于 JSON 内容 或空体。

并对生成的高级对象执行断言：

client.get().uri("/persons")
		.exchange()
		.expectStatus().isOk()
		.expectBodyList(Person.class).hasSize(3).contains(person);

如果内置断言不足够，你可以消费对象并执行任何其他断言：

import infra.test.web.reactive.server.expectBody

client.get().uri("/persons/1")
  .exchange()
  .expectStatus().isOk()
  .expectBody(Person.class)
  .consumeWith(result -> {
    // 自定义断言 (例如 AssertJ)...
  });

或者你可以退出工作流并获取 EntityExchangeResult：

EntityExchangeResult<Person> result = client.get().uri("/persons/1")
    .exchange()
    .expectStatus().isOk()
    .expectBody(Person.class)
    .returnResult();
当你需要解码为带有泛型的目标类型时，请寻找接受 ParameterizedTypeReference 而不是 Class<T> 的重载方法。

无内容

如果预期响应没有内容，你可以按如下方式断言：

client.post().uri("/persons")
    .body(personMono, Person.class)
    .exchange()
    .expectStatus().isCreated()
    .expectBody().isEmpty();

如果你想忽略响应内容，以下代码将释放内容而不进行任何断言：

client.get().uri("/persons/123")
    .exchange()
    .expectStatus().isNotFound()
    .expectBody(Void.class);

JSON 内容

你可以使用不带目标类型的 expectBody() 来对原始内容而不是高级对象执行断言。

要使用 JSONAssert 验证完整的 JSON 内容：

client.get().uri("/persons/1")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json("{\"name\":\"Jane\"}")

要使用 JSONPath 验证 JSON 内容：

client.get().uri("/persons")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .jsonPath("$[0].name").isEqualTo("Jane")
    .jsonPath("$[1].name").isEqualTo("Jason");

流式响应

要测试潜在的无限流，如 "text/event-stream" 或 "application/x-ndjson"，首先验证响应状态和头，然后获取 FluxExchangeResult：

FluxExchangeResult<MyEvent> result = client.get().uri("/events")
    .accept(TEXT_EVENT_STREAM)
    .exchange()
    .expectStatus().isOk()
    .returnResult(MyEvent.class);

现在你已准备好使用 reactor-test 中的 StepVerifier 消费响应流：

Flux<Event> eventFlux = result.getResponseBody();

StepVerifier.create(eventFlux)
    .expectNext(person)
    .expectNextCount(4)
    .consumeNextWith(p -> ...)
    .thenCancel()
    .verify();

MockMvc 断言

WebTestClient 是一个 HTTP 客户端，因此它只能验证客户端响应中的内容，包括状态、头和体。

当使用 MockMvc 服务器设置测试 Web MVC 应用程序时，你可以额外选择对服务器响应执行进一步断言。为此，请在断言体之后获取 ExchangeResult：

// 对于带有体的响应
EntityExchangeResult<Person> result = client.get().uri("/persons/1")
    .exchange()
    .expectStatus().isOk()
    .expectBody(Person.class)
    .returnResult();

// 对于没有体的响应
EntityExchangeResult<Void> result = client.get().uri("/path")
    .exchange()
    .expectBody().isEmpty();

然后切换到 MockMvc 服务器响应断言：

MockMvcWebTestClient.resultActionsFor(result)
    .andExpect(model().attribute("integer", 3))
    .andExpect(model().attribute("string", "a string value"));