testcontainers-integration-tests

TestContainers を使った統合テスト

このスキルを使うタイミング

以下の場合にこのスキルを使用します:

• 実際のインフラ（データベース、キャッシュ、メッセージキュー）が必要な統合テストを記述する場合
• 実際のデータベースに対してデータアクセス層をテストする場合
• メッセージキュー統合を検証する場合
• Redis キャッシュの動作をテストする場合
• インフラコンポーネントのモックを避ける場合
• 本番環境に近い環境でテストが動作することを確認する場合
• データベースのマイグレーションとスキーマ変更をテストする場合

参照ファイル

• database-patterns.md: SQL Server、PostgreSQL、およびマイグレーションテストの例
• infrastructure-patterns.md: Redis、RabbitMQ、マルチコンテナネットワーク、コンテナ再利用、Respawn について

基本原則

1. モックよりも実際のインフラ - モックではなく、コンテナ内の実際のデータベース/サービスを使用する
2. テストの分離 - 各テストは新しいコンテナまたは新しいデータを取得する
3. 自動クリーンアップ - TestContainers がコンテナのライフサイクルとクリーンアップを処理する
4. 高速起動 - 適切な場合、同じクラス内のテスト間でコンテナを再利用する
5. CI/CD 互換 - Docker が有効な CI 環境でシームレスに動作する
6. ポートのランダム化 - コンテナは競合を避けるためにランダムなポートを使用する

モックよりも TestContainers を使う理由

インフラのモックの問題点

// 悪い例：データベースのモック
public class OrderRepositoryTests
{
    private readonly Mock<IDbConnection> _mockDb = new();

    [Fact]
    public async Task GetOrder_ReturnsOrder()
    {
        // これは実際の SQL の動作、制約、パフォーマンスをテストしない
        _mockDb.Setup(db => db.QueryAsync<Order>(It.IsAny<string>()))
            .ReturnsAsync(new[] { new Order { Id = 1 } });

        var repo = new OrderRepository(_mockDb.Object);
        var order = await repo.GetOrderAsync(1);

        Assert.NotNull(order);
    }
}

問題点: 実際の SQL クエリをテストしない、制約/インデックスを見逃す、誤った自信を与える、SQL 構文エラーをキャッチしない。

より良い方法：実際のデータベースを使用した TestContainers

// 良い例：実際のデータベースに対するテスト
public class OrderRepositoryTests : IAsyncLifetime
{
    private readonly TestcontainersContainer _dbContainer;
    private IDbConnection _connection;

    public OrderRepositoryTests()
    {
        _dbContainer = new TestcontainersBuilder<TestcontainersContainer>()
            .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
            .WithEnvironment("ACCEPT_EULA", "Y")
            .WithEnvironment("SA_PASSWORD", "Your_password123")
            .WithPortBinding(1433, true)
            .Build();
    }

    public async Task InitializeAsync()
    {
        await _dbContainer.StartAsync();
        var port = _dbContainer.GetMappedPublicPort(1433);
        var connectionString = $"Server=localhost,{port};Database=TestDb;User Id=sa;Password=Your_password123;TrustServerCertificate=true";
        _connection = new SqlConnection(connectionString);
        await _connection.OpenAsync();
        await RunMigrationsAsync(_connection);
    }

    public async Task DisposeAsync()
    {
        await _connection.DisposeAsync();
        await _dbContainer.DisposeAsync();
    }

    [Fact]
    public async Task GetOrder_WithRealDatabase_ReturnsOrder()
    {
        await _connection.ExecuteAsync(
            "INSERT INTO Orders (Id, CustomerId, Total) VALUES (1, 'CUST1', 100.00)");

        var repo = new OrderRepository(_connection);
        var order = await repo.GetOrderAsync(1);

        Assert.NotNull(order);
        Assert.Equal("CUST1", order.CustomerId);
        Assert.Equal(100.00m, order.Total);
    }
}

完全な SQL Server、PostgreSQL、およびマイグレーションテストの例については database-patterns.md を参照してください。

Redis、RabbitMQ、マルチコンテナネットワーク、コンテナ再利用、および Respawn データベースリセットパターンについては infrastructure-patterns.md を参照してください。

必要な NuGet パッケージ

<ItemGroup>
  <PackageReference Include="Testcontainers" Version="*" />
  <PackageReference Include="xunit" Version="*" />
  <PackageReference Include="xunit.runner.visualstudio" Version="*" />

  <!-- データベース固有のパッケージ -->
  <PackageReference Include="Microsoft.Data.SqlClient" Version="*" />
  <PackageReference Include="Npgsql" Version="*" /> <!-- PostgreSQL 用 -->
  <PackageReference Include="MySqlConnector" Version="*" /> <!-- MySQL 用 -->

  <!-- その他のインフラ -->
  <PackageReference Include="StackExchange.Redis" Version="*" /> <!-- Redis 用 -->
  <PackageReference Include="RabbitMQ.Client" Version="*" /> <!-- RabbitMQ 用 -->
</ItemGroup>

ベストプラクティス

1. 常に IAsyncLifetime を使用する - 適切な非同期のセットアップとクリーンアップ
2. ポートの利用可能性を待つ - WaitStrategy を使用してコンテナの準備ができるのを確認する
3. ランダムなポートを使用する - TestContainers にポートを自動的に割り当てさせる
4. テスト間でデータをクリーンアップする - 新しいコンテナを使用するか、テーブルを切り捨てる
5. 可能な場合はコンテナを再利用する - テストごとに新しいコンテナを作成するより高速
6. 実際のクエリをテストする - モックだけでなく、実際の SQL 動作を検証する
7. 制約を検証する - 外部キー、一意制約、インデックスをテストする
8. トランザクションをテストする - ロールバックとコミットの動作を検証する
9. 現実的なデータを使用する - 本番に近いデータ量でテストする
10. クリーンアップを処理する - 常に DisposeAsync でコンテナを破棄する

よくある問題と解決策

コンテナ起動のタイムアウト

_container = new TestcontainersBuilder<TestcontainersContainer>()
    .WithImage("postgres:latest")
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilPortIsAvailable(5432)
        .WithTimeout(TimeSpan.FromMinutes(2)))
    .Build();

ポートがすでに使用中

常にランダムなポートマッピングを使用する:

.WithPortBinding(5432, true) // true = ランダムな公開ポートを割り当て

コンテナがクリーンアップされない

適切な破棄を確保する:

public async Task DisposeAsync()
{
    await _connection?.DisposeAsync();
    await _container?.DisposeAsync();
}

CI でテストが失敗するがローカルではパスする

CI に Docker サポートがあることを確認する:

# GitHub Actions
runs-on: ubuntu-latest # Docker がプリインストール済み

CI/CD 統合

GitHub Actions

name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 9.0.x

    - name: Run Integration Tests
      run: |
        dotnet test tests/YourApp.IntegrationTests \
          --filter Category=Integration \
          --logger trx

    - name: Cleanup Containers
      if: always()
      run: docker container prune -f

パフォーマンスのヒント

1. コンテナを再利用する - コレクション内のテスト間でフィクスチャを共有する
2. Respawn を使用する - コンテナを再作成せずにデータをリセットする
3. 並列実行 - TestContainers はポート競合を自動的に処理する
4. 軽量イメージを使用する - Alpine バージョンは小さくて高速
5. イメージをキャッシュする - Docker はプルしたイメージをローカルにキャッシュする