コンテナ

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

使う理由

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

例

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 のウィジェットと衝突するためです。

テストクラスのコンテナ

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

モジュール デフォルト @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 に入れます。

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]);

待機戦略

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

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

関数として

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、プライベートレジストリにはまだ対応していません (イメージは事前に取得してください)。

後片付けと再利用

Spring (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 型がありません)。

関連項目