Testcontainers

About

Testcontainers 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.

Testcontainers make the following kinds of tests easier:

Data access layer integration tests : use a containerized instance of a MySQL, PostgreSQL or Oracle database to test your data access layer code for complete compatibility, but without requiring complex setup on developers' machines and safe in the knowledge that your tests will always start with a known DB state. Any other database type that can be containerized can also be used.

: use a containerized instance of a MySQL, PostgreSQL or Oracle database to test your data access layer code for complete compatibility, but without requiring complex setup on developers' machines and safe in the knowledge that your tests will always start with a known DB state. Any other database type that can be containerized can also be used. Application integration tests : for running your application in a short-lived test mode with dependencies, such as databases, message queues or web servers.

: for running your application in a short-lived test mode with dependencies, such as databases, message queues or web servers. UI/Acceptance tests : use containerized web browsers, compatible with Selenium, for conducting automated UI tests. Each test can get a fresh instance of the browser, with no browser state, plugin variations or automated browser upgrades to worry about. And you get a video recording of each test session, or just each session where tests failed.

: use containerized web browsers, compatible with Selenium, for conducting automated UI tests. Each test can get a fresh instance of the browser, with no browser state, plugin variations or automated browser upgrades to worry about. And you get a video recording of each test session, or just each session where tests failed. Much more! Check out the various contributed modules or create your own custom container classes using GenericContainer as a base.

Prerequisites

Maven dependencies

Testcontainers is distributed as separate JARs with a common version number:

A core JAR file for core functionality, generic containers and docker-compose support

A separate JAR file for each of the specialised modules. Each module's documentation describes the Maven/Gradle dependency to add to your project's build.

For the core library, the latest Maven/Gradle dependency is as follows:

Gradle testCompile "org.testcontainers:testcontainers:1.14.3" Maven <dependency> <groupId> org.testcontainers </groupId> <artifactId> testcontainers </artifactId> <version> 1.14.3 </version> <scope> test </scope> </dependency>

You can also check the latest version available on Maven Central.

Managing versions for multiple Testcontainers dependencies

To avoid specifying the version of each dependency, you can use a BOM or Bill Of Materials .

Using Maven you can add the following to dependencyManagement section in your pom.xml :

Maven <dependencyManagement> <dependencies> <dependency> <groupId> org.testcontainers </groupId> <artifactId> testcontainers-bom </artifactId> <version> 1.14.3 </version> <type> pom </type> <scope> import </scope> </dependency> </dependencies> </dependencyManagement> Maven <dependency> <groupId> org.testcontainers </groupId> <artifactId> mysql </artifactId> <scope> test </scope> </dependency> and then use dependencies without specifying a version:

Using Gradle 5.0 or higher, you can add the following to the dependencies section in your build.gradle :

Gradle implementation platform ( 'org.testcontainers:testcontainers-bom:1.14.3' ) //import bom testImplementation ( 'org.testcontainers:mysql' ) //no version specified

JitPack builds are available for pre-release versions.

Shaded dependencies Testcontainers uses the docker-java client library, which in turn depends on JAX-RS, Jersey and Jackson libraries. These libraries in particular seem to be especially prone to conflicts with test code/application under test code. As such, these libraries are 'shaded' into the core testcontainers JAR and relocated under org.testcontainers.shaded to prevent class conflicts.

Who is using Testcontainers?

Testcontainers is on Github Sponsors! Please consider sponsoring us to sustain the project and help us improve it further.

Backers

A huge thank you to our backers:

License

See LICENSE.

Attributions

This project includes a modified class (ScriptUtils) taken from the Spring JDBC project, adapted under the terms of the Apache license. Copyright for that class remains with the original authors.

This project was initially inspired by a gist by Moshe Eshel.

Copyright

Copyright (c) 2015-2020 Richard North and other authors.

See AUTHORS for contributors.