Skip to content
Testcontainers Cloud ドキュメント

Testcontainers Cloud ドキュメント

概要

Testcontainers Cloud を使用して Testcontainers のテストを実行すると、すぐに利用できます。人気のある技術を使用してアプリケーションをテストするための同じ Testcontainers モジュールにアクセスでき、ローカルマシンで重いコンテナを起動する必要がありません。

Testcontainers Cloud はどのように動作するのか？

Testcontainers Cloud エージェントは SSH トンネルを開き、クラウド環境内の Docker デーモンに接続します。

Testcontainers Cloud を使用することで、ローカル環境でコンテナを実行する必要がなくなります。ローカル環境でテストを実行すると、Testcontainers Cloud エージェントが SSH トンネルを開き、クラウド環境内の Docker デーモンに接続します。この際、Testcontainers を使用したテストで定義された Docker イメージをクラウド環境で取得し、コンテナを起動します。クラウド環境への接続はテスト実行中のみアクティブであり、テストスイートの完了後、Testcontainers Cloud は短時間待機した後、自動的に接続を閉じ、割り当てられたリソースを削除します。

Testcontainers Desktopのクラウド接続図

はじめる

クライアントをインストール

  1. Testcontainers Desktopをダウンロードしてインストールします
  2. Run with Testcontainers Cloud を選択します

Testcontainers Desktop のクラウドランタイム

Testcontainers Cloud 上で実行されるコンテナを使用して、Testcontainers ベースのテストを実行できるようになりました。

もし Testcontainers を使用した既存のテストがない場合は、Testcontainers Cloud があなたの環境で正しく設定されていることを確認するためのいくつかのテストを含むサンプルプロジェクトを利用することができます。

サンプルプロジェクト

.NET

git clone https://github.com/AtomicJar/testcontainers-cloud-dotnet-example
cd testcontainers-cloud-dotnet-example
dotnet test --logger:"console;verbosity=detailed"

Go

git clone https://github.com/AtomicJar/testcontainers-cloud-go-example
cd testcontainers-cloud-go-example
go mod download
go test -v -count=1

Java

git clone https://github.com/AtomicJar/testcontainers-cloud-java-example
cd testcontainers-cloud-java-example
./mvnw test

Node.js

git clone https://github.com/AtomicJar/testcontainers-cloud-nodejs-example
cd testcontainers-cloud-nodejs-example
npm install
npm test

既存のテストの実行

Testcontainers ベースの統合テストは、Testcontainers Cloud を使用することでそのまま実行できます。Testcontainers Cloud の使用感をより良く理解するために、短時間で2回連続してテストを実行することをおすすめします。これにより、ウォームアップされた環境での動作を体験できます。

Testcontainers Cloud は、IDE からテストを実行する場合にも動作します。そのため、最初に IDE からいくつかのテストを実行して、プロジェクトのテストが Testcontainers Cloud でどのように動作するかを確認するのが便利です。通常の IDE の機能を使用してテストを実行し、Testcontainers Cloud が使用されている Docker 実装であることを確認するために出力ログをチェックしてください。

ローカルの Docker に切り替えたい場合は、Testcontainers Cloud クライアントアプリを停止するだけで、Testcontainers ベースの統合テストがローカル Docker を使用して実行されるようになります。

適切なコンテナランタイムの選択方法

システムが Docker daemon と Testcontainers Cloud の両方にアクセスできる場合、Testcontainers ライブラリは次の順序で使用する Docker 環境を決定します:

  1. ~/.testcontainers.properties ファイルを確認（存在する場合）:

    • tc.host プロパティからDockerデーモンの場所を取得。

  2. 環境変数 DOCKER_HOST から Docker daemon の場所を取得。

  3. 現在のオペレーティングシステムのデフォルトの Docker ロケーションを試す。

Testcontainers Cloud エージェント（Desktop と CI の両方）は、~/.testcontainers.properties ファイルに自分のロケーションを設定します。これにより、テストは自動的に Testcontainers Cloud を優先します。

特定のプロジェクトで無効化

Testcontainers Cloudを起動すると、デフォルトでローカル環境がTestcontainersのテストで使用されるように構成されます。ただし、特定のプロジェクトではこれを無効化したい場合があります。例えば、古いTestcontainersライブラリを使用しており、Testcontainers Cloudと互換性がない場合や、クラウドベースのコンテナ実行に適していないコードパターンを使用している場合です。

特定のプロジェクトでグローバルな Testcontainers Cloud 設定を使用しないようにするには、プロジェクト内（クラスパス上）の testcontainers.properties 設定ファイルで dockerconfig.source プロパティを更新します。

このオプションは Java 用 Testcontainers でのみ利用可能です。

以下の内容を含む testcontainers.properties 設定ファイルをプロジェクトのクラスパスに追加してください：

dockerconfig.source=autoIgnoringUserProperties

Testcontainers Cloud クライアントアプリを実行したままにしても問題ありませんが、それ以上の変更は必要ありません。このプロジェクトは、通常の自動 Testcontainers 環境検出メカニズムを使用して、Docker と通信するための適切な方法を見つけるようになります。

Turbo モードでテストを並列化

Testcontainers Cloud の Turbo モードを使用すると、テストを並列実行できるようになります。各テストプロセスが独自のクラウド環境を受け取るため、テストの並列化がスケーラブルになります。テストを並列化することは、ビルドの実行速度を向上させる方法の1つです。

