测试 Compose Multiplatform UI

Compose Multiplatform 的 UI 测试采用了与 Jetpack Compose 测试 API 相同的查找器、断言、操作和匹配器实现。如果您对其不熟悉，请先阅读 Jetpack Compose 指南，再继续阅读本文。

Compose Multiplatform 测试与 Jetpack Compose 的差异

Compose Multiplatform 通用测试 API 不依赖 JUnit 的 TestRule 类，而是通过调用 runComposeUiTest 函数并在 ComposeUiTest 接收器上执行测试函数。

不过，基于 JUnit 的 API 仍适用于桌面平台目标。

编写与运行 Compose Multiplatform 测试

首先为模块添加测试源集和必要依赖，随后编写并运行示例测试，最后尝试自定义测试。

创建测试源集并添加测试库依赖

为提供具体示例，本页说明遵循 Kotlin Multiplatform 向导生成的项目结构。若您要向现有项目添加测试，可能需要将路径和命令中的 composeApp 替换为实际测试的模块名（例如 shared）。

创建通用测试源集并添加依赖的步骤如下：

创建通用测试源集目录： composeApp/src/commonTest/kotlin。
在 composeApp/build.gradle.kts 文件中添加以下依赖：
kotlin { //... sourceSets { val desktopTest by getting // 添加通用测试依赖 commonTest.dependencies { implementation(kotlin("test")) @OptIn(org.jetbrains.compose.ExperimentalComposeLibrary::class) implementation(compose.uiTest) } // 添加桌面测试依赖 desktopTest.dependencies { implementation(compose.desktop.currentOs) } } }
如需为 Android 运行仪器化（模拟器）测试，需进一步修改 Gradle 配置：
1. 在 androidTarget {} 块中添加以下代码，并按 IDE 提示补全导入：
  kotlin { //... androidTarget { @OptIn(ExperimentalKotlinGradlePluginApi::class) instrumentedTestVariant.sourceSetTree.set(KotlinSourceSetTree.test) //... } //... }
2. 在 android.defaultConfig {} 块中添加：
  android { //... defaultConfig { //... testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" } }
3. 在配置顶层添加：
  //https://developer.android.com/develop/ui/compose/testing#setup dependencies { androidTestImplementation("androidx.compose.ui:ui-test-junit4-android:1.6.8") debugImplementation("androidx.compose.ui:ui-test-manifest:1.6.8") }

完成上述步骤后，即可为 Compose Multiplatform UI 编写和运行通用测试。

编写与运行通用测试

在 composeApp/src/commonTest/kotlin 目录下创建 ExampleTest.kt 文件，并复制以下代码：

import androidx.compose.material.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.testTag
import androidx.compose.ui.test.*
import kotlin.test.Test

class ExampleTest {

    @OptIn(ExperimentalTestApi::class)
    @Test
    fun myTest() = runComposeUiTest {
        // 声明模拟 UI 以演示 API 调用
        //
        // 替换为您自己的声明以测试项目代码
        setContent {
            var text by remember { mutableStateOf("Hello") }
            Text(
                text = text,
                modifier = Modifier.testTag("text")
            )
            Button(
                onClick = { text = "Compose" },
                modifier = Modifier.testTag("button")
            ) {
                Text("Click me")
            }
        }

        // 使用 Compose Multiplatform 测试 API 的断言和操作测试声明 UI
        onNodeWithTag("text").assertTextEquals("Hello")
        onNodeWithTag("button").performClick()
        onNodeWithTag("text").assertTextEquals("Compose")
    }
}

运行测试的方法：

有两种选择：

在 Android Studio 中点击 myTest() 函数旁的行标绿色运行图标，选择运行并指定 iOS 测试目标。
在终端执行命令：
./gradlew :composeApp:iosSimulatorArm64Test

在终端执行：

./gradlew :composeApp:connectedAndroidTest

目前无法通过 android (local) 测试配置运行通用 Compose Multiplatform 测试，因此 Android Studio 的行标图标等工具暂不可用。

有两种选择：

点击 myTest() 函数旁的行标绿色运行图标，选择运行 | desktop。
在终端执行：
./gradlew :composeApp:desktopTest

在终端执行：

./gradlew :composeApp:wasmJsTest

后续步骤

掌握 Compose Multiplatform UI 测试基础后，可进一步探索以下资源：

关于 Kotlin Multiplatform 项目测试的概述，请参阅了解基本项目结构和测试跨平台应用教程。
桌面平台基于 JUnit 测试的配置细节，请见使用 JUnit 测试 Compose Multiplatform UI。
Android Studio 中包括自动化在内的进阶测试方法，请参考官方文档测试应用。

22 四月 2025