目录

• 依赖
• Web 控制器的职责
• 单元测试还是集成测试？
• 使用 @WebMvcTest 验证控制器职责
• @ExtendWith
• 使用带或不带 controllers 参数的 @WebMvcTest？
• 1.验证 HTTP 请求匹配
• 2.验证输入序列化
• 3.验证输入验证
• 4.验证业务逻辑调用
• 5.验证输出序列化
• 6.验证异常处理
• 创建自定义 ResultMatcher
• 匹配 JSON 输出
• 匹配预期的验证错误
• 结论

在有关使用 Spring Boot 进行测试的系列的第二部分中，我们将了解 Web 控制器。首先，我们将探索 Web 控制器的实际作用，这样我们就可以构建涵盖其所有职责的测试。

然后，我们将找出如何在测试中涵盖这些职责。只有涵盖了这些职责，我们才能确保我们的控制器在生产环境中按预期运行。

依赖

我们将使用 JUnit Jupiter (JUnit 5) 作为测试框架，使用 Mockito 进行模拟，使用 AssertJ 来创建断言，使用 Lombok 来减少样板代码：

dependencies {
    compile('org.springframework.boot:spring-boot-starter-web')
    compileOnly('org.projectlombok:lombok')
    testCompile('org.springframework.boot:spring-boot-starter-test')
    testCompile('org.junit.jupiter:junit-jupiter:5.4.0')
    testCompile('org.mockito:mockito-junit-jupiter:2.23.0')
}

AssertJ 和 Mockito 跟随 spring-boot-starter-test 依赖自动获得。

Web 控制器的职责

让我们从一个典型的 REST 控制器开始：

@RestController
@RequiredArgsConstructor
class RegisterRestController {
    private final RegisterUseCase registerUseCase;
    @PostMapping("/forums/{forumId}/register")
    UserResource register(@PathVariable("forumId") Long forumId, @Valid @RequestBody UserResource userResource,
            @RequestParam("sendWelcomeMail") boolean sendWelcomeMail) {
        User user = new User(userResource.getName(), userResource.getEmail());
        Long userId = registerUseCase.registerUser(user, sendWelcomeMail);
        return new UserResource(userId, user.getName(), user.getEmail());
    }
}

控制器方法用 @PostMapping 注解来定义它应该侦听的 URL、HTTP 方法和内容类型。

它通过用 @PathVariable、@RequestBody 和 @RequestParam 注解的参数获取输入，这些参数会从传入的 HTTP 请求中自动填充。

参数可以使用 @Valid 进行注解，以指示 Spring 应该对它们 bean 验证。

然后控制器使用这些参数，调用业务逻辑返回一个普通的 Java 对象，默认情况下该对象会自动映射到 JSON 并写入 HTTP 响应体。

这里有很多 spring 魔法。总之，对于每个请求，控制器通常会执行以下步骤：

控制器显然有很多工作要做！

我们应该注意不要添加更多的职责，比如执行业务逻辑。否则，我们的控制器测试将变得臃肿且无法维护。

我们将如何编写有意义的测试，涵盖所有这些职责？

单元测试还是集成测试？

我们写单元测试吗？还是集成测试？到底有什么区别？让我们讨论这两种方法并决定其中一种。

在单元测试中，我们将单独测试控制器。这意味着我们将实例化一个控制器对象，模拟业务逻辑，然后调用控制器的方法并验证响应。

这对我们有用吗？让我们检查一下可以单独的单元测试中涵盖上面确定的 6 个职责中的哪一个：

与 Spring 的集成测试会启动一个包含我们需要的所有 bean 的 Spring 应用程序上下文。这包括负责侦听某些 URL、与 JSON 之间进行序列化和反序列化以及将异常转换为 HTTP 的框架 bean。这些 bean 将评估简单单元测试会忽略的注释。总之，简单的单元测试不会覆盖 HTTP 层。所以，我们需要在我们的测试中引入 Spring 来为我们做 HTTP 魔法。因此，我们正在构建一个集成测试来测试我们的控制器代码和 Spring 为 HTTP 支持提供的组件之间的集成。

