Trait testcontainers::Image

source · [−]
pub trait Image where
    Self: Sized,
    Self::Args: ImageArgs + Clone + Debug, {
    type Args;
    fn name(&self) -> String;
    fn tag(&self) -> String;
    fn ready_conditions(&self) -> Vec<WaitFor>;

    fn env_vars(&self) -> Box<dyn Iterator<Item = (&String, &String)>> { ... }
    fn volumes(&self) -> Box<dyn Iterator<Item = (&String, &String)>> { ... }
    fn entrypoint(&self) -> Option<String> { ... }
    fn expose_ports(&self) -> Vec<u16> { ... }
    fn exec_after_start(&self, cs: ContainerState) -> Vec<ExecCommand> { ... }
}
Expand description

Represents a docker image.

Implementations are required to implement Default. The default instance of an Image should have a meaningful configuration! It should be possible to run the default instance of an Image and get back a working container!

Associated Types

A type representing the arguments for an Image.

There are a couple of things regarding the arguments of images:

  1. Similar to the Default implementation of an Image, the Default instance of its arguments should be meaningful!
  2. Implementations should be conservative about which arguments they expose. Many times, users will either go with the default arguments or just override one or two. When defining the arguments of your image, consider that the whole purpose is to facilitate integration testing. Only expose those that actually make sense for this case.

Required methods

The name of the docker image to pull from the Docker Hub registry.

Implementations are encouraged to include a tag that will not change (i.e. NOT latest) in order to prevent test code from randomly breaking because the underlying docker suddenly changed.

Returns a list of conditions that need to be met before a started container is considered ready.

This method is the 🍞 and butter of the whole testcontainers library. Containers are rarely instantly available as soon as they are started. Most of them take some time to boot up.

The conditions returned from this method are evaluated in the order they are returned. Therefore you most likely want to start with a WaitFor::StdOutMessage or WaitFor::StdErrMessage and potentially follow up with a WaitFor::Duration in case the container usually needs a little more time before it is ready.

Provided methods

There are a couple of things regarding the environment variables of images:

  1. Similar to the Default implementation of an Image, the Default instance of its environment variables should be meaningful!
  2. Implementations should be conservative about which environment variables they expose. Many times, users will either go with the default ones or just override one or two. When defining the environment variables of your image, consider that the whole purpose is to facilitate integration testing. Only expose those that actually make sense for this case.

There are a couple of things regarding the volumes of images:

  1. Similar to the Default implementation of an Image, the Default instance of its volumes should be meaningful!
  2. Implementations should be conservative about which volumes they expose. Many times, users will either go with the default ones or just override one or two. When defining the volumes of your image, consider that the whole purpose is to facilitate integration testing. Only expose those that actually make sense for this case.

Returns the entrypoint this instance was created with.

Returns the ports that needs to be exposed when a container is created.

This method is useful when there is a need to expose some ports, but there is no EXPOSE instruction in the Dockerfile of an image.

Returns the commands that needs to be executed after a container is started i.e. commands to be run in a running container.

This method is useful when certain re-configuration is required after the start of container for the container to be considered ready for use in tests.

Implementors