テストスイートの構成や利用可能なコンピューティングリソースによっては、ローカルリソースのボトルネックにより並列テストがパフォーマンス向上に繋がらない場合もあります。Testcontainers Cloud の Turbo モードでは、Testcontainers テストを実行する各プロセスに1つのクラウド環境が割り当てられるため、この問題を解決します。

これにより、同時にテストを実行するプロセス数を増やしても、ローカルコンピュートリソースの負荷が直線的に増加することはありません。クラウド環境のスケーラビリティによって、テストの実行速度を向上させることができます。

Turboモードは、大規模なテストスイートが許容範囲を超えて長時間実行される課題を抱えるユーザーにとって特に有益です。以下に、Testcontainers Cloud の Turbo モードを有効化してテストを並列実行する方法を説明します。

Turboモードは現在、Free アカウントでは制限されています。

デスクトップで Testcontainers Cloud の Turbo モードを開始する

Testcontainers Desktop アプリケーションで、Turbo モードを有効化するには、Turbo モードのチェックボックスを選択してください。


Testcontainers Cloud の Turbo モード

CI で Turbo モードを有効化する方法

CI でエージェントを起動する際、--max-concurrency=N フラグを指定すると、このエージェントを使用するプロセスが利用できる最大 N 個の並列 Testcontainers Cloud 環境を有効化できます。

  • --max-concurrency のデフォルト値は4です。
  • 環境変数 TC_CLOUD_CONCURRENCY を使用して並列実行オプションを設定することもできます。例えば、以下のように設定します:
export TC_CLOUD_CONCURRENCY=2

これで、Testcontainers Cloud のスケーラビリティを利用して並列テストを実行する準備が整いました。並列テストを初めて行う場合、以下の一般的なビルドツールでの試し方をご覧ください。

Gradleを使用したJavaプロジェクトでのTurboモード有効化

Gradle でテストを並列実行するには、build.gradle ファイルのテストタスクに maxParallelForks を追加します：

test.maxParallelForks = 4

これにより、Gradleは最大4つのプロセスを使用してテストを実行します。Turboモードが設定されている場合、各プロセスで作成されたコンテナは同じDocker環境をオーバーロードしません。

JavaプロジェクトでTurboモードを試してみたい場合は、GitHubリポジトリの手順に従ってサンプルプロジェクトを使用してみてください。

Mavenを使用したJavaプロジェクトでのTurboモード有効化

Maven をビルドツールとして使用している場合、テスト実行には Surefire プラグインを使用している可能性があります。Surefire プラグインは並列テスト実行をサポートしており、その有効化方法は公式ドキュメントを参照できます。

一般的に、Maven で並列テストを実行するには、pom.xml ファイルの Surefire または Failsafe プラグインの設定に parallel および forkCount プロパティを追加します。以下は、最新バージョンの Surefire プラグインのサンプル設定です：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.0.0-M7</version>
  <configuration>
    <parallel>classes</parallel>
    <forkCount>4</forkCount>
  </configuration>
</plugin>

Java プロジェクトで Turbo モードを試したい場合は、GitHub リポジトリの手順に従ってサンプルプロジェクトを使用してみてください。

Turboモードが有効化されたかを確認する方法

Testcontainers Cloud で Turbo モードを有効化し、ビルドツールで並列テストを設定した場合、テストを実行すると Testcontainers Cloud アプリケーションの「connection」タブで複数のリース割り当てが表示されるはずです。

Testcontainers DesktopでTurboモードが有効になっているか確認する

Testcontainers Cloud がどのコンテナを同じクラウド環境で実行するかを決定する方法

Testcontainers Cloud ではセッションを使用してコンテナを区別します。同じプロセスであれば、例えば複数のコンテナを起動する必要がある場合でも、同じクラウド環境に接続します。

一方で、並列プロセスが実行される場合、現在実行中の Testcontainers Cloud エージェントの最大並列設定が許容する限り、新しいクラウド環境が割り当てられます。

したがって、Turbo モードを設定している場合でも、テストプロセスが1つしかない場合は、すべてのコンテナが同じクラウド環境で実行されます。たとえその1つのプロセス内でテストを並列実行していたとしても同様です。

複数のテストプロセス（例えばフォークされたJVM）を使用している場合、Turbo モードが有効になっていれば、可能な限り各JVMに専用のクラウド環境が割り当てられます。

メモリ制限

各Testcontainers Cloudセッションには8GBのRAMが割り当てられます。この情報は接続が確立された際のログで確認できます:

Connected to docker: 
  Server Version: 70+testcontainerscloud
  API Version: 1.41
  Operating System: Ubuntu 22.04 LTS
  Total Memory: 7396 MB

現在、1つのTestcontainers Cloudセッションのメモリ使用量を拡張または制限することはできません。

テストがクラウドで実行されているか確認する方法

Testcontainers Desktop アプリケーションの「Connection」セクションを確認します。

ローカルマシンに Testcontainers Cloud アプリケーションをインストールしている場合、トレイメニューにアプリアイコンが表示されます。テストが Testcontainers Cloud アプリケーションを使用して実行されていることを確認するには、Testcontainers Cloud アプリケーションのアイコンをクリックしてください。接続状態として「Running」または「Passive」が表示されます。「Connection」サブメニューをクリックすると、詳細な接続情報が確認できます。

  • Connected to: 接続されているゾーン/リージョン（接続遅延がミリ秒単位で表示されます）

  • Leases: 開かれたコネクションのID（状態）

ACTIVE Leases: コネクションがアクティブで、テストのための Testcontainers Cloud リソースが割り当てられている状態

