MockMvc

spring_boot_starter_web がある場合、app.mockMvc はメモリ上でコントローラーにリクエストを送ります。本物のサーバーが動かすのと同じディスパッチャー (フィルター、マッピング、バインド、@Valid、例外ハンドラー、ProblemDetail の応答) を、ソケットなしで動かすため、速く、空きポートも必要ありません。デフォルト (WebEnvironment.mock) では、サーバーはまったく起動しません。

使う理由

コントローラーのテストは本物の Web 層を通るべきです。パスのマッピング、JSON のバインド、バリデーション、エラーの応答です。ソケットはそこに遅さとポートの衝突以外何も加えません。クライアントが本当にソケットを必要とする場合 (Feign クライアント、dart:io の HttpClient、WebSocket クライアント) は、webEnvironment が空きポートで本物のサーバーを起動します。

例

final app = springBootTest(springApplication);

test('finds, searches, rejects and deletes books', () async {
  final mvc = app.mockMvc;

  await mvc.get('/api/books/1111').andExpect(
    status: 200,
    contentType: MediaType.applicationJson,
    headers: {'X-Trace': 'on'},
    json: {'isbn': '1111', 'title': 'Dune'}, // またはマッチャー: containsPair('title', 'Dune')
  );

  await mvc.get('/api/books', params: {'q': 'dune'}).andExpect(json: hasLength(1));

  // 空の ISBN はバリデーションに失敗する: ProblemDetail のボディ付きの 400。
  await mvc
      .post('/api/books', json: {'isbn': '', 'title': ''})
      .andExpect(status: 400, contentType: MediaType.applicationProblemJson);

  await mvc.delete('/api/books/2222').andExpect(status: 204);
});

各呼び出しは Future である ResultActions を返します。await してください。そうしないと、失敗した期待値が報告されません。

リクエスト

呼び出し 送るもの
get(path, headers:, params:) GET
post、put、patch(path, json:, body:, headers:) json は Content-Type: application/json でエンコードされる。body は String またはバイトで、そのまま送られる
delete(path, headers:) DELETE
multipart(path, files: [...], params: {...}) multipart/form-data のボディ。サーバーのマルチパートの解析と制限を通る
perform(MockRequestBuilder(...)) それ以外のすべて
webSocket(path) メモリ上での WebSocket のハンドシェイク (spring_boot_starter_websocket)

MockRequestBuilder(HttpMethod.get, '/api/books/{isbn}', ['978-0']) は {name} のプレースホルダーをリストから埋め、headers、params、cookies、principal、content(...)、json(...) を持ちます。

期待値

andExpect(status:, contentType:, headers:, body:, json:) は指定したものだけをチェックします。

andDo((result) => ...) は結果を使ってコードを実行します。andReturn() (または await) は MvcResult を返し、request と response (statusCode、headers、cookies、bodyText、bodyBytes、json) を持ちます。

ファイル、ストリーム、WebSocket

test('streams the new orders', () async {
  final result = await app.mockMvc.get('/api/orders/stream');
  final first = await result.response.eventStream.first;
  expect(first.data, contains('"id"'));
  await result.cancel();
});

リクエストポストプロセッサー

RequestPostProcessor は、送られる直前のリクエストを変更します。ログイン済みのユーザー、CSRF トークン、ヘッダーなどです。一つのリクエストには builder.with_(processor) で、すべてのリクエストには MockMvc(app.getBean<DispatcherHandler>(), defaultPostProcessors: [...]) で追加します。package:spring_boot_starter_security/testing.dart は user(...)、jwt()、csrf() などを提供します。

本物のサーバー: webEnvironment

final app = springBootTest(springApplication, webEnvironment: WebEnvironment.randomPort);

test('over HTTP', () async {
  final url = Uri.parse('http://localhost:${app.localServerPort}/api/books/1111');
  final response = await HttpClient().getUrl(url).then((r) => r.close());
  expect(response.statusCode, 200);
});
webEnvironment Spring サーバー
WebEnvironment.mock (デフォルト) MOCK なし。app.mockMvc を使う
WebEnvironment.randomPort RANDOM_PORT 空きポートで本物のサーバー (server.port=0)。待ち受けを始めるとコンテキストは起動済みとみなされる。app.localServerPort がポートを返す (local.server.port)
WebEnvironment.definedPort DEFINED_PORT server.port で本物のサーバー。ポートが使用中なら起動が失敗する
WebEnvironment.none NONE なし。app.mockMvc は引き続き動く

これは spring.test.web-environment (mock、random-port、defined-port、none) を設定します。app.localServerPort は本物のサーバーが動いていなければ StateError を投げます。app.mockMvc は Web スターターがなければ StateError を投げます。

テストクラスでは: @SpringBootTest(webEnvironment: WebEnvironment.randomPort)、@LocalServerPort() late int port; フィールド、@Autowired() late MockMvc mvc; フィールドを使います。

Spring (Java) との対応

mockMvc.perform(get("/api/books/1111"))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.title").value("Dune"));

違い: @AutoConfigureMockMvc は不要です。andExpect は status().isOk() や jsonPath(...) ではなく、マッチャーを使う名前付きのチェックを受け取ります。WebTestClient も TestRestTemplate もありません (localServerPort に対して Feign クライアントか HttpClient を使ってください)。

関連項目