Crate dockertest

dockertest is a testing and automation abstraction for Docker.

The primary utility for this crate is to easily employ docker in test infrastructure, with the following key features:

• Ensure that the docker container is running prior to test code.
• Support multiple containers per test.
• Support multiple containers from same image, with different configurations.
• Retrieve Image from remote source according to PullPolicy.
• Support multiple Remote registries, which can be individually assigned to Image.
• Dictate how each Container is created and operated from an Image through a Composition.
• This allows us to have muliple containers with the same Image, but with different start conditions.
• Control each Composition condition for when it is deemed running through WaitFor.
• There exists multiple convenient WaitFor implementations, however, user-supplied implementations through the trait can be provided.
• Control the StartPolicy of each Composition. For inter-dependant containers, a Strict policy can be sat, and they will be started in succession until their WaitFor condition is met, according to the order they where added to DockerTest.

Once the DockerTest test is run, the provided closure will be ran once all predicates for each supplied Composition has successfully been fulfilled. The closure is provided with one DockerOperations parameter, allowing the test body to interact with DockerTest and each individual Container. The reference to each Container is queried through a handle, which is the user provided container name, specified in Composition through with_container_name.

Once the reference to a Container is retrieved, one may call all methods public methods to interact with it. This includes retrieving the host_port that a port in the Container is mapped to on the host.

Handle - referencing the same container throughout your test

dockertest assigns a handle to each Composition, which carries over to a RunningContainer. When writing a test, one will reference the intended object through its handle.

By default, the handle is auto-assigned to be the repository name of the Composition.

The user may change the handle by changing the container name (as seen from the user

• the final container name will be disambiguated for each dockertest) through the with_container_name builder method on Composition.

If the test includes multiple Compositions with the same handle, attempting to reference one that has multiple occurrences will fail the test (e.g., panic).

WaitFor - Control how to determine when the container is ready

Each Composition require a trait object of WaitFor whose method wait_for_ready must resolve until the container can become a RunningContainer. This trait may be implemented and supplied to Composition through with_wait_for.

Example

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

let repo = "postgres";
let postgres = Composition::with_repository(repo);

test.add_instance(postgres);

test.run(|ops| {
    let container = ops.handle("postgres").expect("retrieve postgres container");
    let host_port = container.host_port(5432);
    let conn_string = format!("postgres://postgres:postgres@localhost:{}", host_port);
    let pgconn = PgConnection::establish(&conn_string);

    assert!(
        pgconn.is_ok(),
        "failed to establish connection to postgres docker"
    );
});

Modules

error	Custom error types library.
waitfor	Contains WaitFor trait used to determine when a PendingContainer has started and all the default implementations of it.

Structs

Composition	Represents an instance of an Image. The Composition is used to specialize an Image whose name, version, tag and source is known, but before one can create a RunningContainer from an Image, it must be augmented with information about how to start it, how to ensure it has been started, environment variables and runtime commands. Thus, this structure represents the concrete instance of an Image that will be started and become a RunningContainer.
Container	Represents a docker container. This object lives in two phases:
DockerOperations	Represents all operations that can be performed against all the started containers and docker during a test.
DockerTest	Represents the docker test environment, and keep track of all containers that should be started.
Image	Represents a docker image, and describes where its stored (locally or remote).
Remote	Represents a remote registry, currently only described by an address.

Enums

PullPolicy	The policy for pulling from remote locations.
Source	Represents the source of an Image.
StartPolicy	Specifies the starting policy of a Composition. A Strict policy will enforce that the Composition is started in the order it was added to DockerTest. A Relaxed policy will not enforce any ordering, all Compositions with a Relaxed policy will be started concurrently.