A Docker test fixture system available for use from any JUnit tests,
JenkinsRule in the Jenkins functional test harness.
The use case is for tests which need to connect to some kind of self-contained (Linux) service which cannot be easily hosted on the test machine itself. Typical examples would include Jenkins agents with specific software packages preloaded, or SCM servers which it would be hard to launch portably from any environment.
Another reason to run some things inside Docker is to simply simulate cases where code runs remotely, with different filesystem paths, user accounts, etc.
Note that the typical architecture is that of a single machine with a local Docker daemon. Tests are assumed to be running on the host itself; i.e., this is unlike a multicontainer test system you might orchestrate with Docker Compose.
Probably this library should be deprecated in favor of testcontainers.org.
Defining a fixture
Each fixture is defined in terms of a
DockerContainer subtype with a
This type typically exposes various methods needed to interact with the running fixture.
A fixture also needs to define a
Dockerfile in the resources directory.
If a fixture class is
then by default the definition must be located at
(In the case of inner classes, dollar sign (
$) is replaced with a slash (
The same directory may contain other files
ADDed to or
COPYd into the image, as usual with
Subclassing another fixture
If your fixture extends another one rather than
you can inherit behaviors while adding new ones.
In this case the
FROM directive of your
Dockerfile should specify the image of the parent,
as detailed in the Javadoc for
Running a fixture
Simply add to your (JUnit 4) test:
@ClassRule public static DockerClassRule<MyContainer> docker = new DockerClassRule<>(MyContainer.class);
If and when you wish to start using the fixture from a test case, call the
This will launch the container and give you a handle you can use to call fixture methods.
If the test is run on a system which cannot run the
the test will be treated as skipped automatically.
When the test case finishes, the container is stopped and cleaned up automatically.
When you specify
ports in the annotation, you allow services in the fixture to be accessed from the test.
Always use the
port methods on each container to determine where to make the actual connection.
If you want your docker containers to connect to a custom network you can set the environment variable
DOCKER_FIXTURES_NETWORK to the name of the network you want to use.
mercurial-plugin sources for a complete example of defining and using a fixture, including inheritance:
src/test/java/hudson/plugins/mercurial/MercurialContainer.javadeclares the fixture, along with some helper nethods
src/test/resources/hudson/plugins/mercurial/MercurialContainer/Dockerfiledefines the fixture’s contents
src/test/java/hudson/plugins/mercurial/MercurialContainerTest.javademonstrates its usage
See GitHub Releases. (For 1.8 and earlier, see the old changelog.