Struct dockertest::DynamicSpecification

pub struct DynamicSpecification { /* private fields */ }

A full specification of a container whose lifecycle is partially managed by dockertest.

A dynamic container specification has the ability to create and re-use an existing container matching its properties, but will never attempt to terminate the container.

Implementations

impl DynamicSpecification

pub fn with_repository<T: ToString, S: ToString>( repository: T, container_name: S, ) -> Self

Create a new TestSuiteSpecification based on the image pointed to by this repository.

The provided container_name will be used to locate an existing container, or create the container if it does not exist.

pub fn with_image<S: ToString>(image: Image, container_name: S) -> Self

Create a new TestBodySpecification based on provided Image.

The provided container_name will be used to locate an existing container, or create the container if it does not exist.

impl DynamicSpecification

pub fn set_start_policy(self, start_policy: StartPolicy) -> Self

Sets the StartPolicy when having to create and spin up this container.

The start policy is needed to determine the order of containers to start in order to successfully start dependant containers.

If not specified, StartPolicy::Relaxed is the default policy.

pub fn replace_env(self, env: HashMap<String, String>) -> Self

Assign the full set of environment variables into the OperationalContainer.

Each key in the map should be the environmental variable name and its corresponding value will be set as its value.

This method replaces all existing environment variables previously provided.

pub fn modify_env<T: ToString, S: ToString>( &mut self, name: T, value: S, ) -> &mut Self

Modify a single environment variable available for the OperationalContainer.

A replace_env call will undo what has been configured individually with this method.

pub fn replace_cmd(self, cmd: Vec<String>) -> Self

Assign the full set of command vector entries for the OperationalContainer.

This method replaces all existing command vector entries previously provided.

pub fn tmpfs<T: ToString>(&mut self, path: T) -> &mut Self

Appends the tmpfs mount path to the current set of tmpfs mount paths.

Details:

• Only available on linux.
• Size of the tmpfs mount defaults to 50% of the hosts total RAM.
• Defaults to file mode ‘1777’ (world-writable).

pub fn replace_tmpfs(self, paths: Vec<String>) -> Self

Replaces all the tmpfs mount paths for the OperationalContainer

This method replaces all existing tmpfs mount paths previously provided.

See tmpfs for details.

pub fn append_cmd<T: ToString>(&mut self, cmd: T) -> &mut Self

Append a command entry into the command vector.

A replace_cmd call will undo what has been configured individually with this method.

pub fn set_publish_all_ports(self, publish: bool) -> Self

Allocate an ephemeral host port for all exposed ports specified in the container.

Mapped host ports can be found via OperationalContainer::host_port method.

pub fn modify_port_map(&mut self, exported: u32, host: u32) -> &mut Self

Add a host port mapping to the container.

This is useful when the host environment running docker cannot support IP routing within the docker network, such that test containers cannot communicate between themselves. This escape hatch allows the host to be involved to route traffic.

This mechanism is not recommended, as concurrent tests utilizing the same host port will fail since the port is already in use. If utilizing the host is needed, it is recommended to use set_publish_all_ports.

This function can overwrite previously mapped ports, if invoked repeatedly.

pub fn privileged(&mut self, privileged: bool) -> &mut Self

Specify the privilege mode of the started container.

This may be required for some containers to run correctly. See the corresponding docker reference on this topic.

pub fn set_privileged(self, privileged: bool) -> Self

Specify the privilege mode of the started container.

This may be required for some containers to run correctly. See the corresponding docker reference on this topic.

pub fn set_handle<T: ToString>(self, handle: T) -> Self

Specify a string handle used to retrieve a reference to the OperationalContainer within the test body.

This value defaults to the repository name of the image used when constructing this container specification.

pub fn replace_network_alias(self, aliases: Vec<String>) -> Self

Assign the full set of container name aliases on the docker network.

pub fn append_network_alias(&mut self, alias: String) -> &mut Self

Add a single container name alias on the docker network.

pub fn set_wait_for(self, wait: Box<dyn WaitFor>) -> Self

Set the WaitFor trait object for this container specification.

If not specified, RunningWait will be the default value.

pub fn set_log_options(self, log_options: Option<LogOptions>) -> Self

Specify how to handle logging from the container.

If not specified, LogAction::Forward, LogPolicy::OnError and LogSource::StdErr is enabled. To clear the default options, invoke this method with a None value.

pub fn modify_named_volume<T: ToString, S: ToString>( &mut self, volume_name: T, path_in_container: S, ) -> &mut Self

Add a named volume to this container.

Named volumes can be shared between multiple containers. By specifying the same volume name across multiple container specifications, both container will be given access to the same volume.

• path_in_container must be an absolute path.

pub fn modify_bind_mount<T: ToString, S: ToString>( &mut self, host_path: T, path_in_container: S, ) -> &mut Self

Add a bind mount to this container.

A bind mount only exists for a single container, and maps a given file or directory from the host into the container.

Use named volumes if you require shared data access between containers.

• host_path can either point to a file or directory that must exist on the host.
• path_in_container must be an absolute path.

pub fn inject_container_name<T: ToString, E: ToString>( &mut self, handle: T, env: E, ) -> &mut Self

Inject the full, generated container name identified by handle into this container specification environment.

This is used to establish inter communication between running containers controlled by dockertest. This is traditionally established through environment variables for connection details, and thus the DNS resolving capabilities within docker will map the container name into the correct IP address.

To correctly use this feature, the StartPolicy between the dependant containers must be configured such that these connections can successfully be established. Dockertest will not make any attempt to verify the integrity of these dependencies.

Trait Implementations

impl Clone for DynamicSpecification

fn clone(&self) -> DynamicSpecification

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ContainerSpecification for DynamicSpecification

fn into_composition(self) -> Composition

Convert the specification of a container into a Composition.

impl Debug for DynamicSpecification

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.