testcontainers

Testcontainers

データベース、ブローカー、クラウドエミュレーター、Compose スタック、待機戦略、Ryuk によるクリーンアップ、CI のコンテナランタイムなど、統合テスト用の使い捨て Docker コンテナに関わる作業では、このスキルを使用してください。

ワークフロー

1. コードを変更する前に、ローカルの Testcontainers の構成を確認します。
   • 言語とパッケージのバージョン（testcontainers、@testcontainers/*、Java の org.testcontainers:*、Python の extras、Go の modules/...）。
   • コンテナランタイム：Docker Desktop、Colima、Podman、OrbStack、Rancher、DinD、Testcontainers Cloud。
   • テストランナーのライフサイクル：Vitest/Jest のグローバルセットアップ、JUnit の @Container、pytest のフィクスチャ、Go の CleanupContainer。
   • 既存のモジュールと独自に作成した汎用コンテナのどちらを使用しているか、ネットワーク、Compose、再利用フラグ。
2. バージョンが不明な場合、言語 API が異なる場合、または CI／ランタイム／Cloud に関わる作業では、最新の公式ドキュメントを確認します。source-map.md から始めてください。
3. 作業内容に応じて、適切なリファレンスを参照します。
   • Node/TypeScript のコア機能、待機、ネットワーク、モジュール、ランナー：node-core.md。
   • Java、Python、Go、その他の言語：languages.md。
   • 複数の言語にまたがるモジュールカタログ：modules-catalog.md。
   • 環境変数、CI、ランタイム、Ryuk、再利用、セキュリティ：ci-runtimes-ops.md。
4. プロジェクトで使用している言語と既存のモジュールパッケージを優先してください。別の言語バインディングを導入しないでください。
5. 必要最小限の範囲（1 つのモジュールとクライアント）で検証してから、スイート全体のライフサイクルを確認します。

基本的な判断基準

• 依存関係のモジュールが存在する場合は、GenericContainer／DockerContainer よりも公式モジュールを優先します。
• 常にランタイムのホスト名とマッピングされたポート（getHost()／getMappedPort()／各言語の同等機能）を解決してください。localhost:5432 や固定のホストポートをハードコードしないでください。
• イメージタグ（postgres:16.3、redis:7.4）を固定してください。CI では変動する latest の使用を避けてください。
• バインドマウントよりもコンテナへのコピーを優先してください（バインドマウントは DinD／リモート Docker で動作しないことがあります）。
• 複数コンテナ間の DNS にはネットワークとエイリアスを使用してください。固定のコンテナ名やホスト名は避けてください。
• 待機戦略は意図的に選択してください：リスニングポート（デフォルト）、ログメッセージ、HTTP、ヘルスチェック、複合戦略など。Colima/Rancher では、ログ／ヘルスチェックによる待機とリスニングポートによる待機を組み合わせてください。
• 環境でサポートできない場合を除き、CI では Ryuk を有効にしてください。無効にする場合は、別のクリーンアップ手段を確保してください。
• 再利用を有効にするのはローカルの開発マシンに限ってください（withReuse／TESTCONTAINERS_REUSE_ENABLE）。CI では再利用に依存しないでください。
• Testcontainers は統合テスト／コントラクトテストの境界で使用してください。純粋なユニットテストでは Docker を使用しないでください。
• モジュールのメジャーバージョンをコアに合わせてください（Node 12.x のモジュールは testcontainers@12 と組み合わせます。このバージョンには Node >=22.22 が必要です。Java では testcontainers-* アーティファクトの 2.x と BOM を組み合わせます）。
• 使い捨ての認証情報のみを使用してください。本番環境のシークレットをコンテナ環境変数に設定しないでください。

言語ごとのデフォルト

言語	コアパッケージ	推奨
Node/TS	testcontainers + @testcontainers/<svc>	モジュール + await using／確実なティアダウン
Java	org.testcontainers:testcontainers + BOM 2.x	モジュール + try-with-resources または JUnit の @Container
Python	testcontainers[extras]	モジュール + コンテキストマネージャー／フィクスチャ
Go	testcontainers-go + modules/<svc>	testcontainers.Run + CleanupContainer(t, …)

検証

リポジトリが用意しているコマンドを優先してください。Testcontainers に関する重要な作業では、関連する範囲を確認してください。

• テストの失敗を調査する前に、Docker（または Cloud エージェント）に接続できることを確認します。
• 対象を絞った統合テスト：モジュールを起動 → 実際のクライアントで接続 → 1 つの動作をアサート → 停止／クリーンアップします。
• それらの API を変更した場合は、複数コンテナー／ネットワーク／Compose のスモークテストを実施します。
• 待機戦略の失敗モード：テストスイートがハングせず、有用なタイムアウトエラーが返ることをアサートします。
• 環境変数、Ryuk、DinD、ソケットのマウント、または Cloud のセットアップを変更する場合は、CI に即した実行を行います。
• 並列実行の確認：ランダムなポートを使用し、設計上テストスイート単位で共有する場合を除き、変更可能なコンテナー状態を共有しないようにします。
• Postgres モジュールのスナップショット／復元を確認します（スナップショットにはデータベース名 postgres を使用しないでください）。

実行した確認と実行しなかった確認、および残っているランタイムやパッケージバージョンに関する前提を報告してください。