spicy-sauce/testcontainers-python

Testcontainers is a Python library that providing a friendly API to run Docker container. It is designed to create runtime environment to use during your automatic tests.

testcontainers-python

testcontainers-python facilitates the use of Docker containers for functional and integration testing. The collection of packages currently supports the following features.

.. toctree::

    core/README
    arangodb/README
    azurite/README
    clickhouse/README
    compose/README
    elasticsearch/README
    google/README
    kafka/README
    keycloak/README
    localstack/README
    minio/README
    mongodb/README
    mssql/README
    mysql/README
    neo4j/README
    nginx/README
    opensearch/README
    oracle/README
    postgres/README
    rabbitmq/README
    redis/README
    selenium/README

Getting Started

>>> from testcontainers.postgres import PostgresContainer
>>> import sqlalchemy

>>> with PostgresContainer("postgres:9.5") as postgres:
...     engine = sqlalchemy.create_engine(postgres.get_connection_url())
...     result = engine.execute("select version()")
...     version, = result.fetchone()
>>> version
'PostgreSQL 9.5...'

The snippet above will spin up a postgres database in a container. The get_connection_url() convenience method returns a sqlalchemy compatible url we use to connect to the database and retrieve the database version.

Installation

The suite of testcontainers packages is available on PyPI, and individual packages can be installed using pip. We recommend installing the package you need by running pip install testcontainers-<feature>, e.g., pip install testcontainers-postgres.

Note

For backwards compatibility, packages can also be installed by specifying extras, e.g., pip install testcontainers[postgres].

Docker in Docker (DinD)

When trying to launch a testcontainer from within a Docker container, e.g., in continuous integration testing, two things have to be provided:

1. The container has to provide a docker client installation. Either use an image that has docker pre-installed (e.g. the official docker images) or install the client from within the Dockerfile specification.
2. The container has to have access to the docker daemon which can be achieved by mounting /var/run/docker.sock or setting the DOCKER_HOST environment variable as part of your docker run command.

Development and Contributing

We recommend you use a virtual environment for development (python>=3.7 is required). After setting up your virtual environment, you can install all dependencies and test the installation by running the following snippet.

pip install -r requirements/[your python version].txt
pytest -s

Package Structure

Testcontainers is a collection of implicit namespace packages to decouple the development of different extensions, e.g., testcontainers-mysql and testcontainers-postgres for MySQL and PostgreSQL database containers, respectively. The folder structure is as follows.

# One folder per feature.
[feature name]
    # Folder without __init__.py for implicit namespace packages.
    testcontainers
        # Implementation as namespace package with __init__.py.
        [feature name]
            __init__.py
            # Other files for this
            ...
    # Tests for the feature.
    tests
        test_[feature_name].py
        ...
    # README for this feature.
    README.rst
    # Setup script for this feature.
    setup.py

Contributing a New Feature

You want to contribute a new feature or container? Great! You can do that in six steps.

1. Create a new feature directory and populate it with the [package structure]_ as described above. Copying one of the existing features is likely the best way to get started.
2. Implement the new feature (typically in __init__.py) and corresponding tests.
3. Add a line -e file:[feature name] to requirements.in and run make requirements. This command will find any new requirements and generate lock files to ensure reproducible builds (see the pip-tools documentation for details). Then run pip install -r requirements/[your python version].txt to install the new requirements.
4. Update the feature README.rst and add it to the table of contents (toctree directive) in the top-level README.rst.
5. Add a line [feature name] to the list of components in the GitHub Action workflow in .github/workflows/main.yml to run tests, build, and publish your package when pushed to the master branch.
6. Rebase your development branch on master (or merge master into your development branch).