Unciv测试自动化：Gradle任务与CI流水线配置

Unciv测试自动化：Gradle任务与CI流水线配置

引言：测试自动化在开源项目中的价值

在开源策略游戏Unciv（Civilization V的开源重制版）的开发过程中，测试自动化是保障代码质量和迭代效率的核心环节。本文将系统剖析Unciv项目的测试架构，重点讲解Gradle测试任务配置与CI流水线实现，帮助开发者快速掌握从本地测试到持续集成的全流程最佳实践。通过本文，你将学习如何：

• 配置多模块项目的Gradle测试任务
• 实现单元测试与集成测试的分离执行
• 构建基于GitHub Actions的自动化测试流水线
• 解析测试覆盖率报告与质量门禁设置

一、项目测试架构概览

Unciv采用模块化架构设计，测试体系遵循"核心逻辑优先"原则，将测试代码与业务代码分离管理。项目测试层次结构如下：

Unciv/
├── core/                # 游戏核心模块（含业务逻辑）
├── tests/               # 测试专用模块
│   └── src/com/unciv/   # 测试代码根目录
│       ├── logic/       # 游戏逻辑单元测试
│       ├── ui/          # UI组件测试
│       └── utils/       # 工具类测试
└── build.gradle.kts     # 根项目构建配置

测试技术栈选型

• 测试框架：JUnit 4（基础测试框架）
• 模拟工具：Mockito 5.13.0（依赖注入与行为验证）
• 构建工具：Gradle 8.9（任务编排与依赖管理）
• CI平台：GitHub Actions（自动化流水线）

二、Gradle测试任务配置详解

2.1 根项目测试配置（build.gradle.kts）

Unciv在根构建脚本中定义了跨模块测试策略，通过project(":tests")块配置测试专用模块：

project(":tests") {
    apply(plugin = "java")
    apply(plugin = "kotlin")

    dependencies {
        "implementation"(project(":core"))  // 依赖核心业务模块
        "implementation"("junit:junit:4.13.2")  // JUnit基础依赖
        "implementation"("org.mockito:mockito-core:5.13.0")  // 模拟框架
        
        // 游戏引擎测试支持
        "implementation"("com.badlogicgames.gdx:gdx-backend-lwjgl3:$gdxVersion")
        "implementation"("com.badlogicgames.gdx:gdx-platform:$gdxVersion:natives-desktop")
    }
}

2.2 测试源集与任务定义

核心模块的构建脚本（core/build.gradle.kts）配置了测试源集：

sourceSets {
    main {
        java.srcDir("src/")
    }
}

虽然未显式定义test任务，但Gradle的Java插件会自动创建标准测试任务，默认行为包括：

• 执行src/test/java下的所有测试类
• 生成测试报告至build/reports/tests/test/
• 在构建生命周期的test阶段运行

2.3 自定义测试任务示例

开发者可通过以下配置扩展测试能力（建议添加至core/build.gradle.kts）：

tasks.test {
    // 启用测试超时（防止无限循环）
    timeout.set(Duration.ofMinutes(5))
    
    // 测试失败后继续执行其他测试
    ignoreFailures = false
    
    // 配置测试报告格式
    reports {
        html.required.set(true)  // 生成HTML报告
        junitXml.required.set(true)  // 生成JUnit XML报告（CI需要）
    }
    
    // 测试覆盖率集成（需添加JaCoCo插件）
    extensions.configure(JacocoTaskExtension::class) {
        destinationFile.set(file("$buildDir/jacoco/test.exec"))
    }
}

三、测试代码组织与最佳实践

3.1 测试文件命名规范

Unciv测试文件遵循[被测试类]Test.kt命名模式，例如：

• GameRulerTest.kt对应GameRuler.kt的单元测试
• CityScreenTest.kt对应UI类CityScreen.kt的组件测试

3.2 典型单元测试示例

class CivilizationTest {
    @Test
    fun `new civilization should start with correct initial resources`() {
        // Arrange
        val civ = Civilization("Rome")
        
        // Act
        val initialGold = civ.gold
        
        // Assert
        assertEquals(50, initialGold, "New civilization should start with 50 gold")
    }

