Testcontainers .NET C# 完整指南：集成测试实战

在现代软件开发中，集成测试是验证应用程序与外部依赖（如数据库、消息队列、缓存等）交互的关键环节。传统做法要么使用模拟对象（mocks/stubs），无法完全保证代码正确性；要么手动启动测试服务，过程繁琐、速度慢且难以复现。Testcontainers .NET 库从根本上解决了这一问题：它允许你在测试中通过编程方式管理 Docker 容器，为每个测试场景提供轻量、一次性且隔离的运行环境。

Testcontainers 的核心目标是让集成测试变得像单元测试一样简单快捷。你只需在测试中声明需要 PostgreSQL 或 Redis 等服务，库便会自动下载对应 Docker 镜像（若本地不存在）、启动容器、等待服务就绪，并返回连接字符串。测试结束后，容器会自动停止并删除。这确保了测试环境的纯净、无残留，并且可以在任何开发机或 CI 服务器上完全复现。

Testcontainers .NET 是流行 Java 库 Testcontainers 的官方 .NET 移植版本，全面支持 xUnit、NUnit 和 MSTest 等测试框架。它提供了针对大多数主流服务（数据库、NoSQL、队列、Web 服务器）的现成模块，并允许你轻松为任意 Docker 镜像创建自定义容器。使用 Testcontainers .NET 已成为 .NET 社区编写可靠、高质量集成测试的现代标准。

安装指南

安装 Testcontainers .NET 库需使用 NuGet 包管理器。在项目根目录的终端中执行以下命令，或通过 Visual Studio 的包管理器控制台运行：

dotnet add package Testcontainers

该命令将安装核心包 Testcontainers，其中包含基础类和对自定义容器的支持。若需使用特定服务（如 PostgreSQL、MSSQL、Redis），还需安装对应的扩展包，安装方式类似：

dotnet add package Testcontainers.PostgreSql
dotnet add package Testcontainers.Redis
dotnet add package Testcontainers.MsSql
dotnet add package Testcontainers.MongoDb
dotnet add package Testcontainers.RabbitMq

安装完成后，请确保你的机器上已运行 Docker Daemon（Windows/Mac 使用 Docker Desktop，Linux 使用 Docker Engine）。Testcontainers 通过 Docker API 与 Docker 通信。

快速上手：最小化工作示例

下面我们编写一个使用 xUnit 的简单测试，该测试启动 PostgreSQL 容器、创建表、插入数据并验证读取结果。此示例展示了库的基本工作原理。

using Testcontainers.PostgreSql;
using Xunit;
using Npgsql;

namespace MyIntegrationTests;

public class PostgresQuickStartTest : IAsyncLifetime
{
    private PostgreSqlContainer _postgresContainer;

    // IAsyncLifetime 接口用于管理容器的生命周期
    public async Task InitializeAsync()
    {
        // 1. 使用默认配置定义容器
        _postgresContainer = new PostgreSqlBuilder()
            .WithImage("postgres:15-alpine") // 指定镜像
            .WithDatabase("testdb")          // 数据库名称
            .WithUsername("testuser")        // 用户名
            .WithPassword("testpassword")    // 密码
            .Build();