ljwx-health/ljwx-boot/scripts

LJWX Boot 测试套件

概述

LJWX Boot 测试套件提供全面的自动化测试和可视化报告功能，包括：

• 单元测试 - JUnit 5 测试框架
• 代码覆盖率 - JaCoCo 覆盖率分析
• 可视化报告 - 美观的 HTML 测试报告和摘要
• CI/CD 集成 - Gitea Actions 自动测试流程

快速开始

本地运行测试

# 进入 ljwx-boot 目录
cd ljwx-boot

# 运行测试脚本（推荐）
./scripts/run-tests.sh

# 或者使用 Maven 直接运行
mvn clean test -Ptest -Dspring.profiles.active=test

查看测试报告

运行测试后，会生成以下报告：

1. 可视化测试报告 - target/test-report-visualization.html

   • 汇总测试结果和覆盖率
   • 交互式测试套件展示
   • 美观的可视化图表

2. JaCoCo 覆盖率报告 - ljwx-boot-modules/target/site/jacoco/index.html

   • 详细的代码覆盖率分析
   • 包级别、类级别、方法级别覆盖率
   • 未覆盖代码高亮显示

3. JUnit 原始报告 - ljwx-boot-modules/target/surefire-reports/

   • XML 和文本格式的测试结果

自动打开报告

# 运行测试并自动在浏览器中打开报告
./scripts/run-tests.sh --open

脚本使用

run-tests.sh

测试执行脚本，提供便捷的测试运行和报告生成功能。

语法:

./scripts/run-tests.sh [选项]

选项:

• --skip-clean - 跳过清理旧报告
• --open - 自动打开测试报告
• --help - 显示帮助信息

示例:

# 运行测试并自动打开报告
./scripts/run-tests.sh --open

# 运行测试但保留旧报告
./scripts/run-tests.sh --skip-clean

# 运行测试并自动打开报告，跳过清理
./scripts/run-tests.sh --skip-clean --open

generate-test-report.py

测试报告生成器，从 JUnit 和 JaCoCo 报告生成可视化 HTML 页面。

语法:

python3 scripts/generate-test-report.py [项目根目录]

输出:

• target/test-report-visualization.html - 可视化 HTML 报告
• target/test-summary.json - JSON 格式的测试摘要

示例:

# 在 ljwx-boot 目录中运行
cd ljwx-boot
python3 scripts/generate-test-report.py .

# 从其他目录运行
python3 ljwx-boot/scripts/generate-test-report.py ljwx-boot

CI/CD 集成

Gitea Actions 工作流

项目配置了两个测试相关的工作流：

1. 独立测试工作流（.gitea/workflows/test.yml）

专门用于运行测试的工作流，不涉及构建和部署。

触发条件:

• Push 到 main/develop 分支，且 ljwx-boot 代码有变更
• Pull Request 到 main/develop 分支
• 手动触发（workflow_dispatch）

输出:

• GitHub Actions Summary 显示测试摘要
• 上传测试报告工件（Artifacts），保留 30 天
• 测试失败时 CI 失败

2. CI/CD 主流程（.gitea/workflows/ci-cd.yml）

在构建和部署之前运行测试。

流程:

1. test-boot - 运行测试（前置条件）
2. build-boot - 构建镜像（测试通过后）
3. build-admin - 构建前端镜像
4. build-bigscreen - 构建大屏镜像
5. deploy-to-k8s - 部署到 K8s

特性:

• 测试失败时不会触发构建
• 测试报告作为工件上传，保留 7 天
• 在 Actions 页面可以直接查看测试摘要

查看 CI 测试报告

1. 进入 Gitea 仓库页面
2. 点击 Actions 标签
3. 选择对应的工作流运行
4. 在 Summary 中查看测试摘要
5. 点击 Artifacts 下载详细报告

测试报告内容

测试结果指标