那么，我们该怎么做呢？

使用 @WebMvcTest 验证控制器职责

Spring Boot 提供了 @WebMvcTest 注释来启动一个应用程序上下文，该上下文只包含测试 Web 控制器所需的 bean：

@ExtendWith(SpringExtension.class)
@WebMvcTest(controllers = RegisterRestController.class)
class RegisterRestControllerTest {
    @Autowired
    private MockMvc mockMvc;
    @Autowired
    private ObjectMapper objectMapper;
    @MockBean
    private RegisterUseCase registerUseCase;
  @Test
  void whenValidInput_thenReturns200() throws Exception {
    mockMvc.perform(...);
  }
}

@ExtendWith

本教程中的代码示例使用 @ExtendWith 批注告诉 JUnit 5 启用 Spring 支持。从 Spring Boot 2.1 开始，我们不再需要加载 SpringExtension，因为它作为元注释包含在 Spring Boot 测试注解中，例如 @DataJpaTest、@WebMvcTest 和 @SpringBootTest。

我们现在可以 @Autowire 从应用程序上下文中获取我们需要的所有 bean。Spring Boot 自动提供了像 ObjectMapper 这样的 bean 来映射到 JSON 和一个 MockMvc 实例来模拟 HTTP 请求。

我们使用 @MockBean 来模拟业务逻辑，因为我们不想测试控制器和业务逻辑之间的集成，而是控制器和 HTTP 层之间的集成。@MockBean 自动用 Mockito 模拟替换应用程序上下文中相同类型的 bean。

您可以在我关于模拟的文章中阅读有关 @MockBean 注解的更多信息。

使用带或不带 controllers 参数的 @WebMvcTest？

通过在上面的示例中将 controllers 参数设置为 RegisterRestController.class，我们告诉 Spring Boot 将为此测试创建的应用程序上下文限制为给定的控制器 bean 和 Spring Web MVC 所需的一些框架 bean。我们可能需要的所有其他 bean 必须单独包含或使用 @MockBean 模拟。

如果我们不使用 controllers 参数，Spring Boot 将在应用程序上下文中包含所有控制器。因此，我们需要包含或模拟掉任何控制器所依赖的所有 bean。这使得测试设置更加复杂，具有更多的依赖项，但节省了运行时间，因为所有控制器测试都将重用相同的应用程序上下文。

我倾向于将控制器测试限制在最窄的应用程序上下文中，以使测试独立于我在测试中甚至不需要的 bean，即使 Spring Boot 必须为每个单独的测试创建一个新的应用程序上下文。

让我们来回顾一下每个职责，看看我们如何使用 MockMvc 来验证每一个职责，以便构建我们力所能及的最好的集成测试。

1.验证 HTTP 请求匹配

验证控制器是否侦听某个 HTTP 请求非常简单。我们只需调用 MockMvc 的 perform() 方法并提供我们要测试的 URL：

mockMvc.perform(post("/forums/42/register")
    .contentType("application/json"))
    .andExpect(status().isOk());

除了验证控制器对特定 URL 的响应之外，此测试还验证正确的 HTTP 方法（在我们的示例中为 POST）和正确的请求内容类型。我们上面看到的控制器会拒绝任何具有不同 HTTP 方法或内容类型的请求。

请注意，此测试仍然会失败，因为我们的控制器需要一些输入参数。

更多匹配 HTTP 请求的选项可以在 MockHttpServletRequestBuilder 的 Javadoc 中找到。

2.验证输入序列化

为了验证输入是否成功序列化为 Java 对象，我们必须在测试请求中提供它。输入可以是请求正文的 JSON 内容 (@RequestBody)、URL 路径中的变量 (@PathVariable) 或 HTTP 请求参数 (@RequestParam)：

