测试多平台应用 − 教程
本教程使用 IntelliJ IDEA,但您也可以在 Android Studio 中进行操作——两款 IDE 具有相同的核心功能和 Kotlin Multiplatform 支持。
在本教程中,您将学习如何在 Kotlin Multiplatform 应用程序中创建、配置和运行测试。
多平台项目的测试可以分为两类:
- 通用代码测试。此类测试可以使用任何受支持的框架在任何平台上运行。
- 平台特定代码测试。这对于测试平台特定逻辑至关重要。它们使用平台特定的框架,并可以受益于其附加功能,例如更丰富的 API 和更广泛的断言。
多平台项目对这两类测试均提供支持。本教程将首先向您展示如何在简单的 Kotlin Multiplatform 项目中设置、创建并运行通用代码的单元测试。随后,您将处理一个更复杂的示例,该示例需要针对通用代码和平台特定代码同时编写测试。
测试简单的多平台项目
创建项目
在 IntelliJ IDEA 中,选择 File | New | Project。
在左侧面板中,选择 Kotlin Multiplatform。
在 New Project 窗口中指定以下字段:
- Name:KMP testing
- Project ID:kmp.project.testing
选择 Android 目标。 如果您使用的是 Mac,也请选择 iOS。请务必选择 Do not share UI 选项。
取消选中 Include tests 并点击 Create。

