Testcontainers Python

Warnings

• breaking With version 4.0.0, the `testcontainers-*` individual PyPI packages (e.g., `testcontainers-postgres`) were deprecated. Users must now install the main `testcontainers` package and specify required modules as 'extras' (e.g., `pip install 'testcontainers[postgres]'`).
  Fix: Update your `pip install` commands and `requirements.txt` to use the main `testcontainers` package with bracketed extras (e.g., `testcontainers[mysql,kafka]`).
• gotcha Testcontainers requires a running Docker daemon accessible by the Python process. Common issues include Docker not running, insufficient user permissions, or misconfigured DOCKER_HOST environment variables, especially in CI/CD environments (e.g., Docker-in-Docker setups).
  Fix: Ensure Docker is installed and running. For CI/CD, confirm that `/var/run/docker.sock` is mounted or `DOCKER_HOST` is correctly set within the container where tests run. Check Docker permissions for the user executing the tests.
• gotcha Using ':latest' Docker image tags can lead to flaky or unpredictable tests, as the 'latest' image can change without notice and introduce breaking changes. It's a best practice to pin specific image versions (e.g., 'postgres:16').
  Fix: Always specify a fixed, known-good version tag for Docker images (e.g., `PostgresContainer('postgres:16')`) to ensure reproducible test environments.
• deprecated Older wait strategies, particularly those using decorators for `wait_for_container_ready` or custom, less explicit waiting logic, are being superseded. Newer versions of Testcontainers encourage or internally use explicit `WaitStrategy` classes and `ExecWaitStrategy`.
  Fix: Review container initialization logic. Where possible, adopt the enhanced `WaitStrategy` classes or ensure built-in container modules (e.g., `PostgresContainer`) are using the latest internal waiting mechanisms, avoiding manual `time.sleep()` calls.
• gotcha While the `core` package adheres to Semantic Versioning, community modules (e.g., `testcontainers[mysql]`) are supported on a 'best-effort' basis. Breaking changes may occur in these modules with minor version updates of the main `testcontainers` package.
  Fix: When relying on community modules, consult the changelog for each `testcontainers` minor update. Pin the `testcontainers` version in your `requirements.txt` to mitigate unexpected behavior if a module breaks compatibility.
• gotcha Though Testcontainers uses Ryuk for automatic container cleanup, it's good practice to ensure containers are explicitly stopped and removed, especially in complex `pytest` fixtures without `yield` or for custom `DockerContainer` instances not using context managers, to prevent resource leakage.
  Fix: Prefer using `with SomeContainer(...) as container:` for automatic cleanup. For non-context-manager usage or in `pytest` fixtures, ensure `container.stop()` is called in a `finally` block or `addfinalizer` to explicitly manage container lifecycle.

Install

• pip install testcontainers Core library
• pip install 'testcontainers[postgres]' With specific module (e.g., PostgreSQL)

Imports

• DockerContainer

  from testcontainers.core.container import DockerContainer

• PostgresContainer

  from testcontainers.postgres import PostgresContainer

• DockerCompose

  from testcontainers.compose import DockerCompose

• KafkaContainer

  from testcontainers.kafka import KafkaContainer

  Specific module containers are imported directly from their module, not from `testcontainers.core`.

Quickstart

This quickstart demonstrates how to spin up a PostgreSQL container using `PostgresContainer` as a context manager. It connects to the database using `psycopg` and executes a simple query to verify connectivity. The container is automatically started before the `with` block and torn down afterward, ensuring a clean and isolated environment.

import os
from testcontainers.postgres import PostgresContainer
import psycopg

# Example of using PostgresContainer in a test context
def test_postgres_container_starts():
    # Use a specific image version for reproducibility
    # The database driver (psycopg) is expected to be installed in your environment
    with PostgresContainer("postgres:16") as postgres:
        connection_url = postgres.get_connection_url()
        print(f"PostgreSQL container started, connection URL: {connection_url}")
        # Connect to the database
        with psycopg.connect(connection_url) as conn:
            with conn.cursor() as cur:
                cur.execute("SELECT 1")
                result = cur.fetchone()
                assert result == (1,)
        print("Successfully connected and executed a query.")

if __name__ == "__main__":
    # Ensure Docker is running before executing
    # In a real test suite, this would typically be run by pytest
    test_postgres_container_starts()