
# テスト

`spring_boot_starter_test` は Web 層を二つの方法でテストします。`MockMvc` でメモリー内で、サーバーと同じディスパッチャー、フィルター、バインド、エラー処理を通す方法と、空いているポートでサーバーを起動し、実際のソケットを通す方法です。

## 使う理由

コントローラーのテストは、クライアントに見えるもの、つまりステータス、ヘッダー、JSON、エラーの `ProblemDetail` を確認するべきです。コントローラーメソッドを直接呼ぶと、マッピング、バインド、`@Valid`、フィルター、例外ハンドラーを飛ばしてしまいますが、Web の誤りの多くはそこにあります。`MockMvc` はリクエストをアプリケーションの `dispatcherHandler` Bean、つまりサーバーが呼ぶものに、ソケットなしで送ります。ここで通るテストは HTTP 越しでも同じように動き、速く、空いているポートも必要ありません。

テスト対象のクライアントが接続を必要とする場合 (Feign クライアント、`dart:io` の `HttpClient`、WebSocket クライアント) は、実際のサーバーを起動します。

## セットアップ

```yaml
# pubspec.yaml
dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
  spring_boot_starter_test: ^0.9.0
  test: ^1.33.0
```

テストは、ジェネレーターが `main` のために書き出したアプリケーション、つまり生成された `main.spring.dart` の `springApplication` を起動します。テスト用の設定は `test/resources/` (たとえば `application-test.properties`) に置きます。テスト中はこれが `lib/resources/` より優先されます。

## 例

関数として:

```dart
// test/book_controller_test.dart
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:test/test.dart';

import '../bin/spring_gen/main.spring.dart';

void main() {
  // アプリケーション全体を一度だけ、サーバーなしで起動する。
  final app = springBootTest(springApplication);

  test('finds a book', () async {
    await app.mockMvc.get('/api/books/978-0').andExpect(
      status: 200,
      contentType: MediaType.applicationJson,
      json: {'isbn': '978-0', 'title': 'Dune'},
    );
  });

  test('rejects an invalid book', () async {
    await app.mockMvc
        .post('/api/books', json: {'isbn': '', 'title': ''})
        .andExpect(
          status: 400,
          contentType: MediaType.applicationProblemJson,
          json: containsPair('detail', 'Invalid request content.'),
        );
  });

  test('an unknown book is a 404 problem', () async {
    await app.mockMvc
        .get('/api/books/123')
        .andExpect(status: 404, json: containsPair('detail', 'No book 123'));
  });

  test('creates a book', () async {
    final result = await app.mockMvc
        .post('/api/books', json: {'isbn': '978-1', 'title': 'Emma'})
        .andExpect(status: 201, headers: {'Location': '/api/books/978-1'})
        .andReturn();
    expect((result.response.json! as Map)['title'], 'Emma');
  });
}
```

テストクラスとして (ジェネレーターが同じ呼び出しに変換します):

```dart
// test/book_controller_class_test.dart
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:test/test.dart';

import 'spring_gen/book_controller_class.test.spring.dart'; // 生成される

@SpringBootTest()
@AutoConfigureMockMvc() // 省略可能: Spring と同様に意図を示す
class BookControllerTest {
  @Autowired()
  late MockMvc mvc;

  @Test()
  Future<void> findsABook() async {
    await mvc.get('/api/books/978-0').andExpect(
      status: 200,
      json: containsPair('title', 'Dune'),
    );
  }
}

void main() => runSpringTests();
```

`dart run build_runner build` を実行して `test/spring_gen/...test.spring.dart` を書き出し、それから `dart test` を実行します。

各呼び出しは `ResultActions` を返し、これは `Future` です。必ず `await` してください。await されないチェーンは、失敗した期待値を報告しません。

## リクエストの送信

