#Testcontainers for MoonBit

#Features

• Simple Container Management: Start, stop, and remove Docker containers programmatically
• Port Mapping: Automatically map container ports to random host ports
• Environment Variables: Configure containers with custom environment variables
• Volume Mounting: Mount host files and directories into containers
• Fluent API: Builder pattern for intuitive container configuration
• Async Support: Built on MoonBit's async primitives for efficient I/O
• Wait Strategies: TCP port, HTTP endpoint, log message, and simple delay strategies
• Container Logs: Retrieve and stream container logs in real-time
• Multi-Backend Support: Works with both Native (LLVM) and JavaScript (Node.js) backends
• Helpful Error Messages: Provides clear installation instructions if Docker CLI is not found

#Requirements

• MoonBit: Latest version with multi-backend support
• Docker: Docker must be installed and running on your system
  • The library will provide helpful installation instructions if Docker CLI is not found
• For Native Backend: Linux or macOS platform
• For JavaScript Backend: Node.js v14 or later

#Backend Support

#Native Backend (LLVM)

• Best performance
• Direct system calls
• Recommended for production use and CI/CD

moon test --target native

#JavaScript Backend (Node.js)

• Works in Node.js environments
• Same API and test compatibility as Native backend
• Useful for JavaScript-focused development workflows

• Node.js v14 or later
• Note: Browser environments are not supported (requires Node.js child_process module)

moon test --target js

#Backend Implementation Details

• Native: docker_native.mbt uses @process.collect_output_merged
• JavaScript: docker_js.mbt uses Node.js child_process.execSync via FFI

#Installation

{
  "deps": {
    "ryota0624/moonbit_test_containers": "0.1.0",
    "moonbitlang/async": "0.16.5"
  }
}

{
  "import": [
    "moonbitlang/async",
    "moonbitlang/async/process",
    "moonbitlang/async/http"
  ]
}

#Usage

#Basic Example

// Create and start a Redis container
let container = ContainerImage::new("redis", "7.2.4")
  .with_exposed_port(6379)
  .with_env_var("REDIS_PORT", "6379")
  .start()

match container {
  Ok(c) => {
    // Get the host port
    match c.get_host_port(6379) {
      Some(port) => println("Redis running on port: \{port}")
      None => println("Port not mapped")
    }

    // Cleanup when done
    let _ = c.cleanup()
  }
  Err(e) => println("Error: \{e.to_string()}")
}

#Advanced Configuration

let container = ContainerImage::new("postgres", "16")
  .with_exposed_port(5432)
  .with_env_var("POSTGRES_USER", "testuser")
  .with_env_var("POSTGRES_PASSWORD", "testpass")
  .with_env_var("POSTGRES_DB", "testdb")
  .start()

match container {
  Ok(c) => {
    println("PostgreSQL container: \{c.get_id()}")

    // Use the container in your tests
    // ...

    // Stop and remove separately
    let _ = c.stop()
    let _ = c.remove()
  }
  Err(e) => println("Failed to start: \{e.to_string()}")
}

#Volume Mounting

#Basic File Mount

///|
let container = ContainerImage::new("nginx", "1.25-alpine")
  .with_exposed_port(80)
  .with_volume("./nginx.conf", "/etc/nginx/nginx.conf")
  .start()

#Read-Only Mount

///|
let container = ContainerImage::new("myapp", "latest")
  .with_volume_ro("./config", "/app/config")
  .start()

#Multiple Volumes

///|
let container = ContainerImage::new("myapp", "latest")
  .with_volume_ro("./config", "/app/config")
  .with_volume("./data", "/app/data")
  .with_volume("./logs", "/app/logs")
  .start()

#PostgreSQL Initialization Script

let container = ContainerImage::new("postgres", "16")
  .with_exposed_port(5432)
  .with_env_var("POSTGRES_USER", "test")
  .with_env_var("POSTGRES_PASSWORD", "test")
  .with_env_var("POSTGRES_DB", "testdb")
  .with_volume("./init.sql", "/docker-entrypoint-initdb.d/init.sql")
  .with_wait_for(WaitStrategy::TcpPort(5432))
  .with_wait_timeout(60)
  .start()

match container {
  Ok(c) => {
    // PostgreSQL is now ready with your schema initialized
    match c.get_host_port(5432) {
      Some(port) => println("PostgreSQL ready on port: \{port}")
      None => println("Port not mapped")
    }
    let _ = c.cleanup()
  }
  Err(e) => println("Failed: \{e.to_string()}")
}

#Wait Strategies

