服务端开发

Appearance

WebTestClient：Spring Boot 测试的利器 🚀 ​

什么是 WebTestClient？ ​

WebTestClient 是 Spring Framework 提供的一个专门用于测试 Web 应用程序的 HTTP 客户端。它基于 Spring 的 WebClient 构建，但专门为测试场景设计，提供了丰富的断言和验证功能。

NOTE

WebTestClient 不仅可以进行端到端的 HTTP 测试，还可以在不启动真实服务器的情况下，通过模拟请求和响应对象来测试 Spring MVC 和 Spring WebFlux 应用程序。

为什么需要 WebTestClient？🤔 ​

在传统的 Web 应用测试中，我们经常面临以下痛点：

kotlin
// 传统方式：需要启动完整的服务器
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class TraditionalControllerTest {
    
    @Autowired
    private lateinit var restTemplate: TestRestTemplate
    
    @Test
    fun testGetUser() {
        // 需要真实的服务器运行
        val response = restTemplate.getForEntity("/users/1", User::class.java)
        // 断言相对复杂
        assertEquals(HttpStatus.OK, response.statusCode)
        assertNotNull(response.body)
    }
}
kotlin
// WebTestClient：轻量级、流畅的测试体验
@WebFluxTest(UserController::class)
class WebTestClientControllerTest {
    
    @Autowired
    private lateinit var webTestClient: WebTestClient
    
    @Test
    fun testGetUser() {
        webTestClient.get().uri("/users/1") 
            .exchange() 
            .expectStatus().isOk() 
            .expectBody<User>() 
            .consumeWith { result ->
                val user = result.responseBody!!
                assertEquals("John", user.name)
            }
    }
}

WebTestClient 解决了以下核心问题：

  • 测试速度慢：无需启动完整服务器，测试执行更快
  • 断言复杂：提供链式调用的流畅断言 API
  • 配置繁琐：简化测试配置，专注业务逻辑验证
  • 调试困难：提供清晰的错误信息和测试反馈

WebTestClient 的设置方式 ​

1. 绑定到控制器 (Bind to Controller) ​

这种方式适合测试特定的控制器，通过模拟请求和响应对象进行测试。

kotlin
// 创建一个简单的控制器用于演示
@RestController
class UserController {
    
    @GetMapping("/users/{id}")
    fun getUser(@PathVariable id: Long): User {
        return User(id, "John Doe", "[email protected]")
    }
    
    @PostMapping("/users")
    fun createUser(@RequestBody user: User): ResponseEntity<User> {
        return ResponseEntity.status(HttpStatus.CREATED).body(user)
    }
}

data class User(
    val id: Long,
    val name: String,
    val email: String
)
kotlin
class UserControllerWebFluxTest {
    
    private val webTestClient = WebTestClient
        .bindToController(UserController()) 
        .build()
    
    @Test
    fun `should return user when valid id provided`() {
        webTestClient.get().uri("/users/1")
            .exchange()
            .expectStatus().isOk()
            .expectBody<User>()
            .consumeWith { result ->
                val user = result.responseBody!!
                assertEquals(1L, user.id)
                assertEquals("John Doe", user.name)
            }
    }
}
kotlin
class UserControllerMvcTest {
    
    private val webTestClient = MockMvcWebTestClient
        .bindToController(UserController()) 
        .build()
    
    @Test
    fun `should create user successfully`() {
        val newUser = User(0, "Jane Doe", "[email protected]")
        
        webTestClient.post().uri("/users")
            .bodyValue(newUser)
            .exchange()
            .expectStatus().isCreated()
            .expectBody<User>()
            .consumeWith { result ->
                assertEquals("Jane Doe", result.responseBody!!.name)
            }
    }
}

2. 绑定到应用上下文 (Bind to ApplicationContext) ​

这种方式加载完整的 Spring 配置，适合集成测试。

kotlin
@Configuration
@EnableWebFlux
class WebConfig {
    
    @Bean
    fun userController() = UserController()
    
    @Bean
    fun userService() = UserService()
}