| 呼び出し | リクエスト |
|---|---|
| `get(path, headers:, params:)` | `GET`。`params: {'q': 'dune', 'id': [1, 2]}` はクエリパラメーターを追加し、リストは要素ごとにパラメーターを一度ずつ送る |
| `post(path, json:, body:, headers:)` | `POST`。`json` は `Content-Type: application/json` でエンコードされる。`body` (`String` またはバイト) はそのまま送られ、コンテンツタイプは追加されない。両方を指定すると `json` が優先される |
| `put(...)`、`patch(...)` | `PUT` と `PATCH` について同じ |
| `delete(path, headers:)` | `DELETE` |
| `multipart(path, files:, params:, headers:, method:)` | `MockMultipartFile` とテキストフィールドの `multipart/form-data` アップロード。`method` で指定しない限り `POST` |
| `perform(MockRequestBuilder(...))` | その他のすべてのリクエスト |
| `webSocket(path, headers:, postProcessors:)` | `spring_boot_starter_websocket` によるメモリー内の WebSocket ハンドシェイク ([WebSocket](server/websocket.md) を参照) |

`MockRequestBuilder(method, path, [uriVariables])` は任意のリクエストを表します。パスの各 `{name}` は、`uriVariables` から順に URL エンコードされて埋められます。

| メンバー | 意味 |
|---|---|
| `headers` | 送るヘッダーの `Map<String, String>` |
| `params` | クエリパラメーターの `Map<String, Object>`。`List` の値はパラメーターを繰り返す |
| `cookies` | Cookie の `Map<String, String>` |
| `principal` | 認証済みのユーザー (`Principal?`)。匿名のリクエストでは `null` |
| `content(body)` | ボディ。`String` (UTF-8) またはバイト。`Content-Type` は追加されない |
| `json(value)` | JSON としてのボディ。設定されていなければ `Content-Type: application/json` を付ける |
| `with_(postProcessor)` | 送信の直前にリクエストを変更する `RequestPostProcessor` |

```dart
await app.mockMvc.perform(
  MockRequestBuilder(HttpMethod.head, '/api/books/{isbn}', ['978-0'])
    ..headers['Accept'] = 'application/json'
    ..cookies['theme'] = 'dark',
).andExpect(status: 200);
```

## レスポンスの確認

`andExpect` は与えられたものだけを確認します。

| 引数 | 確認内容 |
|---|---|
| `status` | ステータスコードの完全一致 |
| `contentType` | レスポンスのものと互換性のあるメディアタイプ (`application/json` は `application/json;charset=utf-8` に一致する) |
| `headers` | 列挙した各ヘッダーがちょうどこの値を持つこと |
| `body` | テキストとしてのボディ。`String` と等しいか、マッチャーに一致すること |
| `json` | JSON からデコードしたボディ。値と等しいか、マッチャーに一致すること (`hasLength(1)`、`containsPair('title', 'Dune')`)。JSON でないボディは `FormatException` を投げる。 |

失敗した確認は `TestFailure` で、リクエストを示し、レスポンス全体を表示します: `GET http://localhost/api/books/978-0: expected status 404, got 200` に続いて、ステータス、ヘッダー、ボディです。

| `ResultActions` に対して | 動作 |
|---|---|
| `andExpect(...)` | 確認し、チェーンを返す |
| `andDo((result) => ...)` | 結果を使ってコードを実行する。テストを書いている間にボディをログに出すなど |
| `andReturn()` | `MvcResult`。チェーンを await するのと同じ |

`MvcResult` には `request` (送られたとおりの `MockServerHttpRequest`)、`response`、`completion` (アプリケーションがリクエストを終えたときに完了する)、`cancel()` (クライアントが去ったかのようにストリーミングされたレスポンスを終える) があります。

レスポンスは `MockServerHttpResponse` です。

