4. 基础UI元素匹配：onNodeWithText、onNodeWithTag 等定位组件

4.1 为什么需要精准定位

Compose 测试本质上是「找一个节点，然后对它做点什么」。记住，你不是在跑真机上的点击坐标，而是在虚拟布局树里搜索特定节点。

我刚开始写测试时总习惯用 onNodeWithText 一把梭——因为直观嘛。直到有一次，同一个文本出现在两个不同的弹窗里，测试永远点到了错误的那个。嗯，从那以后我就开始认真思考定位策略了。

定位器（SemanticsMatcher）匹配的是语义树中的节点。每个 Compose 组件都会自动生成语义属性，比如文本、标签、内容描述、角色等。我们的任务就是选一个「足够唯一」的组合去锁定它。

4.2 onNodeWithText：文本匹配的利与弊

这是最常用的定位器，没有之一。它的原理很简单：找语义树里 text 属性等于你传入字符串的那个节点。

// 基础用法
composeTestRule.onNodeWithText("提交").performClick()

// 支持 contains 模糊匹配
composeTestRule.onNodeWithText("提", substring = true).performClick()

遇到的问题：

• 文本国际化后，不同语言的文字不一样，测试代码需要维护多套字符串。
• 同一个页面出现两个相同的文本（比如表格里多行都叫“确定”），会抛出 AmbiguousMatcherException。
• 含有动态拼接文本时，字符串硬编码容易失效。

4.3 onNodeWithTag：语义化测试标签

这是我最推荐的方式。在 Compose 里给组件加上 Modifier.semantics { testTags = ... } 或直接用 Modifier.testTag()，测试侧就通过标签定位，完全不依赖文本。

// Component 定义
Button(
    modifier = Modifier.testTag("btn_submit"),
    onClick = { /* ... */ }
) { Text("提交") }

// Test 代码
composeTestRule.onNodeWithTag("btn_submit").performClick()

优点：

• 与文本解耦，国际化无忧。
• 语义唯一，开发者可以手动保证不重复。
• 布局重构时只要标签不改，测试就不需要动。

缺点：

• 需要开发者额外写标签，团队协作时容易忘记。
• 标签命名规范如果不统一，后期会混乱。

4.4 其他常用定位器

光靠文本和标签有时候还是不够。我把项目中用过的其他定位器整理了一张表：

你想想看，如果测试用例里要找一个列表项里的「删除」按钮，但列表中有多个「删除」，这时候就不能只用文本了。可以用 onNode 加上 hasAnySibling 或者 hasParent 做组合。

composeTestRule
    .onNode(
        hasText("删除") and
        hasParent(hasContentDescription("第1项"))
    )
    .performClick()

4.5 定位策略选择与避坑

说来说去，到底该用哪个？我一般这样决策：

1. 优先用 testTag —— 只要组件有标签，无脑选它。
2. 次选文本匹配 —— 文本唯一且不会变时用，配合 substring 可以应对部分动态变化。
3. 再选 contentDescription —— 图标类、图片类场景。
4. 最后才用层级组合 —— 尽量避免，因为布局一改就失效。

知识体系图：UI元素匹配核心流程