testcontainers-java :: index

Testcontainers

Testcontainers logo

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:

Prerequisites

Maven dependencies

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

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

testImplementation "org.testcontainers:testcontainers:{{latest_version}}"
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>{{latest_version}}</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:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>testcontainers-bom</artifactId>
            <version>{{latest_version}}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

and then use dependencies without specifying a version:

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

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

implementation platform('org.testcontainers:testcontainers-bom:{{latest_version}}') //import bom
testImplementation('org.testcontainers:mysql') //no version specified

JitPack builds are available for pre-release versions.

!!! warning "Shaded dependencies" Testcontainers depends on other libraries (like docker-java) for it to work.
Some of them (JUnit, docker-java-{api,transport} and its transitive dependencies, JNA, visible-assertions and others) are part of our public API.
But there are also "private", implementation detail dependencies (e.g. docker-java-core, Guava, OkHttp, etc etc) that are not exposed to public API but 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.

Sponsors

A huge thank you to our sponsors:

Bronze sponsors

Cirrus CI

Vivy

jOOQ

Backbase

Backers

Who is using Testcontainers?

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-2021 Richard North and other authors.

See AUTHORS for contributors.