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:) は指定したものだけをチェックします。
contentTypeは互換性のある型に一致します (application/jsonはapplication/json;charset=utf-8に一致します)。bodyとjsonは値またはマッチャーを受け取ります。- 失敗はリクエストを示し、レスポンス全体を表示します。
- JSON でないボディに対する
json:のチェックは、失敗した期待値を報告するのではなく、FormatExceptionを投げます。
andDo((result) => ...) は結果を使ってコードを実行します。andReturn() (または await) は MvcResult を返し、request と response (statusCode、headers、cookies、bodyText、bodyBytes、json) を持ちます。
ファイル、ストリーム、WebSocket
- アップロード:
MockMultipartFile('cover', 'dune.png', 'image/png', bytes)はファイルです。ファイル名がなくapplication/jsonのものは、@RequestPartのための JSON のパートです。 - ダウンロードは
result.response.bodyBytesから読みます。RangeやIf-Modified-Sinceのヘッダーは他のヘッダーと同じように送ります。 - サーバー送信イベント: ヘッダーが出るとすぐに結果の準備ができます。イベントは
result.response.eventStreamから読み (eventsはそれまでのものを持ちます)、result.cancel()でストリームを終えます。 - WebSocket のエンドポイント:
await mvc.webSocket('/ws/chat')はクライアントのWebSocketSessionを返します。拒否されたハンドシェイクは、ステータスとボディを持つWebSocketExceptionを投げます。
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 を使ってください)。