📚 课程目录第3章开发环境搭建

开发环境搭建：IntelliJ IDEA 配置与 Gradle/Maven 工程引入 kotlin.test

环境搭建这事，说简单也简单，说坑也多。我见过不少新手在 ide 里折腾半天，结果跑测试的时候报个“类找不到”。其实，只要你把 IntelliJ IDEA 配顺手，构建工具里引对依赖，后面几十章的代码都能稳稳跑起来。咱们直接动手。

IntelliJ IDEA 的准备工作

如果你还没装 IntelliJ IDEA，记得去官网下 Ultimate 或 Community 版。我建议用 Ultimate，因为对 Kotlin 的支持更全，尤其是 Spring 项目。不过 Community 版做纯 Kotlin 测试也完全够用。

JDK 版本：至少 JDK 17，推荐 JDK 21。Kotlin 1.9+ 对 JDK 21 兼容很好。
Kotlin 插件：IDEA 2023 以上版本自带，不需要手动装。如果你用的是旧版，去 Settings → Plugins 搜 “Kotlin” 装上就行。
Gradle / Maven 插件：同样内置，不用操心。

💡 小技巧：IDEA 里按 Ctrl+Shift+A（Mac 是 Cmd+Shift+A），输入 “Kotlin”，可以直接看到所有 Kotlin 相关设置。我个人习惯把 “Kotlin → Compiler → Target JVM version” 设成与 JDK 版本一致。

新建一个 Kotlin 项目

在 IDEA 里点 New Project，选 Kotlin，然后选 Gradle 或 Maven。我个人偏好 Gradle，因为它的 Kotlin DSL 写起来很舒服。选好之后，项目结构会自动生成：

my-test-project/
├── build.gradle.kts   (或 pom.xml)
├── src/
│   ├── main/
│   │   └── kotlin/    (生产代码)
│   └── test/
│       └── kotlin/    (测试代码)
│           └── SampleTest.kt

你可能会问：为什么不直接用 IDEA 的 “Kotlin Test” 模板？因为它默认引入的是 JUnit 的依赖，而我们后面要用 kotlin.test 这个官方测试框架。所以，还是手动调整依赖更靠谱。

Gradle 项目里引入 kotlin.test

在 build.gradle.kts 里，你需要做两件事：

确保 Kotlin 插件版本和你编译器版本一致。
在 dependencies 块里添加 kotlin-test。

来看一个最小配置：

plugins {
    kotlin("jvm") version "1.9.22"
    id("org.jetbrains.kotlin.plugin.testing") version "1.9.22" // 可选，但推荐
}

dependencies {
    testImplementation(kotlin("test"))
    // 如果你需要断言库的额外功能，可以再加这个：
    // testImplementation(kotlin("test-junit5"))
}

tasks.test {
    useJUnitPlatform()
}

嗯，这里要注意：kotlin("test") 会自动拉取 kotlin-test 核心库，它自带 Test 注解和 assertEquals 等基础断言。如果你只用 JUnit5 的引擎跑，不需要额外加 JUnit 的依赖——kotlin.test 底层已经适配好了。

我曾经踩过这个坑：只写了 testImplementation("org.jetbrains.kotlin:kotlin-test:1.9.22")，结果跑测试时一直报“没有测试引擎”。后来才发现忘了加 useJUnitPlatform()。Kotlin 1.8 之后默认用 JUnit5，但需要你显式告诉 Gradle 启用它。

Maven 项目里引入 kotlin.test

Maven 的配置稍微啰嗦一点，但逻辑一样。在 pom.xml 里：

<properties>
    <kotlin.version>1.9.22</kotlin.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-test</artifactId>
        <version>${kotlin.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <executions>
                <execution>
                    <id>compile</id>
                    <goals><goal>compile</goal></goals>
                </execution>
                <execution>
                    <id>test-compile</id>
                    <goals><goal>test-compile</goal></goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.1.2</version>
        </plugin>
    </plugins>
</build>

记得要在 maven-surefire-plugin 里指定 JUnit 引擎，不过从 3.0 版本开始它默认就支持 JUnit5 了。如果不放心，可以显式加：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <includes>
            <include>**/*Test.kt</include>
        </includes>
    </configuration>
</plugin>

⚠️ 曾经有同事在 pom.xml 里忘了加 <scope>test</scope>，结果 kotlin-test 被当成生产依赖，打包到 jar 里了。虽然不影响运行，但把测试框架带进生产包，怎么看都不对劲。所以，scope 一定要写 test。

验证环境是否正确

光配好不行，得写个最简单的测试跑一下。在 src/test/kotlin/ 下建一个文件 HelloTest.kt：

import kotlin.test.Test
import kotlin.test.assertEquals

class HelloTest {
    @Test
    fun `should add two numbers`() {
        val sum = 2 + 3
        assertEquals(5, sum)
    }
}

在 IDEA 里点类名旁边的绿色三角，或者直接在终端执行 ./gradlew test（Maven 是 mvn test）。如果看到 BUILD SUCCESSFUL，说明环境搞定。如果报错，八成是插件版本或引擎配置的问题——回去检查 useJUnitPlatform() 或 maven-surefire-plugin 版本。

下面这张图帮你梳理了整个搭建流程的核心逻辑：

常见问题速查表

我把平时群里问得最多的问题整理成了表格，你直接对照着排查就行：

问题现象	根因	解决方案
Test 注解无法识别	没引入 kotlin.test 依赖	检查 dependencies 里是否有 `kotlin("test")`
No tests found for given includes	缺少 JUnit 测试引擎	Gradle 加 `useJUnitPlatform()`；Maven 确保 surefire 3.0+
Kotlin 版本与 JDK 不兼容	Kotlin 1.7 不支持 JDK 21	升级 Kotlin 到 1.9+，并设 target JVM 为 21
IDEA 中测试运行按钮是灰色	项目未正确导入构建配置	重新导入 Gradle/Maven 项目，或清理缓存

还记得我刚入行时，配个测试环境花了一下午。最后发现是 IDEA 的缓存问题——清一下 File → Invalidate Caches 就好了。如果你的配置看起来都没错，但测试就是跑不了，不妨试试这个笨办法。

一些额外的配置建议

到了这一步，基础环境已经稳了。不过有几个可选配置，能让你的测试体验更好：

IDEA 的 Live Template：在 Settings → Editor → Live Templates 里，搜 "test"，给 Kotlin 添加一个快捷生成测试类的模板。比如输入 @Test fun `$NAME$`() { $END$ }，省得每次手敲。
Gradle 并行测试：在 build.gradle.kts 里加 tasks.withType<Test> { maxParallelForks = 4 }，跑大量测试时能省不少时间。
单元测试覆盖率：Gradle 默认集成 JaCoCo，直接 ./gradlew test jacocoTestReport 就能生成报告。

好了，环境这一关咱们算是过去了。你可以先写几个简单的测试试试手感，后面几章我们会深入到 kotlin.test 的各种断言、注解和测试生命周期里。到时候你会发现，今天搭好的这个环境，才是最坚实的起点。