
# テストのプロパティ

テストには、アプリケーションが出荷時に持つものとは別の値が必要になることがよくあります。より小さい上限、偽のサーバーの URL、テスト用のデータベースなどです。`springBootTest` とテスト用のアノテーションは、アプリケーションの設定の上にプロパティソースを追加し、`test/resources/` をクラスパスの先頭に置きます。

## 使う理由

テストはアプリケーションの設定ファイルを編集すべきではなく、実行するマシンに依存すべきでもありません。テスト専用のファイルは `test/resources/` に置かれ、アプリケーションに埋め込まれることはありません。インラインのプロパティは一つのテストファイルで一つのキーを変えます。動的プロパティはテストの実行時にしか存在しない値を運びます。OS の環境変数は、テストが設定しない限り見えません。

## 例

```text
lib/resources/application.yml                 # アプリケーションの設定
test/resources/application-test.yml           # test プロファイルで使うテスト専用の設定
test/resources/payments-test.properties       # 一つのテストのためのプロパティファイル
test/resources/fixtures/books.json            # テストでは resources:fixtures/books.json
```

```dart
late HttpServer catalog;
// springBootTest より前に宣言するため、コンテキストの起動時にはサーバーが動いている。
setUpAll(() async => catalog = await HttpServer.bind('localhost', 0));

final app = springBootTest(
  springApplication,
  profiles: ['test'],                                     // + application-test.yml
  propertyFiles: ['resources:payments-test.properties'],  // まず test/resources/ で見つかる
  properties: {'shop.max-basket-size': 3},
  systemEnvironment: {'SHOP_CURRENCY': 'EUR'},
  dynamicProperties: (registry) =>
      registry.add('catalog.url', () => 'http://localhost:${catalog.port}'),
);
```

## どのソースが優先されるか

高い順に:

1. `dynamicProperties` (`@DynamicPropertySource`) と、`@ServiceConnection` のコンテナの接続プロパティ。
2. `properties` (`@SpringBootTest(properties:)` と `@TestPropertySource(properties:)` をマージしたもの。同じキーでは `@TestPropertySource` が優先される)。
3. `propertyFiles` (`@TestPropertySource(locations:)`)。後のファイルが優先される。
4. コマンドラインの `args`。
5. OS の環境変数の代わりになる `systemEnvironment` (`@TestEnvironment`)。
6. 設定ファイル: まず `test/resources/`、次に `lib/resources/`。`profiles` のプロファイルとともに。

## test/resources/

`springBootTest` の実行中は、`test/resources/` が `lib/resources/` より前、クラスパスの先頭に来ます。アプリケーションに埋め込まれることはありません。ジェネレーターが埋め込むのは `lib/resources/` だけです。

- **テストのプロファイルを優先してください。** `profiles: ['test']` を伴う `application-test.yml` は、`application.yml` の上にそのキーを追加します。
- **同じパスのファイルは、パッケージ内のものを完全に置き換えます。** Spring と同じく、`test/resources/application.yml` は本物を隠します。
- **相対ディレクトリ**はテストファイルのパッケージ (最も近い `pubspec.yaml`) を基準に解決されるため、テストをパッケージ、ワークスペースのルート、IDE のどこから実行しても関係ありません。
- **その他のディレクトリ:** `resourceDirectories: ['test/fixtures', 'test/resources']`。最初に列挙したものが先に来ます。ブラウザーのテストにはファイルシステムがないため、そこではディレクトリは見つかりません。

## プロファイル

`profiles: ['test']` (`@ActiveProfiles(['test'])`) は、Spring と同じく、設定ファイルのプロファイルを置き換えて `spring.profiles.active` を設定します。テストがアプリケーション自身のプロファイルを必要とするなら、それも列挙してください: `profiles: ['dev', 'test']`。

## プロパティファイル

`propertyFiles` (`@TestPropertySource(locations:)`) は `.properties` ファイルのリソースロケーションです。単なるパスはクラスパスのロケーションなので、まず `test/resources/` が検索されます。後のファイルが前のファイルより優先されます。ないファイルは `StateError` で起動を失敗させます。

## 動的プロパティ

`properties:` は `springBootTest` が呼ばれた時点で固定されます。テストの実行時にしか存在しない値 (偽のサーバーのポート、一時ディレクトリ、コンテナのアドレス) は、プロパティごとに関数を登録する `dynamicProperties` を通します。

```dart
final app = springBootTest(
  springApplication,
  dynamicProperties: (registry) => registry
    ..add('catalog.url', () => 'http://localhost:${server.port}')
    ..add('upload.dir', () => tempDir.path),
);
```

コールバックはコンテキストが起動するたびに (`markDirty` の後にも再び) 実行され、各関数はアプリケーションがそのプロパティを読むたびに実行されます。これらの値は他のすべてのソースより優先されます。同じ名前を二度追加すると、2 つ目の関数が保たれます。テストクラスでは、static な `@DynamicPropertySource()` メソッドが同じことを行います。

## 環境変数

OS の環境変数は見えません。`systemEnvironment` はデフォルトで `{}` なので、テストはマシンに依存しません。テストに必要な変数を設定してください。

```dart
final app = springBootTest(
  springApplication,
  systemEnvironment: {'SHOP_MAX_BASKET_SIZE': '25', 'SPRING_PROFILES_ACTIVE': 'dev'},
);
```

## テストが読むプロパティ

| キー | 値 | デフォルト | 意味 |
|---|---|---|---|
| `spring.test.web-environment` | `mock`、`random-port`、`defined-port`、`none` | 未設定: 本物のアプリケーションはサーバーを起動する。`springBootTest` と `ApplicationContextRunner` は、指定がなければ `mock` を設定する | どのテスト環境で Web スターターのサーバーを起動するか。`random-port` は `server.port` を `0` にし、ポートを `local.server.port` で公開する |
| `local.server.port` | `int` | Web スターターが設定する | 本物のサーバーが待ち受けているポート。`app.localServerPort` がこれを読む |

## テストツールの環境変数

| 変数 | 意味 |
|---|---|
| `CONTAINERS_REQUIRED=true` | コンテナを持つテストクラスは、Docker がないとスキップされる代わりに失敗する (CI で設定する) |
| `DOCKER_HOST` | Docker デーモン (`unix:///path`、`tcp://host:2375`) |
| `TESTCONTAINERS_RYUK_DISABLED=true` | リーパーのコンテナを使わない |
| `TESTCONTAINERS_RYUK_CONTAINER_IMAGE` | `testcontainers/ryuk:0.14.0` 以外のリーパーのイメージ |
| `CI` | 設定されていると、`withReuse(true)` は無視される |

これらは `systemEnvironment` からではなく、テストを実行するプロセスから読まれます。[コンテナ](containers.md) を参照してください。

## Spring (Java) との対応

`@SpringBootTest(properties)`、`@TestPropertySource`、`@DynamicPropertySource`、`@ActiveProfiles` と同じソースです。違い: OS の環境変数は設定しない限り空です。`systemEnvironment` (`@TestEnvironment`) に対応するものは Spring にはありません。`test/resources/` は `springBootTest` 自身がクラスパスの先頭に置きます。

## 関連項目

- [springBootTest](spring-boot-test.md)
- [テストクラス](test-classes.md)
- [外部設定](../spring-boot-dart/configuration/index.md)
- [コンテナ](containers.md)
