jaegertracing/xdock-node

node-crossdock 镜像文档

概述

node-crossdock 是基于 Node.js 环境的集成测试专用镜像，专为跨服务（Cross-Service）集成测试场景设计。该镜像提供了轻量级的 Node.js 运行时环境，并集成了 crossdock 测试框架的核心能力，支持开发者在微服务架构中快速构建、执行跨服务交互的集成测试用例，验证多服务间的接口兼容性、数据流转及业务逻辑正确性。

核心功能与特性

核心功能

• Node.js 环境支持：内置稳定版 Node.js 运行时及 npm 包管理工具，支持使用 JavaScript/TypeScript 编写测试脚本。
• 跨服务测试框架：集成 crossdock 测试框架核心组件，简化多服务间依赖的测试编排。
• 灵活的测试配置：支持通过环境变量、配置文件或命令行参数自定义测试目标、流程及断言规则。
• 多协议支持：原生支持 HTTP、gRPC 等常见服务通信协议的测试模拟与验证。
• 轻量级设计：基于 Alpine Linux 构建，镜像体积小，启动速度快，适合 CI/CD 环境集成。

特性

• 即开即用：无需手动安装 crossdock 依赖，镜像预装核心测试工具链。
• 可扩展测试脚本：支持挂载本地测试脚本目录，灵活适配不同业务场景的测试需求。
• 标准化输出：测试结果支持 JSON/XML 格式输出，便于集成到测试报告工具（如 JUnit）。

使用场景与适用范围

适用场景

• 微服务集成测试：验证多个 Node.js 微服务间的接口调用、数据流转及错误处理逻辑。
• 多语言服务交互测试：作为跨语言微服务架构中的测试客户端，验证 Node.js 服务与其他语言服务（如 Java、Go）的兼容性。
• CI/CD 自动化测试：集成到 Jenkins、GitLab CI 等流程中，在代码合并或部署前自动执行跨服务测试。
• 服务版本兼容性验证：测试不同版本服务间的接口兼容性，避免版本升级导致的集成问题。

适用范围

• 基于 Node.js 开发的微服务项目。
• 需要验证多服务交互逻辑的测试场景。
• 追求轻量化、高可用测试环境的开发/测试团队。

使用方法

基本使用

拉取镜像

bash
docker pull node-crossdock:latest

运行测试容器

基本命令格式：

bash
docker run -it --rm \
  -v /path/to/local/test/scripts:/app/tests \  # 挂载本地测试脚本目录
  -e TARGET_SERVICE_URL="http://service:8080" \  # 目标服务地址
  -e TEST_TIMEOUT=30s \  # 测试超时时间
  node-crossdock:latest \
  npm run test /app/tests  # 执行测试命令（假设测试脚本入口为 /app/tests/index.js）

说明：

• /path/to/local/test/scripts：本地测试脚本目录，需包含 crossdock 测试用例（如使用 mocha、jest 等框架编写的测试文件）。
• 测试命令可根据实际测试框架调整（如 mocha /app/tests、jest /app/tests）。

环境变量配置

Docker Compose 示例

适用于多服务集成测试场景（如测试 node-service 与 db-service 的交互）：

yaml
# docker-compose.test.yml
version: '3.8'

services:
  test-runner:
    image: node-crossdock:latest
    volumes:
      - ./tests:/app/tests  # 挂载本地测试脚本
    environment:
      - TARGET_SERVICE_URL=http://node-service:3000
      - TEST_TIMEOUT=45s
      - CROSSDOCK_LOG_LEVEL=debug
    depends_on:
      - node-service
      - db-service
    command: npm run test /app/tests

  node-service:
    image: your-node-service:latest  # 待测试的 Node.js 服务
    environment:
      - DB_HOST=db-service
      - DB_PORT=5432
    depends_on:
      - db-service

  db-service:
    image: postgres:14-alpine  # 依赖的数据库服务
    environment:
      - POSTGRES_USER=test
      - POSTGRES_PASSWORD=test
      - POSTGRES_DB=test_db

使用方式：

bash
docker-compose -f docker-compose.test.yml up --abort-on-container-exit

测试脚本规范

测试脚本需遵循 crossdock 测试框架的基本规范，典型结构（以 mocha 为例）：

javascript
// /app/tests/integration.js
const { expect } = require('chai');
const axios = require('axios');

describe('Node Service Integration Test', () => {
  const targetUrl = process.env.TARGET_SERVICE_URL;

  it('should return 200 when calling /health', async () => {
    const res = await axios.get(`${targetUrl}/health`);
    expect(res.status).to.equal(200);
    expect(res.data.status).to.equal('ok');
  });

  it('should create user via POST /users', async () => {
    const res = await axios.post(`${targetUrl}/users`, { name: 'test' });
    expect(res.status).to.equal(201);
    expect(res.data.id).to.be.a('string');
  });
});

注意事项

1. 测试脚本依赖：若测试脚本需额外 npm 包（如 axios、chai），建议在本地测试目录中添加 package.json，并通过 volumes 挂载 node_modules 目录（或在镜像构建时预安装）。
2. 网络配置：容器需与目标服务处于同一网络（如通过 docker network 或 docker-compose 自动网络），确保 TARGET_SERVICE_URL 可访问。
3. 资源限制：在 CI 环境中运行时，建议通过 --memory、--cpus 限制容器资源，避免影响其他服务。