
# MockMvc

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

## 使う理由

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

## 例

```dart
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` を投げます。

```dart
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

```dart
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) との対応

```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` を使ってください)。

## 関連項目

- [spring_boot_starter_web: テスト](../spring-boot-starter-web/testing.md)
- [springBootTest](spring-boot-test.md)
- [テストのプロパティ](test-properties.md)
