cqse/teamscale-jacoco-agent

Teamscale JaCoCo Agent Docker镜像

镜像概述

Teamscale JaCoCo Agent Docker镜像是一个基于JaCoCo框架的代码覆盖率代理工具容器化实现，旨在收集Java应用程序的代码覆盖率数据，并支持与Teamscale平台集成以进行代码质量分析。该镜像提供了便捷的部署方式，适用于开发调试和CI/CD流程，帮助开发团队实时监控代码覆盖率情况。

核心功能与特性

• 代码覆盖率数据收集：基于JaCoCo实现Java类的instrumentation，收集分支、行级等多维度覆盖率数据
• Teamscale平台集成：支持将收集的覆盖率数据上传至Teamscale，实现代码质量可视化与报告生成
• 灵活配置支持：通过属性文件（jacocoagent.properties）自定义上传参数、覆盖率采集范围等配置
• 本地调试能力：提供IDE（如IntelliJ）调试支持，包含示例应用与调试配置，便于代理功能验证
• 容器化部署：支持Docker环境快速部署，同时提供本地构建脚本满足定制化需求

使用场景与适用范围

• 开发环境覆盖率分析：本地开发阶段对Java应用进行覆盖率测试，辅助调试与单元测试优化
• CI/CD流程集成：嵌入持续集成流水线，自动化收集测试阶段覆盖率数据并上传至Teamscale
• Teamscale用户生态：为使用Teamscale平台的团队提供标准化的覆盖率数据采集工具
• 代理开发调试：供开发人员调试JaCoCo代理功能，定制化覆盖率采集逻辑

使用方法与配置说明

镜像获取

官方镜像下载

通过Docker Hub获取预构建镜像：

bash
docker pull cqse/teamscale-jacoco-agent:<tag>

具体标签版本可参考https://hub.docker.com/r/cqse/teamscale-jacoco-agent/tags/

本地镜像构建

如需自定义构建，执行以下命令：

bash
docker build -f agent/src/docker/Dockerfile .

配置说明

代理核心配置通过jacocoagent.properties文件实现，包含覆盖率数据上传至Teamscale的必要参数（默认注释，可根据需求启用）。配置示例位于项目的sample-debugging-app/jacocoagent.properties，关键配置项包括：

• Teamscale服务器地址与端口
• 项目ID与认证令牌
• 数据上传触发条件（如周期、阈值）

运行示例

镜像运行需挂载配置文件并指定目标Java应用。详细运行参数与示例可参考官方文档：https://github.com/cqse/teamscale-jacoco-agent/blob/master/agent/README.md

开发与调试指南

本地开发环境配置

构建项目

• IDE导入：作为Gradle项目导入Eclipse/IntelliJ
• 命令行构建：执行./gradlew assemble生成构件
• 调试配置：IntelliJ提供SampleApp运行配置，可直接调试内置sample-debugging-app

调试注意事项

• 调试时需禁用shadow jar的包重定位（避免IDE代码与jar包中包名不一致）
• 配置文件sample-debugging-app/jacocoagent.properties需根据调试需求调整（如启用上传配置）
• 若出现IllegalStateException: Cannot process instrumented class错误，需在IntelliJ设置中配置"Build and run using: IntelliJ IDEA"（路径：Settings -> Build, Execution, Deployment -> Build Tools -> Gradle）

Gradle插件调试

1. 版本准备：更新build.gradle与BuildVersion.kt中的插件版本号
2. 本地发布：执行./gradlew publishToMavenLocal将插件部署至本地Maven仓库
3. 项目集成：在目标Gradle项目中配置mavenLocal()仓库并依赖该插件版本
4. 调试构建：
   • 构建调试：./gradlew --no-daemon -Dorg.gradle.debug=true，通过IntelliJ"Run > Attach to Process"附加调试器
   • 测试引擎调试：./gradlew --no-daemon --debug-jvm，在测试阶段启动时附加调试器

贡献与发布流程

贡献指南

• 提交变更前需创建JIRA issue记录需求
• 通过Pull Request提交代码，确保完成"Definition of Done" checklist
• 提交前需修复Teamscale项目中的所有代码规范问题

发布流程

1. 版本准备：
   • 更新https://github.com/cqse/teamscale-jacoco-agent/blob/master/CHANGELOG.md%EF%BC%8C%E5%B0%86%22Next release"内容迁移至新版本（如21.3.0）
   • 更新build.gradle中的appVersion版本号
2. 提交与标签：提交版本更新并创建同名GitHub Release标签
3. 构建与发布：标签构建通过GitHub Actions自动执行，完成后通知Slack #release-crew频道进行Maven Central发布（通过Sonatype Staging Repository）

版本号遵循语义化版本规范，所有发布二进制文件托管于GitHub Releases，建议生产环境仅使用官方发布版本。