在 C# 项目中做集成测试时，我们往往希望验证代码与真实数据库、消息队列等基础设施的交互，而不是只靠内存实现蒙混过关。TestContainer 是一个基于 Docker 的库，它允许测试代码在运行期间启动真实的容器化依赖，测试结束自动销毁，从而保证环境一致性和可重复性。
一、为什么需要容器化集成测试
传统单元测试通常使用 mocked 对象或轻量内存数据库（如 SQLite 内存模式）来替代真实依赖。这种方式速度快，但无法覆盖 SQL 方言差异、事务隔离级别、索引行为等生产环境特有的细节。例如，EF Core 在 SQLite 上能通过的迁移，在 PostgreSQL 上可能因为类型或函数不支持而失败。
TestContainer 通过 Docker 启动官方镜像，比如 postgres、rabbitmq、redis，使测试运行在和预发环境高度一致的中间件上。每次测试都是全新容器，不残留脏数据，也不需要开发机全局安装这些服务。对于 CI 流水线而言，只要 runner 支持 Docker，就能直接跑通。
二、引入必要的 NuGet 包
在测试项目中，我们需要安装 Testcontainers 的核心库以及对应数据库的专用模块。以 PostgreSQL 为例，添加以下包引用：
<PackageReference Include="Testcontainers.PostgreSql" Version="3.9.0" /> <PackageReference Include="xunit" Version="2.6.6" /> <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.0" /> <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.0" />
其中 Testcontainers.PostgreSql 封装了容器启动逻辑，Npgsql 是 PostgreSQL 的 ADO.NET 与 EF Core 提供器。xUnit 作为测试框架负责生命周期管理。版本号可按实际项目调整，但需注意 Testcontainers 大版本间 API 可能有差异。
安装完成后，建议在测试工程里单独建立一个 Fixture 或基类，统一封装容器初始化，避免每个测试类重复写启动代码。这样也方便后续切换数据库类型或调整镜像标签。
三、编写容器测试基类
下面示例展示如何用 xUnit 的 IAsyncLifetime 接口管理容器启停。测试开始前启动 PostgreSQL 容器，并构造连接字符串；测试结束后释放容器。
using Testcontainers.PostgreSql;
using Xunit;
public class PostgresTestBase : IAsyncLifetime
{
private readonly PostgreSqlContainer _container =
new PostgreSqlBuilder()
.WithImage("postgres:16-alpine")
.WithDatabase("testdb")
.WithUsername("testuser")
.WithPassword("testpass")
.Build();
public string ConnectionString => _container.GetConnectionString();
public async Task InitializeAsync()
{
await _container.StartAsync();
}
public async Task DisposeAsync()
{
await _container.DisposeAsync();
}
}
上面的代码使用 PostgreSqlBuilder 声明镜像与账号信息。WithImage 指定了小体积 alpine 版本，加快拉取速度。StartAsync 会等待容器健康检查通过，因此测试不会连到未就绪的库。
如果你使用 EF Core，可以在子类里基于 ConnectionString 构建 DbContext。由于容器端口是随机映射的，GetConnectionString 会自动替换为宿主机可访问的地址与端口，不需要硬编码。
四、在测试中验证真实查询
继承上面的基类，写一个最小用例：创建表、插入数据、查询并断言。这样能验证从 C# 代码到真实 PG 引擎的整条链路。
using Microsoft.EntityFrameworkCore;
using Xunit;
public class UserContext : DbContext
{
public UserContext(DbContextOptions<UserContext> o) : base(o) { }
public DbSet<User> Users => Set<User>();
}
public class User
{
public int Id { get; set; }
public string Name { get; set; }
}
public class UserTests : PostgresTestBase
{
[Fact]
public async Task InsertAndQuery_Works()
{
var options = new DbContextOptionsBuilder<UserContext>()
.UseNpgsql(ConnectionString)
.Options;
await using var ctx = new UserContext(options);
await ctx.Database.EnsureCreatedAsync();
ctx.Users.Add(new User { Name = "alice" });
await ctx.SaveChangesAsync();
var count = await ctx.Users.CountAsync(u => u.Name == "alice");
Assert.Equal(1, count);
}
}
该测试在运行时会先拉起容器，EF Core 用 EnsureCreatedAsync 建表，再执行插入与查询。因为底层是真实 PostgreSQL，像字符串大小写、jsonb 类型等特性都能被真实检验。
如果团队有多条集成测试并行，Testcontainers 默认会为每个实例启动独立容器，互不干扰。但在资源受限的 CI 上，频繁启停可能拖慢流水线，此时可配合复用容器或集中式服务容器策略优化。
五、常见误区与避坑建议
一个典型错误是在没有 Docker 环境的机器上运行测试，却未配置跳过逻辑，导致本地无法调试。建议在 CI 脚本中确认 Docker 可用，或在无 Docker 时利用环境变量跳过集成测试类。
另一个坑是镜像版本漂移：如果不锁版本，某次 CI 拉取了新 tag 的 PostgreSQL，可能引入不兼容行为。因此 WithImage 应写死小版本，如 postgres:16.2-alpine，并在升级时主动评估。此外，容器启动有耗时，测试项目不宜把这类用例和纯单元测试混在同一频繁执行的集合中，可按目录或特征分组运行。
| 方式 | 环境真实性 | 启动成本 | 适用场景 |
|---|---|---|---|
| Mock 对象 | 低 | 极低 | 纯逻辑单元测试 |
| 内存库 | 中 | 低 | 简单仓储测试 |
| TestContainer | 高 | 中 | 数据库交互集成测试 |
通过合理运用 TestContainer，C# 项目的集成测试能从“形似”走向“神似”，显著降低环境差异带来的线上故障风险。
C#TestContainerintegration_testing修改时间：2026-08-06 23:45:29