@Service
class UserService {
    private val users = mutableMapOf<Long, User>()
    
    fun findById(id: Long): User? = users[id]
    
    fun save(user: User): User {
        users[user.id] = user
        return user
    }
}
kotlin
@SpringJUnitConfig(WebConfig::class) 
class UserIntegrationWebFluxTest {
    
    private lateinit var webTestClient: WebTestClient
    
    @BeforeEach
    fun setUp(context: ApplicationContext) { 
        webTestClient = WebTestClient
            .bindToApplicationContext(context) 
            .build()
    }
    
    @Test
    fun `should handle complete user workflow`() {
        // 测试完整的用户创建和查询流程
        val user = User(1, "Integration Test User", "[email protected]")
        
        // 创建用户
        webTestClient.post().uri("/users")
            .bodyValue(user)
            .exchange()
            .expectStatus().isCreated()
        
        // 查询用户
        webTestClient.get().uri("/users/1")
            .exchange()
            .expectStatus().isOk()
            .expectBody<User>()
            .consumeWith { result ->
                assertEquals("Integration Test User", result.responseBody!!.name)
            }
    }
}
kotlin
@ExtendWith(SpringExtension::class)
@WebAppConfiguration("classpath:META-INF/web-resources") 
@ContextHierarchy(
    ContextConfiguration(classes = [RootConfig::class]),
    ContextConfiguration(classes = [WebConfig::class])
)
class UserIntegrationMvcTest {
    
    @Autowired
    private lateinit var wac: WebApplicationContext
    
    private lateinit var webTestClient: WebTestClient
    
    @BeforeEach
    fun setUp() {
        webTestClient = MockMvcWebTestClient
            .bindToApplicationContext(wac) 
            .build()
    }
    
    @Test
    fun `should perform end-to-end user operations`() {
        // 端到端测试逻辑
        webTestClient.get().uri("/users")
            .exchange()
            .expectStatus().isOk()
            .expectBodyList<User>()
            .hasSize(0) // 初始状态为空
    }
}

3. 绑定到路由函数 (Bind to Router Function) ​

适用于函数式编程风格的 WebFlux 应用。

kotlin
// 函数式路由定义
@Configuration
class RouterConfig {
    
    @Bean
    fun userRoutes(userHandler: UserHandler): RouterFunction<ServerResponse> {
        return RouterFunctions.route()
            .GET("/api/users/{id}", userHandler::getUser) 
            .POST("/api/users", userHandler::createUser) 
            .build()
    }
}

@Component
class UserHandler {
    
    fun getUser(request: ServerRequest): Mono<ServerResponse> {
        val id = request.pathVariable("id").toLong()
        val user = User(id, "Functional User", "[email protected]")
        return ServerResponse.ok().bodyValue(user)
    }
    
    fun createUser(request: ServerRequest): Mono<ServerResponse> {
        return request.bodyToMono<User>()
            .flatMap { user ->
                ServerResponse.status(HttpStatus.CREATED).bodyValue(user)
            }
    }
}
kotlin
class FunctionalRoutingTest {
    
    private val userHandler = UserHandler()
    private val webTestClient = WebTestClient
        .bindToRouterFunction(RouterConfig().userRoutes(userHandler)) 
        .build()
    
    @Test
    fun `should handle functional routing`() {
        webTestClient.get().uri("/api/users/42")
            .exchange()
            .expectStatus().isOk()
            .expectBody<User>()
            .consumeWith { result ->
                assertEquals(42L, result.responseBody!!.id)
                assertEquals("Functional User", result.responseBody!!.name)
            }
    }
}

4. 绑定到服务器 (Bind to Server) ​

用于真实的端到端测试，连接到运行中的服务器。

kotlin
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class EndToEndTest {
    
    @LocalServerPort
    private var port: Int = 0
    
    private lateinit var webTestClient: WebTestClient
    
    @BeforeEach
    fun setUp() {
        webTestClient = WebTestClient
            .bindToServer() 
            .baseUrl("http://localhost:$port") 
            .build()
    }
    
    @Test
    fun `should perform real HTTP requests`() {
        webTestClient.get().uri("/actuator/health")
            .exchange()
            .expectStatus().isOk()
            .expectBody()
            .jsonPath("$.status").isEqualTo("UP")
    }
}

