#docker #integration #test #container


A library to control docker containers when running your integration tests

7 releases

0.1.2 Sep 15, 2020
0.1.1 Sep 11, 2020
0.1.0 May 29, 2020
0.0.4 Mar 19, 2020
0.0.2 Oct 25, 2019

#66 in Testing

Download history 19/week @ 2020-06-09 39/week @ 2020-06-16 26/week @ 2020-06-23 50/week @ 2020-06-30 5/week @ 2020-07-07 10/week @ 2020-07-14 10/week @ 2020-07-21 3/week @ 2020-07-28 1/week @ 2020-08-04 22/week @ 2020-08-11 9/week @ 2020-08-18 16/week @ 2020-08-25 35/week @ 2020-09-01 38/week @ 2020-09-08 33/week @ 2020-09-15 6/week @ 2020-09-22

81 downloads per month

MIT license

2.5K SLoC


Control docker containers from a rust ingegration test suite. Full fledge management support with automatic cleanup.

This crate provides the following features for your docker testing needs:

  • Ensure docker containers are invoked and running according to WaitFor strategy.
  • Customize your own or use one of the batteries included.
  • Interact with the RunningContainer in the test body through its ip address.
  • Setup inter-container communication with inject_container_name into environment variables.
  • Teardown each started container after test is terminated - both successfully and on test failure.
  • Concurrent capabilies. All tests are isolated into separate networks per test, with uniquely generated container names.

See the crate documentation for extensive explainations.


The canonical example and motivation for this crate can be expressed with the following use-case example - host a database used by your test in a container, which is fresh between each test.

use diesel::pg::PgConnection;
use diesel::prelude::*;
use dockertest::waitfor::{MessageSource, MessageWait};
use dockertest::{Composition, DockerTest, PullPolicy, Source};
use std::rc::Rc;

// Define our test
let source = Source::DockerHub(PullPolicy::IfNotPresent);
let mut test = DockerTest::new().with_default_source(source);

// Define our Composition - the Image we will start and end up as our RunningContainer
let mut postgres = Composition::with_repository("postgres").with_wait_for(Box::new(MessageWait {
   message: "database system is ready to accept connections".to_string(),
   source: MessageSource::Stderr,
   timeout: 20,
postgres.env("POSTGRES_PASSWORD", "password");

// Run the test body
test.run(|ops| async move {
   let container = ops.handle("postgres");
   let conn_string = format!("postgres://postgres:password@{}:{}", container.ip(), 5432);
   let pgconn = PgConnection::establish(&conn_string);

   // Perform your database operations here
       "failed to establish connection to postgres docker"


Testing this library requires the following:

  • docker daemon available on localhost.
  • Capable of compiling diesel with the postgres feature.
  • Set DOCKERTEST_BUILD_TEST_IMAGES=1 in your environment, will triger the test images to be built.

Tests are designed to be run in parallel, and should not conflict with existing system images. Local images are build with repository prefix dockertest-rs/.


~278K SLoC