testcontainers-python

Python port for testcontainers-java that allows using docker containers for functional and integration testing. Testcontainers-python provides capabilities to spin up docker containers (such as a database, Selenium web browser, or any other container) for testing.

This fork of testcontainers-python fixes bugs in upstream's Windows support, and it also works on Linux and MacOS.

Currently available features:

• Selenium Grid containers
• Selenium Standalone containers
• MySql Db container
• MariaDb container
• Neo4j container
• OracleDb container
• PostgreSQL Db container
• ClickHouse container
• Microsoft SQL Server container
• Generic docker containers
• ArangoDB container
• LocalStack
• RabbitMQ
• Keycloak
• Azurite container

Installation

The testcontainers package is available from PyPI, and it can be installed using pip. Depending on which containers are needed, you can specify additional dependencies as extras:

# Install without extras
pip install testcontainers
# Install with one or more extras
pip install testcontainers[mysql]
pip install testcontainers[mysql,oracle]

Basic usage

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

>>> postgres_container = PostgresContainer("postgres:9.5")
>>> with postgres_container as postgres:
...     e = sqlalchemy.create_engine(postgres.get_connection_url())
...     result = e.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.

More extensive documentation can be found at Read The Docs.

Usage within Docker (e.g., in a CI)

When trying to launch a testcontainer from within a Docker container 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.

Setting up a development environment

We recommend you use a virtual environment for development. Note that a python version >=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/$(python -c 'import sys; print("%d.%d" % sys.version_info[:2])').txt
pytest -s

Note, the anonymous tier of Docker Hub rate limits downloads to 100 container image requests per six hours, and running all of the tests in the tests directory for the first time appears to exceed the limit.

<<<<<<< HEAD Also, the SQL Server tests will fail unless you have Microsoft ODBC Driver 17 for SQL Server installed, available from https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server. ======= The SQL Server tests will fail unless you have Microsoft ODBC Driver 17 for SQL Server installed, available from https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server.

There is an apparent bug in Docker Desktop for Windows, described at docker/docker-py#2792, that causes the DockerContainer.getExposedPort() method to fail if it is called immediately after starting the container. Some of the test cases implement a 5 second timeout to avoid hitting this bug. >>>>>>> 8c6ba3d (Fix typo in the README.rst.)

Adding requirements

We use pip-tools to resolve and manage dependencies. If you need to add a dependency to testcontainers or one of the extras, modify the setup.py as well as the requirements.in accordingly and then run pip install pip-tools followed by make requirements to update the requirements files.

Contributing a new container

You can contribute a new container in three steps:

1. Create a new module at testcontainers/[my fancy container].py that implements the new functionality.
2. Create a new test module at tests/test_[my fancy container].py that tests the new functionality.
3. Add [my fancy container] to the list of test components in the GitHub Action configuration at .github/workflows/main.yml.