@Test
void whenValidInput_thenReturns200() throws Exception {
  UserResource user = new UserResource("Zaphod", "zaphod@galaxy.net");
 
   mockMvc.perform(post("/forums/{forumId}/register", 42L)
        .contentType("application/json")
        .param("sendWelcomeMail", "true")
        .content(objectMapper.writeValueAsString(user)))
        .andExpect(status().isOk());
}

我们现在提供路径变量 forumId、请求参数 sendWelcomeMail 和控制器期望的请求正文。请求正文是使用 Spring Boot 提供的 ObjectMapper 生成的，将 UserResource 对象序列化为 JSON 字符串。

如果测试结果为绿色，我们现在知道控制器的 register() 方法已将这些参数作为 Java 对象接收，并且它们已从 HTTP 请求中成功解析。

3.验证输入验证

假设 UserResource 使用 @NotNull 注释来拒绝 null 值：

@Value
public class UserResource {
    @NotNull
    private final String name;
    @NotNull
    private final String email;
}

当我们将 @Valid 注解添加到方法参数时，Bean 验证会自动触发，就像我们在控制器中使用 userResource 参数所做的那样。因此，对于快乐路径（即验证成功时），我们在上一节中创建的测试就足够了。

如果我们想测试验证是否按预期失败，我们需要添加一个测试用例，在该用例中我们将无效的 UserResource JSON 对象发送到控制器。然后我们期望控制器返回 HTTP 状态 400（错误请求）：

@Test
void whenNullValue_thenReturns400() throws Exception {
  UserResource user = new UserResource(null, "zaphod@galaxy.net");
 
  mockMvc.perform(post("/forums/{forumId}/register", 42L)
      ...
      .content(objectMapper.writeValueAsString(user)))
      .andExpect(status().isBadRequest());
}

根据验证对应用程序的重要性，我们可能会为每个可能的无效值添加这样的测试用例。但是，这会很快增加很多测试用例，因此您应该与您的团队讨论您希望如何处理项目中的验证测试。

4.验证业务逻辑调用

接下来，我们要验证业务逻辑是否按预期调用。在我们的例子中，业务逻辑由 RegisterUseCase 接口提供，并需要一个 User 对象和一个 boolean 值作为输入：

interface RegisterUseCase {
    Long registerUser(User user, boolean sendWelcomeMail);
}

我们希望控制器将传入的 UserResource 对象转换为 User 并将此对象传递给 registerUser() 方法。

为了验证这一点，我们可以要求 RegisterUseCase 模拟，它已使用 @MockBean 注解注入到应用程序上下文中：

@Test
void whenValidInput_thenMapsToBusinessModel() throws Exception {
  UserResource user = new UserResource("Zaphod", "zaphod@galaxy.net");
  mockMvc.perform(...);
  ArgumentCaptor<User> userCaptor = ArgumentCaptor.forClass(User.class);
  verify(registerUseCase, times(1)).registerUser(userCaptor.capture(), eq(true));
  assertThat(userCaptor.getValue().getName()).isEqualTo("Zaphod");
  assertThat(userCaptor.getValue().getEmail()).isEqualTo("zaphod@galaxy.net");
}

在执行了对控制器的调用之后，我们使用 ArgumentCaptor 来捕获传递给 RegisterUseCase.registerUser() 的 User 对象并断言它包含预期值。

调用 verify 检查 registerUser() 是否被调用过一次。

请注意，如果我们对 User 对象进行大量断言，我们可以 创建自己的自定义 Mockito 断言方法 以获得更好的可读性。

5.验证输出序列化

调用业务逻辑后，我们希望控制器将结果映射到 JSON 字符串并将其包含在 HTTP 响应中。在我们的例子中，我们希望 HTTP 响应正文包含一个有效的 JSON 格式的 UserResource 对象：