    @Test
    fun `researching technology should unlock correct units`() {
        // Arrange
        val civ = Civilization("Greece")
        val techTree = TechTree()
        
        // Act
        civ.researchTechnology(techTree.getTech("Iron Working"))
        
        // Assert
        assertTrue(civ.units.canBuild("Swordsman"), "Iron Working should unlock Swordsman")
    }
}

3.3 测试数据管理

复杂测试场景采用JSON测试数据文件，存储于tests/src/test/resources目录：

{
  "civName": "Egypt",
  "startingTechs": ["Agriculture", "Mining"],
  "initialResources": {"food": 100, "production": 50}
}

四、CI流水线配置：GitHub Actions实现

4.1 流水线架构概览

Unciv的CI流水线通过.github/workflows/buildAndDeploy.yml实现，测试阶段作为构建流程的关键环节，在代码合并前执行自动化验证：

4.2 测试阶段关键配置

虽然未直接获取到CI配置文件，但根据项目文档，测试阶段配置大致如下：

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      
      - name: Run tests with Gradle
        run: ./gradlew test --no-daemon
      
      - name: Upload test reports
        if: always()  # 即使测试失败也上传报告
        uses: actions/upload-artifact@v3
        with:
          name: test-reports
          path: build/reports/tests/

4.3 测试触发条件

• PR触发：对master分支的所有PR自动运行测试
• 定时触发：每日凌晨执行完整测试套件（含集成测试）
• 发布触发：版本标签推送时执行验收测试

五、本地测试工作流

5.1 常用Gradle测试命令

命令	功能描述
./gradlew test	运行所有模块测试
./gradlew tests:test	仅运行测试模块
./gradlew test --tests *CivilizationTest	运行指定测试类
./gradlew test --info	显示测试执行详细日志
./gradlew cleanTest test	清理旧测试结果后重新测试

5.2 测试问题排查流程

1. 本地复现：

   ./gradlew test --tests *FailingTest
   

2. 查看HTML报告：

   xdg-open core/build/reports/tests/test/index.html  # Linux
   open core/build/reports/tests/test/index.html      # macOS
   

3. 调试单个测试：

   ./gradlew test --tests *FailingTest --debug-jvm
   

六、测试覆盖率与质量门禁

6.1 JaCoCo覆盖率配置

添加至core/build.gradle.kts：

plugins {
    id("jacoco")
}

tasks.jacocoTestReport {
    dependsOn(tasks.test)  // 先运行测试再生成报告
    
    reports {
        html.required.set(true)
        xml.required.set(true)  // 供SonarQube分析
    }
}

执行覆盖率分析：

./gradlew jacocoTestReport
xdg-open core/build/reports/jacoco/test/html/index.html

6.2 质量门禁设置（建议）

在CI流水线中添加质量检查：

- name: Code coverage check
  run: |
    COVERAGE=$(grep -oP 'Total.*?(\d+\.\d+)%' build/reports/jacoco/test/html/index.html | tail -1 | grep -oP '\d+\.\d+')
    if (( $(echo "$COVERAGE < 70" | bc -l) )); then
      echo "Error: Code coverage $COVERAGE% is below 70% threshold"
      exit 1
    fi

七、持续集成流水线深度解析

7.1 GitHub Actions完整工作流

Unciv的CI流水线（.github/workflows/buildAndDeploy.yml）包含以下关键阶段：

7.2 多平台测试策略

Unciv通过矩阵构建实现跨平台测试：

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    java-version: [1.8, 11, 17]
    
steps:
  - name: Set up JDK ${{ matrix.java-version }}
    uses: actions/setup-java@v4
    with:
      java-version: ${{ matrix.java-version }}
      distribution: 'temurin'
  
  - name: Run tests
    run: ./gradlew test

八、测试自动化进阶技巧

8.1 并行测试执行

大型测试套件可通过Gradle配置并行执行：

tasks.test {
    maxParallelForks = if (JavaVersion.current().isJava11Compatible) 4 else 2
}

8.2 测试数据工厂模式

创建可复用的测试数据生成器：

