Testcontainers-dotnet 项目中使用 CosmosDB 模拟器镜像的注意事项

在基于 Testcontainers-dotnet 项目进行集成测试时，开发人员可能会遇到 CosmosDB 模拟器镜像过期导致的问题。本文将深入分析这一问题的成因，并提供多种解决方案。

问题现象

当使用 Testcontainers-dotnet 启动 CosmosDB 模拟器容器时，可能会遇到两种典型错误：

1. 端口映射异常：System.InvalidOperationException : Exposed port 8081/tcp is not mapped.
2. 评估期已过：Error: The evaluation period has expired.

这些错误通常发生在开发环境长时间未更新镜像的情况下。

问题根源

CosmosDB 模拟器镜像采用了评估授权机制，每个镜像版本都有固定的有效期。当本地缓存的镜像超过有效期后，就会触发评估期过期的错误。同时，Docker 默认不会自动拉取最新镜像，导致容器启动时使用了过期的本地镜像。

解决方案

方法一：强制拉取最新镜像

最直接的解决方法是删除本地缓存并重新拉取镜像：

docker rmi mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

方法二：使用 Testcontainers 的镜像拉取策略

在代码层面，可以通过配置 Testcontainers 的镜像拉取策略来确保使用最新镜像：

_cosmosDbContainer = new CosmosDbBuilder()
    .WithImage("mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest")
    .WithImagePullPolicy(PullPolicy.Always)
    .Build();

方法三：智能镜像更新策略

对于需要长期维护的项目，可以设置更智能的更新策略，例如仅当本地镜像超过20天时才拉取新镜像：

.WithImagePullPolicy(cachedImage => 
    cachedImage == null || cachedImage.Created < DateTime.Now.AddDays(-20))

最佳实践建议

1. 定期维护：建议在持续集成环境中定期清理和更新测试镜像
2. 版本固定：考虑使用特定版本标签而非latest，以获得更稳定的测试环境
3. 错误处理：在测试代码中加入对评估期过期的检测和处理逻辑
4. 文档记录：在项目文档中明确记录测试依赖的镜像更新策略

总结

Testcontainers-dotnet 与 CosmosDB 模拟器的集成测试中，镜像有效期管理是一个需要特别注意的环节。通过合理配置镜像拉取策略和建立定期维护机制，可以有效避免因镜像过期导致的测试失败问题。开发团队应根据项目实际情况选择最适合的镜像管理策略，确保测试环境的稳定性和可靠性。