@Test
void whenValidInput_thenReturnsUserResource() throws Exception {
  MvcResult mvcResult = mockMvc.perform(...)
      ...
      .andReturn();
  UserResource expectedResponseBody = ...;
  String actualResponseBody = mvcResult.getResponse().getContentAsString();
 
  assertThat(actualResponseBody).isEqualToIgnoringWhitespace(
              objectMapper.writeValueAsString(expectedResponseBody));
}

要对响应主体进行断言，我们需要使用 andReturn() 方法将 HTTP 交互的结果存储在 MvcResult 类型的变量中。

然后我们可以从响应正文中读取 JSON 字符串，并使用 isEqualToIgnoringWhitespace() 将其与预期的字符串进行比较。我们可以使用 Spring Boot 提供的 ObjectMapper 从 Java 对象构建预期的 JSON 字符串。

请注意，我们可以通过使用自定义的 ResultMatcher 使其更具可读性，稍后对此加以描述。

6.验证异常处理

通常，如果发生异常，控制器应该返回某个 HTTP 状态。400 --- 如果请求有问题，500 --- 如果出现异常，等等。

默认情况下，Spring 会处理大多数这些情况。但是，如果我们有自定义异常处理，我们想测试它。假设我们想要返回一个结构化的 JSON 错误响应，其中包含请求中每个无效字段的字段名称和错误消息。我们会像这样创建一个 @ControllerAdvice：

@ControllerAdvice
class ControllerExceptionHandler {
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseBody
    ErrorResult handleMethodArgumentNotValidException(MethodArgumentNotValidException e) {
        ErrorResult errorResult = new ErrorResult();
        for (FieldError fieldError : e.getBindingResult().getFieldErrors()) {
            errorResult.getFieldErrors()
                    .add(new FieldValidationError(fieldError.getField(), fieldError.getDefaultMessage()));
        }
        return errorResult;
    }
    @Getter
    @NoArgsConstructor
    static class ErrorResult {
        private final List<FieldValidationError> fieldErrors = new ArrayList<>();
        ErrorResult(String field, String message) {
            this.fieldErrors.add(new FieldValidationError(field, message));
        }
    }
    @Getter
    @AllArgsConstructor
    static class FieldValidationError {
        private String field;
        private String message;
    }
}

如果 bean 验证失败，Spring 将抛出 MethodArgumentNotValidException。我们通过将 Spring 的 FieldError 对象映射到我们自己的 ErrorResult 数据结构来处理这个异常。在这种情况下，异常处理程序会导致所有控制器返回 HTTP 状态 400，并将 ErrorResult 对象作为 JSON 字符串放入响应正文中。

为了验证这确实发生了，我们扩展了我们之前对失败验证的测试：

@Test
void whenNullValue_thenReturns400AndErrorResult() throws Exception {
  UserResource user = new UserResource(null, "zaphod@galaxy.net");
  MvcResult mvcResult = mockMvc.perform(...)
          .contentType("application/json")
          .param("sendWelcomeMail", "true")
          .content(objectMapper.writeValueAsString(user)))
          .andExpect(status().isBadRequest())
          .andReturn();
  ErrorResult expectedErrorResponse = new ErrorResult("name", "must not be null");
  String actualResponseBody =
      mvcResult.getResponse().getContentAsString();
  String expectedResponseBody =
      objectMapper.writeValueAsString(expectedErrorResponse);
  assertThat(actualResponseBody)
      .isEqualToIgnoringWhitespace(expectedResponseBody);
}

同样，我们从响应正文中读取 JSON 字符串，并将其与预期的 JSON 字符串进行比较。此外，我们检查响应状态是否为 400。

这也可以以可读性更强的方式实现，我们接下来将要学习。

创建自定义 ResultMatcher

某些断言很难写，更重要的是，很难阅读。特别是当我们想要将来自 HTTP 响应的 JSON 字符串与预期值进行比较时，它需要大量代码，正如我们在最后两个示例中看到的那样。

