dockertest 0.0.1

A library to control docker containers when running your integration tests.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# dockertest-rs

Run docker containers in your Rust integration tests.

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

* Ensure one or more docker containers are running before your test executes.
* Teardown each started container after test is terminated (both successfully and on test failure).
* Control origin and management of `Image`s used for your docker containers and the pull policy thereof.
Supported sources are:
  * Local - must be present on the host machine.
  * DockerHub - fetch from the offical DockerHub.
  * Custom - custom docker registry. (Currently not implemented)

## Architecture

This shows the various stages of components in dockertest-rs.

```
Image -> Composition -> PendingContainer -> RunningContainer
```

An `Image` represents a built image from docker that we may attempt to start a container of.

A `Composition` is a specific instance of an `Image`, with its runtime parameters supplied.

The `PendingContainer` represents a docker container who is either built or running,
but not yet in the control of the test body.

Once the test body executes, all containers will be available as `RunningContainer`s and
all operations present on this object will be available to the test body.

## Example

 ```rust
use diesel::pg::PgConnection;
use diesel::prelude::*;
use dockertest::image::{PullPolicy, Source};
use dockertest::{Composition, DockerTest};

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_composition(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"
    );
});
```

## Development

This library is in its initial inception. Breaking changes are to be expected.

## Testing

Testing this library requires the following:
* docker daemon available on localhost.
* Capable of compiling `diesel` with the postgres feature.

Run the tests with the following command:
```
cargo test -- --test-threads=1
```

Caveats that may fail tests:
* Port `5432` is already taken for postgres on the host.
* Exited `hello-world` containers on the system. This will currently make removing
old images fail and many tests will fail. This is an area we need to improve.

## TODO:
* Document limits when spawning stuff in test body.
* Document handle concept.
* Break up Container into PendingContainer and RunningContainer.
* Document and implement port mapping for random host port assignment.