• 总测试数 - 执行的测试用例总数
• 通过数 - 成功通过的测试用例
• 失败数 - 失败的测试用例
• 跳过数 - 被跳过的测试用例
• 成功率 - 通过测试的百分比

代码覆盖率指标

• 行覆盖率 (Line Coverage) - 执行到的代码行百分比
• 分支覆盖率 (Branch Coverage) - 执行到的分支百分比
• 方法覆盖率 (Method Coverage) - 调用到的方法百分比
• 类覆盖率 (Class Coverage) - 测试到的类百分比

覆盖率门槛

项目配置了以下覆盖率门槛（ljwx-boot-modules/pom.xml）：

• 行覆盖率: ≥ 40%
• 分支覆盖率: ≥ 30%
• 类行覆盖率: ≥ 30%

未达到门槛时会有警告，但不会阻止构建（haltOnFailure=false）。

Maven 配置

测试专用 Profile

项目定义了 test profile（pom.xml），用于测试环境：

<profile>
    <id>test</id>
    <properties>
        <env>test</env>
        <maven.test.skip>false</maven.test.skip>
    </properties>
</profile>

使用方法:

mvn test -Ptest -Dspring.profiles.active=test

关键插件

1. maven-surefire-plugin (3.2.5)

   • 运行单元测试
   • 生成 JUnit XML 报告

2. jacoco-maven-plugin (0.8.12)

   • 生成代码覆盖率报告
   • 检查覆盖率门槛
   • 输出 HTML、XML、CSV 格式

3. maven-surefire-report-plugin (3.2.5)

   • 生成 HTML 测试报告

测试最佳实践

编写测试

@SpringBootTest
class UserServiceTest {

    @Autowired
    private UserService userService;

    @Test
    @DisplayName("应该成功创建用户")
    void shouldCreateUserSuccessfully() {
        // Given
        UserDTO userDTO = new UserDTO("test@example.com", "张三");

        // When
        User createdUser = userService.createUser(userDTO);

        // Then
        assertThat(createdUser).isNotNull();
        assertThat(createdUser.getEmail()).isEqualTo("test@example.com");
        assertThat(createdUser.getName()).isEqualTo("张三");
    }
}

测试命名规范

• 测试类: *Test.java 或 *Tests.java
• 测试方法: 使用 @DisplayName 提供清晰的中文描述
• 遵循 Given-When-Then 模式

提高覆盖率

1. 优先测试业务逻辑 - Service 层和 Controller 层
2. 边界条件测试 - 空值、异常情况
3. 集成测试 - 多个组件协同工作
4. Mock 外部依赖 - 使用 Mockito 模拟外部服务

故障排查

问题: 测试报告未生成

可能原因:

• 测试未执行或全部失败
• JaCoCo 插件配置错误

解决方法:

1. 检查 target/surefire-reports/ 目录是否存在
2. 查看 Maven 日志确认测试是否执行
3. 确认 jacoco-maven-plugin 在 pom.xml 中正确配置

问题: Python 脚本执行失败

可能原因:

• Python 3 未安装
• 依赖的 XML 文件不存在

解决方法:

# 检查 Python 版本
python3 --version

# 手动运行脚本查看错误
cd ljwx-boot
python3 scripts/generate-test-report.py .

问题: CI 测试失败

排查步骤:

1. 在 Gitea Actions 页面查看日志
2. 下载测试报告工件查看详细失败信息
3. 本地复现测试：mvn clean test -Ptest
4. 检查测试环境配置（数据库、Redis 等）

相关文件

• 测试脚本: ljwx-boot/scripts/run-tests.sh
• 报告生成器: ljwx-boot/scripts/generate-test-report.py
• Maven 配置: ljwx-boot/pom.xml
• 模块配置: ljwx-boot-modules/pom.xml
• 测试工作流: .gitea/workflows/test.yml
• CI/CD 工作流: .gitea/workflows/ci-cd.yml

支持

如有问题或建议，请联系团队或在项目仓库创建 Issue。