TestContainers Node 中自定义启动检查策略的正确实现方式

在TestContainers Node项目中，开发者经常需要为容器配置自定义的等待策略以确保容器在测试前已准备就绪。文档中提供的示例代码曾存在一个潜在问题，值得开发者注意。

问题背景

TestContainers Node的等待策略机制允许开发者通过实现StartupCheckStrategy接口来创建自定义的容器启动检查逻辑。在早期版本中，文档示例展示了一个简单的延迟等待策略实现：

class ReadyAfterDelayWaitStrategy extends StartupCheckStrategy {
  async waitUntilReady(container) {
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

然而，在某个版本更新后，StartupCheckStrategy基类被修改为需要接收ContainerRuntimeClient作为构造函数参数。这一变更导致直接使用文档示例代码会抛出"TypeError: Cannot read properties of undefined"错误。

解决方案演进

项目经历了两个阶段的改进：

1. 临时解决方案：开发者需要显式获取容器运行时客户端并传递给策略类：

const client = await getContainerRuntimeClient();
const container = await new GenericContainer("alpine")
  .withWaitStrategy(new ReadyAfterDelayWaitStrategy(client))
  .start();

2. 最终优化：项目维护者意识到客户端参数可以默认获取，于是移除了构造函数参数要求，使文档示例重新变得有效。这一改动简化了API使用方式，保持了向后兼容性。

最佳实践建议

对于需要实现自定义等待策略的开发者，建议：

1. 继承StartupCheckStrategy基类
2. 实现waitUntilReady方法，该方法接收容器实例作为参数
3. 在方法内部实现具体的等待逻辑（如端口检查、HTTP请求或简单延迟）
4. 通过withWaitStrategy方法将策略应用到容器

示例实现：

class HealthCheckWaitStrategy extends StartupCheckStrategy {
  async waitUntilReady(container) {
    const maxAttempts = 10;
    for (let i = 0; i < maxAttempts; i++) {
      if (await this.checkHealth(container)) {
        return;
      }
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
    throw new Error("容器健康检查超时");
  }
  
  async checkHealth(container) {
    // 实现具体的健康检查逻辑
  }
}

总结

TestContainers Node项目通过不断优化API设计，使自定义等待策略的实现变得更加简洁。开发者现在可以放心按照文档示例实现策略类，无需担心运行时客户端注入问题。这一改进体现了项目对开发者体验的重视，也展示了开源项目通过社区反馈持续完善的典型过程。

对于需要更复杂等待逻辑的场景，开发者可以结合多种检查方式（如端口可用性、特定日志输出或HTTP端点响应）来确保容器真正准备就绪，从而提升测试的可靠性。