Testcontainers JUnit 5 快速入门用 Docker 容器彻底告别本地依赖的集成测试【免费下载链接】testcontainers-javaTestcontainers is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.项目地址: https://gitcode.com/GitHub_Trending/te/testcontainers-java本指南基于 Testcontainers Java 官方 quickstart 文档完整演示如何将一个依赖本地 Redis 的普通测试一步步改造成由 Docker 容器驱动、可移植、可并行的 JUnit 5 集成测试。读完本文你将掌握Testcontainers/Container注解的组合用法、随机端口的获取方式以及disabledWithoutDocker、parallel等高级属性的实际语义。从一个不可靠的测试说起设想一个简单的程序它的RedisBackedCache类负责把数据存入 Redis、按 key 读取。仓库中的真实示例位于 RedisBackedCache.java内部基于 Lettuce 客户端建立连接public RedisBackedCache(String hostname, Integer port) { RedisClient client RedisClient.create(String.format(redis://%s:%d/0, hostname, port)); connection client.connect(); }在没有使用 Testcontainers 之前我们可能会写出下面这样的测试见 RedisBackedCacheIntTestStep0.javaDisabled(This test class is deliberately invalid, as it relies on a non-existent local Redis) public class RedisBackedCacheIntTestStep0 { private RedisBackedCache underTest; BeforeEach public void setUp() { // Assume that we have Redis running locally? underTest new RedisBackedCache(localhost, 6379); } Test public void testSimplePutAndGet() { underTest.put(test, example); String retrieved underTest.get(test); assertThat(retrieved).isEqualTo(example); } }这个测试存在明显的可靠性隐患依赖本机安装的 Redis只有每个开发者和 CI 机器都恰好安装了 Redis 且版本行为一致测试才能通过否则必然失败端口冲突与状态污染多个测试并发运行时共用localhost:6379会出现端口抢占、数据互相泄漏state bleeding等问题环境不可复现Redis 的配置、数据、版本在不同机器上无法保证一致测试结果难以稳定复现。这些正是 Testcontainers 要解决的痛点为 JUnit 测试提供轻量、一次性throwaway的 Docker 容器实例用完即销毁环境完全隔离且可复现。下面我们从这里出发逐步改造。第一步添加 test-scoped 依赖首先把 Testcontainers 及相关 JUnit 5 集成库加入测试作用域。 Gradlegroovy testImplementation org.junit.jupiter:junit-jupiter:5.8.1 testImplementation org.testcontainers:testcontainers:{{latest_version}} testImplementation org.testcontainers:testcontainers-junit-jupiter:{{latest_version}} Mavenxml dependency groupIdorg.junit.jupiter/groupId artifactIdjunit-jupiter/artifactId version5.8.1/version scopetest/scope /dependency dependency groupIdorg.testcontainers/groupId artifactIdtestcontainers/artifactId version{{latest_version}}/version scopetest/scope /dependency dependency groupIdorg.testcontainers/groupId artifactIdtestcontainers-junit-jupiter/artifactId version{{latest_version}}/version scopetest/scope /dependency其中{{latest_version}}为当前仓库发布的最新版本号请以 Maven Central 上org.testcontainers的最新 release 为准。三个依赖的分工是testcontainers核心库提供GenericContainer、DockerImageName等容器抽象与 Docker 交互能力testcontainers-junit-jupiterJUnit 5 扩展提供Testcontainers、Container注解与生命周期管理源码见 modules/junit-jupiterjunit-jupiterJUnit 5 本身提供Test,BeforeEach等测试框架能力。另外如果测试中要用到断言可自行引入 AssertJ 等断言库示例测试即使用了org.assertj.core.api.Assertions.assertThat。第二步让 Testcontainers 在测试期间启动 Redis 容器给测试类加上Testcontainers注解并在类体内声明一个用Container标注的容器字段Testcontainers public class RedisBackedCacheIntTest { Container public GenericContainer redis new GenericContainer(DockerImageName.parse(redis:6-alpine)) .withExposedPorts(6379); ... }这一段来自示例测试 RedisBackedCacheIntTest.java 的container代码块。这里有几个关键点Testcontainers类级注解从源码看它本质是ExtendWith(TestcontainersExtension.class)的元注解见 Testcontainers.java用于激活 JUnit 5 扩展让扩展接管所有Container字段的生命周期Container字段级注解标记哪些字段需要被扩展托管见 Container.java。可以标注在静态字段或实例字段上静态字段的容器在所有测试方法之间共享只启动一次、在最后一个测试方法执行完毕后停止实例字段的容器则每个测试方法都会启动、停止一次该语义在Testcontainers注解的 Javadoc 中有明确说明GenericContainerTestcontainers 最通用的容器类型通过DockerImageName.parse(redis:6-alpine)指定镜像用.withExposedPorts(6379)声明需要暴露的容器内端口。按原样运行测试无论测试断言最终通过与否日志都会展示 Testcontainers 依次完成了这些动作在测试方法执行前激活扩展探测并快速验证本地 Docker 环境是否可用必要时拉取镜像启动一个新容器并等待其就绪测试结束后关闭并删除容器。这就是一次性、用完即销毁的核心体验每个测试运行都是从一个干净、确定的环境中开始。第三步让被测代码与容器通信随机端口 getHost改造前我们硬编码了localhost:6379。Testcontainers 为每个容器分配的是随机宿主机端口但提供了非常方便的运行时查询手段。在测试的setUp方法中完成被测对象的装配BeforeEach public void setUp() { String address redis.getHost(); Integer port redis.getFirstMappedPort(); // Now we have an address and port for Redis, no matter where it is running underTest new RedisBackedCache(address, port); }这段代码来自示例测试的setUp代码块。两个关键 APIredis.getHost()返回容器映射到的宿主机地址。文档特别强调不要硬编码localhost——它在某些环境比如部分 CI下并不指向宿主机因此应始终使用getHost()redis.getFirstMappedPort()返回第一个被映射的宿主机端口对应withExposedPorts(6379)声明的端口。由于端口是随机映射的多个测试、多个容器之间不会互相抢占 6379 端口这正是解决并行测试端口冲突问题的关键机制。只要 Docker 环境可用这段测试代码在任何机器上的行为都是一致的真正做到了no matter where it is running。第四步Testcontainers的高级属性Testcontainers注解还提供了两个可选属性源码定义见 Testcontainers.javaboolean disabledWithoutDocker() default false; boolean parallel() default false;disabledWithoutDocker true当当前环境没有可用的 Docker 时**跳过skip而非失败fail**相关测试。适合在混合环境中运行测试套件避免因缺少 Docker 导致整个构建失败parallel true开启并行容器初始化默认是串行。当测试类里有多个Container字段时让它们同时启动缩短整体等待时间。用法示例Testcontainers(disabledWithoutDocker true, parallel true) public class RedisBackedCacheIntTest { ... }第五步运行测试欣赏完整成果改造到这里就全部完成了。让我们看看最终测试类的全貌来自示例测试的class代码块Testcontainers public class RedisBackedCacheIntTest { private RedisBackedCache underTest; Container public GenericContainer redis new GenericContainer(DockerImageName.parse(redis:6-alpine)) .withExposedPorts(6379); BeforeEach public void setUp() { String address redis.getHost(); Integer port redis.getFirstMappedPort(); // Now we have an address and port for Redis, no matter where it is running underTest new RedisBackedCache(address, port); } Test public void testSimplePutAndGet() { underTest.put(test, example); String retrieved underTest.get(test); assertThat(retrieved).isEqualTo(example); } }与改造前相比我们只增加了三个 test-scoped 依赖类上的Testcontainers注解一个Container声明的GenericContainer字段setUp中改用getHost()getFirstMappedPort()获取连接信息。其余测试逻辑一字未动。运行方式与普通 JUnit 5 测试完全相同如./gradlew test或 IDE 中直接运行前提是运行环境具备可用的 Docker。深入JUnit 5 扩展背后的生命周期机制如果想把这套机制用得更深可以进一步阅读testcontainers-junit-jupiter模块的源码TestcontainersExtension.java 实现了 JUnit 5 的BeforeAllCallback、BeforeEachCallback、AfterEachCallback、AfterAllCallback等扩展点这正是静态容器全类共享、实例容器逐方法启停语义的底层实现。DockerAvailableDetector与EnabledIfDockerAvailable则对应disabledWithoutDocker背后的 Docker 可用性探测逻辑。该模块的测试用例见 modules/junit-jupiter/src/test/java/org/testcontainers 下的测试源码覆盖了静态/实例容器、继承父类注解等场景是研究扩展行为的绝佳参考。如果你使用的是 JUnit 4 或 Spock仓库还提供了对应的 JUnit 4 快速入门 与 Spock 快速入门机制同源、用法略有差异可对比阅读。至此一个不再依赖本机 Redis、可在任意具备 Docker 的环境本机、CI、并行执行中稳定运行的集成测试就完成了——这就是 Testcontainers 为 JUnit 5 测试带来的核心价值。【免费下载链接】testcontainers-javaTestcontainers is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.项目地址: https://gitcode.com/GitHub_Trending/te/testcontainers-java创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考