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.
@Container
to be used as a meta-annotation (#6914) @eddumelendezMySQLContainer
are now automatically compatible with their corresponding images with the library
prefixMySQLContainer<?> mysql = new MySQLContainer<>("library/mysql");
testcontainers/vnc
has been bumped to version 1.3.0, which brings ARM support.tc
prefix has been added to display all container logs or tc.<image-name:tag>
for a specific one. Check the logging docs.WaitStrategy
, ShellStrategy
. It can also be used by calling Wait.forSuccessfulCommand(<command>)
Jib has been integrated to Testcontainers in order to take advantage of the nice API it provides to create containers
GenericContainer<?> busybox = new GenericContainer<>(
new JibImage(
"busybox:1.35",
jibContainerBuilder -> {
return jibContainerBuilder.setEntrypoint("echo", "Hello World");
}
)
)
.withStartupCheckStrategy(new OneShotStartupCheckStrategy().withTimeout(Duration.ofSeconds(3)))
In order to use CrateDBContainer
, declare the dependency in your pom.xml/build.gradle
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>cratedb</artifactId>
<version>1.18.0</version>
<scope>test</scope>
</dependency>
testImplementation "org.testcontainers:cratedb:1.18.0"
Choose a crate image version and use it as declared below with your postgres driver
CrateDBContainer cratedb = new CrateDBContainer("crate:5.2.5");
In order to use SolaceContainer
, declare the dependency in your pom.xml/build.gradle
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>solace</artifactId>
<version>1.18.0</version>
<scope>test</scope>
</dependency>
testImplementation "org.testcontainers:solace:1.18.0"
Now, you can use a Solace PubSub running in a container and connecting via AMQP by doing the following:
SolaceContainer solace = new SolaceContainer("solace/solace-pubsub-standard:10.2");
solace.start();
Session session = createSession(
solaceContainer.getUsername(),
solaceContainer.getPassword(),
solaceContainer.getOrigin(Service.AMQP)
);
More information about SolaceContainer
can be found in the documentation.
Starting with cockroachdb/cockroach:22.1.0
, there is support for setting the username, password and database name via environment variables. Now, the Testcontainers module provides convenient setters:
CockroachContainer cockroach = new CockroachContainer("cockroachdb/cockroach:22.1.0")
.withUsername("test_user")
.withPassword("test_password")
.withDatabaseName("test_database");
Google has released a new image which supports ARM and therefore BigtableEmulatorContainer
, DatastoreEmulatorContainer
, FirestoreEmulatorContainer
, PubSubEmulatorContainer
now support it as well.
So, if previously you were doing something like
DockerImageName.parse("gcr.io/google.com/cloudsdktool/google-cloud-cli:380.0.0-emulators")
.asCompatibleSubstituteFor("gcr.io/google.com/cloudsdktool/cloud-sdk");
Now, you can simply do
DockerImageName.parse("gcr.io/google.com/cloudsdktool/google-cloud-cli:380.0.0-emulators");
@Testcontainers
offers a new attribute parallel
, which start those containers classes annotated by @Container
@Testcontainers(parallel = true)
class ParallelTest {
@Container
private static final PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15-alpine")
.withCopyFileToContainer(MountableFile.forClasspathResource("db.sql"), "/docker-entrypoint-initdb.d/")
.withNetwork(network)
.withNetworkAliases("postgres");
@Container
private static final ToxiproxyContainer toxiproxy = new ToxiproxyContainer("ghcr.io/shopify/toxiproxy:2.5.0")
.withNetwork(network);
}
Self-managed or Kraft mode (a.k.a Zookeeperless) support has been added
KafkaContainer kafka = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.0.1")).withKraft()
SERVICES
environment variable became optional in version 0.13.0 and instead LocalStack will initialize a service once the first request is served. So, nowadays LocalStackContainer
can be used just like this:
LocalStackContainer localstack = new LocalStackContainer("localstack/localstack:2.0.0");
Also, LocalStack module supports version 2.0. It is highly recommended to use the latest version of LocalStack images. Last but not least, dependency on AWS SDK V1 was dropped. So, that means by upgrading to version 1.18.0, the dependency can be removed if not used directly.
MongoDBContainer
by default has been enabling ReplicaSet mode. Starting in this version, sharding has been added.
MongoDBContainer mongodb = new MongoDBContainer("mongo:6")
.withSharding();
Selenium 4 has built-in support for Microsoft Edge (which is based on Chromium) and now it is supported by BrowserWebDriverContainer
as well:
BrowserWebDriverContainer<?> edge = new BrowserWebDriverContainer<>("selenium/standalone-edge:4.8.0")
.withCapabilities(new EdgeOptions());
allowInsecure()
on HttpWaitStrategy
for non-localhost Docker daemon (#6314) @kiviewThis release has been made possible through the efforts of 20 contributors. The Testcontainers does not cease to amaze us, thanks to everyone of you and thanks for the ongoing support and collaboration π₯°.
This release brings a lot of database love with 2 new modules, and as always a couple of bug fixes and improvements
QuestDB, is a high-performance, open-source SQL database for applications in financial services, IoT, machine learning, DevOps and observability.
var container = new QuestDBContainer("questdb/questdb:6.5.3")
container.start()
var connectionUrl = container.getHttpUrl()
// use the connectionUrl and start testing!
YugabyteDB, is a modern distributed SQL database for transactional cloud native applications. PostgreSQL compatible. It offers two APIs, SQL and CQL.
var container = new YugabyteDBYSQLContainer("yugabytedb/yugabyte:2.14.4.0-b26");
container.start()
var jdbcUrl = container.getJdbcUrl();
// use the jdbcUrl and start testing!
var container = new YugabyteDBYCQLContainer("yugabytedb/yugabyte:2.14.4.0-b26");
container.start()
var contactPoint = container.getContactPoint();
// use the contactPoint and start testing!
setCustomContent
and withCustomContent
at NginxContainer
(#5997) @eddumelendezsetCustomContent
and withCustomContent
at NginxContainer
(#5997) @eddumelendezgradle/gradle-build-action
(#6121) @eddumelendezWarning Version 1.17.4 was released upgrading slf4j-api to version 2.x. This dependency has been reverted to 1.17.x.
This release has been made possible through the efforts of whopping 23 contributors, wow! π€―
Besides 3 new modules, this release brings a couple of bugfixes, improved compatibility and resilience in certain scenarios, better defaults and more configurability.
You might also notice many PRs related to the documentation, templates for PRs and issues, and automation regarding OSS contributions. Testcontainers has always been a project with a lot of involvement by the community and we are very proud of this. Thatβs why want to make contributing to Testcontainers a great experience, no matter if you raise an issue, submit a PR or initiate a discussion in GitHhub Discussions.
Redpanda, a Kafka-compatible streaming platform, recently added a special dev-container
mode to their container image, that allows even faster startup times. A great reason to work in a Testcontainers module that leverages this flag by default to give you a great integration testing experience when using Redpanda. And of course, using Redpanda with Testcontainers is as easy and convenient as you are used to:
var container = new RedpandaContainer("docker.redpanda.com/vectorized/redpanda:v22.2.1")
container.start()
var connectionUrl = container.getBootstrapServers()
// use the connectionUrl and start testing!
You can check out the docs to learn more.
With TiDB, we are adding support for a new database module. As with other databases that can be accessed via JDBC, you can leverage Testcontainersβ special JDBC URL integration:
jdbc:tc:tidb:v6.1.0:///databasename
Transferable.of(String, int)
(#5741) @eddumelendezDockerComposeContainer
configurable (#5588) @henri-tremblaydisque-job-queue
and mongodb-container
examples (#5782) @eddumelendezorg.testcontainers.shaded.*
package and upgrade deps (#5775) @eddumelendeztestCompileOnly
instead of testCompileClasspath
(#5849) @eddumelendezdisque-job-queue
and mongodb-container
examples (#5782) @eddumelendezorg.junit.platform.commons.util
(#5729) @eddumelendezTestInstances
API from JUnit Jupiter (#2719) @tobiasstadlerdeleteOnExit
is false (#5391) @kiviewroot
user password section to docs (#5498) @kiviewWhile this release had a major focus on stability, we managed to optimize the startup sequence and it should make your tests even faster!
Here is what it takes to have a Redis up and running with Testcontainers, end-to-end from the test's start to an instance ready to be connected: Before (1.17.1): 2.4s Before (1.17.2): 1.7s π
And here is just the "initialize Testcontainers" measurements:
Before (1.17.1): 1102ms Before (1.17.2): 928ms
How we did it? We noticed that we can cache a couple of Docker responses, plus also removed now obsolete (yet expensive!) disk space check.
GenericContainer
in RyukResourceReaper
(#5358) @bsideupindexServerAddress
from Docker's /info
(#5347) @bsideupDOCKER_HOST
in DockerClientProviderStrategy
(#5357) @bsideupTransportConfig
to read DOCKER_HOST
env variable for DockerComposeContainer
(#5276) @eddumelendezLocalImagesCache
(#5356) @bsideupcore
tests in parallel (#5365) @bsideupcreateSubscription()
(#5350) @felix-seifertgetHost
instead of getContainerIpAddress()
(#5277) @eddumelendezThis new version of Testcontainers comes packed with many new features and quality-of-life improvements, so we appropriately bumped the version to 1.17.0
.
Having started its Open Source life as its own 3rd-party Testcontainers library, we are very happy to welcome HiveMQ into the main repository. Now, using HiveMQ as part of your integration tests is as simple as a couple of lines of Java code:
@Container
HiveMQContainer hivemq = new HiveMQContainer(DockerImageName.parse("hivemq/hivemq-ce:2021.3"));
hivemq.start();
Mqtt5BlockingClient client = Mqtt5Client.builder()
.serverPort(hivemqCe.getMqttPort())
.serverHost(hivemqCe.getHost())
.buildBlocking();
client.connect();
Check out the docs to learn more about its many features!
Many Testcontainers user love the convenience Ryuk brings to Testcontainers: No matter what you do in your integration tests, Ryuk has got you covered and will cleanup all Docker resources created by Testcontainers after your test run is finished.
But some users operate Testcontainers in environments which do not support our container-based Ryuk implementation. So far their only option was to disable Ryuk alltogether.
Coming with this release, Testcontainers will now fallback to a JVM based resource-cleanup implementation in case of Ryuk being disabled. While this won't be as robust as the Ryuk container based implementation in all circumstances, it is nevertheless a great addition and acts as a useful compromise.
getContainerIpAddress
(#5247) @kiviewcheckAndPullImage
with RemoteDockerImage
(#5148) @bsideupgetTestHostIpAddress
and getContainerIpAddress
(#5149) @bsideupByzer
. (#5125) @hellozeppINCUBATING
note from CockroachDB module docs (#4963) @kiviewdocker-java
3.2.13 (#5045) @bsideupTestcontainers 1.16.3 includes many changes, but there are two key highlights in this release:
We've had plenty of feedback from users wanting to use Testcontainers to help test Kubernetes components. In particular, this is useful for people developing Kubernetes controllers/operators, who need something more than just a mocked Kubernetes API. In this release we're bringing the k3s module, which gives you a neat way to spin up the K3S lightweight Kubernetes inside of a container. We believe that k3s hits a sweet spot for ease of use and performance, so is a good option for testing Kubernetes components.
Now, launching a lightweight single-node Kubernetes cluster within your tests is easy as:
K3sContainer k3s = new K3sContainer(DockerImageName.parse("rancher/k3s:v1.21.3-k3s1"));
k3s.start();
String kubeConfigYaml = k3s.getKubeConfigYaml();
ApiClient client = Config.fromConfig(new StringReader(kubeConfigYaml));
// now use `client` to talk to your cluster!
Check out the docs to find out more!
Selenium 4 was announced a while back, but we needed to make some changes to Testcontainers' Selenium/Webdriver module for compatibility. We're happy to announce that these changes have now been made, so you can now use Selenium 4 with Testcontainers!
As part of this upgrade we have to drop compatibility with Selenium 2, but believe that this will not have any practical impact.
READ_ONLY_REMOTE_GRADLE_CACHE
to avoid wrong cache hits (#4853) @kiview