WebTest客户端 (WebTestClient) _ Spring Framework6.2.0-SNAPSHOT中文文档(官方文档中文翻译)|Spring 教程 —

此版本仍在开发中，尚未被视为稳定版本。最新的稳定版本请使用 Spring Framework 6.1.13！spring-doc.cn

WebTestClient是专为测试服务器应用程序而设计的 HTTP 客户端。它包装 Spring 的 WebClient 并使用它来执行请求但公开了一个用于验证响应的 testing 门面。可用于执行端到端 HTTP 测试。它还可用于测试 Spring MVC 和 Spring WebFlux 没有正在运行的服务器的应用程序通过 Mock Server 请求和响应对象。WebTestClientspring-doc.cn

设置

要设置，您需要选择要绑定到的服务器设置。这可以是的几个模拟服务器设置选项或连接到实时服务器。WebTestClientspring-doc.cn

绑定到控制器

此设置允许您通过 mock 请求和响应对象测试特定的控制器，没有正在运行的服务器。spring-doc.cn

对于 WebFlux 应用程序，使用以下命令加载相当于 WebFlux Java 配置的基础设施，注册给定的控制器，并创建一个 WebHandler 链来处理请求：spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

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

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

绑定到`ApplicationContext`

此设置允许您使用 Spring MVC 或 Spring WebFlux 加载 Spring 配置 infrastructure 和 controller 声明，并使用它通过 mock 请求处理请求和 response 对象，但没有正在运行的服务器。spring-doc.cn

对于 WebFlux，请使用以下命令将 Spring 传递给 WebHttpHandlerBuilder 来创建要处理的 WebHandler 链请求：ApplicationContextspring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.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 传递给 MockMvcBuilders.webAppContextSetup 以创建一个 MockMvc 实例来处理请求：ApplicationContextspring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.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`

绑定到路由器功能

此设置允许您通过以下方式测试功能端点 mock 请求和响应对象，而无需正在运行的服务器。spring-doc.cn

对于 WebFlux，请使用以下命令，将 delegates to 创建 Server Setup 以处理请求：RouterFunctions.toWebHandlerspring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

对于 Spring MVC，目前没有测试 WebMvc 功能端点的选项。spring-doc.cn

绑定到服务器

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

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

客户端配置

除了前面描述的 server 设置选项之外，您还可以配置 client 选项，包括基本 URL、默认标头、客户端筛选器等。这些选项在 .对于所有其他配置选项，您需要使用 to 从 Server 过渡到 Client 端配置，因为遵循：bindToServer()configureClient()spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

1	指定要加载的配置
2	注入配置
3	创建`WebTestClient`

1	指定要加载的配置
2	注入配置
3	创建`WebTestClient`

1	指定要加载的配置
2	注入配置
3	创建`WebTestClient`

1	指定要加载的配置
2	注入配置
3	创建`WebTestClient`

编写测试

WebTestClient提供与 WebClient 相同的 API，直到使用执行请求为止。有关如何执行以下操作的示例，请参阅 WebClient 文档准备包含任何内容（包括表单数据、多部分数据等）的请求。exchange()spring-doc.cn

在调用后，与和不同而是继续使用工作流来验证响应。exchange()WebTestClientWebClientspring-doc.cn

要断言响应状态和标头，请使用以下内容：spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.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)

如果您希望即使其中一个期望失败，也可以断言所有期望，则可以 use 而不是多个链式调用。此功能是类似于 AssertJ 中的软断言支持和 JUnit Jupiter.expectAll(..)expect*(..)assertAll()spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

然后，您可以选择通过以下方法之一对响应正文进行解码：spring-doc.cn

expectBody(Class<T>)：解码为单个对象。spring-doc.cn
expectBodyList(Class<T>)：解码并收集对象到。List<T>spring-doc.cn
expectBody()：解码为 JSON 内容或空正文。byte[]spring-doc.cn

并对生成的更高级别 Object 执行断言：spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.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.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

   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)...
		});

client.get().uri("/persons/1")
		.exchange()
		.expectStatus().isOk()
		.expectBody<Person>()
		.consumeWith {
			// custom assertions (for example, AssertJ)...
		}

或者，您可以退出工作流并获取：EntityExchangeResultspring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.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.cn

Javaspring-doc.cn
Kotlinspring-doc.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.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

JSON 内容

您可以在没有目标类型的情况下对原始 content 而不是通过更高级别的 Object（s）。expectBody()spring-doc.cn

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

Javaspring-doc.cn
Kotlinspring-doc.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.cn

Javaspring-doc.cn
Kotlinspring-doc.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"FluxExchangeResultspring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.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>()

现在，你已准备好使用 from 的响应流：StepVerifierreactor-testspring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.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 客户端，因此它只能验证客户端中的内容响应，包括 status、Headers 和 Body。spring-doc.cn

当使用 MockMvc 服务器设置测试 Spring MVC 应用程序时，您有额外的选择对服务器响应执行进一步的断言。为此，首先在断言 body 后获取一个：ExchangeResultspring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.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>()
		.returnResult()

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

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

Javaspring-doc.cn
Kotlinspring-doc.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"));

当您需要使用泛型解码为目标类型时，请查找重载的方法接受 ParameterizedTypeReference 而不是 .Class<T>

设置

绑定到控制器

绑定到ApplicationContext

绑定到路由器功能

绑定到服务器

客户端配置

编写测试

无内容

JSON 内容

流式响应

MockMvc 断言

绑定到`ApplicationContext`