TestContainers Node v11.0.0 重大版本更新解析

TestContainers 是一个流行的开源测试工具库，它允许开发者在测试环境中轻松启动和管理 Docker 容器。TestContainers Node 是该项目的 Node.js 实现版本，特别适合 JavaScript/TypeScript 开发者进行集成测试。最新发布的 v11.0.0 版本带来了一系列重要变更，本文将深入解析这些变化及其对开发者的影响。

核心变更概述

v11.0.0 版本是 TestContainers Node 的一个重大更新，主要包含以下几个方面的改进：

1. Node.js 版本要求提升：最低支持版本提高到 Node.js 20，这意味着开发者需要确保他们的开发环境已经升级到这个版本或更高。

2. 默认容器镜像移除：所有模块不再提供默认容器镜像，开发者需要显式指定要使用的镜像版本。

3. Docker Compose v1 支持移除：由于 Docker Compose v1 已于 2023 年 7 月停止维护，新版本不再支持。

4. API 变更：包括容器停止超时单位的变更、EventStoreDB 重命名为 KurrentDB 等。

详细变更解析

1. Node.js 版本要求提升

TestContainers Node v11.0.0 将最低 Node.js 版本要求提高到 20。这一变更反映了现代 JavaScript 生态系统的演进趋势，同时也确保了项目能够利用最新的语言特性和性能优化。

对于仍在使用旧版本 Node.js 的项目，升级到 Node.js 20 是必要的。Node.js 20 带来了许多改进，包括但不限于：

• 更稳定的性能表现
• 改进的模块系统
• 增强的安全特性
• 更好的 TypeScript 支持

2. 默认容器镜像移除

这一变更是 v11.0.0 中最显著的变化之一。在此之前，TestContainers Node 为每个支持的数据库或服务提供了默认的容器镜像。例如，PostgreSQL 容器会默认使用 postgres:13.3-alpine 镜像。

现在，开发者需要显式指定要使用的镜像版本：

// 旧版本
await new PostgreSqlContainer().start();

// 新版本
await new PostgreSqlContainer("postgres:13.3-alpine").start();

这一变更带来了几个好处：

1. 版本控制更明确：开发者可以清楚地知道他们正在使用哪个版本的数据库或服务。
2. 减少意外升级：避免因为 TestContainers 更新默认镜像版本而导致测试行为变化。
3. 安全性提升：开发者可以主动选择经过安全审计的镜像版本。

对于需要迁移的项目，可以参考项目文档中提供的旧版本默认镜像列表进行迁移。

3. Docker Compose v1 支持移除

随着 Docker Compose v1 的生命周期结束，TestContainers Node v11.0.0 移除了对它的支持。这意味着：

• 开发者需要确保他们的环境使用的是 Docker Compose v2
• 相关 API 也进行了清理，不再提供 Compose 版本信息

4. API 变更

v11.0.0 引入了几项重要的 API 变更：

容器停止超时单位变更

停止容器的超时参数从秒变为毫秒：

// 旧版本 - 10秒
await container.stop({ timeout: 10 });

// 新版本 - 10秒(10000毫秒)
await container.stop({ timeout: 10_000 });

这一变更提供了更精细的超时控制，与其他 JavaScript API 的时间参数单位保持一致。

EventStoreDB 重命名为 KurrentDB

由于上游项目的品牌变更，相关容器类也进行了重命名：

// 旧版本
import { EventStoreDBContainer } from "@testcontainers/eventstoredb";

// 新版本
import { KurrentDbContainer } from "@testcontainers/kurrentdb";

端口生成器变更

RandomUniquePortGenerator 被更简单的 RandomPortGenerator 取代，简化了端口分配逻辑。

迁移建议

对于计划升级到 v11.0.0 的项目，建议采取以下步骤：

1. 升级 Node.js：确保开发环境和 CI 环境都使用 Node.js 20 或更高版本。

2. 显式指定容器镜像：查找所有使用默认镜像的测试用例，添加具体的镜像标签。

3. 更新超时参数：检查所有 container.stop() 调用，将秒单位转换为毫秒。

4. 重命名 EventStoreDB 引用：如果项目中使用 EventStoreDB，更新导入和实例化代码。

5. 验证 Docker Compose 版本：确保环境使用的是 Docker Compose v2。

总结

TestContainers Node v11.0.0 是一个重要的里程碑版本，它通过移除默认镜像、提高 Node.js 版本要求等变更，推动了项目向更明确、更安全的未来发展。虽然这些变更需要开发者进行一定的迁移工作，但它们带来的长期收益是值得的：更清晰的依赖管理、更好的安全性和更一致的 API 设计。

对于新项目，建议直接采用 v11.0.0 或更高版本。对于现有项目，可以按照本文提供的迁移建议逐步升级。TestContainers Node 团队在做出这些变更时已经考虑了向后兼容性，使得迁移过程尽可能平滑。