Skip to content

Testcontainers for Java

Not using Java? Here are other supported languages!

Java Go .NET Node.js Python Rust Haskell Ruby

About Testcontainers for Java

Testcontainers for Java 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.
  • Application integration tests: 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.
  • 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: 

testImplementation "org.testcontainers:testcontainers:1.20.4"

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.20.4</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>1.20.4</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:1.20.4') //import bom
testImplementation('org.testcontainers:mysql') //no version specified

JitPack builds are available for pre-release versions.

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

Donors

Backers

Who is using Testcontainers?

  • ZeroTurnaround - Testing of the Java Agents, micro-services, Selenium browser automation
  • Zipkin - MySQL and Cassandra testing
  • Apache Gora - CouchDB testing
  • Apache James - LDAP and Cassandra integration testing
  • StreamSets - LDAP, MySQL Vault, MongoDB, Redis integration testing
  • Playtika - Kafka, Couchbase, MariaDB, Redis, Neo4j, Aerospike, MemSQL
  • JetBrains - Testing of the TeamCity plugin for HashiCorp Vault
  • Plumbr - Integration testing of data processing pipeline micro-services
  • Streamlio - Integration and Chaos Testing of our fast data platform based on Apache Pulsar, Apache BookKeeper and Apache Heron.
  • Spring Session - Redis, PostgreSQL, MySQL and MariaDB integration testing
  • Apache Camel - Testing Camel against native services such as Consul, Etcd and so on
  • Infinispan - Testing the Infinispan Server as well as integration tests with databases, LDAP and KeyCloak
  • Instana - Testing agents and stream processing backends
  • eBay Marketing - Testing for MySQL, Cassandra, Redis, Couchbase, Kafka, etc.
  • Skyscanner - Integration testing against HTTP service mocks and various data stores
  • Neo4j-OGM - Testing with Neo4j
  • Spring Data Neo4j - Testing imperative and reactive implementations with Neo4j
  • Lightbend - Testing Alpakka Kafka and support in Alpakka Kafka Testkit
  • Zalando SE - Testing core business services
  • Europace AG - Integration testing for databases and micro services
  • Micronaut Data - Testing of Micronaut Data JDBC, a database access toolkit
  • Vert.x SQL Client - Testing with PostgreSQL, MySQL, MariaDB, SQL Server, etc.
  • JHipster - Couchbase and Cassandra integration testing
  • wescale - Integration testing against HTTP service mocks and various data stores
  • Marquez - PostgreSQL integration testing
  • Wise (formerly TransferWise) - Integration testing for different RDBMS, kafka and micro services
  • XWiki - Testing XWiki under all supported configurations
  • Apache SkyWalking - End-to-end testing of the Apache SkyWalking, and plugin tests of its subproject, Apache SkyWalking Python, and of its eco-system built by the community, like SkyAPM NodeJS Agent
  • jOOQ - Integration testing all of jOOQ with a variety of RDBMS
  • Trino (formerly Presto SQL) - Integration testing all Trino core & connectors, including tests of multi-node deployments and security configurations.
  • Google - Various open source projects: OpenTelemetry, Universal Application Tool, CloudBowl
  • Backbase - Unit, Integration and Acceptance testing for different the databases supported (Oracle, SQL Server, MySQL), the different messaging systems supported (Kafka, Rabbit, AMQ) and other microservices and HTTP mocks.
  • CloudBees - Integration testing of products, including but not limited to database and AWS/Localstack integration testing.
  • Jenkins - Integration testing of multiple plugins and the Trilead SSH2 fork maintained by the Jenkins community (query).
  • Elastic - Integration testing of the Java APM agent
  • Alkira - Testing of multiple micro-services using Kafka, PostgreSQL, Apache Zookeeper, Etcd and so on.
  • Togglz - Feature Flags for the Java platform
  • Byzer - Integration tests for Data and AI platforms are based on multiple versions of Byzer, Ray and Apache Spark.
  • Apache SeaTunnel - Integration testing with different datasource.
  • Bucket4j - Java rate-limiting library based on the token-bucket algorithm.
  • Spark ClickHouse Connector - Integration tests for Apache Spark with both single node ClickHouse instance and multi-node ClickHouse cluster.
  • Quarkus - Testcontainers is used extensively for Quarkus' DevServices feature.
  • Apache Kyuubi - Integration testing with Trino as data source engine, Kafka, etc.
  • Dash0 - Integration testing for OpenTelemetry Observability product.

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 (c) 2015-2021 Richard North and other authors.

See AUTHORS for contributors.