jaegertracing/xdock-java

java-crossdock 镜像文档

一、镜像概述

java-crossdock 是一款专为 Java 应用集成测试设计的 Docker 镜像，基于 Crossdock 测试框架构建。该镜像提供标准化的测试环境与工具链，支持开发者对 Java 应用（尤其是分布式、微服务架构中的组件）进行跨服务、跨依赖的集成测试验证，简化测试环境配置流程，提升测试效率。

二、核心功能与特性

1. 集成测试支持

• 内置 Crossdock 测试框架核心组件，支持 Java 应用的跨服务交互测试场景（如 API 调用、消息传递、数据一致性验证等）。
• 提供测试用例模板与执行入口，可直接对接 Java 测试代码（如 JUnit、TestNG 用例）。

2. 标准化环境

• 基于官方 Java 基础镜像（支持 Java 8/11/17 等 LTS 版本），确保测试环境一致性。
• 可选轻量级变体（如基于 eclipse-temurin:${JAVA_VERSION}-alpine），减少镜像体积。

3. 灵活配置能力

• 支持通过环境变量动态调整测试参数（如超时时间、目标服务地址、重试策略等）。
• 提供测试结果输出接口（如日志、JSON 报告），便于 CI/CD 流程集成。

4. 工具链集成

• 预装常用测试工具（如 curl、wget、jq），支持网络请求模拟与响应解析。
• 兼容主流 CI/CD 平台（Jenkins、GitLab CI、GitHub Actions），可直接作为测试步骤集成到流水线中。

三、使用场景与适用范围

1. 微服务架构测试

• 验证 Java 微服务间的接口调用、数据流转正确性（如服务 A 调用服务 B 后的状态同步）。
• 模拟分布式场景下的异常情况（如网络延迟、依赖服务不可用），测试应用容错能力。

2. CI/CD 自动化测试

• 在代码提交或部署前，通过 java-crossdock 镜像自动执行集成测试用例，拦截潜在跨服务兼容性问题。
• 配合 Docker Compose 编排被测服务（如数据库、缓存、消息队列）与测试容器，实现端到端测试。

3. 多环境一致性验证

• 在开发、测试、预发布等环境中复用相同的 java-crossdock 配置，确保测试结果不受环境差异影响。

四、使用方法与配置说明

1. 基础使用（docker run）

通过 docker run 命令启动测试容器，指定测试目标服务地址与必要参数：

bash
docker run -d \
  --name java-crossdock-test \
  -e TEST_TARGET_URL="http://service-a:8080/api/v1" \  # 被测服务地址
  -e JAVA_VERSION="11" \                              # Java 版本（可选，默认 11）
  -e TEST_TIMEOUT="30s" \                             # 测试超时时间（默认 30s）
  -v $(pwd)/test-cases:/app/test-cases \               # 挂载本地测试用例目录
  java-crossdock:latest

2. Docker Compose 集成示例

在微服务测试场景中，可通过 docker-compose.yml 编排被测服务与 java-crossdock 测试容器，实现多服务联动测试：

yaml
version: '3.8'

services:
  # 被测服务（示例：Java 微服务 service-a）
  service-a:
    image: my-java-service:latest
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=test

  # 测试容器（java-crossdock）
  crossdock-test:
    image: java-crossdock:latest
    depends_on:
      - service-a  # 等待被测服务启动完成
    environment:
      - TEST_TARGET_URL="http://service-a:8080/api/v1"  # 被测服务内部访问地址
      - TEST_CASES_PATH="/app/test-cases"                # 测试用例存放路径
      - LOG_LEVEL="INFO"                                 # 日志级别（默认 INFO）
    volumes:
      - ./local-test-cases:/app/test-cases  # 挂载本地测试用例（如 JUnit 测试类）
    command: ["java", "-jar", "/app/crossdock-runner.jar", "--cases", "${TEST_CASES_PATH}"]

3. 核心配置参数（环境变量）

4. 测试结果输出

测试执行完成后，结果默认通过标准输出（STDOUT）打印，格式如下：

[INFO] Test Summary:
[INFO] Total Cases: 5
[INFO] Passed: 4
[INFO] Failed: 1
[INFO] Failed Case: TestUserCreation (Reason: Timeout connecting to service-a)

如需结构化报告，可通过 -e REPORT_PATH="/app/report.json" 指定 JSON 报告输出路径，报告内容包含测试用例详情、耗时、错误堆栈等信息。

五、注意事项

1. 测试用例格式：挂载的测试用例需符合 Crossdock 规范（如继承 CrossdockTestCase 基类，实现 run() 方法），或通过 -e CUSTOM_RUNNER="true" 启用自定义测试执行器。
2. 网络配置：在 Docker Compose 场景中，确保测试容器与被测服务在同一网络（默认 bridge 网络），或通过 networks 字段显式指定自定义网络。
3. 资源限制：根据测试复杂度调整容器资源（如 --memory=2g --cpus=1），避免因资源不足导致测试超时。