编写测试用例 ​

基础断言 ​

kotlin
class BasicAssertionsTest {
    
    private val webTestClient = WebTestClient
        .bindToController(UserController())
        .build()
    
    @Test
    fun `should verify status and headers`() {
        webTestClient.get().uri("/users/1")
            .accept(MediaType.APPLICATION_JSON) 
            .exchange()
            .expectStatus().isOk() 
            .expectHeader().contentType(MediaType.APPLICATION_JSON) 
    }
    
    @Test
    fun `should verify multiple expectations with expectAll`() {
        webTestClient.get().uri("/users/1")
            .exchange()
            .expectAll( 
                { spec -> spec.expectStatus().isOk() },
                { spec -> spec.expectHeader().contentType(MediaType.APPLICATION_JSON) },
                { spec -> spec.expectBody<User>().consumeWith { result ->
                    assertNotNull(result.responseBody)
                }}
            )
    }
}

JSON 内容验证 ​

WebTestClient 提供了强大的 JSON 验证能力：

kotlin
class JsonValidationTest {
    
    private val webTestClient = WebTestClient
        .bindToController(UserController())
        .build()
    
    @Test
    fun `should verify complete JSON content`() {
        webTestClient.get().uri("/users/1")
            .exchange()
            .expectStatus().isOk()
            .expectBody()
            .json("""{"id":1,"name":"John Doe","email":"[email protected]"}""") 
    }
    
    @Test
    fun `should verify JSON with JSONPath`() {
        webTestClient.get().uri("/users")
            .exchange()
            .expectStatus().isOk()
            .expectBody()
            .jsonPath("$[0].name").isEqualTo("John Doe") 
            .jsonPath("$[0].email").isEqualTo("[email protected]") 
            .jsonPath("$.length()").isEqualTo(1) 
    }
    
    @Test
    fun `should verify nested JSON structure`() {
        // 假设返回包含嵌套对象的用户信息
        webTestClient.get().uri("/users/1/profile")
            .exchange()
            .expectStatus().isOk()
            .expectBody()
            .jsonPath("$.user.name").isEqualTo("John Doe")
            .jsonPath("$.profile.preferences.theme").isEqualTo("dark")
            .jsonPath("$.profile.settings.notifications").isEqualTo(true)
    }
}

流式响应测试 ​

对于 Server-Sent Events (SSE) 或流式数据的测试：

kotlin
@RestController
class EventController {
    
    @GetMapping("/events", produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
    fun getEvents(): Flux<ServerSentEvent<String>> {
        return Flux.interval(Duration.ofSeconds(1))
            .map { count -> 
                ServerSentEvent.builder<String>()
                    .data("Event $count")
                    .id(count.toString())
                    .build()
            }
            .take(5) // 只发送5个事件用于测试
    }
}

class StreamingResponseTest {
    
    private val webTestClient = WebTestClient
        .bindToController(EventController())
        .build()
    
    @Test
    fun `should handle streaming responses`() {
        val result = webTestClient.get().uri("/events")
            .accept(MediaType.TEXT_EVENT_STREAM) 
            .exchange()
            .expectStatus().isOk()
            .returnResult<String>() 
        
        // 使用 StepVerifier 验证流式数据
        StepVerifier.create(result.responseBody) 
            .expectNext("Event 0")
            .expectNext("Event 1")
            .expectNext("Event 2")
            .expectNextCount(2) // 期望还有2个元素
            .verifyComplete()
    }
}

错误处理测试 ​

kotlin
@RestController
class ErrorHandlingController {
    
    @GetMapping("/users/{id}")
    fun getUser(@PathVariable id: Long): User {
        if (id <= 0) {
            throw IllegalArgumentException("User ID must be positive") 
        }
        if (id == 404L) {
            throw UserNotFoundException("User not found") 
        }
        return User(id, "User $id", "user$id@example.com")
    }
}

class ErrorHandlingTest {
    
