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

#![deny(missing_debug_implementations)]
#![warn(rust_2018_idioms)]
#![cfg_attr(docsrs, deny(rustdoc::broken_intra_doc_links))]
#![cfg_attr(docsrs, feature(doc_cfg))]

//! A library for integration testing against docker containers from within Rust.
//!
//! This crate is the official Rust language fork of [`Testcontainers`][tc_website].
//!
//! Tests should be self-contained and isolated. While this is usually easy for unit-tests, integration-tests typically require a more complex environment.
//! The testcontainers ecosystem facilitates self-contained and isolated integration tests. It allows to easily spin up Docker containers from within your tests and removes them afterwards.
//!
//! A very typical usecase for testcontainers are integration-tests of persistence layers. These require an actual database to be present. Using testcontainers, your tests can spin up database containers themselves, without the need for any other setup.
//!
//! # Main benefits
//!
//! - Run integration tests in parallel (because each test sets up its own environment)
//! - Run integration tests the same way you run unit tests (`cargo test` and you are fine)
//!
//! # Usage
//!
//! Unsurprisingly, working with testcontainers is very similar to working with Docker itself.
//!
//! First, you need to define the [`Image`] that you want to run, and then simply call the `start` method on it from either the [`AsyncRunner`] or [`SyncRunner`] trait.
//! This will return you [`ContainerAsync`] or [`Container`] respectively.
//! Containers implement `Drop`. As soon as they go out of scope, the underlying docker container is removed.
//! To disable this behavior, you can set ENV variable `TESTCONTAINERS_COMMAND` to `keep`.
//!
//! See examples in the corresponding runner ([`AsyncRunner`] and [`SyncRunner`])
//!
//! ### Docker host resolution
//!
//! You can change the configuration of the Docker host used by the client in two ways:
//! - environment variables
//! - `~/.testcontainers.properties` file (a Java properties file, enabled by the `properties-config` feature)
//!
//! ##### The host is resolved in the following order:
//!
//! 1. Docker host from the `tc.host` property in the `~/.testcontainers.properties` file.
//! 2. `DOCKER_HOST` environment variable.
//! 3. Docker host from the "docker.host" property in the `~/.testcontainers.properties` file.
//! 4. Else, the default Docker socket will be returned.
//!
//! ### Docker authentication
//!
//! Sometimes the Docker images you use live in a private Docker registry.
//! For that reason, Testcontainers for Rust gives you the ability to read the Docker configuration and retrieve the authentication for a given registry.
//! Configuration is fetched in the following order:
//!
//! 1. `DOCKER_AUTH_CONFIG` environment variable, unmarshalling the string value from its JSON representation and using it as the Docker config.
//! 2. `DOCKER_CONFIG` environment variable, as an alternative path to the Docker config file.
//! 3. else it will load the default Docker config file, which lives in the user's home, e.g. `~/.docker/config.json`.
//!
//! # Ecosystem
//!
//! `testcontainers` is the core crate that provides an API for working with containers in a test environment.
//! The only image that is provided by the core crate is the [`GenericImage`], which is a simple wrapper around any docker image.
//!
//! However, it does not provide ready-to-use modules, you can implement your [`Image`]s using the library directly or use community supported [`testcontainers-modules`].
//!
//! # Usage in production code
//!
//! Although nothing inherently prevents testcontainers from being used in production code, the library itself was not designed with that in mind.
//! For example, many methods will panic if something goes wrong but because the usage is intended to be within tests, this is deemed acceptable.
//!
//! [tc_website]: https://testcontainers.org
//! [`Docker`]: https://docker.com
//! [`AsyncRunner`]: runners::AsyncRunner
//! [`SyncRunner`]: runners::SyncRunner
//! [`testcontainers-modules`]: https://crates.io/crates/testcontainers-modules

pub mod core;
pub use crate::core::{containers::*, CgroupnsMode, Image, ImageArgs, RunnableImage};

#[cfg(feature = "watchdog")]
#[cfg_attr(docsrs, doc(cfg(feature = "watchdog")))]
pub(crate) mod watchdog;

/// All available Docker images.
mod images;
pub use images::generic::GenericImage;

pub mod runners;