#TCP Port Wait

///|
let container = ContainerImage::new("redis", "7.2.4")
  .with_exposed_port(6379)
  .with_wait_for(WaitStrategy::TcpPort(6379))
  .with_wait_timeout(30) // optional, defaults to 60 seconds
  .start()

#HTTP Endpoint Wait

let container = ContainerImage::new("nginx", "1.25-alpine")
  .with_exposed_port(80)
  .with_wait_for(WaitStrategy::HttpGet("/", 200))
  .with_wait_timeout(30)
  .start()

match container {
  Ok(c) => {
    // Nginx is now ready and responding to HTTP requests
    match c.get_host_port(80) {
      Some(port) => println("Nginx ready on port: \{port}")
      None => println("Port not mapped")
    }
    let _ = c.cleanup()
  }
  Err(e) => println("Failed: \{e.to_string()}")
}

// Wait for a health check endpoint to return 200

///|
let container = ContainerImage::new("myapp", "latest")
  .with_exposed_port(8080)
  .with_wait_for(WaitStrategy::HttpGet("/health", 200))
  .with_wait_timeout(60)
  .start()

#Simple Delay

///|
let container = ContainerImage::new("alpine", "3.19")
  .with_cmd(["sleep", "10"])
  .with_wait_for(WaitStrategy::Seconds(5))
  .start()

#Log Message Wait

///|
let container = ContainerImage::new("postgres", "15-alpine")
  .with_exposed_port(5432)
  .with_env_var("POSTGRES_PASSWORD", "password")
  .with_wait_for(
    WaitStrategy::LogMessage("database system is ready to accept connections"),
  )
  .with_wait_timeout(60)
  .start()

#PostgreSQL Example

let container = ContainerImage::new("postgres", "16")
  .with_exposed_port(5432)
  .with_env_var("POSTGRES_USER", "test")
  .with_env_var("POSTGRES_PASSWORD", "test")
  .with_env_var("POSTGRES_DB", "test")
  .with_wait_for(WaitStrategy::TcpPort(5432))
  .with_wait_timeout(60)
  .start()

match container {
  Ok(c) => {
    // PostgreSQL is now ready to accept connections
    match c.get_host_port(5432) {
      Some(port) => println("PostgreSQL ready on port: \{port}")
      None => println("Port not mapped")
    }
    let _ = c.cleanup()
  }
  Err(e) => println("Failed: \{e.to_string()}")
}

let container = ContainerImage::new("postgres", "15-alpine")
  .with_exposed_port(5432)
  .with_env_var("POSTGRES_PASSWORD", "password")
  .with_wait_for(
    WaitStrategy::LogMessage("database system is ready to accept connections")
  )
  .with_wait_timeout(60)
  .start()

match container {
  Ok(c) => {
    // PostgreSQL is fully initialized and ready
    match c.get_host_port(5432) {
      Some(port) => println("PostgreSQL ready on port: \{port}")
      None => println("Port not mapped")
    }
    let _ = c.cleanup()
  }
  Err(e) => println("Failed: \{e.to_string()}")
}

#Other Services with Log Message Wait

///|
let container = ContainerImage::new("redis", "7.2.4")
  .with_exposed_port(6379)
  .with_wait_for(WaitStrategy::LogMessage("Ready to accept connections"))
  .with_wait_timeout(30)
  .start()

///|
let container = ContainerImage::new("nginx", "1.25-alpine")
  .with_exposed_port(80)
  .with_wait_for(WaitStrategy::LogMessage("start worker processes"))
  .with_wait_timeout(30)
  .start()

#Container Logs

#Basic Log Retrieval

match container.get_logs() {
  Ok(logs) => println("Container logs:\n\{logs}")
  Err(e) => println("Failed to get logs: \{e.to_string()}")
}

#Log Options

// Get last 100 lines with timestamps
let options = LogOptions::default()
  .with_tail(100)
  .with_timestamps(true)

match container.get_logs_with_options(options) {
  Ok(logs) => println("Recent logs:\n\{logs}")
  Err(e) => println("Failed to get logs: \{e.to_string()}")
}

• .with_tail(lines: Int): Get only the last N lines
• .with_timestamps(enabled: Bool): Include timestamps
• .with_since(timestamp: String): Get logs since a specific time
• .with_until(timestamp: String): Get logs until a specific time

#Log Streaming

// Stream logs line by line
let callback = fn(line: String) {
  println("Log: \{line}")
}

match container.stream_logs(callback) {
  Ok(_) => println("Streaming complete")
  Err(e) => println("Failed to stream: \{e.to_string()}")
}

