
# コンテナ

リポジトリのテストには、その偽物ではなく、アプリケーションが使うデータベースが必要です。セキュリティのテストには Keycloak が必要です。`package:spring_boot_starter_test/containers.dart` を使うと、テストは必要なものを Docker で起動し、アプリケーションはそれに結び付けられ、コンテナは後で取り除かれます。Spring Boot の `@ServiceConnection` を伴う Testcontainers に当たります。

## 使う理由

データベースの偽物は、本物のデータベースなら失敗するテストを通してしまいます。SQL の方言、制約、トランザクションなどです。コンテナは本物を提供し、テストのために新しく起動し、テストの後に取り除きます。ノート PC でも CI でも同じです。

## 例

```dart
import 'package:spring_boot_starter_test/containers.dart';
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:test/test.dart';

import 'spring_gen/book_repository.test.spring.dart';

@SpringBootTest()
@Testcontainers()
class BookRepositoryTest {
  // クラスのために、そのコンテキストより前に一度だけ起動し、後で取り除く:
  // その URL、ユーザー、パスワードはコンテキストの spring.datasource.* になる。
  @Container()
  @ServiceConnection()
  static final postgres = PostgresContainer('postgres:17-alpine');

  // 任意のイメージ: ログの行、HTTP の応答、ポートを待つ。
  @Container()
  static final redis = GenericContainer('redis:7.4-alpine')
      .withExposedPorts([6379])
      .waitingFor(Wait.forLogMessage('Ready to accept connections'));

  // コンテナの起動後、コンテキストの起動時に実行される。
  @DynamicPropertySource()
  static void properties(DynamicPropertyRegistry registry) => registry.add(
        'cache.redis.url',
        () => 'redis://${redis.host}:${redis.mappedPort(6379)}',
      );

  @Autowired()
  late BookRepository books;

  @Test()
  Future<void> savesAndFinds() async { /* ... */ }
}

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

`containers.dart` は独立したライブラリです。`dart:io` を必要とし (Web にはその何も存在しません)、その `Container` アノテーションは Flutter のウィジェットと衝突するためです。

## テストクラスのコンテナ

- **`@Container()`** は、`GenericContainer` またはモジュールを持つ `static` フィールドを示します。コンテナはフィールドの順に、`@BeforeAll` メソッドとコンテキストより前に起動し、コンテキストが閉じて `@AfterAll` メソッドが実行された後に取り除かれます。テストごとのコンテナには対応していません。
- **`@ServiceConnection()`** は、コンテナの接続プロパティを動的プロパティに入れます。それは `properties:`、設定ファイル、環境変数より優先されます。`@DynamicPropertySource` メソッドはその後に実行され、その一つを変更できます。
- **`@Testcontainers()`** は任意です。Docker がない場合に何が起こるかを設定するだけです: `@Testcontainers(disabledWithoutDocker: false)` はスキップする代わりに失敗させます。
- **Docker がない場合**、クラス全体が理由とともにスキップされます。`CONTAINERS_REQUIRED=true` (CI で設定してください) の場合は代わりに失敗します。
- `spring_boot_starter_data` の **`@DataTest(replaceDatabase: false)`** を `@ServiceConnection` の `PostgresContainer` とともに使うと、リポジトリのテストはその PostgreSQL で、マイグレーションを適用し、各テストをロールバックしながら実行されます。

## モジュールとその接続プロパティ

| モジュール | デフォルト | `@ServiceConnection` が設定するもの |
|---|---|---|
| `PostgresContainer([image])` | データベース、ユーザー、パスワードは `test`。`withDatabaseName`、`withUsername`、`withPassword`、`withInitScript`。`jdbcUrl`、`url` | `spring.datasource.url`、`spring.datasource.username`、`spring.datasource.password` |
| `KeycloakContainer([image])` | 管理者は `admin`/`admin`。`withAdminCredentials`、`withRealmImport(hostPath)`、`withProviderId`。`issuerUri`、`authServerUrl` | `spring.security.oauth2.resourceserver.jwt.issuer-uri`、`spring.security.oauth2.client.provider.<id>.issuer-uri` |
| 独自のもの | | 何でも: `ServiceConnectionProperties` (`Map<String, String> get connectionProperties`) を実装する |

## GenericContainer

任意のイメージです。メソッドはコンテナを返すため、チェーンできます (モジュールでは、その型を保つためにカスケードを使ってください)。

| メソッド | 働き |
|---|---|
| `withEnv(name, value)`、`withEnvironment(map)` | 環境変数 |
| `withCommand(list)`、`withEntrypoint(list)` | イメージのコマンドやエントリーポイントを置き換える |
| `withExposedPorts([5432])` | ポートをホストのランダムな空きポートに、ループバックインターフェースでだけ公開する |
| `withCopyFile(hostPath, containerPath)`、`withCopyContent(text, containerPath)` | 起動前にコピーされるファイル |
| `withLabel(name, value)` | ラベル |
| `withHealthCheck(['CMD-SHELL', 'pg_isready'])` | ヘルスチェックを持たないイメージのためのヘルスチェック |
| `waitingFor(strategy)` | 準備完了とみなすタイミング |
| `withStartupTimeout(duration)` | デフォルトは 60 秒。イメージの取得は数えない |
| `withReuse(true)` | 次の実行のために残す (CI では決して使わない) |
| `withNetwork(network)`、`withNetworkAliases(['db'])` | その実行の `Network` に入れる。そのネットワークの他のコンテナは、これらの名前と、コンテナが待ち受けるポートでこのコンテナに届く。下の「ネットワーク」を参照 |
| `withExtraHost(host, address)` | コンテナの hosts ファイルの一行。`host-gateway` は、デーモンが動いているマシン |

`start()` はイメージがなければ取得し、コンテナを作成し、ファイルをコピーし、起動して待ちます。`stop()` はそれを取り除きます。`host`、`mappedPort(5432)`、`baseUrl(8080)`、`getLogs()`、`execInContainer([...])` は起動後に使えます。準備ができない場合、コンテナは取り除かれ、`ContainerLaunchException` が、最後に出力された行とともに理由を示します。

## ネットワーク

コンテナが届くのはホストに公開されたポートで、別のコンテナではありません。互いに通信しなければならない二つ (API とそのデータベース) は、`Network` に入れます。

```dart
static final network = Network.newNetwork();