PASSIVE Leases: コネクションが閉じられ、Testcontainers Cloud リソースが割り当てられていない状態

  • Data: R: 読み取りデータ量（kB）, W: 書き込みデータ量（kB）

実行中の状態（Running State）

Testcontainers Desktop cloud connection status - active

パッシブ状態 (Passive State)

Testcontainers Desktop cloud connection status - passive

システム再起動時にクライアントを自動起動

ユーザー体験を向上させるため、デスクトップアプリケーションのメニューに「Autostart」チェックボックスを追加しました。コンピュータを起動または再起動した際に Testcontainers Cloud を自動的に起動したい場合は、このチェックボックスを有効にしてください。この機能は、サポートされているすべてのオペレーティングシステムで同じように動作します。


Testcontainers Desktop autostart

テストセッションにプロジェクトタグを付ける

Testcontainers Cloud を使用してテストを実行する際、project または workflow の名前や URL を指定できます。この情報は Testcontainers Cloud のダッシュボードに表示され、実行中のテストやワークフローを簡単に特定することができます。


Testcontainers Desktop project and workflow

URL は任意で、指定を省略することも可能です。GitHub Actions を使用している場合、ワークフロー名と URL は自動的に検出され、Testcontainers Cloud ダッシュボードに表示されます。

CIで環境変数を使用して設定

以下の環境変数を設定してください：

  • プロジェクトの場合
    • TCC_PROJECT_KEY / TCC_PROJECT_URL
    • または、~/.testcontainers.properties ファイルで tcc.project.key と tcc.project.url プロパティを設定できます。
  • ワークフローの場合
    • TCC_WORKFLOW_KEY / TCC_WORKFLOW_URL
    • または、~/.testcontainers.properties ファイルで tcc.workflow.key と tcc.workflow.url プロパティを設定できます。

Testcontainers tests 内のラベルを使用して設定

  • プロジェクト用
    • cloud.testcontainers.tcc.project.key / cloud.testcontainers.tcc.project.url
  • ワークフロー用
    • cloud.testcontainers.tcc.workflow.key / cloud.testcontainers.tcc.workflow.url

使用の最適化

チームが Testcontainers Cloud の利用を拡大するにつれて、使用効率を最適化したいと思う場合があるでしょう。このセクションでは、いくつかの役立つテクニックを紹介します。

Turboモードを調整する

Turbo モードを使用すると、複数のワーカーを要求してテストを並列実行できます。一般的に、これはCIパイプラインの実行時間を短縮し、全体的な使用量を一定に保つための有効な方法です。例えば、以前は単一のワーカーで15分かかっていたパイプラインが、3つのワーカーで並列化されると5分で完了する場合があります。

しかし、必要以上のワーカーを要求すると、実行時間の大幅な短縮が得られないにもかかわらず、全体の使用量が増加する可能性があります。このような場合、要求するワーカー数（例: --max-concurrency フラグ）を減らし、実行時間が一定に保たれることを確認することで、非効率な使用を取り戻すことができます。

テスト完了時にワーカーを瞬時に終了する

デフォルトでは、ワーカーは一定期間アクティブな状態を維持してからシャットダウンします。これは特にデスクトップ環境でスムーズなユーザー体験を提供するためです。しかし、CIパイプラインでは、特定のパイプラインやジョブが完了した後に、Testcontainers Cloud ワーカーへのアクセスが不要になることが予測できる場合があります。このような場合、エージェントのシャットダウン時にワーカーを瞬時に終了することで使用を最適化できます。

これを行うには、エージェントを起動する際に --terminate フラグを引数として渡すだけです。あるいは、エージェントがまだ実行中の場合に terminate コマンドを呼び出すことでも実現できます。

Dockerとの互換性

Docker CLIの使用

現在、Dockerコンテキストを使用して、基盤となる Docker API に直接アクセスすることが可能です:

docker context use tcc
docker ps

また、TCCセッションのCPUやメモリ使用量に関する情報を確認するには、以下のコマンドを使用します:

docker stats

または

DOCKER_CONTEXT=tcc docker stats

ただし、Testcontainers Cloudは汎用的な「Docker-as-a-Service」ではなく、これらの機能は実装上の詳細として扱うべきである点に注意してください。

ローカルファイルシステムのマウント

ローカルファイルシステムからコンテナへのファイルのマウントは現在実装されていません。その代わりに、copyFileToContainer および copyFileFromContainer メソッドの使用を検討してください。

例えば、コンテナを定義する際にファイルをコピーする場合：

GenericContainer myContainer = new GenericContainer(ALPINE_IMAGE)
    .withCopyFileToContainer(
        MountableFile.forClasspathResource("/mappable-resource/"),
        directoryInContainer
    );

また、コンテナからファイルをコピーする場合は以下のようにします：

myContainer.copyFileFromContainer(directoryInContainer + fileName, destinationOnHost);

ファイル操作に関する詳細な例は、ライブラリのドキュメントに記載されていますので参照してください。

ネットワーク設定

インターナル Docker レジストリの使用

Testcontainers Cloud は、パブリックインターネットからアクセスできない「プライベート」レジストリからイメージを取得する必要があるユーザー向けに設定を提供します。Docker Hub、Amazon ECR、GCR などのレジストリを使用している場合、この機能は不要です。これらのレジストリはパブリックインターネットに公開されています。

Testcontainers Desktop での設定方法

ユーザーごとの設定を ~/.testcontainers.properties ファイルに追加

cloud.private_registry.proxy.url = https://private.registry.example.com:8999

