对于最新稳定版本，请使用 Spring Framework 7.0.6！spring-doc.cadn.net.cn

WebTestClient

WebTestClient 是一个专为测试服务器应用程序而设计的 HTTP 客户端。它封装了 Spring 的 WebClient，并使用它来执行请求，但同时提供了一个用于验证响应的测试外观（facade）。WebTestClient 可用于执行端到端的 HTTP 测试。此外，它还可以通过模拟的服务器请求和响应对象，在无需启动服务器的情况下测试 Spring MVC 和 Spring WebFlux 应用程序。spring-doc.cadn.net.cn

Kotlin 用户：请参阅本节， 其中介绍了 WebTestClient 的使用。

设置

要设置 WebTestClient，您需要选择一个要绑定的服务器配置。这可以是多种模拟服务器配置选项之一，也可以是连接到一个真实运行的服务器。spring-doc.cadn.net.cn

绑定到控制器

此设置允许您通过模拟的请求和响应对象测试特定的控制器，而无需启动服务器。spring-doc.cadn.net.cn

对于 WebFlux 应用程序，请使用以下方式：它会加载与WebFlux Java 配置等效的基础设施，注册给定的控制器，并创建一个WebHandler 链来处理请求：spring-doc.cadn.net.cn

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

对于 Spring MVC，请使用以下方式，它会委托给 StandaloneMockMvcBuilder 以加载与 WebMvc Java 配置 等效的基础设施， 注册给定的控制器，并创建一个 MockMvc 实例来处理请求：spring-doc.cadn.net.cn

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

绑定到ApplicationContext

此设置允许你加载包含 Spring MVC 或 Spring WebFlux 基础设施及控制器声明的 Spring 配置，并使用该配置通过模拟的请求和响应对象来处理请求，而无需启动服务器。spring-doc.cadn.net.cn

对于 WebFlux，请使用以下方式，其中 Spring ApplicationContext 被传递给 WebHttpHandlerBuilder 以创建WebHandler 链来处理请求：spring-doc.cadn.net.cn

@SpringJUnitConfig(WebConfig.class) (1)
class MyTests {

	WebTestClient client;

	@BeforeEach
	void setUp(ApplicationContext context) {  (2)
		client = WebTestClient.bindToApplicationContext(context).build(); (3)
	}
}
1 指定要加载的配置
2 注入配置
3 创建 WebTestClient 
@SpringJUnitConfig(WebConfig::class) (1)
class MyTests {

	lateinit var client: WebTestClient

	@BeforeEach
	fun setUp(context: ApplicationContext) { (2)
		client = WebTestClient.bindToApplicationContext(context).build() (3)
	}
}
1 指定要加载的配置
2 注入配置
3 创建 WebTestClient

对于 Spring MVC，请使用以下方式，其中将 Spring 的 ApplicationContext 传递给 MockMvcBuilders.webAppContextSetup 以创建一个 MockMvc 实例来处理请求：spring-doc.cadn.net.cn

@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)
	}
}
1 指定要加载的配置
2 注入配置
3 创建 WebTestClient 
@ExtendWith(SpringExtension.class)
@WebAppConfiguration("classpath:META-INF/web-resources") (1)
@ContextHierarchy({
	@ContextConfiguration(classes = RootConfig.class),
	@ContextConfiguration(classes = WebConfig.class)
})
class MyTests {

	@Autowired
	lateinit var wac: WebApplicationContext; (2)

