devkuma – Testcontainers

Testcontainers について紹介

kc@example.com (kc kim) — Thu, 25 Aug 2022 10:42:43 +0900

概要

テスト環境は、プロジェクト設定の中でも特に重要な部分の 1 つである。テストでは、本番環境と同じ形のテスト環境で実行することが重要だからである。
しかし、毎回同じ環境を構築することはできず、すべての開発者と同じ環境を揃えることも簡単ではない。

そのためには、テストコードを実行するたびに Docker を使ってテスト用コンテナを起動し、テストを実行し、終了後にコンテナを停止して削除できるとよい。 Testcontainers を使うと、そのような機能を実現できる。

Testcontainers とは

Testcontainers は、テストのために Docker コンテナを実行する Java ライブラリである。
Docker を活用してインフラを構成でき、非常に多様なサービスをサポートしている。 FIRST 原則のうち、Repeatable 原則を守る助けにもなる。

Testcontainers 関連サイト

公式ドキュメント: https://www.testcontainers.org/
GitHub: https://github.com/testcontainers/testcontainers-java/

Testcontainers はなぜ使うべきか

テスト環境は、プロジェクト設定の中でも特に重要な部分の 1 つである。

もっとも難しく面倒な作業でもあるが、最初に一度きちんと整えておけば、その後テストを書くときに環境を気にせず、かなりきれいなテストコードを書けるようになる。一方で、プロジェクト環境設定の中で最も多くの時間を使い、多くの試行錯誤を経験する区間の 1 つともいえる。

Testcontainers は、MySQL、PostgreSQL、Redis、Apache Kafka、Amazon SQS などのシステムを Docker コンテナとして作成し、テストできる環境を提供する。

Testcontainers がなければ、実際のシステム環境を用意し、テストを行うたびにテストデータを初期化する過程が必要になる。また、テスト用に作ったシステム環境へ他の人が同時にアクセスすると、別のテストの影響でテストが失敗することがある。あるいは外部モジュールの影響で、テストが断続的に失敗することもある。

つまり、状況や外部の影響によって結果が変わる可能性があるということだ。この場合、失敗箇所を見つけるのが非常に難しい。このような状態は冪等性が維持されていないと言われることがあり、テストでは非常に重要な概念である。冪等性を守ることが、テスト全体の生産性に大きな影響を与えるためである。

冪等性とは

演算を複数回適用しても結果が変わらない性質を意味する。簡単に言えば、関数または API を何度実行しても常に同じ結果が得られるべきだという意味である。

さまざまな Module のサポート

Testcontainers はさまざまなモジュールをサポートしている。いくつか挙げると次のとおりである。

Testcontainers を使う

ここでは簡単な使い方を説明する。

ライブラリの追加

Gradle で JUnit 5 と一緒に使うには、次のライブラリが必要である。

testImplementation "org.junit.jupiter:junit-jupiter:5.8.1"
testImplementation "org.testcontainers:testcontainers:1.17.3"
testImplementation "org.testcontainers:junit-jupiter:1.17.3"

テストコードの作成

@Testcontainers
public class RedisBackedCacheIntTest {

    private RedisBackedCache underTest;

    // container {
    @Container
    public GenericContainer redis = new GenericContainer(DockerImageName.parse("redis:5.0.3-alpine"))
        .withExposedPorts(6379);

    // }

    @BeforeEach
    public void setUp() {
        String address = redis.getHost();
        Integer port = redis.getFirstMappedPort();

        // Now we have an address and port for Redis, no matter where it is running
        underTest = new RedisBackedCache(address, port);
    }

    @Test
    public void testSimplePutAndGet() {
        underTest.put("test", "example");

        String retrieved = underTest.get("test");
        assertThat(retrieved).isEqualTo("example");
    }
}

`@Testcontainers`

テスト中に Redis コンテナを実行するには、まず @Testcontainers をテストクラスに指定する必要がある。

