pytest-ephemeral-container

This is a bit of code to allow test suites (namely pytest) to spawn and destroy containers tied to fixtures.

This uses the Docker Python library, not the Docker CLI, and should be compatible with a wide variety of platforms and implementations. It should work either as the container host or with the Docker socket mounted in.

Example

For example, to create an S3 based on localstack:

from pytest_ephemeral_container import spawn_container, discover_ports, wait_for_http


@pytest.fixture(scope="session")
def _localstack_s3():
    with spawn_container(
        image="docker.io/localstack/localstack:s3-latest",
        ports={"4566/tcp": None},
        environment={
            "DEBUG": "0",
        },
    ) as container:
        ip, port = next(discover_ports(container, "4566/tcp"))

        wait_for_http(ip, port)

        yield f"{ip}:{port}"

Reference

Jamie doesn't feel like doing a full docs site yet, so have quick reference.

There are features of the library not discussed here; read the source for more information.

def spawn_container(**props) -> ContextManager[Container]

Start a container, as a context manager. Cleans itself up.

props are the container properties passed to client.containers.run(). The image parameter is required, and you probably want to pass a ports (see discover_ports()). name is left to be autogenerated by Docker, and you probably want to keep that.

def discover_ports(container: Container, port: str) -> typing.Iterable[tuple[str, int]]

Docker has the option to automatically pick ports for you. This is very valuable in the context of ephemeral containers, since you can avoid conflicting with anything else the user is running.

This function will find the ports that Docker picked, and tell you about them.

In most cases, the first port given is fine, so you can wrap this in next().

def wait_for_http(addr: str, port: int, *, timeout: float = 30.0) -> None

Uses urllib to repeatedly make HTTP requests at the given port until success.

timeout is for the total wait time.

pytest fixture dockerclient ()

Gets the Docker client that is in use, in case you want to do anything advanced.