pytest-cov-container

Collect code coverage from Python applications running inside Docker containers during integration tests. Works alongside pytest-cov to combine container coverage with your local test coverage.

Built for AWS SAM local testing: by default it collects from the Lambda containers sam local starts for this checkout.

How It Works

1. Before tests — moves your <build_dir>/run.sh aside to _orig_run.sh, then injects a coverage wrapper, .coveragerc, and a shim run.sh that exec's the wrapper. The wrapper invokes your unmodified _orig_run.sh under coverage. Your production entrypoint is the test entrypoint by construction — no duplicate command string to drift.
2. During tests — your containerized app runs under coverage via the injected wrapper, which forwards SIGTERM to your app on container shutdown so coverage data is saved cleanly.
3. After tests — signals each owned container's coverage process to save, waits for its save sentinel, copies the data files out and drops them next to pytest-cov's data file. pytest-cov's own combine merges them with the host data, so its report and --cov-fail-under include container coverage.

Installation

pip install pytest-cov-container

Requires Python 3.11+ and, for the default container selection, SAM CLI 1.165+ (the first release that labels its Lambda containers).

Configuration

Add to your pyproject.toml:

[tool.pytest-cov-container]

[tool.pytest-cov-container.path_mapping]
"src/api" = "/var/task"

[tool.pytest-cov-container.python]
build_dir = ".aws-sam/build/ApiFunction"

[tool.pytest-cov-container.python]:

Default Path: Convention Discovery

The plugin reads your existing <build_dir>/run.sh (whatever sam build produced) and arranges for coverage to wrap it. Requirements:

• <build_dir>/run.sh must exist after sam build.
• Your build_dir must include the coverage package as an installed dependency (the plugin checks for a coverage*.pth file under any site-packages directory below build_dir). This is what enables subprocess coverage attach.

If either precondition fails, inject() raises with a migration hint.

Usage

Run your tests with --cov as usual:

pytest --cov=src/api tests/

The plugin activates automatically when:

• pytest-cov is active (--cov flag present)
• [tool.pytest-cov-container] is configured in pyproject.toml

Disable it for a run with:

pytest --cov=src/api --no-cov-container tests/

Mid-Session Collection

If you need to collect coverage before containers stop (e.g., in a session-scoped fixture teardown), use the public API:

from pytest_cov_container import collect_container_coverage

@pytest.fixture(scope="session")
def sam_api():
    proc = start_sam(...)
    yield SAM_URL
    collect_container_coverage()
    proc.terminate()

This saves and collects the running containers this process owns and returns the number of data files collected. With required, collecting nothing raises. Containers still around after the tests are collected automatically before pytest-cov reports.

The wrapper's SIGUSR1 save flushes the wrapper process only. A long-running server started by _orig_run.sh saves when it gets SIGTERM (container stop), so for mid-session collection from a server, set wrapper = false and run the save protocol in the application.

Save Protocol

The process that owns the coverage.Coverage object follows three rules:

1. After cov.start(), write its pid to PID_FILE (/tmp/.cov_container.pid).
2. On SIGUSR1, call cov.save(), then create DONE_FILE (/tmp/.cov_container.done).
3. Read the injected .coveragerc (path in COVERAGE_PROCESS_START), which writes data files as /tmp/.coverage.container*.

With wrapper = false, the application does this itself, for example:

import os
import signal
from pathlib import Path


def maybe_start_coverage() -> None:
    rcfile = os.environ.get("COVERAGE_PROCESS_START")
    if not rcfile:
        return  # production: no coverage
    import coverage

    cov = coverage.Coverage(config_file=rcfile)
    cov.start()
    Path("/tmp/.cov_container.pid").write_text(str(os.getpid()))

    def save(*_):
        cov.save()
        Path("/tmp/.cov_container.done").touch()

    signal.signal(signal.SIGUSR1, save)

pytest-xdist and Concurrent Checkouts

Image and label say what a container is, not whose it is. Two xdist workers, or two checkouts of the project, run identical images. Set the ownership keys and pass the marker into the containers:

[tool.pytest-cov-container]
worker_env = "MY_TEST_WORKER"  # label and mount_prefix keep their SAM defaults

import pytest_cov_container

env_vars = {"Parameters": pytest_cov_container.container_env(project_root)}
# write env_vars to env.json, then: sam local start-api --env-vars env.json

container_env() returns the worker marker and, while the plugin is active, COVERAGE_PROCESS_START. sam local --env-vars only overrides variables the template declares, so declare both in template.yaml (empty values are fine) or sam drops them silently.

Under xdist the controller injects before any worker starts, each worker collects only its own containers, and pytest-cov's controller combines everything once.

owned_containers(rootpath, all_workers=False) lists the same containers for other uses, such as a reaper that removes leaked containers without touching a concurrent session's.

Pluggable Drivers

Language support is pluggable via entry points. The built-in Python driver handles:

• Moving your <build_dir>/run.sh aside to _orig_run.sh (mode preserved, idempotent across re-runs)
• Writing .coveragerc with parallel = true, sigterm = true and the host's branch setting
• Writing _cov_wrapper.py that starts coverage, runs the save protocol, splits SIGUSR1/SIGTERM handling (save-only vs save+forward), forwards SIGTERM to the child process so the runtime grace period saves cleanly, and invokes your unmodified _orig_run.sh
• Writing a shim run.sh that exec's the wrapper
• Extracting .coverage.container* files from /tmp in containers

All injected files are written atomically.

To add a driver for another language, register an entry point:

[project.entry-points."pytest_cov_container.drivers"]
node = "my_package.drivers.node:NodeDriver"

Drivers must implement the LanguageDriver protocol from pytest_cov_container.models.

Development

# Run tests
hatch test

# Run across all Python versions
hatch test --all

# Format and lint
hatch fmt

# Type check
hatch run types:check

# Security scan
hatch run security:scan

# Cut a release: bump + commit + tag + push in one shot. Pass a version
# literal or a hatch segment (`patch`, `minor`, `major`, `rc`, etc.).
# Omit the arg to bump the minor version.
hatch run release           # 0.2.0 → 0.3.0
hatch run release patch     # 0.2.0 → 0.2.1
hatch run release 0.3.5     # explicit

License

pytest-cov-container is distributed under the terms of the MIT license.