testcontainers/testcontainers-go
Testcontainers Go
testcontainers-go is a Docker integration testing library for Go designed to provision and manage disposable containerized infrastructure. It functions as a container lifecycle manager and ephemeral infrastructure provisioner, allowing developers to programmatically create, start, and destroy containers as dependencies for automated integration tests.
The library acts as a Docker network orchestrator by mapping container ports to random host ports and resolving network endpoints for test clients. This capability enables parallel test execution by preventing network collisions and ensures that each test run operates within an isolated environment.
The system covers a broad range of orchestration capabilities, including image-based provisioning, container readiness verification through wait-strategy polling, and automated resource cleanup via a sidecar reaper to remove orphaned containers. These features support the creation of ephemeral test environments for services such as databases to verify software behavior in production-like conditions.
Features
- Programmatic Container Managers - Allows developers to programmatically define and manage the lifecycle of Docker containers within Go code.
- Container-Based Provisioning - Automates the deployment of pre-configured runtimes by pulling and instantiating containers from registry images.
- Container Lifecycle Management - Provides programmatic capabilities to create, start, and destroy containers based on specific image configurations.
- Container Startup Dependency Management - Manages the creation and removal of container-based service dependencies to ensure isolated test environments.
- Docker Container Orchestrators - Orchestrates the mapping of container ports to host ports and resolves network endpoints for test clients.
- Container Port Mappings - Resolves host addresses and mapped ports of running containers to establish client connections for tests.
- Container Networking Configurations - Configures isolated virtual networks and random port mappings to facilitate parallel test execution.
- Container Port Mapping - Implements dynamic mapping of container ports to random host ports to enable parallel test execution.
- Infrastructure Provisioners - Handles the automatic setup and cleanup of temporary containerized services for clean test execution.
- Containerized Test Libraries - Provides a Go library for managing Docker containers as disposable dependencies during integration tests.
- Containerized Integration Tests - Enables running automated integration tests against real service instances in Docker containers.
- Ephemeral Testing Environments - Provisions short-lived, isolated containerized infrastructure on demand for each automated test run.
- Test Database Provisioners - Automatically creates and manages temporary database instances for isolated integration testing.
- Orphaned Container Cleanup - Includes a sidecar reaper container that automatically removes orphaned containers after test completion.
- Readiness Wait Strategies - Provides wait strategies that poll logs or network ports to verify container readiness before testing.
- Dependency Orchestrators - Coordinates the readiness and lifecycle of external containerized service dependencies during test execution.
- Docker Engine API Clients - Provides a programmatic Go client to interact with the Docker Engine API for container management.
- Service Readiness Probes - Monitors logs and port status to determine when a containerized service is initialized and ready for traffic.
- Parallel Test Execution - Supports concurrent test suite execution by mapping containers to random host ports to avoid collisions.
