跳到主要内容
版本：7.0.3

WebTestClient

Hunyuan 7b 中英对照 WebTestClient

WebTestClient 是一种专为测试服务器应用程序而设计的 HTTP 客户端。它封装了 Spring 的 WebClient，利用该客户端执行请求，但提供了用于验证响应的测试接口。WebTestClient 可以用来执行端到端的 HTTP 测试。此外，通过使用模拟的请求和响应对象，它还可以在没有运行中的服务器的情况下测试 Spring MVC 和 Spring WebFlux 应用程序。

设置​

要设置一个WebTestClient，您需要选择一个要绑定的服务器配置。这可以是几种模拟服务器配置选项中的一种，也可以是与实时服务器的连接。

绑定到控制器​

这种设置允许你通过模拟的请求和响应对象来测试特定的控制器，而无需运行服务器。

对于 WebFlux 应用程序，可以使用以下方法：该方法会加载与 WebFlux Java 配置 相当的基础设施，注册给定的控制器，并创建一个 WebHandler 链 来处理请求：

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

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

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

绑定到 ApplicationContext​

这种设置允许你使用Spring MVC或Spring WebFlux基础设施以及控制器声明来加载Spring配置，并通过模拟请求和响应对象来处理请求，而无需运行服务器。

对于 WebFlux，在将 Spring ApplicationContext 传递给 WebHttpHandlerBuilder 以创建用于处理请求的 WebHandler 链 时，请使用以下方法：

@SpringJUnitConfig(WebConfig.class) 1
class MyTests {

	WebTestClient client;

	@BeforeEach
	void setUp(ApplicationContext context) {  2
		client = WebTestClient.bindToApplicationContext(context).build(); 3
	}
}

  • 指定要加载的配置

  • 注入配置

  • 创建 WebTestClient

对于Spring MVC，当Spring的ApplicationContext被传递给MockMvcBuilders.webAppContextSetup时，使用以下方法来创建一个MockMvc实例来处理请求：

@ExtendWith(SpringExtension.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
	}
}

  • 指定要加载的配置

  • 注入配置

  • 创建 WebTestClient

绑定到路由器函数​

这种设置允许你通过模拟请求和响应对象来测试函数端点，而无需运行服务器。

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

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

对于Spring MVC，目前还没有选项可以测试WebMvc功能端点。

绑定到服务器​

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

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

客户端配置​

除了前面描述的服务器设置选项外，您还可以配置客户端选项，包括基础URL、默认头部信息、客户端过滤器等。这些选项在调用bindToServer()之后就可以轻松访问了。对于所有其他的配置选项，您需要使用configureClient()来从服务器配置切换到客户端配置，具体操作如下：

client = WebTestClient.bindToController(new TestController())
		.configureClient()
		.baseUrl("/test")
		.apiVersionInserter(ApiVersionInserter.fromHeader("API-Version").build())
		.build();

编写测试​

WebClient 和 WebTestClient 在调用 exchange() 之前的 API 是相同的。在此之后，WebTestClient 提供了两种替代方法来验证响应：

  1. 内置断言 通过一系列预期来扩展请求工作流程
  2. AssertJ集成 通过 assertThat() 语句验证响应
提示

有关如何准备包含表单数据、多部分数据等内容的请求的示例，请参阅WebClient文档。

内置断言​

要获取响应状态码和头部信息，请使用以下方法：

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

如果你希望所有预期都能得到验证，即使其中有一个失败了，你可以使用expectAll(..)，而不用多个连续的expect*(..)调用。这个功能类似于AssertJ中的软断言支持以及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内容），或者为空体。

并对得到的更高层次的对象（Object(s)）进行断言（assertions）：

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

如果内置的断言不足以满足需求，你可以直接使用该对象，并执行任何其他的断言操作：

import org.springframework.test.web.reactive.server.expectBody

client.get().uri("/persons/1")
		.exchange()
		.expectStatus().isOk()
		.expectBody(Person.class)
		.consumeWith(result -> {
			// custom assertions (for example, 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()方法而无需指定目标类型，从而直接对原始内容进行断言，而无需通过更高层次的Object对象来进行。

要使用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();

AssertJ集成​

WebTestClientResponse 是 AssertJ 集成的主要入口点。它是一个 AssertProvider，用于封装交换（exchange）的 ResponseSpec，以便能够使用 assertThat() 语句。例如：

ResponseSpec spec = client.get().uri("/persons").exchange();

WebTestClientResponse response = WebTestClientResponse.from(spec);
assertThat(response).hasStatusOk();
assertThat(response).hasContentTypeCompatibleWith(MediaType.TEXT_PLAIN);
// ...

您也可以首先使用内置的工作流，然后获取一个 ExchangeResult 来包装它，并继续使用 AssertJ。例如：

ExchangeResult result = client.get().uri("/persons").exchange()
		. // ...
		.returnResult();

WebTestClientResponse response = WebTestClientResponse.from(result);
assertThat(response).hasStatusOk();
assertThat(response).hasContentTypeCompatibleWith(MediaType.TEXT_PLAIN);
// ...

MockMvcAssertions​

WebTestClient 是一个 HTTP 客户端，因此它只能验证客户端响应中的内容，包括状态码、头部信息（headers）和响应体（body）。

在使用MockMvc服务器设置测试Spring MVC应用程序时，你还可以进一步对服务器响应进行断言。要这样做，首先在完成对响应体的断言后获取一个ExchangeResult对象：

// For a response with a body
EntityExchangeResult<Person> result = client.get().uri("/persons/1")
		.exchange()
		.expectStatus().isOk()
		.expectBody(Person.class)
		.returnResult();

// For a response without a body
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"));