top of page

Programmers T-shirts

Test your Docker Container with Testcontainers

Updated: Feb 26, 2021

In this tutorial, we will explain how to test Docker Container with Testcontainers.

Testcontainers is a popular and powerful library especially designed for Docker Container tests. Even though it was written in Java, you can test any container, regardless the language it was written in.

The Testcontianers project:

The Docker project:

What is Testcontainers?

It is a Java library that provides the ability to interact with the Docker Engine on your machine.

With Testcontainers the state of the containers that you are running are loaded into Java objects, hence you can configure containers, start them, get any information you want about them (e.g IP, exposed ports), stop them, and more.

The most basic object in Testcontainers is the GenericContainer object.

Here is an example of an Nginx container, configured with GenericContainer

When the program is running, nginxContainer is an instance of an object that stores all information on that Docker container. The same information that you get when running docker inspect against it.

Think about the power this library gives - sure you can run Docker containers without Testcontainers, for example with "Docker file" or "docker-compose", but to know which ports are exposed, or what are the containers' IPs, that requires to parse the "docker ps" and "docker inspect" output. With Testcontainers all of that is much more simple.

With that said, let's continue with a practical example.

We are going to create a test that starts Nginx and verifies if it is up and running.

Code can be downloaded from here:

Code Explanation

For the Java testing FW, I'm using Junit, but you can use any test framework you like.

At the @Before method, I'm configuring the Nginx Container.

I'm providing the following parameters:

1. Image Name

It tells the Docker Engine which image to use when the "docker pull" executes. Under the hood, the Docker Engine is running

docker pull nginx:latest

2. Alias Name

Just like a DNS name. It assigns the nginx_server string as the container's IP.

3. WithExposedPorts()

Expose Port 80. It is exactly as we run "docker run -p 8087:80 nginx" from the command line. The only difference is that we don't tell it the exposed port. Testcontainers will decide that. We'll use the getMappedPort(80) method to get that.

Testcontainers will search for a free Port and use it. It much safer - it eliminates any port collisions that might happen with multiple containers.

Then we start the container with the start() method.

Now that the container is running we execute the getMappedPort(80). let's assume for this example the exposed port 80 is mapped to 3245.

Once we have that, we can send an HTTP GET request to https://localhost:3245 and we should get the Nginx Welcome Page

At this point, we use the Assert.assertTrue() method to validate the title of that web page.

I hope you found this tutorial valuable,



Practical Programming Tutorials for Developers

Work Desk

The SW Developer

The SW Developer was built in order to provide Practical and Simple Tutorials for programmers.

Created by Dotan Raz, Michael Rodov & Kobi Atiya

  • github
  • LinkedIn


Programmers T-shirts

bottom of page