@Testcontainers
public class RedisBackedCacheIntTest {

コンテナの作成

@Container
public GenericContainer redis = new GenericContainer(DockerImageName.parse("redis:5.0.3-alpine"))
    .withExposedPorts(6379);

@Container アノテーションは、テストライフサイクルのさまざまなイベントをこのフィールドに通知するよう JUnit に指定する。ここでは Testcontainers の GenericContainer を使い、Docker Hub の特定の Redis イメージを使用するよう設定し、指定したポート 6379 を公開するよう設定している。

コードがコンテナと通信できるか確認する

コンテナのアドレスを Testcontainers に問い合わせる。

String address = redis.getHost();

コンテナのポートを Testcontainers に問い合わせる。

Integer port = redis.getFirstMappedPort();

Container 再利用 (option)

Testcontainers を使うと、テストを実行するたびに Docker コンテナが毎回新しく作成されるため、時間がかかる。

これを解決するため、Testcontainers ではまだ公開サポートされていない機能ではあるが、Container 再利用オプションを提供している。Fast 原則に関係する機能である。

Requirements:

開発者のホームディレクトリにある .testcontainers.properties ファイルを設定する。
```
testcontainers.reuse.enable=true
```

JDBC URL 設定で TC_REUSABLE=true オプションを指定する。

jdbc:tc:mysql:///test?TC_REUSABLE=true&TC_INITSCRIPT=file:src/test/resources/schema.ddl

上記 2 つの設定が行われている場合に、コンテナの再利用が可能になる。

Apple M1 チップの macOS 環境で Colima を活用して Testcontainers を実行する方法

kc@example.com (kc kim) — Wed, 23 Aug 2023 01:05:59 +0900

Docker が Docker Desktop の利用規約を変更したことで、大企業で働く開発者は Docker Desktop を無料で使えなくなった。 macOS 環境で無料で使うには代替 driver が必要であり、hyperkit、VirtualBox など複数の代案が出ているが、現時点では Apple M1 チップの macOS 環境ではまだ使いやすいとは言いにくい。

2023 年 8 月時点の状況は次のとおりである。

hyperkit: Apple M1 チップ環境では動作しない。Homebrew でインストールしようとするとエラーになる。
VirtualBox: Apple M1 チップ環境で動作可能なバージョンは Beta である。

ここでは Docker Desktop を使わず、Colima を活用して Apple M1 環境で Testcontainers を実行する最も簡単な方法を紹介する。

Docker 設定

まず、Homebrew を使って Docker をインストールする。

brew install docker

Colima 設定

次に、Homebrew を使って Colima をインストールする。

brew install colima

その後、指定した CPU とメモリで Colima を実行する。

colima start --cpu 4 --memory 8

上記のコマンドは VM を 4 CPU、8 GiB メモリで実行している。

Colima サーバーは次の sock アドレスで利用可能になる。

unix:///Users/${HOME}/.colima/default/docker.sock.

Docker クライアントを使って Colima サーバーに接続できる。

docker context ls コマンドを使ってすべてのコンテキストを確認でき、docker context use colima コマンドで Colima に切り替えられる。

% docker context ls
NAME            DESCRIPTION                               DOCKER ENDPOINT                                  ERROR
colima *        colima                                    unix:///Users/user/.colima/default/docker.sock
default         Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
desktop-linux                                             unix:///Users/user/.docker/run/docker.sock

Colima を停止する方法は次のとおりである。

colima stop

Testcontainers 設定

Apple M1

Apple M1 チップで macOS を使っている場合は、少なくとも JNA (Java Native Access) が 5.7.0 以上のバージョンで使われているか確認する必要がある。

IntelliJ IDEA で、依存関係として次のライブラリが含まれているか確認すればよい。

もしバージョンが低ければ、5.7.0 に上げればよい。

Testcontainers 環境変数

Colima を使って Testcontainers を実行するには、次の環境変数が必要である。

DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock
TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock
TESTCONTAINERS_RYUK_DISABLED=true

これらの環境変数が必要な理由は次のとおりである。

DOCKER_HOST: Colima の sock アドレスを指定する。
TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE: コンテナ内部の sock アドレスを指定する。
TESTCONTAINERS_RYUK_DISABLED: Ryuk を無効化する。無効化しない場合、コンテナが終了せず、テストがタイムアウトすることがある。

Bash/Zsh シェルでは、次のように環境変数を宣言して Docker ホストを上書きできる。
~/.bashrc or ~/.zshrc

export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock
export DOCKER_HOST="unix://${HOME}/.colima/docker.sock"
export TESTCONTAINERS_RYUK_DISABLED=true

変更後は、環境変更を反映するために IntelliJ IDEA を再起動する必要がある。

Testcontainers

kc@example.com (kc kim) — Mon, 01 Jan 0001 00:00:00 +0000

Kotestテストコンテナ(Testcontainers)拡張

kc@example.com (kc kim) — Sun, 31 Mar 2024 15:11:00 +0900

Testcontainers

Testcontainersは、独立して再利用可能なテスト環境を構築するためのツールである。コンテナベースのテストをサポートし、ローカルマシンで実行されるテスト環境と同じ環境をプログラムで構築できる。KotestはTestcontainersと一緒に使用でき、テストに必要な外部リソースを管理し、より堅牢で信頼できるテストを書くのに役立つ。

Testcontainersを使用する主な利点は次のとおりである。

一貫した環境: 各テストが実行されるたびに一貫した環境を提供し、テスト結果を予測できる。
独立性: 外部リソースをコンテナ化し、テストが互いに影響しないよう保証する。
テスト環境構築の容易さ: コードでテスト環境をプログラム的に構築し管理できる。
多様なコンテナサポート: Docker、Kubernetesなど、さまざまな種類のコンテナをサポートし、多様なテストシナリオを構築できる。

Testcontainersプロジェクトは、テスト内部で使用するのに理想的な一般的なデータベース、Elasticsearch、Kafka、Selenium Webブラウザ、またはその他Dockerコンテナで実行できるあらゆるものの軽量な一時インスタンスを提供する。

Kotestは、データベースおよびKafka向けの特殊な拡張、サポートされるすべてのDockerイメージに対する汎用コンテナサポートなど、複数の拡張機能を提供する追加モジュールを通じてTestcontainersとの統合を提供する。

依存関係の追加

使用するには、Gradleビルドファイルに次の依存関係を追加する必要がある。

dependencies {
    testImplementation("io.kotest.extensions:kotest-extensions-testcontainers:${kotestVersion}")
}

参考: io.kotest.extensionsのGroup IDは、基本Kotest(io.kotest)とは異なる。

Mavenプロジェクトの場合は、次のように依存関係を追加する。

<dependency>
    <groupId>io.kotest.extensions</groupId>
    <artifactId>kotest-extensions-testcontainers</artifactId>
    <version>${kotest.version}</version>
    <scope>test</scope>
</dependency>

Databases

KotestでTestcontainersを使用する方法は簡単である。テストコード内でTestcontainersライブラリを使って必要なコンテナを起動し、テストを実行した後にコンテナを整理すればよい。

たとえば、データベース連携テストを行う場合、テスト開始時にデータベースコンテナを起動し、テスト終了時にコンテナを停止するのが一般的である。

このためにKotestでは、beforeTestとafterTestを使用して、テスト実行前後に必要な作業を実行できる。

以下はKotestとTestcontainersを一緒に使用するサンプルコードである。

import io.kotest.core.spec.style.FreeSpec
import org.testcontainers.containers.PostgreSQLContainer
import org.testcontainers.junit.jupiter.Container
import org.testcontainers.junit.jupiter.Testcontainers

@Testcontainers
class PostgreSqlTest : FreeSpec() {

