c#如何使用TestContainers集成测试_c#TestContainers集成测试的最佳实践与常见坑点-C#.Net教程-PHP中文网

TestContainers 在 .NET 中需使用社区库 DotNet.Testcontainers（非官方），安装命令为 dotnet add package DotNet.Testcontainers；必须运行 Docker Desktop（Linux 需加入 docker 组），容器启动需显式调用 StartAsync/StopAsync，连接时 Host 应用 host.docker.internal（CI 用 172.17.0.1）。

c#如何使用testcontainers集成测试_c#testcontainers集成测试的最佳实践与常见坑点

TestContainers 在 .NET 中不原生支持，得靠 Testcontainers-dotnet

TestContainers 官方库只支持 Java、Go、Node.js 等语言，Testcontainers（注意大小写）在 C# 里不是官方项目，而是社区维护的 Testcontainers-dotnet。直接 NuGet 搜索 Testcontainers 会找到它，但包名是 DotNet.Testcontainers —— 这是第一个容易装错的地方。

正确安装方式：

dotnet add package DotNet.Testcontainers

别装成 Testcontainers（已废弃）或 Testcontainers.Xunit（仅提供 xUnit 集成，不包含核心容器逻辑）。

必须引用 DotNet.Testcontainers 才能创建和管理容器
Testcontainers.Xunit 可选，仅当你用 xUnit 且想用 [CollectionDefinition] 共享容器时才需要
.NET 6+ 是硬性要求；.NET Framework 不支持

启动 PostgreSQL 容器失败：Docker Desktop 未运行或权限不足

最常见报错是 Unable to connect to Docker daemon 或 Docker API responded with status code=NotFound，本质不是代码问题，而是环境没就绪。

关键检查点：

Docker Desktop 必须正在运行（Windows/macOS），且“Start Docker Desktop when you log in”已启用
Linux 用户需确认当前用户在 docker 组中：sudo usermod -aG docker $USER，然后重新登录终端
若用 WSL2，确保 Docker Desktop 的 “Use the WSL 2 based engine” 已勾选，并在 WSL 内执行 docker info 能返回结果
避免在 CI（如 GitHub Actions）中漏掉 services 声明或 docker:// runtime

代码里别依赖“自动重试”，先确保 docker ps 能跑通再写测试。

容器生命周期管理不当导致端口冲突或资源泄漏

很多人把 ITestcontainer 当作普通对象 new 出来就完事，结果测试并行跑时抢同一个端口，或测试结束后容器还在后台运行。

"避开 C# 常见错误——空陷阱、异步陷阱、LINQ 陷阱及资源泄漏。"

下载

正确做法：

用 await container.StartAsync() 启动，await container.StopAsync() 显式停止 —— 不要依赖析构函数或 IDisposable 的 Dispose（它不 await）
在 xUnit 中，用 IAsyncLifetime 接口统一管理启停，而非在每个 [Fact] 里重复写
为容器指定唯一网络别名（WithNetworkAliases("pg-test")）和固定内部端口（WithPortBinding(5432, true)），避免宿主机端口随机分配引发不稳定
测试类之间不要共享单个容器实例（除非明确用了集合隔离），否则并发执行会出错

示例片段：

public class DatabaseTests : IAsyncLifetime
{
  private readonly Container _postgres;
<p>public DatabaseTests()
{
_postgres = new ContainerBuilder()
.WithImage("postgres:15")
.WithEnvironment("POSTGRES_PASSWORD=password")
.WithPortBinding(5432, true)
.WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(5432))
.Build();
}</p><p>public async Task InitializeAsync() => await _postgres.StartAsync();
public async Task DisposeAsync() => await _postgres.StopAsync();
}</p>