gruberma/flapy

Flaky Test Detector Docker镜像文档

镜像概述和主要用途

该Docker镜像旨在通过自动化重新运行测试套件，帮助开发和测试团队识别项目中的不稳定测试（flaky tests）。不稳定测试指在相同代码和环境下，多次运行结果不一致（时而通过时而失败）的测试用例，这类测试会影响CI/CD流程的可靠性和测试结果的可信度。本镜像提供轻量级、可配置的解决方案，支持集成到现有开发和测试流程中。

核心功能和特性

• 自动化重试机制：可配置测试套件的重试次数，自动执行多次测试并记录结果
• 结果分析能力：统计测试用例的通过/失败次数，计算稳定性指标（如通过率波动率）
• 多框架兼容：支持主流测试框架（如JUnit、pytest、Mocha等），无需修改测试代码
• 轻量级设计：基于 Alpine Linux构建，镜像体积小，启动速度快
• 灵活集成：支持命令行参数和环境变量配置，可无缝接入CI/CD管道（如Jenkins、GitHub Actions等）
• 报告生成：输出结构化测试结果报告（JSON/HTML格式），包含不稳定测试详细信息

使用场景和适用范围

适用场景

• CI/CD流程集成：在自动化测试阶段自动检测不稳定测试，避免因flaky tests导致的构建波动
• 测试质量优化：定期对项目测试套件进行稳定性扫描，持续提升测试可靠性
• 本地开发调试：开发人员在提交代码前，本地快速验证测试稳定性
• 测试环境验证：验证新部署的测试环境是否引入测试不稳定性

适用范围

• 支持所有可通过命令行运行测试套件的项目（Java、Python、JavaScript、Go等）
• 兼容基于容器化测试环境的项目
• 适用于需要提升测试套件可信度的中小型团队及大型企业项目

详细使用方法和配置说明

基本使用流程

1. 准备待检测的测试项目目录
2. 配置测试运行命令及重试参数
3. 运行镜像并挂载项目目录
4. 查看生成的测试稳定性报告

Docker Run命令示例

bash
docker run -v /本地项目路径:/app \
  -e TEST_COMMAND="pytest ./tests" \  # 项目测试命令（必填）
  -e RETRY_COUNT=5 \                 # 测试重试次数（默认3次）
  -e REPORT_FORMAT="html" \           # 报告格式（可选：json/html，默认json）
  -e REPORT_PATH="/app/flaky-report" \ # 报告输出路径（默认/app/report）
  flaky-test-detector:latest

Docker Compose配置示例

yaml
version: '3.8'
services:
  flaky-detector:
    image: flaky-test-detector:latest
    volumes:
      - ./my-project:/app                # 挂载本地项目到容器/app目录
      - ./reports:/app/flaky-report      # 持久化存储报告（可选）
    environment:
      - TEST_COMMAND="npm run test"      # Node.js项目测试命令
      - RETRY_COUNT=4                    # 重试4次
      - TEST_TIMEOUT=300                 # 单次测试超时时间（秒，默认300）
      - LOG_LEVEL="debug"                # 日志级别（可选：debug/info/warn/error，默认info）

核心配置参数说明

环境变量配置

测试结果报告说明

报告默认生成在REPORT_PATH目录下，包含以下信息：

• 测试套件基本信息（总测试数、运行时长、重试次数）
• 不稳定测试列表（测试名称、通过次数、失败次数、波动原因分析）
• 稳定性统计数据（整体稳定性百分比、各测试用例稳定性评分）
• 建议操作（针对高频不稳定测试的优化建议）

注意事项

1. 确保挂载的项目目录具有可执行权限，容器内运行用户需有权限读取测试文件并执行测试命令
2. 测试命令需支持非交互模式运行（避免需要人工输入的场景）
3. 对于依赖特定环境的测试（如数据库、外部服务），需通过Docker网络或卷挂载确保依赖可用
4. 首次运行时可能因拉取基础依赖（如测试框架运行时）导致耗时较长，建议提前预热缓存