Simple docker container starter as JUnit Rule
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

Maven Central Build Status



see changelog

What is it ?

Simple JUnit Rule starting docker container right for your test case:

package org.example;

import static org.hamcrest.CoreMatchers.containsString;
import static org.junit.Assert.assertThat;

import org.apache.http.client.fluent.Request;
import org.junit.Rule;
import org.junit.Test;
import pl.domzal.junit.docker.rule.DockerRule;

public class HomepageExampleTest {

    public DockerRule container = DockerRule.builder() //
            .imageName("nginx") //

    public void shouldExposePorts() throws InterruptedException, IOException {

        // url container homepage will be exposed under
        String homepage = "http://"+container.getDockerHost()+":"+container.getExposedContainerPort("80")+"/";

        // use fluent apache http client to retrieve homepage content
        String pageContent = Request.Get(homepage).connectTimeout(1000).socketTimeout(1000).execute().returnContent().asString();

        // make sure this is indeed nginx welcome page
        assertThat(pageContent, containsString("Welcome to nginx!"));


Container is started just before your test case and destroyed after.

It was created as side product and I'll be more than happy if you'll find it useful !

What docker options it currently supports ?

You can:

  • use it as JUnit @Rule or @ClassRule
  • specify image name/tag
  • specify container name (equivalent of command line --name)
  • define links to other containers (--link)
  • pass environment variables (--env or -e)
  • publish all exposed port to dynamically allocated host ports (--publish-all or -P)
  • publish specified container ports to specified host ports (-p - tcp or udp, no port ranges support yet)
  • mount host directory as a data volume (--volume or -v - also works for workstation dirs to boot2docker container with restriction that dir must be under user homedir)
  • specify extra /etc/hosts entries (--add-host)
  • access container stderr and stdout (forwarded to java System.err and System.out by default)
  • wait for message or sequence of messages in container output at container start

See usage examples in test cases.

Also - just type DockerRule.builder(). .. and try code assist in your favorite IDE (Alt-Enter in IDEA, Ctrl-Space in Eclipse) to see all possible options.

What do I need to use it ?

1. Install Docker (of course)

Docker should be installed and configured - which in general means you must have docker variables (DOCKER_HOST, DOCKER_MACHINE_NAME, ...) available in runtime. Preferred way to set them is via docker-machine command.

2. Declare dependency in pom.xml


3. Use in test case

import pl.domzal.junit.docker.rule.DockerRule;

public class MyTestCase {
    public DockerRule testee = DockerRule.builder()
        // ... other build options (try code assist from your IDE to explore available options)
    // your test cases

What else should I know for now ?

  • It uses java docker client from Spotify
  • Build and tested with docker 1.9
  • This is work in progress (but all features are verified by tests)

How to use latest (SNAPSHOT) version

Change dependency to:


Add OSS Sonatype snapshot repository to you pom.xml:


How to build ?

Assuming you have apache maven installed it's just:

git clone
cd junit-docker-rule
mvn install -DskipTests

or, if you want to build with tests - substitute last command with:

mvn install

Of course test cases will run only if you have working docker environment.