Struct ContainerGuard 

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

RAII guard for automatic container lifecycle management.

When this guard is dropped, the container is automatically stopped and removed (unless configured otherwise via ContainerGuardBuilder).

Example

use docker_wrapper::testing::ContainerGuard;
use docker_wrapper::RedisTemplate;

#[tokio::test]
async fn test_example() -> Result<(), Box<dyn std::error::Error>> {
    let guard = ContainerGuard::new(RedisTemplate::new("test"))
        .keep_on_panic(true)  // Keep container for debugging if test fails
        .capture_logs(true)   // Print logs on failure
        .start()
        .await?;

    // Container is automatically cleaned up when guard goes out of scope
    Ok(())
}

Implementations

impl<T: Template> ContainerGuard<T>

pub fn new(template: T) -> ContainerGuardBuilder<T>

Create a new builder for a container guard.

Note: This returns a builder, not a ContainerGuard. Call .start().await on the builder to create the guard.

pub fn template(&self) -> &T

Get a reference to the underlying template.

pub fn container_id(&self) -> Option<&str>

Get the container ID, if available.

This may be None if the container was reused from a previous run.

pub fn was_reused(&self) -> bool

Check if this guard is reusing an existing container.

pub fn network(&self) -> Option<&str>

Get the network name, if one was configured.

pub async fn is_running(&self) -> Result<bool, TemplateError>

Check if the container is currently running.

Errors

Returns an error if the Docker command fails.

pub async fn wait_for_ready(&self) -> Result<(), TemplateError>

Wait for the container to be ready.

This calls the underlying template’s readiness check. The exact behavior depends on the template implementation - for example, Redis templates wait for a successful PING response.

Errors

Returns an error if the readiness check times out or the Docker command fails.

Example

let guard = ContainerGuard::new(RedisTemplate::new("test"))
    .start()
    .await?;

// Wait for Redis to be ready to accept connections
guard.wait_for_ready().await?;

pub async fn host_port(&self, container_port: u16) -> Result<u16, TemplateError>

Get the host port mapped to a container port.

This is useful when using dynamic port allocation - Docker assigns a random available host port which you can query with this method.

Errors

Returns an error if the Docker command fails or no port mapping is found.

Example

let guard = ContainerGuard::new(RedisTemplate::new("test"))
    .start()
    .await?;

let host_port = guard.host_port(6379).await?;
println!("Redis available at localhost:{}", host_port);

pub async fn logs(&self) -> Result<String, TemplateError>

Get the container logs.

Errors

Returns an error if the Docker command fails.

pub async fn stop(&self) -> Result<(), TemplateError>

Manually stop the container.

The container will still be removed on drop if remove_on_drop is enabled.

Errors

Returns an error if the Docker command fails.

pub async fn cleanup(&self) -> Result<(), TemplateError>

Manually clean up the container (stop and remove).

After calling this, the drop implementation will not attempt cleanup again.

Errors

Returns an error if the Docker commands fail.

impl<T: Template + HasConnectionString> ContainerGuard<T>

pub fn connection_string(&self) -> String

Get the connection string for the underlying service.

This is a convenience method that delegates to the template’s connection_string() implementation. The format depends on the service type (e.g., redis://host:port for Redis).

This method is only available for templates that implement HasConnectionString.

Example

let guard = ContainerGuard::new(RedisTemplate::new("redis").port(6379))
    .start()
    .await?;

// Direct access to connection string
let conn = guard.connection_string();
// Instead of: guard.template().connection_string()

Trait Implementations

impl<T: Template> Drop for ContainerGuard<T>

fn drop(&mut self)

Executes the destructor for this type.