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.
Currently available features:
Selenium Grid containers
Selenium Standalone containers
MySql Db container
PostgreSQL Db container
Microsoft SQL Server container
Generic docker containers
# Install without extras pip install testcontainers # Install with one or more extras pip install testcontainers[mysql] pip install testcontainers[mysql,oracle]
>>> 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:
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.
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
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:
Create a new module at
testcontainers/[my fancy container].pythat implements the new functionality.
Create a new test module at
tests/test_[my fancy container].pythat tests the new functionality.
[my fancy container]to the list of test components in the GitHub Action configuration at
- Database containers
- Selenium containers
- Docker Compose Support
- Google Cloud Emulators