| メンバー | 値 |
|---|---|
| `statusCode` | ステータス |
| `headers` | `HttpHeaders` |
| `cookies` | アプリケーションが設定した `ResponseCookie` (順番どおり) |
| `bodyText`、`bodyBytes` | テキスト (UTF-8) またはバイトとしてのボディ |
| `json` | JSON からデコードしたボディ |
| `events` | これまでに書かれたサーバー送信イベント |
| `eventStream` | 書かれるそばからのサーバー送信イベント |
| `chunks` | 今から先の生のボディ (ストリームとして) |

## サーバー送信イベント

ストリームは終わる前に応答するので、`andReturn()` はヘッダーが送られるとすぐに完了します。イベントを届くそばから読み、クライアント側からストリームを終えます。

```dart
test('streams changes', () async {
  final result = await app.mockMvc.get('/api/books/changes').andReturn();
  expect(result.response.headers.contentType, startsWith('text/event-stream'));

  // 先頭の ':' コメント行を飛ばし、最初の本当のイベントを待つ。
  final next = result.response.eventStream.firstWhere((e) => e.data != null);
  await app.mockMvc.post('/api/books', json: {'isbn': '5555', 'title': 'Vurt'});

  final event = await next;
  expect(event.id, '5555');
  expect(event.data, contains('Vurt')); // 送られたとおりのデータ: JSON テキスト
  await result.cancel(); // クライアントが去る
});
```

`SseEmitter` と `application/x-ndjson` のストリームも同じように読みます ([サーバー送信イベント](streaming/sse.md) を参照)。

## アップロードとダウンロード

```dart
import 'dart:convert';

test('uploads a cover with the book as a JSON part', () async {
  await app.mockMvc.multipart('/api/books', files: [
    MockMultipartFile('cover', 'dune.png', 'image/png', [1, 2, 3]),
    MockMultipartFile(
      'book',
      null, // ファイル名なし: 通常のパート。application/json はオブジェクトを埋める
      'application/json',
      utf8.encode('{"isbn": "9780441013593", "title": "Dune"}'),
    ),
  ], params: {'note': 'first edition'}).andExpect(status: 200);
});

test('downloads part of a cover', () async {
  final result = await app.mockMvc
      .get('/api/books/9780441013593/cover', headers: {'Range': 'bytes=0-99'})
      .andExpect(status: 206, headers: {'Accept-Ranges': 'bytes'})
      .andReturn();
  expect(result.response.bodyBytes, hasLength(100));
});
```

`MockMultipartFile(name, originalFilename, contentType, bytes)` は `spring_boot_starter_test` に含まれます。アップロードはサーバー上と同じマルチパートの解析と上限を通ります。テストで上限を設定するには `properties: {'spring.web.multipart.max-file-size': '64KB'}` を使います ([アップロード](streaming/uploads.md)、[ダウンロード](streaming/downloads.md) を参照)。

## すべてのリクエストを変更する: RequestPostProcessor

`RequestPostProcessor` は送信の直前にリクエストを変更します。`spring_boot_starter_security` はセキュリティ用のもの (ログイン済みのユーザー、JWT、CSRF トークン) を提供します。独自のものは `FunctionRequestPostProcessor` で書きます。

```dart
// すべてのリクエストが、本番の HTTPS プロキシを通ったかのように届く。
final viaProxy = FunctionRequestPostProcessor(
  (request) => request..headers.set('X-Forwarded-Proto', 'https'),
);

test('one request through the proxy', () async {
  await app.mockMvc
      .perform(MockRequestBuilder(HttpMethod.get, '/api/books/978-0')..with_(viaProxy))
      .andExpect(status: 200);
});

test('every request of a MockMvc through the proxy', () async {
  final mvc = MockMvc(
    app.getBean<DispatcherHandler>(),
    defaultPostProcessors: [viaProxy],
  );
  await mvc.get('/api/books/978-0').andExpect(status: 200);
});
```

`defaultPostProcessors` は、リクエスト自身のものより先に実行されます。`MockMvc.of(context)` は、Web スターターを持つ任意のコンテキストに対して `MockMvc` を作ります。Web スターターがなければ `StateError` になります。

