testcontainers

TestContainers を使用した統合テスト

このスキルを使用するタイミング

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

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

基本原則

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

モックではなく TestContainers を使用する理由

インフラストラクチャのモックに関する問題

// BAD: Mocking a database
public class OrderRepositoryTests
{
    private readonly Mock<IDbConnection> _mockDb = new();

    [Fact]
    public async Task GetOrder_ReturnsOrder()
    {
        // This doesn't test real SQL behavior, constraints, or performance
        _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 を使用する

// GOOD: Testing against a real database
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();

        // Run migrations
        await RunMigrationsAsync(_connection);
    }

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

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

        var repo = new OrderRepository(_connection);

        // Act: Execute against real database
        var order = await repo.GetOrderAsync(1);

        // Assert: Verify actual database behavior
        Assert.NotNull(order);
        Assert.Equal(1, order.Id);
        Assert.Equal("CUST1", order.CustomerId);
        Assert.Equal(100.00m, order.Total);
    }
}

メリット：

• 実際の SQL クエリとデータベースの動作をテストできます
• 制約違反、インデックスの問題、パフォーマンスの問題を検出できます
• マイグレーションが正しく動作することを検証できます
• データアクセス層に対する確かな信頼が得られます

必要な 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="*" /> 
  <PackageReference Include="MySqlConnector" Version="*" /> 

  
  <PackageReference Include="StackExchange.Redis" Version="*" /> 
  <PackageReference Include="RabbitMQ.Client" Version="*" /> 
</ItemGroup>

はじめに

Testcontainers ライブラリは、テスト内で Docker コンテナを管理するためのシンプルな API を提供します。各テストで必要なインフラストラクチャを起動でき、Testcontainers がライフサイクルを自動的に管理します。

リファレンスドキュメント

詳細なパターンと例については、以下のリファレンスファイルを参照してください。

• データベースコンテナ - SQL Server、PostgreSQL、MySQL、マイグレーションのパターン
• メッセージブローカーコンテナ - RabbitMQ、Kafka、Service Bus のパターン
• 高度なパターン - ネットワーク、ボリューム、待機戦略、クリーンアップ、パフォーマンスの最適化

ベストプラクティス

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