    private val webTestClient = WebTestClient
        .bindToController(ErrorHandlingController())
        .build()
    
    @Test
    fun `should handle validation errors`() {
        webTestClient.get().uri("/users/-1")
            .exchange()
            .expectStatus().isBadRequest() 
            .expectBody()
            .jsonPath("$.message").isEqualTo("User ID must be positive")
    }
    
    @Test
    fun `should handle not found errors`() {
        webTestClient.get().uri("/users/404")
            .exchange()
            .expectStatus().isNotFound() 
            .expectBody()
            .jsonPath("$.error").isEqualTo("User not found")
    }
    
    @Test
    fun `should verify empty response for no content`() {
        webTestClient.delete().uri("/users/1")
            .exchange()
            .expectStatus().isNoContent()
            .expectBody().isEmpty() 
    }
}

高级功能与最佳实践 ​

自定义配置 ​

kotlin
class CustomConfigurationTest {
    
    private val webTestClient = WebTestClient
        .bindToController(UserController())
        .configureClient() 
        .baseUrl("/api/v1") 
        .defaultHeader("X-API-Version", "1.0") 
        .defaultCookie("session", "test-session") 
        .responseTimeout(Duration.ofSeconds(10)) 
        .build()
    
    @Test
    fun `should use custom configuration`() {
        webTestClient.get().uri("/users/1") // 实际请求: /api/v1/users/1
            .exchange()
            .expectStatus().isOk()
    }
}

与 MockMvc 断言结合 ​

kotlin
class MockMvcIntegrationTest {
    
    private val webTestClient = MockMvcWebTestClient
        .bindToController(UserController())
        .build()
    
    @Test
    fun `should combine WebTestClient with MockMvc assertions`() {
        val result = webTestClient.get().uri("/users/1")
            .exchange()
            .expectStatus().isOk()
            .expectBody<User>()
            .returnResult() 
        
        // 切换到 MockMvc 断言进行更深层次的验证
        MockMvcWebTestClient.resultActionsFor(result) 
            .andExpect(model().attribute("user", notNullValue()))
            .andExpect(view().name("user-detail"))
    }
}

测试工具类封装 ​

点击查看完整的测试工具类实现
kotlin
/**
 * WebTestClient 测试工具类
 * 提供常用的测试方法和断言封装
 */
class WebTestClientHelper(private val webTestClient: WebTestClient) {
    
    /**
     * GET 请求的便捷方法
     */
    fun get(uri: String): WebTestClient.ResponseSpec {
        return webTestClient.get()
            .uri(uri)
            .accept(MediaType.APPLICATION_JSON)
            .exchange()
    }
    
    /**
     * POST 请求的便捷方法
     */
    fun <T> post(uri: String, body: T): WebTestClient.ResponseSpec {
        return webTestClient.post()
            .uri(uri)
            .contentType(MediaType.APPLICATION_JSON)
            .bodyValue(body)
            .exchange()
    }
    
    /**
     * 验证成功响应并返回指定类型的对象
     */
    inline fun <reified T> expectSuccessWithBody(
        responseSpec: WebTestClient.ResponseSpec
    ): T {
        return responseSpec
            .expectStatus().isOk()
            .expectBody<T>()
            .returnResult()
            .responseBody!!
    }
    
    /**
     * 验证创建成功响应
     */
    inline fun <reified T> expectCreatedWithBody(
        responseSpec: WebTestClient.ResponseSpec
    ): T {
        return responseSpec
            .expectStatus().isCreated()
            .expectBody<T>()
            .returnResult()
            .responseBody!!
    }
    
    /**
     * 验证错误响应
     */
    fun expectError(
        responseSpec: WebTestClient.ResponseSpec,
        expectedStatus: HttpStatus,
        expectedMessage: String? = null
    ) {
        val spec = responseSpec.expectStatus().isEqualTo(expectedStatus)
        
        expectedMessage?.let {
            spec.expectBody()
                .jsonPath("$.message").isEqualTo(it)
        }
    }
}

// 使用示例
class WebTestClientHelperTest {
    
