测试环境搭建：Kotlin项目配置与依赖管理

说实话，很多人在写测试时最容易翻车的地方，恰恰不是测试逻辑本身，而是环境没搭对。我见过不少人花了半天时间写测试用例，结果发现跑不起来——不是缺依赖，就是版本冲突。所以这一章，咱们先把地基打牢。

2.1 创建 Kotlin 项目：选 Gradle 还是 Maven？

我个人习惯用 Gradle 搭 Kotlin 项目。原因很简单：Kotlin 官方对 Gradle 的支持最及时，配置也最简洁。当然 Maven 也能用，但你需要额外处理 kotlin-maven-plugin 的版本匹配。如果是新项目，直接上 Gradle Kotlin DSL 就对了。

创建一个最简单的项目结构：

my-test-project/
├── build.gradle.kts
├── settings.gradle.kts
└── src/
    ├── main/kotlin/
    └── test/kotlin/

嗯，这里要注意：test/kotlin/ 目录是 Kotlin 测试源码的默认位置。如果你用 Maven，对应的是 src/test/kotlin。

2.2 添加 kotlin.test 依赖

核心依赖就两个：

• kotlin-test — 官方测试库，提供 @Test、assertEquals 等基础 API。
• kotlin-test-junit5 — 桥接 JUnit5 运行器，让测试可以集成到 IDE 和 CI 中。

在 build.gradle.kts 中写入：

plugins {
    kotlin("jvm") version "1.9.0" // 根据你实际版本调整
}

dependencies {
    testImplementation("org.jetbrains.kotlin:kotlin-test:1.9.0")
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5:1.9.0")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.test {
    useJUnitPlatform()
}

这里有个小坑：kotlin-test 和 kotlin-test-junit5 的版本必须跟 Kotlin 编译器版本保持一致。我曾经在一个项目里用了 Kotlin 1.8 却引了 1.9 的 kotlin-test，结果 @Test 注解直接报红色下划线——折腾了半天才发现是版本没对齐。

2.3 配置测试运行器

你可能会问：为什么有了 kotlin-test 还要加 kotlin-test-junit5？原因很简单——kotlin.test 自己只是一个 API 定义层，真正执行测试需要 JUnit5 的引擎。说白了，kotlin-test-junit5 就是那个桥梁。

配置跑起来后，记得在 src/test/kotlin 目录下放一个简单的测试来验证环境：

import kotlin.test.*

class FirstTest {

    @Test
    fun `hello test should pass`() {
        assertEquals(4, 2 + 2, "2+2 应该等于 4")
    }

    @Test
    fun `string length check`() {
        assertEquals(5, "hello".length)
    }
}

运行 ./gradlew test，如果控制台输出 BUILD SUCCESSFUL 并且没有红色错误，那环境就搭好了。

2.4 验证环境：小试牛刀

我第一次搭 Kotlin 测试环境时，总喜欢写一个最简单的断言来确认所有组件都正常。这不是矫情——因为依赖冲突、缓存问题经常悄无声息地翻车。我的习惯是：每加一个新依赖，都跑一个最小测试来验证。

如果遇到测试跑不起来，先检查这几个点：

现象	可能原因	解决
测试类找不到 @Test	缺少 kotlin-test-junit5	添加该依赖并确保版本一致
执行测试时报 No tests found	源集目录不对或 Gradle 没识别	检查 src/test/kotlin/ 路径，重新 import
编译时报 Unresolved reference: test	依赖作用域写成了 implementation	改为 testImplementation
版本冲突	kotlin-test 版本与 Kotlin 编译器不一致	统一使用同一个版本的 Kotlin

2.5 避坑：我踩过的几个大坑

依赖作用域用错。 我曾经把 testImplementation 误写成 implementation，结果测试依赖被打进了生产包，CI 构建直接报 jar 冲突。记住：测试用的依赖永远用 testImplementation。

Kotlin 版本与插件版本不匹配。 Gradle 的 kotlin("jvm") 插件版本必须等于你依赖的 kotlin-test 版本。如果你用的 Kotlin 1.9.0，那所有 kotlin-* 依赖也必须是 1.9.0。

JUnit5 引擎未配置。 有些人只加了 kotlin-test 就觉得够了，结果跑测试时一直报 “No tests were found”。其实只需要加上 kotlin-test-junit5 和 useJUnitPlatform() 就能解决。

2.6 本章知识结构

下面这张图涵盖了测试环境搭建的核心流程和关键决策点：

流程很简单，但每一步都有细节。别怕麻烦，按照这个步骤走一遍，后面写测试就不会被环境卡住。我的经验是：花15分钟把环境搭牢，能省下后面几个小时的调错时间。