複数のレジストリを設定することも可能です：

cloud.private_registry.proxy.url = https://private.registry.example.com:8999
cloud.private_registry.proxy.url.second = https://private2.registry.example.com:8999
cloud.private_registry.proxy.url.test = https://test.registry.example.com:8999

.url. の後の部分はユニークである必要がありますが、任意の値を使用できます（利便性のための識別子に過ぎません）。

特定のイメージ（例: private.registry.example.com:8999/prefix/name）を取得可能にするには、次の設定を行います：

すべてのイメージを許可する場合：

cloud.private_registry.proxy.allowed_image_name_globs = **

より具体的に特定のイメージを許可する場合：

cloud.private_registry.proxy.allowed_image_name_globs = prefix/*,prefix/name

このように、取得を許可するイメージをカンマ区切りで指定します。このリストを （すべて許可）ではなく、可能な限り小さく保つ ことを推奨します。

証明書関連の問題を無視する場合、以下の設定を使用します：

cloud.private_registry.proxy.insecure_skip_verify = true

ただし、この設定は推奨されません。この設定を有効にすると、中間者攻撃（MitM攻撃） のリスクが生じるため、接続問題をテストする場合など、限られた状況でのみ使用してください。

これらの設定変更は、Testcontainers Cloudアプリケーションの起動時に読み込まれるため、設定を反映させるにはアプリケーションを再起動する必要があります。

エージェントCLIの使用方法

CLIを使用してプライベートレジストリを設定する場合、以下のようにフラグを追加します（有効にしたい各レジストリごとに指定可能です）:

--private-registry-url=https://private.registry.example.com:8999 --private-registry-url=https://private2.registry.example.com:8999

以下のようなイメージを取得可能にします：

  • private.registry.example.com:8999/prefix/name
  • private.registry.example.com:8999/name

すべてのイメージを許可する場合：

--private-registry-allowed-image-name-globs=**

より具体的に特定のイメージを許可する場合

--private-registry-allowed-image-name-globs=prefix/*,prefix/name

このように、取得を許可するイメージをカンマ区切りで指定します。すべてを許可するよりも、許可リストを可能な限り小さく保つことを推奨します。

現在の制限事項

  • イメージの取得のみサポート、イメージのプッシュ操作は許可されていません。
  • プロキシ設定は各マシンで設定する必要がありますが、将来的には組織全体で設定可能になる予定です。
  • パブリックおよびプライベートDockerレジストリの資格情報やトークンは、Testcontainers ライブラリおよび Testcontainers Cloud で可視化されます（データはプロキシされますが、保存はされません）。
  • 取得したイメージは、ユーザーの Testcontainers Cloud VM 内にキャッシュされます。このキャッシュは、約30分間非アクティブになると自動的に削除されます。

エージェントでは、セキュリティ対策として、プロキシ接続が設定された単一のレジストリホストに対してのみ許可されています。また、HTTPメソッドはHEADおよびGETに制限されており、リクエストが許可されるのは、あらかじめ設定された許可リストに一致するパスだけです。この許可リストは、エージェントで許可されたイメージに基づいています。

現在、この設定はインストール単位で構成されていますが、将来的には中央で一括管理できるようになる見込みです。

プロキシ環境での使用方法

Testcontainers Cloud クライアントをプロキシに向けるには、環境変数または Testcontainers の設定を使用して構成できます。HTTP プロキシを使用しているネットワークで Testcontainers Cloud クライアントを実行する場合、以下の3つの方法で設定が可能です。

1. 環境変数を使用する場合

以下の環境変数のいずれかがプロキシを指すように設定されたシェルからクライアントを起動することで、クライアントは自動的にそれらを認識し、設定が完了します：

http_proxy または HTTP_PROXY
https_proxy または HTTPS_PROXY
no_proxy または NO_PROXY

2. Testcontainers Cloud プロパティファイルを使用する場合

シェルの環境変数を設定できない場合、次のオプション行を追加してプロキシ設定を行うことができます：

http_proxy=host:port
https_proxy=host:port
no_proxy=host1, host2

これを以下のいずれかの場所に保存されている cloud.properties ファイルに記述してください：

MacOS および Linux

$XDG_CONFIG_HOME が設定されている場合：

$XDG_CONFIG_HOME/testcontainers/cloud.properties

設定されていない場合：

$HOME/.config/testcontainers/cloud.properties
Windows

$XDG_CONFIG_HOME が設定されている場合：

%xdg_config_home%\testcontainers\cloud.properties

設定されていない場合：

%userprofile%\.config\testcontainers\cloud.properties

3. Testcontainers設定を使用する場合

もう1つの方法として、設定を $HOME/.testcontainers.properties ファイルに記述してプロキシ設定を行うこともできます。使用するキーの名前は、前述の Testcontainers Cloud プロパティファイルと同じです

トラブルシューティング

ログへのアクセス

Testcontainers Desktop

アプリケーションはログをシステム依存の場所に保存します。ログへの最も簡単なアクセス方法は、メニューの Preferences > Show logs... からです。

ログファイルの保存先を手動で確認する場合は以下の場所を参照してください：

  • macOS: $HOME/Library/Logs/AtomicJar/testcontainers.cloud.desktop/testcontainers-cloud-desktop.log
  • Linux: ${XDG_CACHE_HOME:-$HOME}/.cache/AtomicJar/testcontainers.cloud.desktop/testcontainers-cloud-desktop.log
  • Windows: %LocalAppData%/AtomicJar/testcontainers.cloud.desktop/testcontainers-cloud-desktop.log

ログファイルは5MBを超えるとローテーションされます。

Testcontainers Cloud エージェント

エージェントは実行時に stderr にログを書き込みます。ログをファイルに保存するには以下のようにエージェントを起動します:

./tcc-agent > "./tcc/agent.log" 2>&1 &

これにより、stdout と stderr の両方が指定したファイルにリダイレクトされます。

GitHub Action

公式の GitHub Action では logfile パラメータを使用して特定のログファイルへの書き込みをサポートしています。その後、actions/upload-artifactアクションを使用してログファイルをアップロードできます。

詳細ログの有効化

詳細ログは、追加のデバッグ情報を取得する際に役立ちます。

Testcontainers Desktopでの設定

~/.testcontainers.properties ファイルに次のプロパティを追加してください：

cloud.logs.verbose = true

設定を反映するには、クライアントを終了し、再起動する必要があります。

エージェントCLIでの設定

CLI呼び出しに以下のフラグを追加します:

--verbose

または、環境変数を設定します:

export TC_CLOUD_LOGS_VERBOSE=true

エージェントCLIは、Testcontainers Desktop の設定セクションで指定されたプロパティ値も尊重します。

また、Linuxでは次の方法を試すことができます

~/.profile ファイルに以下の行を追加します：

export TC_CLOUD_LOGS_VERBOSE=true

MacOSでのデバッグ

環境変数を利用してデスクトップクライアントをターミナルから起動できます：

open -W --stdout $(tty) --stderr $(tty) /Applications/Testcontainers\ Desktop.app

すべての環境変数をインラインで設定することも可能です：

TC_CLOUD_LOGS_VERBOSE=true open -W --stdout $(tty) --stderr $(tty)
/Applications/Testcontainers\ Desktop.app

有効化の確認方法

設定が正しく有効化されていれば、ログの初期段階で次のような行が表示されます:

2022-11-07T18:47:56.964Z --- DBG Verbose output enabled

Dockerアクティビティが検出されない場合

主な原因

「this worker was requested by the Testcontainers Cloud agent but seemingly didn’t run any containers.」という警告メッセージが表示されることがあります。この警告は、ワーカーが想定された作業を行わなかったことを示します。この問題は以下の状況で発生する可能性があります：

  1. ターミナルで直接Dockerコマンドを実行した 通常、Testcontainers Cloud のユーザーは、コンテナのライフサイクルを管理するために Testcontainers オープンソースライブラリを使用します。TCC Docker コンテキストに対して生の Docker コマンドを直接実行することはサポートされていません。例えば、Testcontainers Cloud エージェントがアクティブだが接続中のワーカーがいない状態で、docker ps のような Docker コマンドを直接実行すると、新しいワーカーが意図せず起動してしまう可能性があります。

  2. CI パイプラインで Testcontainers Cloudエージェントを起動したが、Testcontainers ベースのテストが含まれていない CI/CDパイプライン内で Testcontainers Cloud エージェントを起動する場合、パイプラインジョブに Testcontainers ベースのテストが含まれていることを確認する必要があります。テストが含まれていない場合、ワーカーは待機状態のままとなり、実際には何も作業を行いません。

トラブルシューティング手順

「No activity detected」の警告が表示された場合は、以下の手順を試してください:

  1. CI パイプラインの設定を確認: CI/CDパイプラインの設定を確認し、Testcontainers ベースのテストが実行される適切なステージが構成されていることを確認してください。パイプラインがこれらのテストを実行するようトリガーを設定します。

  2. Docker コマンドの干渉を回避: Testcontainers Cloud エージェントがアクティブな状態で、デスクトップマシン上で直接 Docker コマンドを実行しないようにしてください。これらの外部コマンドは、エージェントがコンテナを制御および管理する能力に干渉する可能性があります。

  3. Testcontainers の統合を確認: テストコードベースに Testcontainers が正しく統合されていることを再確認してください。必要な依存関係と設定が正しく構成されていることを確認し、テストが Testcontainers API を使用してコンテナの作成と管理を適切に呼び出していることを確認します。

結論

Testcontainers Cloud で表示される「No activity detected」の警告は、ワーカーが期待どおりにコンテナを実行しなかったことを示します。デスクトップでの外部 Docker コマンドの実行を避け、CI パイプラインが Testcontainers ベースのテストを実行するよう設定することで、「空の」ワーカーを最小限に抑え、Testcontainers Cloud の機能を最大限に活用できます。

問題が解決しない場合は、Testcontainers Cloud のドキュメントを参照するか、サポートに問い合わせてさらに問題を解決してください。

トラブルシューティング用にクラウドワーカーに接続する方法

高度なトラブルシューティングが必要な場合、Testcontainers Cloud のワーカーに接続することが役立つ場合があります。

Web ターミナルを使用して接続

ダッシュボードに移動すると、利用可能なクラウドワーカーの「live」アクティビティを確認できます。行をクリックして詳細ビューを展開し、「Connect」ボタンをクリックするとWebターミナルを開くことができます。

Webターミナルが開いたら、「Connect Terminal」をクリックすることで、選択したワーカーへの安全な接続が開始されます。

ローカルターミナルを使用して接続

1. 「Worker ID」を取得

ダッシュボードで利用可能なクラウドワーカーの「live」アクティビティを確認し、詳細ビューを展開します。対象ワーカーの右側にある「kebabメニュー」（3点アイコン）をクリックし、「Worker ID」をクリップボードにコピーします。

2. CI エージェントをダウンロードして実行可能にする

Testcontainers Cloud のバイナリに接続機能が含まれています。エージェントをまだ持っていない場合は、インストールページまたは https://get.testcontainers.cloud/bash から直接ダウンロードしてください。

curl -o tcc-agent -L https://get.testcontainers.cloud/testcontainers-cloud-agent_darwin_arm64
chmod +x tcc-agent
3. クラウドワーカーに接続する

ターミナルで以下のコマンドを使用して、取得した Worker ID をパラメータとしてワーカーに接続します:

./tcc-agent connect <worker-id>

Testcontainers Desktop を実行中でサインインしている場合、Testcontainers Cloud エージェントは認証トークンを自動的に再利用するため、追加の手順は必要ありません。それ以外の場合は、次の手順を参照してください。

4. (任意) Testcontainers Cloud 認証トークンを提供

トークンを手動で渡したい場合は、TC_CLOUD_TOKEN 環境変数を設定するか、コマンドライン引数として指定することができます：

./tcc-agent --token <token> connect <worker-id>

テストが遅くなる場合

通常、インターネット接続が速い場合、テストの速度はローカルの Docker Desktop と同等またはそれ以上になります。もしテストが遅いと感じた場合は、Testcontainers Desktop アプリの「Connection」サブメニューを確認してください。最後に記録された遅延が表示されます。理想的な接続遅延は20ms以下です。

さらに、Testcontainers Cloudではテストを並列実行することができ、Turboモードを有効にすると、各テストフォークが独自のVMに接続されるため、テストを3～4倍速く実行することが可能です。

CI 環境での Testcontainers Cloud の使用

CI ジョブでエージェントを起動する

Testcontainers Cloud を CI 環境で使用するには、テストを実行する前に Testcontainers Cloud エージェントを起動するステップを CI ジョブに追加してください。また、Testcontainers Cloud のトークンを設定することを忘れないでください。

さらに、内蔵の wait コマンドを使用して、Testcontainers Cloud への接続が確立されるまで待機することを推奨します。これにより、テストが準備完了状態の Testcontainers Cloud と確実に連携できるようになります。

# エージェントのバイナリを取得し、すぐに実行
sh -c "$(curl -fsSL https://get.testcontainers.cloud/bash)"
 
# 通常通りTestcontainersを使用したテストを実行
mvn verify

Testcontainers Cloud トークンを設定する必要もあります。多くの環境では、環境変数 TC_CLOUD_TOKEN を使用するのが最も便利です。ただし、このトークンは可能な限り秘密に保持してください。

GitHub Actions での Testcontainers Cloud の使用

GitHub Actions で Testcontainers Cloud を使用するには、TC_CLOUD_TOKEN を対応するトークン値に設定し、エージェントをダウンロードして起動するだけです。

以下のスクリプトを使用して、ワークフローに必要なステップを追加できます:

steps:
  - name: Checkout code
    uses: actions/checkout@v3
 
  - name: Set up Testcontainers Cloud agent
    run: |
      export TC_CLOUD_TOKEN=<your-token-here>
      sh -c "$(curl -fsSL https://get.testcontainers.cloud/bash)"
      
  - name: Run tests
    run: mvn verify

Dependabot によってトリガーされたジョブが失敗する場合、Dependabot のシークレットにも TC_CLOUD_TOKEN を設定していることを確認してください。

Kubernetes 環境での Testcontainers Cloud の使用

Testcontainers Cloud は、Tekton や Jenkins X などの Kubernetes ベースの CI 環境でも使用可能です。

エージェントをダウンロードして起動し、TC_CLOUD_TOKEN を対応するトークン値に設定するだけで利用可能です。

command:
    - sh -c "$(curl -fsSL https://get.testcontainers.cloud/bash)"
    - mvn verify
envs:
    - name: TC_CLOUD_TOKEN
      valueFromSecretRef: tccToken

CircleCI での Testcontainers Cloud の使用

CircleCI で Testcontainers Cloud を使用するには、TC_CLOUD_TOKEN を対応するサービスアカウントトークンに設定する必要があります。このトークンは Testcontainers Cloud のダッシュボードで生成できます。その後、トークンをCircleCIのプロジェクト設定で環境変数として追加してください。

次に、CircleCI のワークフローを設定して Testcontainers Cloud をインストールして使用できるようにします。testcontainers-cloud-orb の setup を CircleCI Job の pre-step として追加できます。また、テストを実行する前に Testcontainers Cloud エージェントが起動するように構成します。

以下のスクリプトを使用してワークフローに必要なステップを追加できます。この中で特に、tcc: orb と tcc/setup の設定が「pre-steps」に含まれている点に注目してください:

version: "2.1"
orbs:
  tcc: atomicjar/testcontainers-cloud-orb@0.1.0
workflows:
  workflow_name:
    jobs:
      - job_name:
          # ... existing steps go here (run tests, etc.)
          pre-steps:
            - tcc/setup

Google Cloud Build での Testcontainers Cloud の使用

Google Cloud Build で Testcontainers Cloud を使用するには、TC_CLOUD_TOKEN を対応するサービスアカウントトークンに設定する必要があります。このトークンは、Testcontainers Cloud のダッシュボードで生成できます。

サービスアカウントのトークンは、Google Cloud Secrets Manager に安全に保存することができます。シークレットを作成した後、以下を行います：

  1. アクセス権の付与

    プリンシパルに YOUR_PROJECT_ID@cloudbuild.gserviceaccount.com を指定し、Secret Manager Secret Accessor ロールを割り当てます。

  2. Testcontainers Cloudエージェントのインストールと起動

    次に、Google Cloud Secrets Manager から TC_CLOUD_TOKEN の値を取得し、環境変数として設定して、Testcontainers Cloud エージェントをインストールして起動します。

以下のスクリプトを cloudbuild.yaml 設定に追加してください:

steps:
    - name: "docker-image:tag" # ex: maven:3-eclipse-temurin-19
      args:
          - "-c"
          - |
              curl -fsSL https://get.testcontainers.cloud/bash | sh
              cp ~/.testcontainers.properties /root/.testcontainers.properties
              # Your test command like "mvn test" or "npm test"
      dir: "${_APP_NAME}"
      entrypoint: bash
      secretEnv:
          - TC_CLOUD_TOKEN
availableSecrets:
    secretManager:
        - versionName: projects/<PROJECT_ID>/secrets/TC_CLOUD_TOKEN/versions/latest
          env: TC_CLOUD_TOKEN

GitLab CI/CDでのTestcontainers Cloudの使用

GitLab で Testcontainers Cloud を使用するには、TC_CLOUD_TOKEN を対応するサービスアカウントトークンに設定する必要があります。このトークンは Testcontainers Cloud のダッシュボードで生成できます。

GitLabのプロジェクト設定で環境変数として TC_CLOUD_TOKEN を追加し、トークンをジョブ内で使用できるようにします。

次に、GitLab のパイプラインジョブを設定し、Testcontainers Cloud をインストールして使用できるようにします。Testcontainers Cloud エージェントのインストールスクリプトを使用し、テストを実行する前にエージェントを起動します。

以下は、.gitlab-ci.yml の設定例です：

image: "docker-image:tag" # ex: maven:3-eclipse-temurin-19
 
job_name:
    stage: test
    script:
        - curl -fsSL https://get.testcontainers.cloud/bash | sh
        -  # ... existing steps go here (run tests, etc.)

Azure Pipelines での Testcontainers Cloud の使用

Azure Pipelines で Testcontainers Cloud を使用するには、TC_CLOUD_TOKEN を対応するサービスアカウントトークンに設定する必要があります。このトークンは Testcontainers Cloud のダッシュボードで生成できます。

その後、トークンをパイプライン設定に追加し、タスク内で環境変数として使用できるように設定します。

次に Azure Pipelines のジョブを構成し、Testcontainers Cloud をインストールして使用するようにします。Testcontainers Cloud エージェントのインストールスクリプトを使用し、テストを実行する前にエージェントを起動します。

以下は、azure-pipelines.yml の設定例です:

steps:
- task: Bash@3
  inputs:
    targetType: 'inline'
    script: 'sh -c "$(curl -fsSL https://get.testcontainers.cloud/bash)"'
  env:
    TC_CLOUD_TOKEN: $(TC_CLOUD_TOKEN)

Jenkins での Testcontainers Cloud の使用

Jenkins で Testcontainers Cloud を使用するには、まず Testcontainers Cloud ダッシュボードでトークンを生成する必要があります。その後、以下の手順でトークンをシークレットとして保存します：

  • Dashboard で Manage Jenkins -> Manage Credentials を選択します。
  • Stores scoped to Jenkins の下にある (global) ドメインをクリックし、Add Credentials を選択します。
  • 次の値を入力し、Create をクリックします：
    • Kind: Secret text
    • Secret: YOUR_TOKEN_VALUE
    • ID: tc-cloud-token-secret-id

次に、Jenkins パイプラインを設定して、上記で保存したシークレットを参照し、TC_CLOUD_TOKEN 環境変数を設定します。その後、Testcontainers Cloud エージェントのインストールスクリプトを使用し、テストを実行する前にエージェントを起動します。

以下は、Jenkinsfile に追加する設定例です:

pipeline {
    agent any
    stages {
        stage('Setup Testcontainers Cloud') {
            steps {
                withCredentials([string(credentialsId: 'tc-cloud-token-secret-id', variable: 'TC_CLOUD_TOKEN')]) {
                    sh 'curl -fsSL https://get.testcontainers.cloud/bash | sh'  // Testcontainers Cloudエージェントのインストールと起動
                }
            }
        }
        stage('Run Tests') {
            steps {
                sh 'mvn verify'  // Testcontainersを使用したテストの実行
            }
        }
    }
}

Tekton での Testcontainers Cloud の使用

Tekton で Testcontainers Cloud を使用するには、TC_CLOUD_TOKENを対応するサービスアカウントトークンに設定する必要があります。このトークンは Testcontainers Cloud のダッシュボードで生成できます。その後、シークレットを作成し、パイプラインタスク内で変数として使用するよう設定します。

例えば、次のように secret.yaml ファイルを作成してシークレットを定義します：

apiVersion: v1
kind: Secret
metadata:
  name: tcc-token
stringData:
  token: YOUR_TOKEN_VALUE_GOES_HERE

次に、Tekton パイプラインを設定し、テストを実行する前に Testcontainers Cloud エージェントをインストールして使用できるようにします。そのために、Testcontainers Cloud エージェントのインストールスクリプトを使用します。

以下は、先ほどのシークレットを TC_CLOUD_TOKEN 環境変数にバインドし、Testcontainers Cloud エージェントをインストールして起動した後、Maven のテストコマンドを実行する Tekton タスクのサンプル設定（task.build.yaml）です:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: build-java-maven
spec:
  workspaces:
    - name: source
  steps:
    - name: maven-build
      image: amazoncorretto:17.0.5-al2
      env:
        - name: TC_CLOUD_TOKEN
          valueFrom:
            secretKeyRef:
              name: tcc-token
              key: token
      script: |
        set -e
        cd "$(workspaces.source.path)"
        sh -c "$(curl -fsSL https://get.testcontainers.cloud/bash)"
        ./mvnw test

これは柔軟なアプローチであり、mvn コマンドを対応するビルドツールのコマンドに置き換えることで、他の言語で記述されたテストを Tekton で Testcontainers Cloud を使用して実行することができます。

請求

使用量の測定と請求

概要

Testcontainers Cloud の使用量は、Testcontainers Cloud エージェントによってトリガーされます。使用をトリガーするには、エージェントが顧客アカウント内の認可されたユーザーの資格情報を使用して認証されている必要があります。認可されたユーザーは以下のいずれかです：

  • メンバー（通常は個人ユーザー）
  • サービスアカウント（通常は自動化されたシステムで使用）

使用量の計測方法は、メンバーとサービスアカウントで異なります：

  • サービスアカウントの場合:「Testcontainers Cloud for CI」を参照してください。
  • メンバーの場合:「Testcontainers Cloud for Desktop」を参照してください。

Testcontainers Cloud for CI

計測単位: Worker Minute

Continuous Integration (CI)環境でエージェントがデプロイされると、サービスアカウントの資格情報で認証されます。CIがワークフロー（ビルドやパイプラインとも呼ばれる）を実行するとき、エージェントは Testcontainers Cloud サービスを提供するために1つ以上のワーカーを割り当てます。

各ワーカーの使用量は、そのワーカーが割り当てられている間に計測されます。割り当ては、エージェントによるサービスアカウントのアクティビティでオンデマンドでワーカーがリクエストされた時点で開始され、非アクティブな状態が一定時間続いた後にワーカーが終了した時点で終了します。

顧客は、max-concurrency フラグを設定することで、エージェントが Testcontainers Cloud サービスから1つまたは複数のワーカーを取得するかどうかを制御できます。このフラグを1以上に設定すると、Turboモードを利用して複数のワーカーでテストを並列実行することが可能になります。

サンプル 1

Testcontainers Cloud エージェントが CI 環境にデプロイされており、月曜から金曜まで 1 日 2 回実行されます。各実行には、1 つの Testcontainers Cloud ワーカーが 17 分間必要です。

  • 各ビルドの使用量: 平均で 17 分。
  • 4 週間の合計使用量: CI は 4 週間で 40 回トリガーされ、合計で 680 Worker Minutes が使用されます。
サンプル 2

Testcontainers Cloud エージェントが CI 環境にデプロイされており、月曜から日曜まで 1 日 10 回実行されます。各実行では 4 つの Testcontainers Cloud ワーカーが並列で動作します。

  • 3 つのワーカーは 4 分間稼働します。
  • 1 つのワーカーは 8 分間稼働します。
  • 各ビルドの使用量: 合計で 20 分。
  • 30 日間の合計使用量: CI は 30 日間で 300 回トリガーされ、合計で 6,000 Worker Minutes が使用されます。

Testcontainers Cloud for Desktop

計測単位: Seats

Organization のメンバーが Testcontainers Cloud エージェントを使用する場合、月間に生成された Worker Minutes の数に関係なく、1 人のメンバーにつき 1 つの Seat として計測されます（Fair Useポリシーの範囲内）。これは、Turboモードを使用して複数のワーカーでテストを並列実行する場合も含まれます。

サンプル 3

Organization には2人のメンバーがいます:

  1. Alice: Organization の管理者（Admin）。製品を積極的に使用していないため、Alice は Seat を生成しません。
  2. Barbara: 開発者で、Turboモードを有効にして平日に頻繁に製品を使用しています。Barbara は月間 2,500 Worker Minutes を使用しますが、1 つの Seat としてカウントされます。

メンバー 2 人のうち、1 人（Barbara）の使用が計測され、1 か月あたり1 Seat としてカウントされます。

よくある質問 (FAQ)

請求サイクルはいつ開始されますか？

請求サイクルは、登録日を問わず毎月1日（UTC）に開始されます。

初月の利用について、Testcontainers Cloud for CI はアップグレード日以降に使用された実際の Worker Minutes に基づいて請求され、Testcontainers Cloud for Desktop は Organization のアップグレード日に基づいて日割り計算されます。

翌月以降の利用については、Testcontainers Cloud for CI は実際の Worker Minutes 使用量に基づいて請求され、Testcontainers Cloud for Desktop は月初前に Organization に参加したメンバーのみが請求対象となります。つまり、新しいメンバーが参加した月に発生した使用量については、翌月の開始まで Seat 料金が免除されます。

Fair Use ポリシーとは？

SeatはTestcontainers Cloud for Desktopの「無制限」使用を提供しますが、不正利用（例: 暗号通貨のマイニング）を防ぐため、いくつかの現実的な制限が設けられています。Fair Use ポリシーの下では、1つの Seat に月間 3,000 Worker Minutesのクォータが割り当てられます。このクォータは、実際のところ大多数のユーザーが通常の使用で到達しない上限値として設定されています。

さらに、すべての Seat のクォータは合算されるため、Organization 内に数名の「パワーユーザー」がいても、通常はチーム全体のクォータを使い切ることはありません。

Docker セキュリティ(WIP)Testcontainers ガイド