コンテナ
リポジトリのテストには、その偽物ではなく、アプリケーションが使うデータベースが必要です。セキュリティのテストには 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 のウィジェットと衝突するためです。
テストクラスのコンテナ
@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 に入れます。
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([...]) |
そのすべて |
戦略が待っている間に終了したコンテナは、その終了コードとともに即座に起動を失敗させます。
関数として
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) との対応
@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 型がありません)。