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

README.md

Maven Central Build Status codecov.io

junit-docker-rule

Changelog

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 java.io.IOException;
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 {

    @Rule
    public DockerRule container = DockerRule.builder() //
            .imageName("nginx") //
            .build();

    @Test
    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

...
<dependency>
    <groupId>com.github.tdomzal</groupId>
    <artifactId>junit-docker-rule</artifactId>
    <version>0.4.1</version>
    <scope>test</scope>
</dependency>
...

3. Use in test case

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

public class MyTestCase {
    ...
    @Rule
    public DockerRule testee = DockerRule.builder()
        .imageName("nginx")
        // ... other build options (try code assist from your IDE to explore available options)
        .build();
    ...
    // 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:

...
<dependency>
    <groupId>com.github.tdomzal</groupId>
    <artifactId>junit-docker-rule</artifactId>
    <version>0.5-SNAPSHOT</version>
    <scope>test</scope>
</dependency>
...

Add OSS Sonatype snapshot repository to you pom.xml:

<project>
    ...
    <repositories>
        ...
        <repository>
            <id>ossrh</id>
            <releases><enabled>false</enabled></releases>
            <snapshots><enabled>true</enabled></snapshots>
            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
        </repository>
        ...
    </repositories>
    ...
</project>

How to build ?

Assuming you have apache maven installed it's just:

git clone https://github.com/tdomzal/junit-docker-rule.git
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.