Test containers with Docker in PyTest - Framework Patterns

Framework Mode - Test containers with Docker

Folder Structure

project-root/
├── tests/
│   ├── test_service.py          # Test files using pytest
│   └── conftest.py              # Fixtures for test containers setup
├── docker/
│   ├── Dockerfile               # Dockerfile for service under test
│   └── docker-compose.yml       # Optional: Compose for multi-container setup
├── src/
│   └── app.py                   # Application source code
├── requirements.txt             # Python dependencies including testcontainers
└── pytest.ini                   # pytest configuration
    

Test Framework Layers

• Test Layer: pytest test functions in tests/ that use fixtures to start/stop Docker containers.
• Fixture Layer: conftest.py defines reusable pytest fixtures that manage lifecycle of Docker containers using testcontainers Python library.
• Application Layer: Source code under src/ which is tested by the tests.
• Docker Layer: Dockerfiles and optional docker-compose files to build container images for services under test.
• Utilities Layer: Helper functions or modules to interact with containers or test data setup.
• Configuration Layer: pytest.ini and requirements.txt to configure pytest and dependencies.

Configuration Patterns

• Environment Variables: Use environment variables to configure container images, ports, and credentials dynamically.
• pytest.ini: Central place to configure pytest options like markers and test paths.
• Docker Compose: Optional for multi-container orchestration during tests.
• Fixture Parameters: Pass parameters to fixtures to customize container setup per test or environment.
• Secrets Management: Use environment variables or .env files to securely pass credentials to containers.

Test Reporting and CI/CD Integration

• Use pytest built-in reporting with --junitxml=report.xml for CI systems to parse test results.
• Integrate with CI pipelines (GitHub Actions, Jenkins, GitLab CI) to run tests inside containers or with Docker daemon access.
• Use pytest plugins like pytest-html for human-readable reports.
• Ensure Docker environment is available in CI agents for container lifecycle management.
• Fail fast on container startup errors to save CI resources.

Best Practices

1. Isolate Tests: Each test should start fresh containers to avoid state leakage.
2. Use Fixtures: Manage container lifecycle with pytest fixtures for clean setup and teardown.
3. Explicit Waits: Wait for container services to be ready before running tests to avoid flaky failures.
4. Parameterize Containers: Allow easy switching of container images or versions via config or environment variables.
5. Keep Containers Lightweight: Use minimal images to speed up test execution.

Self Check

Where in this folder structure would you add a new pytest fixture to start a Redis container for tests?

Key Result

Use pytest fixtures with testcontainers library to manage Docker containers lifecycle for isolated, repeatable tests.