# 使用 WireMock 对 REST API 进行单元测试 ## 概述该技能提供了使用 WireMock 对外部 REST API 集成进行单元测试的全面模式。它涵盖了存根 HTTP 响应、验证请求、测试错误场景（4xx/5xx 响应）以及确保快速、可靠的测试，而无需真正的网络依赖。 ## 何时使用在以下情况下使用此技能： * 测试调用外部REST API的服务 * 需要存根 HTTP 响应以实现可预测的测试行为 * 想要测试错误场景（超时、500 错误、格式错误的响应） * 需要验证请求详细信息（标头、查询参数、请求正文） * 与第三方服务集成（支付网关、天气API等） * 测试没有网络依赖性或速率限制 * 构建在 CI/CD 管道中快速运行的单元测试 ## 说明请按照以下步骤使用 WireMock 测试外部 REST API： ### 1\.添加 WireMock 依赖项将wiremock 与JUnit 5 和AssertJ 一起包含在测试范围中。 ### 2\.注册 WireMock 扩展将 @RegisterExtension 与 WireMockExtension.newInstance().options(wireMockConfig().dynamicPort()) 一起使用进行动态端口分配。 ### 3\.配置 HTTP 客户端使用wireMock.getRuntimeInfo().getHttpBaseUrl()将WireMock基本URL注入到您的API客户端中。 ### 4\.存根 HTTP 响应使用stubFor() 定义请求匹配和响应行为。 ### 5\.执行测试逻辑调用与外部 API 交互的服务方法。 ### 6\.断言结果使用 AssertJ 断言验证服务行为。 ### 7\.验证请求使用 verify() 确保将正确的请求发送到外部 API。 ## 示例 ## 核心依赖 ### Maven <依赖关系> org.wiremock wiremock <版本>3.4.1 <范围>测试 <依赖关系> org.junit.jupiter junit-jupiter <范围>测试 <依赖关系> org.assertj assertj-core <范围>测试 ### 摇篮依赖项{ testImplementation("org.wiremock:wiremock:3.4.1") testImplementation("org.junit.jupiter:junit-jupiter") testImplementation("org.assertj:assertj-core") } ## 基本模式：存根和验证 ### 带有 WireMock 扩展的简单存根导入 com.github.tomakehurst.wiremock.junit5.WireMockExtension; 导入 org.junit.jupiter.api.Test; 导入 org.junit.jupiter.api.extension.RegisterExtension; 导入静态 com.github.tomakehurst.wiremock.client.WireMock.*; 导入静态 org.assertj.core.api.Assertions.assertThat; 类外部天气服务测试{ @注册扩展静态 WireMockExtensionwireMock = WireMockExtension.newInstance() .options(wireMockConfig().dynamicPort()) .build(); @测试无效shouldFetchWeatherDataFromExternalApi（）{ wireMock.stubFor(get(urlEqualTo("/weather?city=London")) .withHeader("接受", 包含("application/json")) .willReturn(aResponse() .withStatus(200) .withHeader("内容类型", "application/json") .withBody("{\"城市\":\"伦敦\",\"温度\":15,\"状况\":\"多云\"}"))); String baseUrl =wireMock.getRuntimeInfo().getHttpBaseUrl(); WeatherApiClient 客户端 = new WeatherApiClient(baseUrl); WeatherData 天气 = client.getWeather("伦敦"); assertThat(weather.getCity()).isEqualTo("伦敦"); assertThat(weather.getTemperature()).isEqualTo(15); wireMock.verify(getRequestedFor(urlEqualTo("/weather?city=London")) .withHeader("接受", 包含("application/json"))); } } ## 测试错误场景 ### 测试 4xx 和 5xx 响应 @测试无效shouldHandleNotFoundError（）{ wireMock.stubFor(get(urlEqualTo(“/api/users/999”)) .willReturn(aResponse() .withStatus(404) .withBody("{\"错误\":\"未找到用户\"}"))); WeatherApiClient 客户端 = new WeatherApiClient(wireMock.getRuntimeInfo().getHttpBaseUrl()); assertThatThrownBy(() -> client.getUser(999)) .isInstanceOf(UserNotFoundException.class) .hasMessageContaining("未找到用户"); } @测试无效shouldRetryOnServerError（）{ wireMock.stubFor(get(urlEqualTo(“/api/data”)) .willReturn(aResponse() .withStatus(500) .withBody("{\"错误\":\"内部服务器错误\"}"))); ApiClient 客户端 = new ApiClient(wireMock.getRuntimeInfo().getHttpBaseUrl()); assertThatThrownBy(() -> client.fetchData()) .isInstanceOf(ServerErrorException.class); } ## 请求验证 ### 验证请求详细信息和有效负载 @测试无效shouldVerifyRequestBody（）{ wireMock.stubFor(post(urlEqualTo(“/api/users”)) .willReturn(aResponse() .withStatus(201) .withBody("{\"id\":123,\"name\":\"Alice\"}"))); ApiClient 客户端 = new ApiClient(wireMock.getRuntimeInfo().getHttpBaseUrl()); UserResponse 响应 = client.createUser("Alice"); assertThat(response.getId()).isEqualTo(123); wireMock.verify(postRequestedFor(urlEqualTo(“/api/users”)) .withRequestBody(matchingJsonPath("$.name", equalTo("Alice"))) .withHeader("Content-Type", contains("application/json"))); } ## 最佳实践 * **使用动态端口**以避免并行测试执行中的端口冲突 * **验证请求**以确保正确的 API 使用 * **彻底测试错误场景** * **保持存根集中** \- 每个测试一个关注点 * **通过`@RegisterExtension`在测试之间自动重置WireMock** * **永远不要调用真正的 API** \- 始终存根第三方端点 ## 限制和警告 * **始终使用动态端口** ：修复端口导致并行测试执行中的冲突 * **HTTPS 测试** ：如果测试 TLS 连接，请为 HTTPS 配置 WireMock * **请求匹配特异性** ：更具体的存根优先于一般存根 * **测试之间的状态** ：WireMock 使用 @RegisterExtension 在测试之间自动重置 * **性能** ：WireMock 增加了开销；考虑在客户端层进行模拟以加快测试速度 * **API 合约更改**：存根可能与真实 API 不同步；让他们保持更新 * **网络超时** ：为测试配置适当的超时；不要让测试挂起 ## 示例 ### 输入：无需测试的服务调用外部 API @服务公共类WeatherService { 私有最终 WeatherApiClient 客户端；公共WeatherData getWeather（字符串城市）{ 返回 client.fetchWeather(city); } } ### 输出：WireMock 测试覆盖率 @注册扩展静态 WireMockExtensionwireMock = WireMockExtension.newInstance() .options(wireMockConfig().dynamicPort()) .build(); @测试无效shouldFetchWeatherFromExternalApi（）{ wireMock.stubFor(get(urlEqualTo("/weather?city=London")) .willReturn(aResponse() .withStatus(200) .withBody("{\"城市\":\"伦敦\",\"温度\":15}"))); WeatherApiClient 客户端 = new WeatherApiClient( wireMock.getRuntimeInfo().getHttpBaseUrl() ）； WeatherData 天气 = client.getWeather("伦敦"); assertThat(weather.getTemperature()).isEqualTo(15); } ### 输入：手动 API 测试（慢） @测试无效 testWithRealApi() { WeatherData 数据 = WeatherService.getWeather("伦敦"); // 取决于外部 API 的可用性 } ### 输出：WireMock 存根测试（快速） @测试无效testWithWireMock（）{ wireMock.stubFor(get(urlPathEqualTo(“/天气”)) .willReturn(aResponse().withStatus(200).withBody("{}"))); // 具有可预测行为的快速、可靠的测试 } ## 限制和警告 **WireMock 不拦截请求** ：确保您的 HTTP 客户端使用来自 `wireMock.getRuntimeInfo().getHttpBaseUrl()` 的存根 URL。 **端口冲突** ：始终使用 `wireMockConfig().dynamicPort()` 让 WireMock 选择可用端口。 ## 参考文献 * [WireMock官方文档]() * [WireMock 存根和模拟]() * [JUnit 5 扩展]()

单元测试 Wiremock Rest Api

包含技能