编写代码
在 sharedLogic/src/commonMain/kotlin 目录下,创建一个新的 common.example.search 软件包。 在此软件包中,创建包含以下函数的 Kotlin 文件 Grep.kt:
fun grep(lines: List<String>, pattern: String, action: (String) -> Unit) {
val regex = pattern.toRegex()
lines.filter(regex::containsMatchIn)
.forEach(action)
}该函数的设计类似于 UNIX grep 命令。在这里,该函数接受多行文本、一个用作正则表达式的模式,以及一个每当某行匹配该模式时调用的函数。
添加测试
现在,我们来测试通用代码。关键部分是用于通用测试的源集,它将 kotlin.test API 库作为依赖项。
在
sharedLogic/build.gradle.kts文件中,检查是否存在对kotlin.test库的依赖项:kotlinsourceSets { //... commonTest.dependencies { implementation(libs.kotlin.test) } }commonTest源集用于存储所有通用测试。您需要在项目中创建一个同名目录:- 右键点击
sharedLogic/src目录并选择 New | Directory。IDE 将显示选项列表。 - 开始键入
commonTest/kotlin路径以缩小选择范围,然后从列表中选择该项:

- 右键点击
在
commonTest/kotlin目录下,创建一个新的common.example.search软件包。在此软件包中,创建
Grep.kt文件并使用以下单元测试进行更新:kotlinimport kotlin.test.Test import kotlin.test.assertContains import kotlin.test.assertEquals class GrepTest { companion object { val sampleData = listOf( "123 abc", "abc 123", "123 ABC", "ABC 123" ) } @Test fun shouldFindMatches() { val results = mutableListOf<String>() grep(sampleData, "[a-z]+") { results.add(it) } assertEquals(2, results.size) for (result in results) { assertContains(result, "abc") } } }
如您所见,导入的注解和断言既不针对特定平台,也不针对特定框架。 稍后运行此测试时,平台特定的框架将提供测试运行程序。
探索 kotlin.test API
kotlin.test API kotlin.test 库提供了与平台无关的注解和断言,供您在测试中使用。诸如 Test 之类的注解会映射到所选框架提供的注解或其最接近的对等项。
断言通过 Asserter 接口的实现来执行。该接口定义了测试中通常执行的各种检查。该 API 拥有一个默认实现,但通常情况下您将使用特定于框架的实现。
例如,JVM 上支持 JUnit 4、JUnit 5 和 TestNG 框架。在 Android 上,调用 assertEquals() 可能会导致调用 asserter.assertEquals(),其中 asserter 对象是 JUnit4Asserter 的实例。而在 iOS 上,Asserter 类型的默认实现会与 Kotlin/Native 测试运行程序结合使用。
运行测试
您可以通过以下方式执行测试:
- 使用装订区域中的 Run 图标运行
shouldFindMatches()测试函数。 - 使用测试文件的上下文菜单运行该测试文件。
- 使用装订区域中的 Run 图标运行
GrepTest测试类。
还可以使用便捷的 ⌃ ⇧ F10/Ctrl+Shift+F10 快捷键。 无论选择哪种方式,您都会看到用于运行测试的目标列表:

对于 android 选项,测试使用 JUnit 4 运行。对于 iosSimulatorArm64,Kotlin 编译器会检测测试注解并创建一个测试二进制文件,该文件由 Kotlin/Native 自带的测试运行程序执行。
以下是成功运行测试所生成的输出示例:

处理更复杂的项目
为通用代码编写测试
您已经通过 grep() 函数为通用代码创建了测试。现在,让我们考虑使用 CurrentRuntime 类进行更高级的通用代码测试。该类包含执行代码所在平台的详细信息。 例如,对于在本地 JVM 上运行的 Android 单元测试,它可能包含值“OpenJDK”和“17.0”。
应使用平台的名称和版本字符串来创建 CurrentRuntime 的实例,其中版本是可选的。当存在版本时,如果可用,您只需提取字符串开头的数字部分。
在
commonMain/kotlin目录下,创建一个新的org.kmp.testing软件包。在此软件包中,创建
CurrentRuntime.kt文件并使用以下实现进行更新:kotlinclass CurrentRuntime(val name: String, rawVersion: String?) { companion object { val versionRegex = Regex("^[0-9]+(\\.[0-9]+)?") } val version = parseVersion(rawVersion) override fun toString() = "$name version $version" private fun parseVersion(rawVersion: String?): String { val result = rawVersion?.let { versionRegex.find(it) } return result?.value ?: "unknown" } }在
commonTest/kotlin目录下,创建一个新的org.kmp.testing软件包。在此软件包中,创建
CurrentRuntimeTest.kt文件并使用以下与平台及框架无关的测试进行更新:kotlinimport kotlin.test.Test import kotlin.test.assertEquals class CurrentRuntimeTest { @Test fun shouldDisplayDetails() { val runtime = CurrentRuntime("MyRuntime", "1.1") assertEquals("MyRuntime version 1.1", runtime.toString()) } @Test fun shouldHandleNullVersion() { val runtime = CurrentRuntime("MyRuntime", null) assertEquals("MyRuntime version unknown", runtime.toString()) } @Test fun shouldParseNumberFromVersionString() { val runtime = CurrentRuntime("MyRuntime", "1.2 Alpha Experimental") assertEquals("MyRuntime version 1.2", runtime.toString()) } @Test fun shouldHandleMissingVersion() { val runtime = CurrentRuntime("MyRuntime", "Alpha Experimental") assertEquals("MyRuntime version unknown", runtime.toString()) } }
您可以使用 IDE 中提供的任何方式运行此测试。
添加平台特定测试
此处为了简明扼要,使用了 expect 与 actual 声明机制。在更复杂的代码中,更好的方法是使用接口和工厂函数。
现在您已经具备了编写通用代码测试的经验,接下来我们来探索为 Android 和 iOS 编写平台特定测试。
为了创建 CurrentRuntime 的实例,请在通用的 CurrentRuntime.kt 文件中按如下方式声明一个函数:
expect fun determineCurrentRuntime(): CurrentRuntime该函数应针对每个受支持的平台提供单独的实现。否则,构建将失败。 除了在每个平台上实现此函数之外,您还应该提供测试。让我们为 Android 和 iOS 创建测试。
针对 Android
在
androidMain/kotlin目录下,创建一个新的org.kmp.testing软件包。在此软件包中,创建
AndroidRuntime.kt文件并使用 expecteddetermineCurrentRuntime()函数的 actual 实现进行更新:kotlinactual fun determineCurrentRuntime(): CurrentRuntime { val name = System.getProperty("java.vm.name") ?: "Android" val version = System.getProperty("java.version") return CurrentRuntime(name, version) }在
sharedLogic/src目录中创建用于测试的目录:右键点击
sharedLogic/src目录并选择 New | Directory。IDE 将显示选项列表。开始键入
androidHostTest/kotlin路径以缩小选择范围,然后从列表中选择该项:
在
androidHostTest/kotlin目录下,创建一个新的org.kmp.testing软件包。在此软件包中,创建
AndroidRuntimeTest.kt文件并使用以下 Android 测试进行更新。 为了使测试通过,请务必设置运行时的实际名称和版本(不过观察测试如何失败也很有帮助):kotlinimport kotlin.test.Test import kotlin.test.assertContains import kotlin.test.assertEquals class AndroidRuntimeTest { @Test fun shouldDetectAndroid() { val runtime = determineCurrentRuntime() assertContains(runtime.name, "OpenJDK") assertEquals(runtime.version, "21.0") } }
Android 特定的测试在本地 JVM 上运行可能看起来有些奇怪。这是因为这些测试作为本地单元测试在当前计算机上运行。如 Android Studio 文档中所述,这些测试不同于在设备或模拟器上运行的插桩测试。
您可以向项目中添加其他类型的测试。若要了解插桩测试,请参阅这份 Touchlab 指南。
针对 iOS
在
iosMain/kotlin目录下,创建一个新的org.kmp.testing目录。在此目录中,创建
IOSRuntime.kt文件并使用 expecteddetermineCurrentRuntime()函数的 actual 实现进行更新:kotlinimport kotlin.experimental.ExperimentalNativeApi import kotlin.native.Platform @OptIn(ExperimentalNativeApi::class) actual fun determineCurrentRuntime(): CurrentRuntime { val name = Platform.osFamily.name.lowercase() return CurrentRuntime(name, null) }在
sharedLogic/src目录下创建一个新目录:- 右键点击
sharedLogic/src目录并选择 New | Directory。IDE 将显示选项列表。 - 开始键入
iosTest/kotlin路径以缩小选择范围,然后从列表中选择该项:
- 右键点击
在
iosTest/kotlin目录下,创建一个新的org.kmp.testing目录。在此目录中,创建
IOSRuntimeTest.kt文件并使用以下 iOS 测试进行更新:kotlinimport kotlin.test.Test import kotlin.test.assertEquals class IOSRuntimeTest { @Test fun shouldDetectOS() { val runtime = determineCurrentRuntime() assertEquals(runtime.name, "ios") assertEquals(runtime.version, "unknown") } }
运行多个测试并分析报告
至此,您已经拥有了通用、Android 和 iOS 实现的代码及其测试。 项目中的目录结构应类似于:

您可以从上下文菜单运行单个测试或使用快捷键。另一个选项是使用 Gradle 任务。例如,如果您运行 allTests Gradle 任务,项目中的每个测试都将使用相应的测试运行程序运行:

运行测试时,除了 IDE 中的输出外,还会生成 HTML 报告。您可以在 sharedLogic/build/reports/tests 目录中找到它们:

运行 allTests 任务并检查其生成的报告:
allTests/index.html文件包含通用测试和 iOS 测试的合并报告(iOS 测试依赖于通用测试,并在其之后运行)。testDebugUnitTest和testReleaseUnitTest文件夹包含两个默认 Android 构建变体(flavor)的报告。(目前,Android 测试报告不会自动与allTests报告合并。)

在多平台项目中使用测试的规则
现在,您已经在 Kotlin Multiplatform 应用程序中创建、配置并执行了测试。 在未来的项目中处理测试时,请记住:
- 为通用代码编写测试时,仅使用多平台库,如 kotlin.test。请将依赖项添加到
commonTest源集中。 - 来自
kotlin.testAPI 的Asserter类型应仅间接使用。虽然Asserter实例是可见的,但您无需在测试中使用它。 - 始终保持在测试库 API 范围内。幸运的是,编译器和 IDE 会阻止您使用特定于框架的功能。
- 尽管使用哪个框架在
commonTest中运行测试并不重要,但最好使用您打算使用的各个框架来运行测试,以检查开发环境是否已正确设置。 - 考虑物理特性的差异。例如,滚动惯性和摩擦力数值因平台和设备而异,因此设置相同的滚动速度可能会导致不同的滚动位置。请务必在目标平台上测试组件,以确保符合预期行为。
- 为平台特定代码编写测试时,您可以使用相应框架的功能,例如注解和扩展。
- 您既可以从 IDE 运行测试,也可以使用 Gradle 任务运行测试。
- 运行测试时,会自动生成 HTML 测试报告。
后续步骤
- 在了解多平台项目结构中探索多平台项目的布局。
- TestBalloon 是一个多平台测试框架,支持所有 Kotlin Multiplatform 目标以及 Kotlin Power Assert 和其他断言库。
- Kotest 是另一个多平台测试框架,允许以多种风格编写测试,并支持对常规测试的补充方法。其中包括数据驱动型和基于属性的测试。
