Struct CleanroomEnvironment 

pub struct CleanroomEnvironment { /* private fields */ }

Simple environment wrapper around existing infrastructure

Implementations

impl CleanroomEnvironment

pub async fn new() -> Result<Self>

Create a new cleanroom environment with default configuration

pub async fn with_config(config: Option<CleanroomConfig>) -> Result<Self>

Create a new cleanroom environment with optional configuration

Arguments

• config - Optional CleanroomConfig. If None, uses default settings. If Some, uses configured default_image for test containers.

Returns

• Result<Self> - CleanroomEnvironment instance

Errors

• Returns error if backend initialization fails (e.g., invalid image)

pub async fn execute_test<F, T>( &self, _test_name: &str, test_fn: F, ) -> Result<T>

where F: FnOnce() -> Result<T>,

Execute a test with OTel tracing and COMPLETE attribute emission

This method implements the FULL schema-compliant telemetry emission that Weaver validation requires. Every attribute in test_execution.yaml MUST be emitted here.

pub async fn get_metrics(&self) -> Result<SimpleMetrics>

Get current metrics

pub async fn enable_tracing(&self) -> Result<()>

Enable tracing for this environment

pub async fn enable_metrics(&self) -> Result<()>

Enable metrics collection for this environment

pub async fn get_traces(&self) -> Result<Vec<String>>

Get traces from this environment

pub async fn get_container_reuse_stats(&self) -> (u32, u32)

Get container reuse statistics

pub async fn has_container(&self, name: &str) -> bool

Check if a container with the given name has been created in this session

pub async fn register_service( &self, plugin: Box<dyn ServicePlugin>, ) -> Result<()>

Register a service plugin

pub async fn start_service(&self, service_name: &str) -> Result<ServiceHandle>

Start a service by name

pub async fn stop_service(&self, handle_id: &str) -> Result<()>

Stop a service by handle ID

pub async fn execute_command_with_output( &self, _handle: &ServiceHandle, command_args: &[String], ) -> Result<Output>

Execute a command in a default test container and return full output

Arguments

• _handle - Service handle (unused - executes in default container)
• command_args - Command and arguments to execute

Returns

• Result<std::process::Output> - Command output with stdout, stderr, and exit status

pub async fn services(&self) -> RwLockReadGuard<'_, ServiceRegistry>

Get service registry (read-only access)

pub async fn register_container<T: Send + Sync + 'static>( &self, name: String, container: T, ) -> Result<()>

Register a container for reuse

pub async fn get_or_create_container<F, T>( &self, name: &str, factory: F, ) -> Result<T>

where F: FnOnce() -> Result<T>, T: Send + Sync + Clone + 'static,

Get or create container with reuse pattern

This method implements true container reuse by storing and returning the actual container instances, providing the promised 10-50x performance improvement.

pub async fn check_health(&self) -> HashMap<String, HealthStatus>

Check health of all services

pub async fn get_service_logs( &self, service_id: &str, lines: usize, ) -> Result<Vec<String>>

Get service logs

pub fn session_id(&self) -> Uuid

Get session ID

pub fn backend(&self) -> &dyn Backend

Get backend

pub async fn execute_in_service( &self, service_handle: &ServiceHandle, command: &[String], ) -> Result<ExecutionResult>

Execute a command in a specific service container

This method enables service-specific command execution, allowing test steps to target specific service containers (e.g., nginx, postgres) instead of always using the default test container.

Arguments

• service_handle - Handle to the service container
• command - Command and arguments to execute

Returns

• Result<ExecutionResult> - Command output with stdout, stderr, and exit status

Errors

• Returns error if service container_id is missing from metadata
• Returns error if command execution fails

Backend API Design

This method implements proper REST-like semantics:

• Resource identification: service_handle.id uniquely identifies the target
• Idempotent operations: Same command can be executed multiple times
• Clear error responses: Detailed error messages for debugging
• Proper status codes: Exit codes map to HTTP-like status semantics

pub async fn execute_in_container( &self, container_name: &str, command: &[String], workdir: Option<&str>, env: Option<&HashMap<String, String>>, ) -> Result<ExecutionResult>

Execute a command in a container with proper error handling and observability Core Team Compliance: Async for I/O operations, proper error handling, no unwrap/expect

This method creates a fresh container for each command execution, which is appropriate for testing scenarios where isolation is more important than performance.

Trait Implementations

impl Debug for CleanroomEnvironment

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

Formats the value using the given formatter.

impl Default for CleanroomEnvironment

fn default() -> Self

WARNING: TEST-ONLY IMPLEMENTATION

This Default implementation is ONLY for test code and WILL panic if Docker is unavailable. NEVER use CleanroomEnvironment::default() in production code.

Production Usage

Use one of these methods instead:

• CleanroomEnvironment::new().await - For default configuration with proper error handling
• CleanroomEnvironment::with_config(config).await - For custom configuration

Panics

Panics if Docker is not available or if the default backend cannot be initialized. This is intentional to ensure tests fail fast when Docker is missing.

Test-Only Rationale

The Default trait cannot be async and cannot return Result, making proper error handling impossible. Therefore, this implementation is explicitly marked as test-only and is allowed to panic since test failures are acceptable when Docker is unavailable.