    companion object {
        @Container
        val postgresContainer: PostgreSQLContainer<Nothing> = PostgreSQLContainer<Nothing>()
            .withDatabaseName("test")
            .withUsername("test")
            .withPassword("test")
            .withExposedPorts(5432)
    }

    override fun beforeTest(testCase: TestCase) {
        postgresContainer.start()
        System.setProperty("DB_URL", postgresContainer.jdbcUrl)
        System.setProperty("DB_USERNAME", postgresContainer.username)
        System.setProperty("DB_PASSWORD", postgresContainer.password)
    }

    override fun afterTest(testCase: TestCase, result: TestResult) {
        postgresContainer.stop()
    }

    init {
        "Database test" {
            // データベーステストコード作成
        }
    }
}

上のコードでは、PostgreSQLコンテナを使用してデータベーステストを行う。@Testcontainersアノテーションを使用してTestcontainersを有効化し、@Containerアノテーションを使用してコンテナを定義する。そしてbeforeTestとafterTestをオーバーライドし、テスト実行前後にコンテナを起動、停止する。

devkuma – Testcontainers

Testcontainers について紹介

概要

Testcontainers とは

Testcontainers 関連サイト

Testcontainers はなぜ使うべきか

さまざまな Module のサポート

Testcontainers を使う

ライブラリの追加

テストコードの作成

@Testcontainers

コンテナの作成

コードがコンテナと通信できるか確認する

Container 再利用 (option)

Apple M1 チップの macOS 環境で Colima を活用して Testcontainers を実行する方法

Docker 設定

Colima 設定

Testcontainers 設定

Apple M1

Testcontainers 環境変数

Testcontainers

Kotestテストコンテナ(Testcontainers)拡張

Testcontainers

依存関係の追加

Databases

参照

`@Testcontainers`