📚 课程目录第2章 Compose UI测试基础

2. Compose UI测试基础：认识ComposeTestRule、ComposeContentTestRule、ActivityScenario与同步机制

2.1 核心组件概览

编写 Compose 界面测试时，有四个核心概念决定了测试的编写方式、运行行为与稳定性：ComposeTestRule、ComposeContentTestRule、ActivityScenario 以及底层同步机制。它们各自负责测试生命周期的不同阶段：内容注入、规则编排、Activity 生命周期管理以及等待界面就绪。

理解这四者的职责与协作关系，是编写可靠 Compose UI 测试的前提。下图展示了它们在一次典型测试中的交互架构：

学习路线提示： 本章依次拆解上图中的每一个组件。建议先通读全章，再回到这张图建立整体认知，后续编写测试时能快速定位每个环节对应的 API。

2.2 ComposeTestRule — 测试的基石

2.2.1 原理与职责

ComposeTestRule 是 Compose UI 测试框架中最核心的入口接口，它负责：

启动一个纯 Compose 内容环境（无需 Activity 或 Fragment）。
提供 setContent 方法注入待测 Composable。
暴露节点查找、断言、交互 API（如 onNodeWithText、assertIsDisplayed）。
管理底层的同步与等待逻辑。

在测试类中通常通过 createComposeRule() 创建实例，并以 JUnit Rule 方式注册：

@get:Rule
val composeTestRule: ComposeTestRule = createComposeRule()

@Test
fun testTextDisplay() {
    composeTestRule.setContent {
        Text(text = "Hello Compose")
    }
    composeTestRule.onNodeWithText("Hello Compose")
        .assertIsDisplayed()
}

2.2.2 常用 API 速查

API	作用	使用场景
`setContent(Composable)`	设置待测 Compose 内容	测试单个 Composable 组件
`onNodeWithText(String)`	按文本查找节点	文本断言 / 点击
`onNodeWithTag(String)`	按 testTag 查找节点	使用 `Modifier.testTag()` 的场景
`waitForIdle()`	等待所有主线程任务完成	异步操作后的同步点
`mainClock`	控制虚拟时钟	动画 / 延迟任务的时间推进
`assertExists()`	断言节点存在	基础存在性验证

2.2.3 使用流程与注意事项

创建规则： 使用 createComposeRule() 创建 纯 JVM 环境 的测试规则，不依赖 Android 设备或 Activity。
注入内容： 在 setContent 中传入待测 Composable，该 lambda 运行在 Compose 作用域内。
查找与交互： 通过语义匹配器（如 onNodeWithText）定位节点，然后执行 assertIsDisplayed、performClick 等操作。
等待同步： 在异步更新后调用 waitForIdle() 确保界面稳定后再断言。

常见错误： 在 setContent 外部直接调用节点查找 API 会导致 IllegalStateException，因为内容尚未初始化。必须在 setContent 之后执行查找。

2.3 ComposeContentTestRule — 自定义内容场景

2.3.1 与 ComposeTestRule 的差异

ComposeContentTestRule 是 ComposeTestRule 的子接口，它在基础规则之上增加了 自定义内容注入控制。典型差异如下：

对比维度	ComposeTestRule	ComposeContentTestRule
内容注入方式	只通过 `setContent`	额外支持 `setContentWithParent` 等自定义父容器
适用场景	简单组件测试	需要自定义 Theme / Parent / 作用域的高级测试
灵活性	低，内容完全由测试决定	高，可封装复用测试环境
实现方式	框架默认实现	通常由开发者继承并实现抽象方法

2.3.2 自定义 ComposeContentTestRule 实现

当测试需要固定的主题、父容器或共享作用域时，可以创建自定义规则：

class MyThemeTestRule : ComposeContentTestRule {

    override fun createComposeContent(): ComposeContent {
        return ComposeContent {
            MyAppTheme {
                // 所有通过 setContent 注入的内容会自动包裹在此主题中
                it()
            }
        }
    }
}

在测试中直接使用该规则，所有 Composable 都会自动应用 MyAppTheme，无需重复书写：

@get:Rule
val myRule = MyThemeTestRule()

@Test
fun testWithCustomTheme() {
    myRule.setContent {
        Text("在自定义主题中渲染")
    }
    myRule.onNodeWithText("在自定义主题中渲染")
        .assertIsDisplayed()
}

最佳实践： 当项目中有统一 Design System 或 Theme 时，抽取 ComposeContentTestRule 子类可大幅减少测试样板代码，并保证环境一致性。

2.4 ActivityScenario — Activity 生命周期管理

2.4.1 作用与原理

ActivityScenario 来自 AndroidX Test，用于在测试中创建、启动、恢复、销毁 Activity，并精准控制其生命周期状态。在 Compose 测试中，当待测界面依赖 Activity 的 setContent 或需要访问 Activity 级别的资源（如 ViewModel、Intent 参数）时，必须使用 ActivityScenario。

通常与 ActivityScenarioRule 配合使用：

@get:Rule
val activityRule = ActivityScenarioRule(MainActivity::class.java)

@Test
fun testActivityComposeContent() {
    activityRule.scenario.onActivity { activity ->
        // 直接操作 Activity 实例
        activity.supportFragmentManager.beginTransaction()
            .add(android.R.id.content, MyFragment())
            .commit()
    }
}

2.4.2 生命周期控制方法