## 実際のサーバー: webEnvironment

```dart
import 'dart:io' as io;

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

  test('answers over HTTP', () async {
    final client = io.HttpClient();
    try {
      final request = await client.getUrl(
        Uri.parse('http://localhost:${app.localServerPort}/api/books/978-0'),
      );
      final response = await request.close();
      expect(response.statusCode, 200);
    } finally {
      client.close();
    }
  });
}
```

| `webEnvironment` | 起動するもの | Spring |
|---|---|---|
| `WebEnvironment.mock` (デフォルト) | サーバーなし。`MockMvc` は動く | `MOCK` |
| `WebEnvironment.randomPort` | 空いているポートのサーバー。待ち受けを始めた時点でコンテキストは起動済みとみなされる | `RANDOM_PORT` |
| `WebEnvironment.definedPort` | `server.port` のサーバー。ポートが使用中なら起動は失敗する | `DEFINED_PORT` |
| `WebEnvironment.none` | サーバーなし。`MockMvc` はそれでも動く | `NONE` |

- `app.localServerPort` は `local.server.port` プロパティを読みます。実行中のサーバーがなければ `StateError` を投げます。
- テストクラスでは: `@SpringBootTest(webEnvironment: WebEnvironment.randomPort)` と `@LocalServerPort() late int port;` フィールドを使います。
- `MockMvc` はどの Web 環境でも動き、実際のサーバーと並べても使えます。
- 選択は `spring.test.web-environment` プロパティ (`mock`、`random-port`、`defined-port`、`none`) としてスターターに届きます。

## 自動設定のテスト

`ApplicationContextRunner` もサーバーを起動しません。`spring.test.web-environment=mock` を設定するためです。ランナーで実際のサーバーを使うには `.withPropertyValues(['spring.test.web-environment=random-port'])` を追加します。すると `await context.getBean<WebServerStartStopLifecycle>().started` が `WebServer` とそのポートを返します。

## ルール

- **`springBootTest` の呼び出しごとに一つのコンテキスト**。最初のテストの前に `setUpAll` で起動され、最後のテストの後に閉じられます。ハンドルはテストの中か `setUp` で使ってください。
- **`properties:`** はこれらのテストの設定を上書きします: `springBootTest(springApplication, properties: {'logging.level.root': 'warn'})`。
- **`MockMvc` はソケットを飛ばします**。そのため、ディスパッチャーより前にサーバー自身が応答するもの (不正な `Host`、パス中のエンコードされた `/`、停滞したボディの 408) はメモリー内では見えません。それらは実際のサーバーに対してテストしてください。
- **ストリームは終える必要があります**。`result.cancel()` で (またはアプリケーションが) 終えないと、テストはリクエストを開いたままにします。

## Spring (Java) との対応

```java
@SpringBootTest
@AutoConfigureMockMvc
class BookControllerTest {
  @Autowired MockMvc mvc;

  @Test
  void findsABook() throws Exception {
    mvc.perform(get("/api/books/978-0"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.title").value("Dune"));
  }
}
```

重要な違い:

- `andExpect` は `status().isOk()` と `jsonPath(...)` の代わりに名前付き引数 (`status: 200`、`json: containsPair(...)`、マッチャーも使える) を受け取ります。
- ショートカット (`mvc.get(...)`) はリクエストを送ります。それ以外は `perform` が `MockRequestBuilder` を受け取ります。`with` は Dart のキーワードなので `with_` です。
- `@AutoConfigureMockMvc` は省略可能です。
- テストスライス (`@WebMvcTest`) はまだありません。アプリケーション全体が起動します。
- `main` はテストファイルに残ります。`dart test` がそれを実行し、`runSpringTests()` がクラスのテストを宣言します。

## 関連項目

- [コントローラー](controllers/index.md)
- [エラー](errors/index.md)
- [サーバー送信イベント](streaming/sse.md)
- [サーバー](server/index.md)