幸运的是，我们可以创建自定义的 ResultMatcher，我们可以在 MockMvc 的流畅 API 中使用它们。让我们看看如何做到这一点。

匹配 JSON 输出

使用以下代码来验证 HTTP 响应正文是否包含某个 Java 对象的 JSON 表示不是很好吗？

@Test
void whenValidInput_thenReturnsUserResource_withFluentApi() throws Exception {
  UserResource user = ...;
  UserResource expected = ...;
  mockMvc.perform(...)
      ...
      .andExpect(responseBody().containsObjectAsJson(expected, UserResource.class));
}

不再需要手动比较 JSON 字符串。它的可读性要好得多。事实上，代码是如此的一目了然，这里我无需解释。

为了能够使用上面的代码，我们创建了一个自定义的 ResultMatcher：

public class ResponseBodyMatchers {
    private ObjectMapper objectMapper = new ObjectMapper();
    public <T> ResultMatcher containsObjectAsJson(Object expectedObject, Class<T> targetClass) {
        return mvcResult -> {
            String json = mvcResult.getResponse().getContentAsString();
            T actualObject = objectMapper.readValue(json, targetClass);
            assertThat(actualObject).isEqualToComparingFieldByField(expectedObject);
        };
    }
    static ResponseBodyMatchers responseBody() {
        return new ResponseBodyMatchers();
    }
}

静态方法 responseBody() 用作我们流畅的 API 的入口点。它返回实际的 ResultMatcher，它从 HTTP 响应正文解析 JSON，并将其与传入的预期对象逐个字段进行比较。

匹配预期的验证错误

我们甚至可以更进一步简化我们的异常处理测试。我们用了 4 行代码来验证 JSON 响应是否包含某个错误消息。我们可以改为一行：

@Test
void whenNullValue_thenReturns400AndErrorResult_withFluentApi() throws Exception {
  UserResource user = new UserResource(null, "zaphod@galaxy.net");
  mockMvc.perform(...)
      ...
      .content(objectMapper.writeValueAsString(user)))
      .andExpect(status().isBadRequest())
      .andExpect(responseBody().containsError("name", "must not be null"));
}

同样，代码是自解释的。

为了启用这个流畅的 API，我们必须从上面添加方法 containsErrorMessageForField() 到我们的 ResponseBodyMatchers 类：

public class ResponseBodyMatchers {
    private ObjectMapper objectMapper = new ObjectMapper();
    public ResultMatcher containsError(String expectedFieldName, String expectedMessage) {
        return mvcResult -> {
            String json = mvcResult.getResponse().getContentAsString();
            ErrorResult errorResult = objectMapper.readValue(json, ErrorResult.class);
            List<FieldValidationError> fieldErrors = errorResult.getFieldErrors().stream()
                    .filter(fieldError -> fieldError.getField().equals(expectedFieldName))
                    .filter(fieldError -> fieldError.getMessage().equals(expectedMessage)).collect(Collectors.toList());
            assertThat(fieldErrors).hasSize(1).withFailMessage(
                    "expecting exactly 1 error message" + "with field name '%s' and message '%s'", expectedFieldName,
                    expectedMessage);
        };
    }
    static ResponseBodyMatchers responseBody() {
        return new ResponseBodyMatchers();
    }
}

所有丑陋的代码都隐藏在这个辅助类中，我们可以在集成测试中愉快地编写干净的断言。

结论

Web 控制器有很多职责。如果我们想用有意义的测试覆盖一个 web 控制器，仅仅检查它是否返回正确的 HTTP 状态是不够的。

通过 @WebMvcTest，Spring Boot 提供了我们构建 Web 控制器测试所需的一切，但为了使测试有意义，我们需要记住涵盖所有职责。否则，我们可能会在运行时遇到丑陋的惊喜。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持自由互联。