    private val helper = WebTestClientHelper(
        WebTestClient.bindToController(UserController()).build()
    )
    
    @Test
    fun `should use helper methods for cleaner tests`() {
        // 测试获取用户
        val user = helper.expectSuccessWithBody<User>(
            helper.get("/users/1")
        )
        assertEquals("John Doe", user.name)
        
        // 测试创建用户
        val newUser = User(0, "Jane Doe", "[email protected]")
        val createdUser = helper.expectCreatedWithBody<User>(
            helper.post("/users", newUser)
        )
        assertEquals("Jane Doe", createdUser.name)
        
        // 测试错误情况
        helper.expectError(
            helper.get("/users/-1"),
            HttpStatus.BAD_REQUEST,
            "User ID must be positive"
        )
    }
}

实际业务场景示例 ​

让我们通过一个完整的用户管理系统来展示 WebTestClient 的实际应用：

kotlin
// 业务实体
data class User(
    val id: Long = 0,
    val username: String,
    val email: String,
    val status: UserStatus = UserStatus.ACTIVE,
    val createdAt: LocalDateTime = LocalDateTime.now()
)

enum class UserStatus { ACTIVE, INACTIVE, SUSPENDED }

// 业务服务
@Service
class UserService {
    private val users = mutableMapOf<Long, User>()
    private var nextId = 1L
    
    fun createUser(user: User): User {
        val newUser = user.copy(id = nextId++)
        users[newUser.id] = newUser
        return newUser
    }
    
    fun findById(id: Long): User? = users[id]
    
    fun findAll(): List<User> = users.values.toList()
    
    fun updateUser(id: Long, user: User): User? {
        return users[id]?.let {
            val updatedUser = user.copy(id = id)
            users[id] = updatedUser
            updatedUser
        }
    }
    
    fun deleteUser(id: Long): Boolean {
        return users.remove(id) != null
    }
}

// 控制器
@RestController
@RequestMapping("/api/users")
class UserController(private val userService: UserService) {
    
    @GetMapping
    fun getAllUsers(): List<User> = userService.findAll()
    
    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): ResponseEntity<User> {
        return userService.findById(id)
            ?.let { ResponseEntity.ok(it) }
            ?: ResponseEntity.notFound().build()
    }
    
    @PostMapping
    fun createUser(@Valid @RequestBody user: User): ResponseEntity<User> {
        val createdUser = userService.createUser(user)
        return ResponseEntity.status(HttpStatus.CREATED).body(createdUser)
    }
    
    @PutMapping("/{id}")
    fun updateUser(
        @PathVariable id: Long,
        @Valid @RequestBody user: User
    ): ResponseEntity<User> {
        return userService.updateUser(id, user)
            ?.let { ResponseEntity.ok(it) }
            ?: ResponseEntity.notFound().build()
    }
    
    @DeleteMapping("/{id}")
    fun deleteUser(@PathVariable id: Long): ResponseEntity<Void> {
        return if (userService.deleteUser(id)) {
            ResponseEntity.noContent().build()
        } else {
            ResponseEntity.notFound().build()
        }
    }
}

完整的测试套件：

kotlin
@WebMvcTest(UserController::class)
class UserControllerIntegrationTest {
    
    @Autowired
    private lateinit var webTestClient: WebTestClient
    
    @MockBean
    private lateinit var userService: UserService
    
    private val testUser = User(
        id = 1L,
        username = "testuser",
        email = "[email protected]",
        status = UserStatus.ACTIVE
    )
    
    @Test
    fun `should get all users successfully`() {
        // Given
        given(userService.findAll()).willReturn(listOf(testUser))
        
        // When & Then
        webTestClient.get().uri("/api/users")
            .exchange()
            .expectStatus().isOk()
            .expectBodyList<User>()
            .hasSize(1)
            .contains(testUser)
    }
    
