Metadata-Version: 2.4
Name: DockerTestContainers
Version: 1.0.0
Summary: Throwaway Docker containers (Postgres, Valkey, LocalStack) for integration tests
Author: Eduardo Almeida
Author-email: eduardo.almeida@e-deploy.com.br
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Description-Content-Type: text/markdown

# DockerTestContainers

Throwaway Docker containers for integration tests: **Postgres**, **Valkey** and **LocalStack**.

Each manager starts a `--rm` container, waits for a readiness marker in its logs, and exposes the reachable
`host`/`port`. On a developer host it publishes an **ephemeral** host port (Docker picks a free port), so a
locally-running service on the well-known port — or a second concurrent test run — never collides. When
pytest itself runs inside a container (Docker-out-of-Docker), the managers join a shared user-defined network
and connect by the sibling container's IP instead.

## Usage

```python
from dockertestcontainers import DockerPostgres, DockerValkey, DockerLocalStack

pg = DockerPostgres()          # pg.host, pg.port, pg.database, pg.username, pg.password
valkey = DockerValkey()        # valkey.host, valkey.port
localstack = DockerLocalStack(services="s3,sqs")   # localstack.endpoint_url
try:
    ...  # run tests against pg.host:pg.port etc.
finally:
    pg.stop(); valkey.stop(); localstack.stop()
```

`DockerPostgres` takes an `image_tag` so clients can pick the Postgres version/variant:
```python
DockerPostgres(image_tag="16-alpine")   # default: "17.9-alpine3.23"
```

Requires the `docker` CLI on PATH and a running daemon. No Python runtime dependencies.

## Development

Managed with Poetry.

```bash
poetry install
poetry run pytest -v     # integration tests — needs Docker running
```

## Extending

Subclass `DockerContainer`, passing `image`, `container_port`, `readiness_marker`, and the stream it appears
on (`readiness_stream="stdout"|"stderr"`), plus any `env`/`extra_run_args`. The base class handles the rest.