@Container()
static final database = PostgresContainer('postgres:17-alpine')
    .withNetwork(network)
    .withNetworkAliases(['db']);

@Container()
static final api = GenericContainer('postgrest/postgrest:v12.2.3')
    .withNetwork(network)
    .withEnv('PGRST_DB_URI', 'postgres://test:test@db:5432/test')
    .withExposedPorts([3000]);
```

- **ネットワークの中では**、データベースは `db:5432` です。そのエイリアスと、待ち受けているポートです。テスト自身は、これまでどおり `mappedPort` を使います。
- **ネットワークは**、最初のコンテナが起動するときに作られ、その実行のコンテナとともに取り除かれます (プロセスが強制終了されたときは、リーパーも取り除きます)。`network.close()` は、それより早く取り除きます。
- **`withReuse` で残すコンテナ**は、ネットワークに入れられません。
- その下では、`DockerClient` に `createNetwork` と `removeNetwork` があり、`DockerContainerConfig` に `network`、`networkAliases`、`extraHosts` があります。

## 待機戦略

| `Wait.` | 準備完了となる条件 |
|---|---|
| `forListeningPort()` (デフォルト) | 公開したすべてのポートが接続を受け付け、維持する |
| `forLogMessage(regex, times)` | 標準出力またはエラー出力の行が一致する |
| `.forStatusCode(200)`、`.forPort(8080)`、`.forStatusCodeMatching(...)`、`.usingTls()` を伴う `forHttp(path)` | HTTP リクエストが応答する |
| `forHealthcheck()` | コンテナのヘルスチェックが通る |
| `forAll([...])` | そのすべて |

戦略が待っている間に終了したコンテナは、その終了コードとともに即座に起動を失敗させます。

## 関数として

```dart
void main() {
  final postgres = PostgresContainer();
  final containers = TestContainers({'postgres': postgres},
      serviceConnections: {'postgres'});
  setUpAll(containers.start);
  tearDownAll(containers.stop);

  final app = springBootTest(
    springApplication,
    dynamicProperties: containers.registerConnections,
  );
}
```

`skip: TestContainers.skipReason()` は、Docker がない場合に `group` や `test` をスキップします。

## Docker デーモン

`DockerClient` は、背後にパッケージを持たず、`dart:io` で Docker Engine API を話します。デーモンは `docker` コマンドと同じ方法で見つけます。`DOCKER_HOST` (`unix:///path`、`tcp://host:2375`)、なければ `/var/run/docker.sock`、`~/.docker/run/docker.sock` (Docker Desktop)、`~/.colima/default/docker.sock`、`~/.rd/docker.sock` (Rancher Desktop)、`$XDG_RUNTIME_DIR/docker.sock` の最初に見つかったものです。Windows の名前付きパイプ、リモートデーモンへの TLS、プライベートレジストリにはまだ対応していません (イメージは事前に取得してください)。

## 後片付けと再利用

- すべてのコンテナは `org.testcontainers=true`、`org.testcontainers.lang=dart`、`org.testcontainers.sessionId=<run id>` のラベルを持ち、`stop()` で取り除かれます。
- プロセスが先に終了した場合 (`kill -9`、クラッシュ)、Testcontainers のリーパー (`testcontainers/ryuk:0.14.0`) が 10 秒後にその実行のすべてのコンテナを取り除きます。`TESTCONTAINERS_RYUK_DISABLED=true` で無効になり、`TESTCONTAINERS_RYUK_CONTAINER_IMAGE` で別のイメージを指定できます。
- `withReuse(true)` は、構成のハッシュで見つかるコンテナを次の実行のために残します。`CI` が設定されていると無視されます。残したコンテナは `docker rm -f $(docker ps -aq --filter label=org.testcontainers.reuse.hash)` で取り除きます。

## Spring (Java) との対応

```java
@SpringBootTest
@Testcontainers
class BookRepositoryTest {
  @Container @ServiceConnection
  static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17-alpine");
}
```

`Network.newNetwork()`、`withNetwork`、`withNetworkAliases` は Testcontainers の名前です。違い: `containers.dart` は独立したインポートです。`@Container` は static フィールドにだけ付けます。Docker がない場合、クラスはデフォルトでスキップされます (Spring は `disabledWithoutDocker = true` でない限り失敗します)。Docker Compose、`RedisContainer` や `MongoContainer` はありません。流れるようなメソッドは `GenericContainer` を返します (Dart には self 型がありません)。

## 関連項目

- [テストのプロパティ](test-properties.md)
- [テストクラス](test-classes.md)
- [springBootTest](spring-boot-test.md)