    @Test
    fun `should get user by id successfully`() {
        // Given
        given(userService.findById(1L)).willReturn(testUser)
        
        // When & Then
        webTestClient.get().uri("/api/users/1")
            .exchange()
            .expectStatus().isOk()
            .expectBody<User>()
            .consumeWith { result ->
                val user = result.responseBody!!
                assertEquals("testuser", user.username)
                assertEquals("[email protected]", user.email)
                assertEquals(UserStatus.ACTIVE, user.status)
            }
    }
    
    @Test
    fun `should return 404 when user not found`() {
        // Given
        given(userService.findById(999L)).willReturn(null)
        
        // When & Then
        webTestClient.get().uri("/api/users/999")
            .exchange()
            .expectStatus().isNotFound()
            .expectBody().isEmpty()
    }
    
    @Test
    fun `should create user successfully`() {
        // Given
        val newUser = User(username = "newuser", email = "[email protected]")
        val createdUser = newUser.copy(id = 2L)
        given(userService.createUser(any())).willReturn(createdUser)
        
        // When & Then
        webTestClient.post().uri("/api/users")
            .bodyValue(newUser)
            .exchange()
            .expectStatus().isCreated()
            .expectBody<User>()
            .consumeWith { result ->
                val user = result.responseBody!!
                assertEquals(2L, user.id)
                assertEquals("newuser", user.username)
            }
    }
    
    @Test
    fun `should update user successfully`() {
        // Given
        val updatedUser = testUser.copy(username = "updateduser")
        given(userService.updateUser(eq(1L), any())).willReturn(updatedUser)
        
        // When & Then
        webTestClient.put().uri("/api/users/1")
            .bodyValue(updatedUser)
            .exchange()
            .expectStatus().isOk()
            .expectBody<User>()
            .consumeWith { result ->
                assertEquals("updateduser", result.responseBody!!.username)
            }
    }
    
    @Test
    fun `should delete user successfully`() {
        // Given
        given(userService.deleteUser(1L)).willReturn(true)
        
        // When & Then
        webTestClient.delete().uri("/api/users/1")
            .exchange()
            .expectStatus().isNoContent()
            .expectBody().isEmpty()
    }
    
    @Test
    fun `should return 404 when deleting non-existent user`() {
        // Given
        given(userService.deleteUser(999L)).willReturn(false)
        
        // When & Then
        webTestClient.delete().uri("/api/users/999")
            .exchange()
            .expectStatus().isNotFound()
    }
}

测试执行流程图 ​

最佳实践与注意事项 ​

测试最佳实践

  1. 选择合适的绑定方式：单元测试用 bindToController，集成测试用 bindToApplicationContext
  2. 使用 expectAll：当有多个断言时，确保所有断言都被执行
  3. 合理使用 Mock：在单元测试中 Mock 依赖服务，在集成测试中使用真实配置
  4. 测试边界情况：不仅测试正常流程，还要测试异常情况和边界值

常见陷阱

  • 不要在测试中使用真实的外部服务调用
  • 注意测试数据的隔离，避免测试之间相互影响
  • 合理设置超时时间，避免测试执行时间过长

性能考虑

WebTestClient 的模拟测试比真实服务器测试快得多，但仍需注意：

  • 避免在测试中进行复杂的数据准备
  • 使用 @DirtiesContext 注解时要谨慎，会重新加载应用上下文

总结 ​

WebTestClient 是 Spring Boot 测试生态系统中的一个强大工具，它通过以下方式解决了传统 Web 测试的痛点：

✅ 简化测试配置：提供多种绑定方式，适应不同测试场景
✅ 流畅的断言 API：链式调用让测试代码更易读易写
✅ 高性能测试：无需启动真实服务器，测试执行更快
✅ 丰富的验证功能：支持 JSON、流式响应、错误处理等多种验证场景

通过合理使用 WebTestClient，我们可以编写出既高效又可靠的 Web 应用测试，确保应用程序的质量和稳定性。🎉