原生移动开发 / 系统课时

Compose UI 测试

Compose UI 测试

Compose UI 测试的关键不是按屏幕坐标“点哪里”,而是从语义树中稳定找到节点,再对节点执行输入、点击与断言。本节用一个最小登录表单演示完整测试链路,并说明组件查找失败时如何从语义信息定位问题。

学习目标

  • 理解 Compose 测试如何通过语义树定位组件
  • 使用 performTextInput、performClick 和断言完成交互验证
  • 能在节点匹配失败时检查语义树并选择更稳定的定位方式

测试如何找到 Compose 组件

Compose 测试 API 读取的是 Semantics 语义树。Text、Button、可编辑输入框以及 testTag 等信息会暴露为可查询的语义属性,测试再通过 onNodeWithText、onNodeWithTag 等匹配器获得节点。

Compose UI 测试的语义树定位流程

当文案稳定且唯一时,可以直接按文本查找;当文案会国际化、重复或经常调整时,优先为关键交互节点增加 Modifier.testTag,让测试定位与展示文案解耦。

完成一次输入、点击与断言

下面的示例可放入 app/src/androidTest/java/.../LoginFormTest.kt。它同时定义最小可测界面和测试用例,便于直接观察语义定位、操作与断言之间的关系。

kotlin
package com.example.composeuitest

import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Button
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.testTag
import androidx.compose.ui.test.*
import androidx.compose.ui.test.junit4.createComposeRule
import org.junit.Rule
import org.junit.Test

@Composable
private fun LoginForm() {
    var username by remember { mutableStateOf("") }
    var message by remember { mutableStateOf("") }

    Column {
        OutlinedTextField(
            value = username,
            onValueChange = { username = it },
            label = { Text("用户名") },
            modifier = Modifier.testTag("username")
        )
        Button(
            onClick = { message = "欢迎 $username" },
            enabled = username.isNotBlank()
        ) {
            Text("登录")
        }
        if (message.isNotEmpty()) {
            Text(message)
        }
    }
}

class LoginFormTest {
    @get:Rule
    val composeRule = createComposeRule()

    @Test
    fun inputUsernameAndLogin() {
        composeRule.setContent { LoginForm() }

        composeRule.onNodeWithTag("username")
            .performTextInput("alice")

        composeRule.onNodeWithText("登录")
            .assertIsEnabled()
            .performClick()

        composeRule.onNodeWithText("欢迎 alice")
            .assertExists()
            .assertIsDisplayed()
    }
}

预期结果:输入框接收 alice 后,“登录”按钮变为可用;点击后语义树中出现文本“欢迎 alice”,三个断言全部通过。

项目需启用 Compose instrumentation test,并包含与当前 Compose 版本对齐的 ui-test-junit4 测试依赖;同时需要 Android instrumentation runner;若测试需要宿主 Activity、导航或系统集成,再改用 createAndroidComposeRule。运行当前模块的连接设备测试:

bash
./gradlew connectedDebugAndroidTest

预期输出:

text
> Task :app:connectedDebugAndroidTest
BUILD SUCCESSFUL in <TIME>

<TIME> 会随设备和构建缓存变化;如果模块名或 variant 不同,对应 Gradle 任务名也会不同。

选择稳定的节点匹配方式

onNodeWithText("登录") 直观,但它依赖用户可见文案;onNodeWithTag("username") 更适合输入框、列表项或重复控件等需要稳定标识的位置。无障碍语义本身已经唯一时,也可以用 onNodeWithContentDescription、角色或状态进行匹配。

不要为了测试给每个组件都加 tag。优先复用真实语义,只在文案不稳定、节点重复或组合组件难以可靠定位时增加专用 testTag,这样测试仍然接近用户实际感知到的界面结构。

节点找不到时怎么排查

先确认 setContent 已执行,再检查测试使用的文本、tag 或无障碍描述是否与运行时一致。若节点被父组件合并,可以在查询时尝试 useUnmergedTree = true,但应先理解为什么需要绕过合并语义,而不是把它当成默认选项。

调试时可临时调用 composeRule.onRoot().printToLog("SEMANTICS") 输出语义树,确认目标节点实际暴露了哪些属性。测试通过后应保留稳定的语义定位与业务断言,避免依赖坐标、等待固定毫秒数或实现细节,这样 UI 小幅重构时测试不至于无意义地失效。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Compose UI 测试

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通