测试环境搭建

Compose UI 测试依赖专用的测试运行库与编译时插件，环境搭建的错误会直接导致测试无法编译或运行。本章覆盖从 Gradle 依赖声明、测试目录创建到模拟器参数设置的完整流程，并提供常见错误的排查路径。

1.1 环境组成原理

Compose UI 测试在 Instrumentation 模式下运行，依赖 ComposeTestRule 控制 Compose 树的渲染与交互。整个环境的组件关系如下：

1.2 添加 Compose UI 测试依赖

在 app/build.gradle 中添加以下依赖（使用 debugImplementation 可避免打包到发布版本）：

android {
    // 必须启用 Compose
    buildFeatures { compose = true }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.4"
    }
}

dependencies {
    // Compose UI 基础（生产版本也需）
    implementation "androidx.compose.ui:ui:1.5.4"
    implementation "androidx.compose.foundation:foundation:1.5.4"
    implementation "androidx.compose.material3:material3:1.1.2"

    // 测试依赖
    debugImplementation "androidx.compose.ui:ui-test-manifest:1.5.4"    // 必须，用于 Activity 注册
    debugImplementation "androidx.compose.ui:ui-test-junit4:1.5.4"      // ComposeTestRule

    // 常规 Instrumentation 测试基础
    androidTestImplementation "androidx.test:runner:1.5.2"
    androidTestImplementation "androidx.test.espresso:espresso-core:3.5.1"
    androidTestImplementation "androidx.test.ext:junit:1.1.5"
}

1.3 配置 Gradle 测试运行器

在 defaultConfig 中设置测试 Instrumentation Runner：

android {
    defaultConfig {
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }
}

1.4 创建测试目录结构

Compose UI 测试属于 Instrumentation 测试（运行在设备上），目录位于 src/androidTest/java/。典型结构如下：

app/
├── src/
│   ├── main/
│   │   ├── java/com/example/app/
│   │   ├── res/
│   │   └── AndroidManifest.xml
│   ├── test/                    # 单元测试（JVM）
│   │   └── java/com/example/app/ExampleUnitTest.kt
│   └── androidTest/             # Instrumentation 测试（设备）
│       └── java/com/example/app/
│           └── MainScreenTest.kt
├── build.gradle.kts
└── ...

1.5 设置模拟器参数

推荐使用 API 29+（Android 10）以上镜像，并启用硬件加速。可通过命令行或 Android Studio 创建模拟器：

# 查看可用系统镜像
sdkmanager --list | grep system-images;android-33

# 创建 AVD（x86_64 架构加速更稳定）
avdmanager create avd -n test_device -k "system-images;android-33;google_apis;x86_64" -d pixel_6

# 启动模拟器
emulator -avd test_device -gpu auto -memory 2048 -cores 2

参数	推荐值	说明
-gpu	auto 或 host	启用 GPU 硬件加速，提升 Compose 渲染速度
-memory	2048 MB	避免 OutOfMemory 错误
-cores	2	模拟多核 CPU，提高测试执行效率
-no-snapshot	（选加）	每次冷启动，避免快照导致的测试状态不纯净

1.6 调试与验证环境

编写一个最简单的空测试，运行以确认环境搭建成功：

// 文件：src/androidTest/java/com/example/app/EnvironmentCheckTest.kt
import androidx.compose.ui.test.junit4.createComposeRule
import androidx.test.ext.junit.runners.AndroidJUnit4
import org.junit.Rule
import org.junit.Test
import org.junit.runner.RunWith

@RunWith(AndroidJUnit4::class)
class EnvironmentCheckTest {

    @get:Rule
    val composeTestRule = createComposeRule()

    @Test
    fun environmentIsReady() {
        // 仅验证 Compose 规则能正常初始化
        composeTestRule.setContent {
            // 空内容，不触发任何 UI 绘制
        }
    }
}

在终端执行：./gradlew :app:connectedDebugAndroidTest。若看到 BUILD SUCCESSFUL 且测试通过，说明环境搭建正确。

1.7 常见错误排查

错误信息	原因	解决方案
Missing compose version / Compiler extension version mismatch	composeOptions 版本与 library 版本不匹配	升级或降级至同一兼容版本
No tests found	测试目录不正确或未添加 @Test 注解	确认文件在 androidTest 目录且方法上有 @Test
java.lang.NoClassDefFoundError: androidx/compose/ui/test/ComposeUiTest	缺少 ui-test-junit4 或 ui-test-manifest	添加 debugImplementation 依赖
Emulator: emulator: ERROR: x86_64 emulation currently requires hardware acceleration!	模拟器未启用 HAXM / Hyper-V	安装 Intel HAXM 或 Windows Hyper-V，或使用 ARM 镜像（较慢）
Test run failed: 'No instrumentation runner found'	未配置 testInstrumentationRunner	在 defaultConfig 中设置 AndroidJUnitRunner

1.8 性能与稳定性优化建议

• 使用 x86 模拟器镜像（而非 ARM），可启用 KVM / Hyper-V 加速，测试执行速度提升 3~5 倍。
• 关闭动画：在模拟器设置中关闭窗口动画、过渡动画，避免 Compose 动画干扰测试断言。
• 复用 AVD 快照：首次启动后保存快照，后续测试使用 -snapshot 参数可减少启动时间。但注意快照可能导致数据库状态残留，若测试需要纯净环境则应使用 -no-snapshot。
• 限制并行度：若同时运行多个模拟器测试，需确保宿主机内存足够（每台模拟器至少 2GB 内存），否则会出现 Emulator crash。
• Gradle 守护进程：保持 org.gradle.daemon=true，避免每次运行测试都重新编译。