1. 项目初始化与依赖配置

MockK 协程测试环境的搭建是整个课程的基础。本章从 Gradle 依赖声明出发，讲解如何引入 mockk、kotlinx-coroutines-test 以及必要的版本对齐策略。正确的依赖配置可以避免运行时类冲突、协程调度器异常等常见问题，为后续章节的实战案例扫清障碍。

1.1 核心依赖与原理

MockK 依赖通过字节码代理生成 mock 对象，kotlinx-coroutines-test 则提供TestCoroutineDispatcher、TestScope 等工具，用于控制协程的虚拟时间与调度。两者在 JVM 平台通过标准 Gradle 依赖机制组合，需注意 Kotlin 编译器版本、协程库版本与 MockK 版本的兼容三角。

依赖	最小版本	推荐版本	说明
io.mockk:mockk	1.12.0	1.13.10	支持协程的 mockk 核心库
org.jetbrains.kotlinx:kotlinx-coroutines-test	1.6.0	1.8.1	协程测试工具库
org.jetbrains.kotlin:kotlin-test	1.8.0	1.9.22	Kotlin 标准测试断言

1.2 实现流程

1. 确认项目 Kotlin 版本（推荐 1.9.x 以上）
2. 在模块级别的 build.gradle.kts 中添加 Maven Central 仓库
3. 声明 testImplementation 依赖，包括 mockk、coroutines-test 和 kotlin-test
4. 同步 Gradle，验证依赖树无冲突
5. 编写最小测试用例验证环境

1.3 Gradle 配置示例

以下为 Kotlin DSL 格式的完整配置片段：

plugins {
    kotlin("jvm") version "1.9.22"
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("io.mockk:mockk:1.13.10")
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.1")
    testImplementation(kotlin("test"))
}

若使用 Groovy DSL：

dependencies {
    testImplementation 'io.mockk:mockk:1.13.10'
    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.1'
    testImplementation "org.jetbrains.kotlin:kotlin-test"
}

1.4 版本兼容性说明

版本对齐是依赖配置中最易出错的一环。核心规则：

• MockK 版本应不低于 1.12.0，推荐 1.13.10（兼容 Kotlin 1.8~2.0）
• kotlinx-coroutines-test 主版本号需与 Kotlin 编译器匹配：一般 kotlinx-coroutines-test:1.8.x 对应 Kotlin 1.9.x
• 若项目中同时使用其他协程扩展（如 Flow、Channel），应保持所有 kotlinx-coroutines-* 版本一致

1.5 常见依赖冲突解决

冲突现象	原因	解决方案
NoClassDefFoundError: kotlinx/coroutines/TestCoroutineDispatcher	项目中有多个版本的 kotlinx-coroutines-core 同时被拉入	使用 Gradle 依赖约束排除重复：
IllegalAccessError: class MockK cannot access class	MockK 版本与 Kotlin 编译器 bytecode 不兼容	升级 MockK 或降级 Kotlin 到推荐范围
Duplicate class kotlinx.coroutines.test.internal	kotlinx-coroutines-test 和其他库（如JUnit5扩展）打包了相同类	添加 @Suppress("Unused") 或使用 module-info

排除传递依赖的 Gradle 语法：

testImplementation("io.mockk:mockk:1.13.10") {
    exclude(group = "org.jetbrains.kotlinx", module = "kotlinx-coroutines-core")
}

1.6 依赖关系全景图

下图展示了 MockK 协程测试环境中的核心模块、版本协调关系以及常见冲突点：

1.7 调试与验证

配置完成后，在 src/test/kotlin 下创建最小测试文件：

import io.mockk.mockk
import kotlinx.coroutines.test.runTest
import org.junit.Test

class DependencyVerificationTest {
    @Test
    fun `mockk and coroutines test should load`() = runTest {
        val mock = mockk<() -> Unit>()
        println("MockK and TestCoroutineDispatcher loaded successfully")
    }
}

运行测试，若无异常则说明依赖配置正确。常见错误日志及排查口诀见下表：

错误日志片段	排查方向
java.lang.NoClassDefFoundError: kotlinx/coroutines/test/TestCoroutineScope	检查 kotlinx-coroutines-test 版本是否过低或未被引入
java.lang.ClassNotFoundException: io.mockk.impl.JvmMockKGateway	MockK 缺少运行时依赖，确认 gradle 仓库已包含 mavenCentral()
kotlin.KotlinVersionMismatchException	Kotlin 标准库版本与 MockK 编译用版本不匹配，使用 Kotlin BOM 对齐

1.8 稳定性优化建议

• 使用 kotlinx-coroutines-bom 统一协程全家桶版本，减少传递依赖版本漂移
• 在 CI 流水线中添加 Gradle 依赖锁（gradle.lockfile），防止因间接依赖升级导致测试环境不稳定
• 定期更新 MockK 和 coroutines-test 至最新 patch 版本以修复已知 bug