项目环境搭建：添加 Roborazzi / Paparazzi 依赖、配置 Gradle、Kotlin 版本要求

环境搭建这事儿，说简单也简单，说坑多也是真多。我刚开始搞快照测试时，就觉得加个依赖而已，结果在 Gradle 版本和 Kotlin 兼容性上卡了大半天。嗯，今天咱们就把这块捋清楚，免得你走弯路。

整个搭建逻辑其实就三步：选工具 → 加依赖 → 配 Gradle。下面这张图把核心流程串起来了，你可以先看个全貌。

1. 选工具：Roborazzi 还是 Paparazzi？

这两个是目前 Compose 快照回归测试的主流方案。我个人的建议：如果你主要做 Compose 截图对比，无脑选 Roborazzi；如果项目还涉及传统 View 系统截图，Paparazzi 也许更合适。但不管选哪个，核心流程是一样的。

2. 添加 Roborazzi 依赖

还记得我说过的，第一次加依赖就踩了版本兼容的坑？其实只要按照官方指引走，没啥大问题。我个人习惯把它作为一个独立的 :app 模块的 test 依赖来加，这样不影响主工程。

// 在 app/build.gradle.kts 中
repositories {
    mavenCentral()
    google()
}

dependencies {
    testImplementation("io.github.takahirom.roborazzi:roborazzi:1.12.0")
    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:1.12.0")
    testImplementation("io.github.takahirom.roborazzi:roborazzi-junit5:1.12.0") // 如果你用 JUnit5
    // JUnit 4 用户不需要最后一行
}

3. 添加 Paparazzi 依赖

如果你选了 Paparazzi，依赖方式稍微不一样。它要求你新建一个独立的测试模块（比如 :benchmark 或 :paparazzi），然后在那个模块里配置。

// 新建模块 build.gradle.kts，例如 app/paparazzi/build.gradle.kts
plugins {
    id("com.android.test")
    id("app.cash.paparazzi") version "1.3.1"
}

android {
    namespace = "com.example.paparazzi"
    compileSdk = 34
    targetProjectPath = ":app"
}

dependencies {
    implementation(project(":app"))
    // 其他依赖...
}

我个人更倾向 Roborazzi，因为不用单独建模块，直接在现有 test 目录下就能写测试，省事。但如果你项目对传统 View 截图有很高要求，Paparazzi 的像素级模拟会更稳定。

4. Gradle 配置要点

不管你选哪个工具，Gradle 版本必须满足最低要求。我遇到过同事用 AGP 7.x，结果 Roborazzi 死活跑不起来，后来升级到 AGP 8.0 就正常了。

• Android Gradle Plugin：最低 8.0，推荐 8.2+
• Gradle 版本：7.5 以上，推荐 8.0+
• JVM 目标：项目 Gradle JVM 建议使用 JDK 17

如果你用 Roborazzi，还需要在 build.gradle.kts 中启用 Compose 编译器扩展：

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
    buildFeatures {
        compose = true
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.4" // 需匹配 Kotlin 版本
    }
}

5. Kotlin 版本要求

这可能是最容易出问题的地方。Roborazzi 和 Paparazzi 都对 Kotlin 编译版本有依赖。我自己的项目用的是 Kotlin 1.9.22，搭配 Compose Compiler 1.5.4，目前很稳定。

以下是我总结的版本对应关系，供你参考：

6. 避坑指南（个人血泪史）

写在这儿，你以后遇到类似问题直接对号入座。

• 问题：添加依赖后编译报错 "Unresolved reference: roborazzi"
  原因： Gradle 仓库顺序问题。
  解决：确保 mavenCentral() 写在 google() 之前，或者两个都写。我遇到过只写了 google()，罗博拉兹的包没找到。
• 问题：运行测试时提示 "Native library not found"
  原因：缺少 Android 系统构建设置。
  解决：在 android 块中添加 testOptions.unitTests.isIncludeAndroidResources = true。
• 问题：Paparazzi 截图一片空白
  原因：没有正确配置布局主题。
  解决：在测试类上添加 @Theme(YourAppTheme::class) 注解。