Struct ContainerGuardBuilder 

pub struct ContainerGuardBuilder<T: Template> { /* private fields */ }

Builder for creating a ContainerGuard with custom options.

Implementations

impl<T: Template> ContainerGuardBuilder<T>

pub fn new(template: T) -> Self

Create a new builder with the given template.

pub fn remove_on_drop(self, remove: bool) -> Self

Set whether to remove the container on drop (default: true).

pub fn stop_on_drop(self, stop: bool) -> Self

Set whether to stop the container on drop (default: true).

pub fn keep_on_panic(self, keep: bool) -> Self

Set whether to keep the container running if the test panics (default: false).

This is useful for debugging failed tests - you can inspect the container state after the test fails.

pub fn capture_logs(self, capture: bool) -> Self

Set whether to capture container logs and print them on panic (default: false).

When enabled, container logs are buffered and printed to stderr if the test panics, making it easier to debug failures.

pub fn reuse_if_running(self, reuse: bool) -> Self

Set whether to reuse an existing container if already running (default: false).

This is useful for faster local development iteration - containers can be kept running between test runs.

pub fn wait_for_ready(self, wait: bool) -> Self

Set whether to automatically wait for the container to be ready after starting (default: false).

When enabled, start() will not return until the container passes its readiness check. This is useful for tests that need to immediately connect to the service.

Example

let guard = ContainerGuard::new(RedisTemplate::new("test"))
    .wait_for_ready(true)
    .start()
    .await?;
// Container is guaranteed ready at this point

pub fn with_network(self, network: impl Into<String>) -> Self

Attach the container to a Docker network.

By default, the network will be created if it doesn’t exist. Use create_network(false) to disable automatic network creation.

Example

let guard = ContainerGuard::new(RedisTemplate::new("redis"))
    .with_network("test-network")
    .start()
    .await?;
// Container is attached to "test-network"

pub fn create_network(self, create: bool) -> Self

Set whether to create the network if it doesn’t exist (default: true).

Only applies when a network is specified via with_network().

pub fn remove_network_on_drop(self, remove: bool) -> Self

Set whether to remove the network on drop (default: false).

This is useful for cleaning up test-specific networks. Only applies when a network is specified via with_network().

Note: The network removal will fail silently if other containers are still using it.

pub fn stop_timeout(self, timeout: Duration) -> Self

Set the timeout for stop operations during cleanup (default: Docker default).

This controls how long Docker waits for the container to stop gracefully before sending SIGKILL.

Example

// Fast cleanup with 1 second timeout
let guard = ContainerGuard::new(RedisTemplate::new("redis"))
    .stop_timeout(Duration::from_secs(1))
    .start()
    .await?;

// Immediate SIGKILL with zero timeout
let guard = ContainerGuard::new(RedisTemplate::new("redis2"))
    .stop_timeout(Duration::ZERO)
    .start()
    .await?;

pub async fn start(self) -> Result<ContainerGuard<T>, TemplateError>

Start the container and return a guard that manages its lifecycle.

If reuse_if_running is enabled and a container is already running, it will be reused instead of starting a new one.

If wait_for_ready is enabled, this method will block until the container passes its readiness check.

If a network is specified via with_network(), the container will be attached to that network. The network will be created if it doesn’t exist (unless create_network(false) was called).

Errors

Returns an error if the container fails to start or the readiness check times out.