跳到主要内容

WebTestClient

ChatGPT-4o-mini 中英对照 WebTestClient

WebTestClient 是一个用于测试服务器应用程序的 HTTP 客户端。它封装了 Spring 的 WebClient，并使用它来执行请求，但提供了一个测试外观以验证响应。WebTestClient 可以用于执行端到端的 HTTP 测试。它还可以用于测试 Spring MVC 和 Spring WebFlux 应用程序，而无需运行服务器，通过模拟服务器请求和响应对象进行测试。

设置​

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

绑定到控制器​

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

对于 WebFlux 应用程序，请使用以下内容，它加载与 WebFlux Java 配置 等效的基础设施，注册给定的控制器，并创建一个 WebHandler 链 来处理请求：

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

对于 Spring MVC，使用以下内容，它委托给 StandaloneMockMvcBuilder 来加载与 WebMvc Java config 等效的基础设施，注册给定的控制器，并创建一个 MockMvc 实例来处理请求：

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

绑定到 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
    }
}
java

  • 指定要加载的配置

  • 注入配置

  • 创建 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
    }
}
java

  • 指定要加载的配置

  • 注入配置

  • 创建 WebTestClient

绑定到路由器函数​

此设置允许您通过模拟请求和响应对象测试 功能端点，而无需运行服务器。

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

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

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

绑定到服务器​

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

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

客户端配置​

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

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

编写测试​

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);
java

如果您希望即使其中一个期望失败也能断言所有期望，可以使用 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)
    );
java

您可以选择通过以下方式解码响应主体：

  • 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);
java

如果内置的断言不足，可以直接使用对象并执行其他断言：

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

或者您可以退出工作流并获得一个 EntityExchangeResult：

EntityExchangeResult<Person> result = client.get().uri("/persons/1")
        .exchange()
        .expectStatus().isOk()
        .expectBody(Person.class)
        .returnResult();
java
提示

当你需要解码到一个目标类型并使用泛型时，寻找接受 ParameterizedTypeReference 的重载方法，而不是 Class<T>。

无内容​

如果响应不应该包含内容，可以这样断言：

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

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

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

JSON 内容​

您可以使用 expectBody() 而不指定目标类型，以对原始内容进行断言，而不是通过更高级的对象进行断言。

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

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

要使用 JSONPath 验证 JSON 内容：

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

流式响应​

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

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

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

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

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

MockMvc 断言​

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

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

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

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