// Stream only recent logs
let options = LogOptions::default().with_tail(50)

match container.stream_logs(callback, options=options) {
  Ok(_) => println("Streaming complete")
  Err(e) => println("Failed to stream: \{e.to_string()}")
}

#Debugging Failed Containers

let container = ContainerImage::new("myapp", "latest")
  .with_exposed_port(8080)
  .start()

match container {
  Ok(c) => {
    // If something goes wrong, check the logs
    match c.get_logs() {
      Ok(logs) => {
        if logs.contains("ERROR") {
          println("Container error detected:\n\{logs}")
        }
      }
      Err(e) => println("Failed to get logs: \{e.to_string()}")
    }
    let _ = c.cleanup()
  }
  Err(e) => println("Failed to start: \{e.to_string()}")
}

#API Reference

#ContainerImage

• ContainerImage::new(name: String, tag: String) -> ContainerImage
• .with_exposed_port(port: Int) -> ContainerImage
• .with_env_var(key: String, value: String) -> ContainerImage
• .with_cmd(cmd: Array[String]) -> ContainerImage
• .with_volume(host_path: String, container_path: String) -> ContainerImage - Mount a volume (read-write)
• .with_volume_ro(host_path: String, container_path: String) -> ContainerImage - Mount a volume as read-only
• .with_wait_for(strategy: WaitStrategy) -> ContainerImage
• .with_wait_timeout(timeout: Int) -> ContainerImage - timeout in seconds (default: 60)
• .start() -> Result[Container, TestContainerError] (async)

#WaitStrategy

• WaitStrategy::TcpPort(port: Int) - Wait for TCP port to be open
• WaitStrategy::HttpGet(path: String, expected_status: Int) - Wait for HTTP endpoint to return expected status code
• WaitStrategy::LogMessage(message: String) - Wait for a specific message to appear in container logs (polls every 500ms, checks last 100 lines)
• WaitStrategy::Seconds(seconds: Int) - Wait for a fixed duration

#Container

• .get_id() -> String
• .get_host_port(container_port: Int) -> Option[Int]
• .stop() -> Result[Unit, TestContainerError] (async)
• .remove() -> Result[Unit, TestContainerError] (async)
• .cleanup() -> Result[Unit, TestContainerError] (async) - stops and removes the container
• .get_logs() -> Result[String, TestContainerError] (async)
• .get_logs_with_options(options: LogOptions) -> Result[String, TestContainerError] (async)
• .stream_logs(callback: (String) -> Unit, options?: LogOptions) -> Result[Unit, TestContainerError] (async)

#LogOptions

• LogOptions::default() -> LogOptions
• .with_tail(lines: Int) -> LogOptions - Get last N lines
• .with_timestamps(enabled: Bool) -> LogOptions - Include timestamps
• .with_since(timestamp: String) -> LogOptions - Get logs since timestamp
• .with_until(timestamp: String) -> LogOptions - Get logs until timestamp
• .with_follow(enabled: Bool) -> LogOptions - Follow log output (only for stream_logs)

#Building and Testing

# Native backend
moon check --target native

# JavaScript backend
moon check --target js

# Native backend (recommended)
moon test --target native

# JavaScript backend (requires Node.js)
moon test --target js

# Both backends
moon test --target native && moon test --target js

#Current Limitations

• JavaScript Backend: Requires Node.js environment; browser environments are not supported
• Wait Strategies: HTTP endpoint wait uses the first exposed port
• HTTP Support: Only HTTP (not HTTPS), GET method only, status code checking only
• Network Management: Custom networks are not supported yet
• Volume Mounting: Only bind mounts are supported; named volumes and tmpfs are not yet supported
• Platform: Native backend supports Linux and macOS only (Windows support requires investigation)

#Future Enhancements

• Wait strategies - TCP port and delay (implemented)
• Wait strategies - HTTP endpoint (implemented)
• Wait strategies - log message (implemented)
• Container logs streaming (implemented)
• Volume mounting - bind mounts (implemented)
• Multi-backend support - Native and JavaScript (implemented)
• Docker CLI installation check with helpful error messages (implemented)
• HTTPS support for HTTP wait strategy
• Custom HTTP headers and methods
• Response body validation for HTTP wait strategy
• Custom network support
• Named volumes and tmpfs support
• Specialized modules for popular services (PostgreSQL, Redis, MongoDB)
• Windows support
• Browser environment support (if possible)

#License

#Contributing

#Acknowledgments