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.


## Example

For example, to create an S3 based on localstack:

```python
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.
