C#中使用TestContainers进行集成测试：最佳实践与常见坑点
想在 .NET 里玩转 TestContainers？这事儿说简单也简单，说麻烦也麻烦。简单在于，它确实能让你用几行代码就拉起一个数据库或中间件进行测试；麻烦在于，从环境配置到代码编写，每一步都有几个“经典”的坑在等着你。今天，咱们就来把这些坑一个个填平。
TestContainers 在 .NET 中不原生支持，得靠 Testcontainers-dotnet
首先得明确一点：TestContainers 的官方“亲儿子”是 Ja va、Go、Node.js 这些语言。在 C# 的世界里，并没有一个官方的 Testcontainers 包。你真正要找的，是社区维护的 Testcontainers-dotnet 项目。这名字听起来就有点“野生”的感觉，对吧？
所以，第一个容易栽跟头的地方就是安装。直接在 NuGet 里搜索 “Testcontainers”，排在前面的很可能就是它，但它的包名其实是 DotNet.Testcontainers —— 对，大小写和命名空间都跟直觉有点出入。
正确的安装命令是：
dotnet add package DotNet.Testcontainers
这里要特别注意，别装错了包。比如别装成那个已经废弃的 Testcontainers，也别误以为 Testcontainers.Xunit 是万能的——它只提供与 xUnit 框架集成的辅助功能，真正的容器管理核心逻辑还在 DotNet.Testcontainers 里。
- 核心依赖：必须引用
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 这类错误。先别急着怀疑自己的代码，十有八九是环境没准备好。
问题根源很简单：TestContainers-dotnet 本质上是通过 Docker 的 API 来操作容器的。如果 Docker 服务没跑起来，或者当前用户没权限访问 Docker 守护进程，那一切就无从谈起。
关键检查点，按顺序来：
- Windows/macOS 用户：确认 Docker Desktop 正在运行，并且最好勾选了“登录时启动 Docker Desktop”这个选项，避免每次重启电脑或终端后都要手动打开。
- Linux 用户：需要将当前用户加入
docker用户组。命令通常是sudo usermod -aG docker $USER，执行后务必退出当前终端会话并重新登录，让组权限生效。之后可以用docker ps命令验证。 - 使用 WSL2 的 Windows 用户：确保 Docker Desktop 设置中勾选了 “Use the WSL 2 based engine”，然后在 WSL 2 的发行版终端里执行
docker info，应该能正常返回信息。 - CI/CD 环境（如 GitHub Actions）：千万别忘了在 workflow 配置中声明
services，或者为 job 指定docker://运行时。这一步漏了，测试跑起来肯定找不到 Docker。
一个实用的建议：在编写测试代码之前，先在命令行里执行一下 docker ps，确保它能正常执行。这比在代码里写一堆重试逻辑要靠谱得多。
容器生命周期管理不当导致端口冲突或资源泄漏
环境搞定了，代码也能跑了，但测试一多或者一并行，问题又来了：端口冲突，或者测试跑完容器没停，吃光内存。这往往是生命周期管理没做好。
很多人会把 ITestcontainer 实例当成普通对象，在构造函数里 new 一个就以为万事大吉。但在并行测试中，多个测试可能同时尝试绑定宿主机同一个端口；测试结束后，如果容器没有正确停止，就会变成“僵尸”容器一直占用资源。
正确的做法是显式、异步地管理容器的生与死：
- 启停必须显式调用：使用
await container.StartAsync()启动容器，测试结束后用await container.StopAsync()显式停止。不要依赖类的析构函数或IDisposable.Dispose()方法（因为Dispose()默认不是异步的，可能无法正确等待容器停止）。 - 利用测试框架的生命周期钩子：在 xUnit 中，可以实现
IAsyncLifetime接口，将容器的启动逻辑放在InitializeAsync方法中，停止逻辑放在DisposeAsync方法中。这样比在每个单独的测试方法[Fact]里重复写启停代码要清晰、安全得多。 - 指定网络和端口：为容器指定唯一的网络别名（
WithNetworkAliases(“pg-test”)）和固定的内部端口绑定（WithPortBinding(5432, true)）。true参数表示绑定到宿主机的一个随机端口，这能有效避免多个测试容器竞争同一个宿主机端口的问题。 - 谨慎共享实例：除非明确使用了 xUnit 的
[Collection]来隔离和共享，否则不要在多个测试类之间共享同一个容器实例。并发执行时，状态很容易混乱。
来看一个更规范的示例片段：
public class DatabaseTests : IAsyncLifetime
{
private readonly Container _postgres;
public DatabaseTests()
{
_postgres = new ContainerBuilder()
.WithImage(“postgres:15”)
.WithEnvironment(“POSTGRES_PASSWORD=password”)
.WithPortBinding(5432, true) // 绑定到宿主机随机端口
.WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsA vailable(5432))
.Build();
}
public async Task InitializeAsync() => await _postgres.StartAsync();
public async Task DisposeAsync() => await _postgres.StopAsync();
}
连接字符串拼接错误：Host 地址不是 localhost
容器启动成功了，测试应用却连不上数据库？这可能是最让人困惑的一个坑。关键在于：从宿主机上的测试进程连接到运行在 Docker 容器内的服务时，连接地址（Host）并不是你想当然的 localhost 或 127.0.0.1。
这里有两个主流方案：
方案一：使用 Docker 提供的特殊域名（推荐用于本地开发）
- 在 Windows 和 macOS 的 Docker Desktop 环境下，容器内可以通过
host.docker.internal这个特殊域名访问宿主机。 - 因此，你的数据库连接字符串中的 Host 部分应该写成
host.docker.internal。同时，端口需要使用容器映射到宿主机的那个随机端口（可以通过容器的GetConnectionString()方法或GetMappedPublicPort(5432)方法获取）。
方案二：让容器和测试进程加入同一网络（更接近生产环境）
- 创建一个自定义的 Docker 网络：
docker network create test-network。 - 启动容器时，使用
WithNetwork(“test-network”)并指定一个网络别名WithNetworkAliases(“pg”)。 - 如果你的测试进程也运行在 Docker 容器内（并加入了同一网络），那么连接字符串的 Host 直接写别名
pg即可。
一个快速的验证方法是：在测试初始化后，输出一下容器的连接字符串看看：Console.WriteLine(await _postgres.GetConnectionString());。
真正的麻烦在 CI 环境，比如 GitHub Actions。它的 ubuntu-latest 运行器里默认没有 host.docker.internal 这个域名。这时候，通常需要回退到使用 Docker 网桥的网关 IP，例如 172.17.0.1，并确保容器的网络模式是 bridge。这就需要为 CI 环境专门准备一套连接字符串的构建逻辑了。
说到底，TestContainers 在 .NET 中的应用，是一套组合拳。打好这套拳，关键不在于记住多少 API，而在于理解 Docker 网络、生命周期以及跨平台差异这些底层概念。把这些理顺了，剩下的就是享受它带来的、接近真实的集成测试便利了。