class CivilizationFactory {
    fun createWithTech(techs: List<String>): Civilization {
        return Civilization("Test").apply {
            techs.forEach { researchTechnology(it) }
        }
    }
}

// 在测试中使用
val civ = CivilizationFactory().createWithTech(listOf("Agriculture", "Pottery"))

8.3 集成测试隔离

通过自定义Gradle任务分离集成测试：

sourceSets {
    create("integrationTest") {
        java.srcDir("src/integrationTest/java")
        resources.srcDir("src/integrationTest/resources")
        compileClasspath += sourceSets.main.get().output
        runtimeClasspath += sourceSets.main.get().output
    }
}

val integrationTest = task<Test>("integrationTest") {
    testClassesDirs = sourceSets["integrationTest"].output.classesDirs
    classpath = sourceSets["integrationTest"].runtimeClasspath
    mustRunAfter(tasks.test)  // 确保单元测试先执行
}

tasks.check { dependsOn(integrationTest) }

九、常见问题解决方案

9.1 测试环境不一致

问题：本地测试通过但CI测试失败
解决方案：标准化测试环境，使用Docker容器执行测试：

- name: Run tests in Docker
  run: |
    docker run --rm -v "$PWD":/usr/src/unciv -w /usr/src/unciv openjdk:8-jdk ./gradlew test

9.2 随机失败的测试（Flaky Tests）

解决方案：

1. 添加重试机制：

tasks.test {
    retry {
        maxRetries.set(3)
        maxFailures.set(2)
    }
}

2. 标记不稳定测试：

@Test
@Flaky
fun `time-dependent test that might fail`() {
    // 实现测试...
}

9.3 资源密集型测试处理

解决方案：使用测试分类器隔离重型测试：

tasks.register<Test>("heavyTests") {
    include("**/*HeavyTest.class")
    jvmArgs("-Xmx2g")  // 分配更多内存
    enabled = project.hasProperty("runHeavyTests")  // 需显式启用
}

执行重型测试：

./gradlew heavyTests -PrunHeavyTests

十、总结与未来展望

Unciv的测试自动化体系通过Gradle任务与GitHub Actions的紧密结合，实现了从代码提交到构建验证的全流程自动化。当前测试架构已覆盖单元测试与部分集成测试，但仍有提升空间：

1. 测试类型扩展：

   • 添加UI自动化测试（使用libGDX Testbed）
   • 实现端到端游戏场景测试

2. 测试效率优化：

   • 引入测试优先策略（TDD）
   • 实现智能测试选择（仅运行变更影响的测试）

3. 质量监控增强：

   • 集成SonarQube进行深度代码质量分析
   • 构建测试性能仪表盘

通过持续优化测试自动化流程，Unciv项目将进一步提升代码质量稳定性，为全球玩家提供更可靠的开源游戏体验。

附录：测试资源速查表

常用测试命令

任务	描述
./gradlew test	运行所有单元测试
./gradlew test --tests *UnitTest	仅运行单元测试
./gradlew integrationTest	运行集成测试
./gradlew jacocoTestReport	生成覆盖率报告
./gradlew detekt	静态代码分析

测试目录结构

tests/src/com/unciv/
├── logic/           # 核心游戏逻辑测试
│   ├── CivilizationTests.kt
│   ├── CityTests.kt
│   └── TechTests.kt
├── ui/              # 用户界面测试
│   ├── CityScreenTests.kt
│   └── WorldScreenTests.kt
├── utils/           # 工具类测试
│   └── DistanceCalculatorTests.kt
└── scenarios/       # 游戏场景测试
    ├── ConquestScenarioTest.kt
    └── DiplomacyScenarioTest.kt 

推荐测试库

1. 测试框架：JUnit 5（替代JUnit 4获取更多特性）
2. 断言库：AssertJ（流式断言API）
3. 模拟工具：MockK（Kotlin专用模拟库）
4. 测试数据：JUnitParams（参数化测试支持）

要深入参与Unciv测试开发，可访问项目仓库：

git clone https://gitcode.com/GitHub_Trending/un/Unciv

通过完善测试覆盖和自动化流程，每个贡献者都能为Unciv的质量保障贡献力量，共同打造更稳定、更可靠的开源文明游戏。