方法	触发事件	典型用途
`moveToState(Lifecycle.State)`	CREATED / STARTED / RESUMED / DESTROYED	模拟后台切换、低内存回收
`onActivity(ActivityAction)`	—	获取 Activity 实例并执行操作
`recreate()`	销毁并重建	测试配置变更（如屏幕旋转）
`launch(Intent)`	启动 Activity	通过特定 Intent 启动

2.4.3 与 Compose 测试的结合

当使用 createAndroidComposeRule() 时，规则内部已经集成了 ActivityScenario 的能力：

@get:Rule
val androidComposeRule = createAndroidComposeRule(MainActivity::class.java)

@Test
fun testAndroidComposeRule() {
    // 自动启动 Activity，且 setContent 会调用 Activity 的 setContent
    androidComposeRule.onNodeWithText("来自Activity")
        .assertIsDisplayed()
}

注意： 在 createAndroidComposeRule 中，setContent 的行为与 createComposeRule 不同——它会将内容设置到 Activity 的 Compose 宿主中，而非独立的测试容器。因此 Activity 的生命周期事件会影响 Compose 内容的可用性。

2.5 同步机制 — 等待与空闲检测

2.5.1 自动同步原理

Compose 测试框架内置了一套自动同步机制，其核心目标是：在执行任何查找或断言之前，确保 Compose 的主线程任务队列、重组队列、动画帧均已处理完毕。该机制通过监控以下条件实现：

主线程 Looper 是否空闲（无待处理 Message）。
Compose 的 recomposition 是否完成。
当前是否有正在运行的动画（Animatable / Animator）。
是否有挂起的 LaunchedEffect 协程。

当所有条件满足时，框架标记为 Idle（空闲），此时才允许执行用户断言。如果超过默认超时（通常 1 秒）仍未空闲，则抛出 WaitForIdleTimeoutException。

2.5.2 手动同步 API

API	行为	阻塞/非阻塞
`waitForIdle()`	阻塞直到主线程空闲或超时	阻塞（同步）
`awaitIdle()`	挂起协程直到空闲	非阻塞（协程）
`mainClock.advanceTimeBy(ms)`	推进虚拟时钟 N 毫秒	阻塞（同步）
`mainClock.autoAdvance`	是否自动推进时钟（默认 false）	配置属性
`waitUntil(timeout, predicate)`	轮询直到条件满足或超时	阻塞（同步）

2.5.3 典型同步场景代码

// 场景1：等待异步数据加载完成
composeTestRule.setContent {
    val viewModel = viewModel()
    Text(text = viewModel.data ?: "加载中")
}
// 假设 viewModel.data 会在 500ms 后更新
composeTestRule.waitUntil(timeout = 2_000) {
    composeTestRule.onNodeWithText("加载中").isNotDisplayed()
}
composeTestRule.onNodeWithText("数据已加载").assertIsDisplayed()

// 场景2：控制动画时钟
composeTestRule.mainClock.autoAdvance = false
composeTestRule.setContent {
    AnimatedVisibility(visible = true) {
        Text("淡入动画")
    }
}
composeTestRule.mainClock.advanceTimeBy(300) // 推进到动画中途
composeTestRule.mainClock.advanceTimeBy(700) // 推进到动画结束
composeTestRule.onNodeWithText("淡入动画").assertIsDisplayed()

核心原则： 任何非 Compose 原生的异步任务（如 Retrofit 网络请求、Room 数据库、自定义 Thread）都不会被自动同步机制识别。必须使用 waitUntil 或 IdlingResource 手动等待。

2.6 常见错误与调试策略

错误现象	根因	解决方案
`IllegalStateException: No content set`	在 `setContent` 之前调用查找 API	确保 `setContent` 在测试方法最前面执行
`WaitForIdleTimeoutException`	异步任务（如网络请求）未完成	使用 `waitUntil` 或模拟异步结果为已知状态
`AssertionError: Node not found`	节点因重组延迟尚未渲染	在断言前增加 `waitForIdle()` 或使用 `waitUntil`
`ActivityNotFoundException`	`ActivityScenarioRule` 的 Activity 未在 Manifest 注册	检查 Manifest 中 Activity 声明以及 exported 属性
动画导致节点位置异常	动画进行中时获取节点偏移	使用 `mainClock.advanceTimeBy` 将动画推进到结束状态

调试技巧

启用测试日志： 在 build.gradle 中设置 android.testInstrumentationRunnerArguments.debug = true 可查看详细同步日志。
使用 printToLog： 调用 composeTestRule.onAllNodes(...).printToLog("TAG") 打印当前节点树，快速定位查找失败原因。
调整超时： 通过 composeTestRule.waitUntil(timeout = 5_000) { ... } 为慢速异步任务设置合理的超时窗口。

稳定性红线： 避免在测试中使用 Thread.sleep() 作为等待手段。这不仅会拖慢测试总耗时，还会在 CI 环境中因设备性能波动产生假阳性失败。始终优先使用 waitUntil 或 IdlingResource。

2.7 本章小结

ComposeTestRule 是所有 Compose UI 测试的起点，掌握 setContent + 节点查找 + waitForIdle 三件套即可覆盖 80% 的测试场景。
ComposeContentTestRule 在需要自定义主题或父容器时提供扩展点，适合中大型项目抽象公共测试环境。
ActivityScenario 管理 Activity 生命周期，在需要 Activity 级资源或测试生命周期切换时使用；createAndroidComposeRule 是更便捷的集成方案。
同步机制 是测试稳定性的关键——自动同步只覆盖 Compose 内部任务，外部异步操作必须手动等待。