	lateinit var client: WebTestClient

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

绑定到路由函数

此设置允许您通过模拟请求和响应对象来测试函数式端点，而无需启动服务器。spring-doc.cadn.net.cn

对于 WebFlux，请使用以下方式，它会委托给 RouterFunctions.toWebHandler 来创建一个用于处理请求的服务器配置：spring-doc.cadn.net.cn

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

对于 Spring MVC，目前没有选项可用于测试 WebMvc 函数式端点。spring-doc.cadn.net.cn

绑定到服务器

此设置连接到一个正在运行的服务器，以执行完整的端到端 HTTP 测试：spring-doc.cadn.net.cn

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

客户端配置

除了前面描述的服务器设置选项外，您还可以配置客户端选项，包括基础 URL、默认请求头、客户端过滤器等。在调用 bindToServer() 之后，这些选项即可直接使用。对于所有其他配置选项，您需要使用 configureClient() 从服务器配置切换到客户端配置，如下所示：spring-doc.cadn.net.cn

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

编写测试

WebTestClient 提供的 API 与 WebClient 完全相同， 直到调用 exchange() 执行请求为止。有关如何 准备包含表单数据、多部分数据等任意内容的请求示例，请参阅 WebClient 文档。spring-doc.cadn.net.cn

在调用 exchange() 之后，WebTestClient 便与 WebClient 分道扬镳，转而继续执行用于验证响应的工作流程。spring-doc.cadn.net.cn

要断言响应状态和响应头，请使用以下方式：spring-doc.cadn.net.cn

client.get().uri("/persons/1")
	.accept(MediaType.APPLICATION_JSON)
	.exchange()
	.expectStatus().isOk()
	.expectHeader().contentType(MediaType.APPLICATION_JSON);
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() 支持。spring-doc.cadn.net.cn

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

然后，您可以选择通过以下方式之一对响应体进行解码：spring-doc.cadn.net.cn

并对生成的高层级对象（Object(s)）执行断言：spring-doc.cadn.net.cn

client.get().uri("/persons")
		.exchange()
		.expectStatus().isOk()
		.expectBodyList(Person.class).hasSize(3).contains(person);
import org.springframework.test.web.reactive.server.expectBodyList

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

如果内置的断言不够用，你可以改为消费该对象，并执行任何其他断言：spring-doc.cadn.net.cn

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

client.get().uri("/persons/1")
		.exchange()
		.expectStatus().isOk()
		.expectBody(Person.class)
		.consumeWith(result -> {
			// custom assertions (e.g. AssertJ)...
		});
client.get().uri("/persons/1")
		.exchange()
		.expectStatus().isOk()
		.expectBody<Person>()
		.consumeWith {
			// custom assertions (e.g. AssertJ)...
		}

或者，您可以退出工作流并获取一个 EntityExchangeResult：spring-doc.cadn.net.cn

EntityExchangeResult<Person> result = client.get().uri("/persons/1")
		.exchange()
		.expectStatus().isOk()
		.expectBody(Person.class)
		.returnResult();
import org.springframework.test.web.reactive.server.expectBody

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

无内容

如果预期响应不包含内容，你可以按如下方式断言：spring-doc.cadn.net.cn

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

如果你想要忽略响应内容，以下方式会释放内容而不进行任何断言：spring-doc.cadn.net.cn

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

JSON 内容

您可以使用 expectBody() 方法而不指定目标类型，以便对原始内容执行断言，而不是通过更高层次的对象进行断言。spring-doc.cadn.net.cn

使用 JSONAssert 验证完整的 JSON 内容：spring-doc.cadn.net.cn

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

使用 JSONPath 验证 JSON 内容：spring-doc.cadn.net.cn

client.get().uri("/persons")
		.exchange()
		.expectStatus().isOk()
		.expectBody()
		.jsonPath("$[0].name").isEqualTo("Jane")
		.jsonPath("$[1].name").isEqualTo("Jason");
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：spring-doc.cadn.net.cn

FluxExchangeResult<MyEvent> result = client.get().uri("/events")
		.accept(TEXT_EVENT_STREAM)
		.exchange()
		.expectStatus().isOk()
		.returnResult(MyEvent.class);
import org.springframework.test.web.reactive.server.returnResult

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

现在，你可以使用来自 StepVerifier 的 reactor-test 来消费响应流了：spring-doc.cadn.net.cn

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

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

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

MockMvc 断言

WebTestClient 是一个 HTTP 客户端，因此它只能验证客户端响应中的内容，包括状态、头信息和正文。spring-doc.cadn.net.cn

在使用 MockMvc 服务器设置测试 Spring MVC 应用程序时，您可以额外选择对服务器响应执行进一步的断言。为此，请在断言响应体之后，首先获取一个 ExchangeResult：spring-doc.cadn.net.cn

// 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();
// For a response with a body
val result = client.get().uri("/persons/1")
		.exchange()
		.expectStatus().isOk()
		.expectBody(Person.class)
		.returnResult();

// For a response without a body
val result = client.get().uri("/path")
		.exchange()
		.expectBody().isEmpty();

然后切换到 MockMvc 服务器响应断言：spring-doc.cadn.net.cn

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