ComposeTestRule 核心概念与生命周期：createComposeRule、AndroidComposeTestRule、测试规则的生命周期绑定

1 原理：测试规则的本质与设计意图

ComposeTestRule 是 Compose UI 测试框架中用于控制 Compose 内容渲染、执行异步等待和触发断言的统一入口。它封装了 Activity 或 Compose 宿主容器的生命周期，使得测试代码不需要手动管理界面线程调度。从实现角度看，测试规则是一个 JUnit 的 TestRule，它拦截测试方法的执行，在方法前后自动完成宿主环境（Activity 或 Compose 虚拟宿主）的启动与销毁。

Compose 官方提供了两条实践路径：

测试规则类型	适用场景	依赖 Android 环境	宿主载体
createComposeRule()	纯 Compose 组件单元测试	否（可在 Robolectric/JVM 运行）	虚拟宿主（ComposeScene）
AndroidComposeTestRule	集成测试（需真实 Activity）	是（Instrumentation）	真实 Activity

两条规则共享相同的 ComposeTestRule 接口，因此 setContent、waitForIdle、onNodeWithText 等 API 签名完全一致。这也是“测试夹具隔离”的基础——测试代码不需要关心底层是纯 Compose 还是 Android 环境。

2 核心 API 与生命周期绑定

理解生命周期绑定，必须掌握测试规则在 JUnit 执行流中的“钩子”位置：

1. @Before 方法执行之前：规则启动宿主（Activity 或 ComposeScene），完成组件树初始化。
2. @Before 方法执行：用户可在此处注入 Mock、设置全局状态。
3. 测试方法体 @Test：使用 setContent 加载 Composable，执行交互与断言。
4. @After 方法执行：用户清理 Mock 或资源。
5. @After 方法之后：规则销毁宿主，回收 Compose 树、释放主线程锁。

3 实现流程：从声明到断言

以下是一个规范的两步流程模板。先定义规则，再编写测试方法。

// 纯 Compose 单元测试 —— 不依赖 Android 环境
class MyComposeUnitTest {
    @get:Rule
    val composeTestRule = createComposeRule()

    @Test
    fun testButtonClick() {
        composeTestRule.setContent {
            MyButton(text = "提交")
        }

        composeTestRule.onNodeWithText("提交")
            .performClick()

        composeTestRule.onNodeWithText("已点击")
            .assertIsDisplayed()
    }
}

// Android 集成测试 —— 依赖真实 Activity
class MyAndroidComposeTest {
    @get:Rule
    val composeTestRule = AndroidComposeTestRule<MyActivity>(
        activityRule = ActivityScenario.launch(MyActivity::class.java)
    )

    @Test
    fun testActivityContent() {
        composeTestRule.setContent {
            MyScreen()
        }

        composeTestRule.waitForIdle()
        composeTestRule.onNodeWithTag("header").assertExists()
    }
}

4 调试技巧：规则状态的主动观测

当测试失败表现为“Compose 内容未渲染”或“节点未找到”时，可按以下步骤定位：

• 打印当前 Compose 树快照：composeTestRule.onRoot().printTo(System.out)
• 确认宿主是否正常启动：对于 AndroidComposeTestRule，检查 activityRule.scenario.state 是否为 State.RESUMED
• 超时调整：使用重载 waitForIdle(timeoutMs = 5000) 排除异步延迟干扰
• 规则冲突检测：确保同一个测试类中只有一个 @get:Rule 标注的 ComposeTestRule，多个规则会导致宿主嵌套启动

5 常见错误与解决方案

错误现象	根因	解决方案
“No activity” 异常	AndroidComposeTestRule 未关联 ActivityScenario	使用 AndroidComposeTestRule(ActivityScenario.launch(...)) 构造
“View tree not attached”	setContent 调用时 Activity 已销毁	检查 @After 中是否调用了 finishScenario()；避免在 @Before 中使用 setContent
节点查找超时（1s 不够）	Composable 含有动画或延迟加载	显式指定 waitForIdle(3000)，或使用 useUnrendered = true 参数跳过渲染等待
重复启动 Activity	测试类中同时声明了 @Rule ActivityScenarioRule 和 @Rule ComposeTestRule	移除多余的 ActivityScenarioRule，由 AndroidComposeTestRule 统一管理

6 性能与稳定性优化

• 减少 waitForIdle 调用次数：每调用一次 waitForIdle 会等待至少一个 frame（≈16ms），连续频繁调用会显著拖慢测试套件。可将多个操作放在一个 runOnIdle 块中批量执行。
• 使用 useUnrendered 跳过首次渲染：当只测试点击事件而不需要屏幕截图时，在 setContent 中设置 useUnrendered = true 可跳过 Compose 第一帧渲染，节省 50-100ms。
• 复用 Activity 实例：对于同一 Activity 的多个测试方法，使用 @get:Rule @JvmField val rule = AndroidComposeTestRule(ActivityScenario.launch(...), useActivityAfterTest = true) 避免反复创建和销毁 Activity。

7 生命周期绑定关系图

上图清晰展示了测试规则从 @Before 到 @After 的完整绑定路径：规则先启动宿主，随后测试方法通过 setContent 加载 UI，执行操作和断言，最后在 @After 之后销毁宿主。其中 “规则启动宿主” 和 “规则销毁宿主” 由框架自动完成，开发者只需关注 setContent 与断言逻辑。

8 小结