📚 课程目录第4章语义树与UI节点查找

语义树与UI节点查找：Compose语义树概念、使用onNodeWithText等查找组件

讲Mock回放，绕不开一个问题：测试代码怎么找到界面上的那个按钮、那个输入框？

你想想看，Compose里没有findViewById这种老朋友了。那自动化测试脚本怎么知道该点哪里？

答案就是——语义树。这是我个人认为Compose测试里最核心、也最容易被忽略的概念。今天我们就把它彻底聊透。

语义树是什么？——说白了就是给UI做“结构化翻译”

语义树，英文叫Semantic Tree。它不是一棵真正的树，而是Compose在运行时自动维护的一份“UI语义结构地图”。

我记得最开始接触UI自动化时，总觉得测试就是“坐标点击”，后来吃了大亏才发现，坐标会变、屏幕尺寸会变，只有语义才靠谱。

Compose框架内部，每个可组合项（Button、Text、TextField等）都会向语义树贡献一个或多个语义节点。这些节点包含：

角色（role）：按钮、文本框、图片
内容（label/text）：文本、描述
状态（state）：选中、禁用、可点击
动作（actions）：点击、滚动、长按

说白了，语义树就是给UI写了一份“使用说明书”，测试框架读这份说明书来操作界面，而不是靠像素坐标猜。

核心点：语义树是Compose测试的“中间人”。你的测试代码不直接碰UI组件，而是通过语义树间接操作。这正是Mock回放能稳定的底层保障。

如何遍历和定位语义节点？——从onNodeWithText说起

定位节点，最常用的就是onNodeWithText()。但我敢打赌，很多人只是简单会用，没深挖过它到底怎么工作的。

// 基本用法：查找包含"登录"文字的节点
composeTestRule.onNodeWithText("登录").performClick()

// 精确匹配（默认是contains，可以改成equals）
composeTestRule.onNodeWithText("登录", substring = false).assertIsDisplayed()

// 用正则匹配
composeTestRule.onNodeWithText("登\\w{1}").assertExists()

我在项目中遇到过一个问题：界面上有两个“确定”按钮，分别在不同的弹窗里。onNodeWithText("确定")会抛异常说找到多个节点。当时排查了半天，最后发现要加useUnmergedTree = true或者配合父节点过滤才行。

小技巧：当文本重复出现时，可以结合onNode(hasText("确定").and(hasParent(hasText("弹窗A"))))来缩小范围。

语义节点查找API全家桶

除了按文本查找，Compose还提供了丰富的查找“武器库”。下表是我整理的主力API：

方法	说大白话就是	我常用的场景
`onNodeWithText()`	按显示文字找	按钮、标签、提示文字
`onNodeWithContentDescription()`	按无障碍描述找	图标按钮、图片
`onNodeWithTag()`	按testTag找	开发标记过的关键组件
`onNode(hasText("xxx"))`	语义条件组合	复杂过滤逻辑
`onAllNodes()`	一次性找全部	验证列表项数量

你可能会问：这么多方法，我该优先用哪个？

我个人习惯优先级是：testTag > contentDescription > text。为什么？因为标签最稳定，不会随国际化翻译而改变。

语义动作——找到节点后能做什么？

找到节点只是第一步。关键是你能对这个节点做什么。大家熟知的performClick()只是冰山一角。

我罗列一下实际工作中高频使用的语义动作：

performClick()——最常用，模拟点击
performScrollTo()——滚动到节点可见
performTextInput()——输入文本
performGesture { swipeLeft() }——手势操作
performImeAction()——模拟键盘动作

// 一段典型的测试流程
composeTestRule.onNodeWithTag("username_input")
    .performTextInput("admin")

composeTestRule.onNodeWithText("登录")
    .performClick()

// 等待新界面出现
composeTestRule.onNodeWithText("欢迎回来")
    .assertIsDisplayed()

嗯，这里要注意：performTextInput()是逐字符输入，而不是直接设置文本。如果有大量文本要填，可以用performTextReplacement()直接替换，效率高得多。

避坑指南：语义树查不到节点怎么办？

我曾经踩过一个坑：自定义组件没设置语义信息，导致onNodeWithText()永远找不到。排查了俩小时，最后发现是自定义Canvas控件没有添加semantics修饰符。

遇到节点查不到，按这个清单排查：

检查组件是否有semantics修饰符
检查是否为自定义可组合项，它可能没有自动继承语义
尝试开启useUnmergedTree = true（默认是合并后的树）
用composeTestRule.onAllNodes()打印所有节点，看看实际有哪些

// 打印整棵语义树，调试神器
composeTestRule.onAllNodes()
    .printToLog("SemanticTree")

自定义语义节点——让所有组件都可测

有些开发觉得：我这是个纯自定义组件，不能语义化，测试测不到算了。这个想法很危险。

其实给自定义组件加语义非常简单，就一行代码的事：

@Composable
fun MyCustomButton(onClick: () -> Unit) {
    Box(
        modifier = Modifier
            .semantics {
                // 定义角色和内容
                role = Role.Button
                contentDescription = "自定义按钮"
                // 标记可点击
                onClick { onClick(); true }
            }
            .clickable(onClick = onClick)
    ) {
        // 你的自绘内容
    }
}

加了语义后，测试代码就能通过onNodeWithContentDescription("自定义按钮")找到它了。

个人建议：团队应该统一约定：所有自定义组件都必须添加语义节点。这就像写代码必须加注释一样，是基本功。

理解语义树分层——为什么有的节点“消失”了？

你可能会发现，某些组件的语义信息在测试中查不到。这往往是因为Compose有“语义树合并”机制。

说白了，父组件和子组件的语义信息默认会合并成一个节点，以减少树的大小。如果你需要精确控制，可以用mergeDescendants = false。

// 禁止子孙节点合并到当前节点
Modifier.semantics(mergeDescendants = false) {
    // 这里定义的语义不会被孩子覆盖
    testTag = "parent_node"
}

我在项目中遇到过：一个Row里面有两个Text，但语义树只暴露了一个合并后的节点。当时查数据怎么也找不到第二个Text，就是因为合并了。后来加上mergeDescendants = false才解决。

总结一下核心要点

语义树是Compose测试的根基。理解了它，你就理解了为什么Mock回放能跨版本执行。再回顾一下关键点：

语义树是Compose自动构建的UI抽象层，不依赖像素坐标
查找节点优先用testTag，然后contentDescription，最后text
学会用semantics修饰符为自定义组件加语义
节点查不到时，试试useUnmergedTree = true或打印整棵树调试

这一套打扎实了，后面讲Mock回放框架时你会觉得特别顺畅。因为本质上，我们就是在操作的这棵语义树。