在 Kotest 测试中运行 Testcontainers

1. 简介

集成测试是保障软件可靠性和正确性的关键环节。Testcontainers 提供了一种强大手段，帮助我们实现隔离且可复现的集成测试环境。本文将探讨如何将 Testcontainers 与 Kotest —— 一个灵活高效的 Kotlin 测试框架 —— 结合使用。✅
我们将重点讲解在 Kotest 中运行测试容器的完整流程：从环境搭建、测试执行到最佳实践，帮你避开常见坑点。

⚠️ 前置要求：确保你的开发环境已安装并正常运行 Docker。如果还没配好，建议先参考 Docker 入门指南完成配置。

2. 依赖配置

要让 Testcontainers 在 Kotest 中跑起来，我们需要引入几个关键依赖。别漏了核心库和专用扩展。

2.1. Kotest 相关依赖

首先，加入 Kotest 框架本身以及它对 Testcontainers 的官方扩展支持：

<dependency>
    <groupId>io.kotest</groupId>
    <artifactId>kotest-runner-junit5</artifactId>
    <version>5.8.1</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>io.kotest.extensions</groupId>
    <artifactId>kotest-extensions-testcontainers</artifactId>
    <version>2.0.1</version>
    <scope>test</scope>
</dependency>

kotest-runner-junit5：用于编写基于 JUnit 5 的 Kotest 测试。
kotest-extensions-testcontainers：这是连接 Kotest 和 Testcontainers 的桥梁，提供便捷的生命周期管理。

2.2. Testcontainers 核心依赖

接下来是 Testcontainers 自身的核心库，以及针对 MySQL 的专用模块：

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.18.3</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>mysql</artifactId>
    <version>1.18.3</version>
    <scope>test</scope>
</dependency>

testcontainers：核心运行时。
mysql：封装了 MySQL 容器的启动逻辑（如自动初始化、健康检查等）。

📌 一旦这些依赖就位，就可以开始写基于容器的集成测试了。

3. 使用数据库容器

我们以一个典型的场景为例：有个 DatabaseService 类负责操作 MySQL 数据库，现在想为它写集成测试。我们将使用 Kotest 的 FunSpec 风格来组织测试代码 —— 这种风格语法清晰，适合表达行为式测试。

3.1. 在 FunSpec 中创建容器

先定义测试类，并初始化 MySQL 容器实例：

class TestContainersSamples : FunSpec({
    val mysql = MySQLContainer("mysql:8")
})

关键来了：如何让这个容器在测试生命周期中自动启停？答案是使用 Kotest 的 install() 函数配合 JdbcDatabaseContainerExtension 扩展：

class TestContainersSamples : FunSpec({
    val mysql = MySQLContainer("mysql:8")

    val dataSource: DataSource = install(JdbcDatabaseContainerExtension(mysql))
})

✅ install() 是 Kotest 的特性，能自动绑定资源的生命周期到当前测试作用域（比如整个 Spec 或单个 Test）。
⚠️ 注意：JdbcDatabaseContainerExtension 会自动完成以下事情：

启动容器
等待数据库就绪
构造可用的 DataSource
测试结束后自动清理容器

这一步完成了从 Testcontainers 到 Kotest 的无缝桥接。

3.2. 编写实际测试用例

有了 DataSource，就可以注入到我们的服务中，然后开测：

class TestContainersSamples : FunSpec({
    val mysql = MySQLContainer("mysql:8")

    val dataSource: DataSource = install(JdbcDatabaseContainerExtension(mysql))

    val service = DatabaseService(dataSource)

    test("Inserting in database should persist an object") {
        service.insert(Person("Leo"))
        service.insert(Person("Colman"))

        service.all() shouldBe listOf(Person("Leo"), Person("Colman"))
    }
})

上面这段测试做了三件事：

插入两个 Person 对象；
调用 service.all() 查询全部数据；
断言结果是否符合预期。

💡 因为每个测试都在独立的容器环境中运行，所以数据完全隔离，不用担心脏数据问题。这也是 Testcontainers 最大的优势之一。

4. 配置与自定义

Testcontainers 支持丰富的配置选项，你可以根据需要调整容器行为，比如端口映射、环境变量、网络模式等。

4.1. 容器基础配置

例如，如果你想显式暴露 MySQL 的 3306 端口给宿主机（虽然通常不需要，因为 Kotest 通过内部网络访问即可），可以这样写：

val exposedMySQL = MySQLContainer("mysql:8").apply {
    withExposedPorts(3306)
}

更多配置项如 withEnv()、withDatabaseName()、withUsername() 等也都可以链式调用设置。

4.2. 生命周期钩子（Lifecycle Hooks）

JdbcDatabaseContainerExtension 构造函数提供了多个回调接口，让你可以在关键节点插入自定义逻辑：

val dataSource: DataSource = install(
    JdbcDatabaseContainerExtension(
        mysql,
        mode = ContainerLifecycleMode.Spec, // 容器生命周期绑定到整个 Spec
        beforeStart = {
            println("即将启动 MySQL 容器...")
        },
        afterStart = { container ->
            println("MySQL 已启动，JDBC URL: ${container.jdbcUrl}")
        },
        beforeShutdown = { 
            println("准备关闭容器...")
        }
    )
)

常用钩子说明：

钩子	触发时机	典型用途
`beforeStart`	容器启动前	设置动态配置、打日志
`afterStart`	容器启动后	获取连接信息、预加载 schema
`beforeShutdown`	容器销毁前	清理临时文件、导出日志

📌 mode 参数控制容器复用策略：

Spec：整个测试类只启动一次容器 ✅ 推荐（性能高）
EachTest：每个测试方法都重启容器 ❌ 慢，除非有强隔离需求

📚 更多高级配置请查阅：

Testcontainers 官方文档 - 网络与配置

Kotest 扩展文档 - Testcontainers

5. 总结

本文演示了如何在 Kotest 中高效集成 Testcontainers 来运行 MySQL 容器进行集成测试。通过 kotest-extensions-testcontainers 提供的 JdbcDatabaseContainerExtension，我们可以轻松实现容器的自动化管理，无需手动处理启停逻辑。

✅ 核心价值：

实现真实环境模拟，提升测试可信度
数据完全隔离，避免测试间干扰
支持高度定制化配置和生命周期控制

借助这套组合拳，你可以在 Kotlin 项目中构建出健壮、可维护的集成测试套件。早发现问题，少背锅。😎

所有示例代码均已开源，欢迎前往 GitHub 查看完整实现：
👉 https://github.com/baeldung/kotlin-tutorials/tree/master/kotlin-kotest/kotest

Persistence

REST

Security