MockMvcを使用したREST コントローラーのユニットテスト

概要

MockMvcを使用して@RestControllerおよび@Controllerクラスをユニットテストするためのパターンを提供します。リクエスト/レスポンス処理、HTTPステータスコード、リクエストパラメーターバインディング、バリデーション、コンテンツネゴシエーション、レスポンスヘッダー、およびモックされたサービス依存関係での例外処理をカバーしています。

使用するタイミング

用途：コントローラーテスト、APIエンドポイントテスト、Spring MVCテスト、モックHTTPリクエスト、Webレイヤーエンドポイントのユニットテスト、REST コントローラーの分離検証。

使用方法

1. スタンドアロンMockMvcをセットアップ: MockMvcBuilders.standaloneSetup(controller) で分離テストを実施
2. サービス依存関係をモック: すべてのサービスに@Mockを、コントローラーに@InjectMocksを使用
3. HTTPメソッドをテスト: GET、POST、PUT、PATCH、DELETE を適切なステータスコードでテスト
4. レスポンスを検証: JSONPathアサーションでJSON、コンテンツマッチャーでボディを検証
5. バリデーションをテスト: 無効な入力を送信し、エラー詳細を含む400ステータスを検証
6. エラーをテスト: 適切な条件で404、400、401、403、500を検証
7. ヘッダーを検証: リクエスト(Authorization)とレスポンスヘッダーの両方
8. コンテンツネゴシエーションをテスト: 異なるAcceptおよびContent-Typeヘッダー

バリデーションワークフロー

テスト実行 → 失敗時：.andDo(print())を追加 → 実際の値と期待値を確認 → アサーションを修正

例

Maven / Gradle 依存関係

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>

基本パターン：GETエンドポイント

import static org.mockito.Mockito.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@ExtendWith(MockitoExtension.class)
class UserControllerTest {

  @Mock
  private UserService userService;

  @InjectMocks
  private UserController userController;

  private MockMvc mockMvc;

  @BeforeEach
  void setUp() {
    mockMvc = MockMvcBuilders.standaloneSetup(userController).build();
  }

  @Test
  void shouldReturnAllUsers() throws Exception {
    List<UserDto> users = List.of(new UserDto(1L, "Alice"), new UserDto(2L, "Bob"));
    when(userService.getAllUsers()).thenReturn(users);

    mockMvc.perform(get("/api/users"))
      .andExpect(status().isOk())
      .andExpect(jsonPath("$[0].id").value(1))
      .andExpect(jsonPath("$[0].name").value("Alice"));

    verify(userService, times(1)).getAllUsers();
  }

  @Test
  void shouldReturn404WhenUserNotFound() throws Exception {
    when(userService.getUserById(999L))
      .thenThrow(new UserNotFoundException("User not found"));

    mockMvc.perform(get("/api/users/999"))
      .andExpect(status().isNotFound());

    verify(userService).getUserById(999L);
  }
}

POST：リソース作成

@Test
void shouldCreateUserAndReturn201() throws Exception {
  UserDto createdUser = new UserDto(1L, "Alice", "alice@example.com");
  when(userService.createUser(any())).thenReturn(createdUser);

  mockMvc.perform(post("/api/users")
      .contentType("application/json")
      .content("{\"name\":\"Alice\",\"email\":\"alice@example.com\"}"))
    .andExpect(status().isCreated())
    .andExpect(jsonPath("$.id").value(1))
    .andExpect(jsonPath("$.name").value("Alice"));

  verify(userService).createUser(any(UserCreateRequest.class));
}

PUT：リソース更新

@Test
void shouldUpdateUserAndReturn200() throws Exception {
  UserDto updatedUser = new UserDto(1L, "Updated");
  when(userService.updateUser(eq(1L), any())).thenReturn(updatedUser);

  mockMvc.perform(put("/api/users/1")
      .contentType("application/json")
      .content("{\"name\":\"Updated\"}"))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.name").value("Updated"));

  verify(userService).updateUser(eq(1L), any());
}

DELETE：リソース削除

@Test
void shouldDeleteUserAndReturn204() throws Exception {
  doNothing().when(userService).deleteUser(1L);

  mockMvc.perform(delete("/api/users/1"))
    .andExpect(status().isNoContent());

  verify(userService).deleteUser(1L);
}

クエリパラメーター

@Test
void shouldFilterUsersByName() throws Exception {
  when(userService.searchUsers("Alice")).thenReturn(List.of(new UserDto(1L, "Alice")));

  mockMvc.perform(get("/api/users/search").param("name", "Alice"))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$[0].name").value("Alice"));

  verify(userService).searchUsers("Alice");
}

パス変数

@Test
void shouldGetUserByIdFromPath() throws Exception {
  when(userService.getUserById(123L)).thenReturn(new UserDto(123L, "Alice"));

  mockMvc.perform(get("/api/users/{id}", 123L))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.id").value(123));
}

バリデーションエラー（400）

@Test
void shouldReturn400WhenRequestBodyInvalid() throws Exception {
  mockMvc.perform(post("/api/users")
      .contentType("application/json")
      .content("{\"name\":\"\"}"))
    .andExpect(status().isBadRequest())
    .andExpect(jsonPath("$.errors").isArray());
}

レスポンスヘッダー

@Test
void shouldReturnCustomHeaders() throws Exception {
  when(userService.getAllUsers()).thenReturn(List.of());

  mockMvc.perform(get("/api/users"))
    .andExpect(status().isOk())
    .andExpect(header().exists("X-Total-Count"))
    .andExpect(header().string("X-Total-Count", "0"));
}

Authorizationヘッダー

@Test
void shouldRequireAuthorizationHeader() throws Exception {
  mockMvc.perform(get("/api/users"))
    .andExpect(status().isUnauthorized());

  mockMvc.perform(get("/api/users").header("Authorization", "Bearer token"))
    .andExpect(status().isOk());
}

コンテンツネゴシエーション

@Test
void shouldReturnJsonWhenAcceptHeaderIsJson() throws Exception {
  when(userService.getUserById(1L)).thenReturn(new UserDto(1L, "Alice"));

  mockMvc.perform(get("/api/users/1").accept("application/json"))
    .andExpect(status().isOk())
    .andExpect(content().contentType("application/json"));
}

ベストプラクティス

• 分離コントローラーテストにstandaloneSetup()を使用
• サービスレイヤーをモック — コントローラーはHTTPを処理、サービスはビジネスロジックを処理
• モックインタラクションを検証：verify(service).method(args)
• 成功パスとエラーシナリオ(404、400、500)の両方をテスト
• JSONアサーションにjsonPath()を使用
• テストメソッドごとに1つの焦点を絞ったアサーション

制約と警告

• コントローラーテストはHTTP処理のみを検証 — 完全なリクエストフローではありません
• standaloneSetup()は完全なコンテキストなしに@Validatedをサポートしない可能性があります
• JsonPathはレスポンスボディに有効なJSONが必要です
• @PreAuthorize/@Securedは追加セットアップが必要 — セキュリティテストを別途検討してください
• ファイルアップロードにはMockMultipartFileが必要です

参考資料

• Spring MockMvcドキュメント
• Spring テストベストプラクティス