Package: tox-docker
tox-dockerAtoxplugin which runs one or
moreDockercontainers during the test run.Links:Source Code|DocumentationUsage and Installationtox loads all plugins automatically. To use tox-docker,pip installit
into the same Python environment as you install tox into, whether that’s a
virtualenv, etc.You do not need to do anything special when running tox to invoke
tox-docker, however you do need to configure your project to configure
docker containers (see “Configuration” below).ConfigurationEach docker container you want to run must be configured via a[docker:container-name]section. Thecontainer-nameis a name you
choose which must start with a letter and consist of only letters, numbers,
dots, hyphens, and underscores. Each[docker:container-name]section must
contain at least animagedirective, which must name aDocker imageas you’d pass todocker run; or abuilddirective, containing the path to aDockerfileas you’d pas todocker build:[docker:db]
image = postgres:9-alpine

# OR

[docker:app]
dockerfile = {toxinidir}/DockerfileThen, in your[testenv], use thedockerdirective to list containers
you wish to run during those tests:[testenv]
docker =
    db
commands = ...The[docker:container-name]section may contain the following directives:imageTheDocker imageto run.
This value is passed directly to Docker, and may be of any of the forms
that Docker accepts in egdocker run. One ofimageordockerfileis required.dockerfilePath to aDockerfileto build and run. One ofdockerfileorimageis required.dockerfile_targetName of the build-stage to build in a multi-stage Dockerfile. An error
is raised ifdockerfile_targetis set withoutdockerfileset.environmentA multi-line list ofKEY=valuesettings which is used to set
environment variables for the container. The variables are only available
to the container, not to other containers or the test environment.portsA multi-line list of port mapping specifications, asHOST_PORT:CONTAINER_PORT/PROTO, which causes the container’sEXPOSEd port to be available onHOST_PORT. See below for
more on port mapping.Ifportsis not specified, all the container’sEXPOSEd ports are
mapped (equivalent todocker run-P...)For each mapped port, an environment variable of the form<container-name>_<port-number>_<protocol>_PORT(egNGINX_80_TCP_PORTorTELEGRAF_8092_UDP_PORT) is set for the test
run.For each container, an environment variable of the form<container_name>_HOSTis set for the test run, indicating the host
name or IP address to use to communicate with the container.If you set theHOST_PORTto zero, a random available port will be
assigned on the tox host. This is useful in case the container does notEXPOSEthe port you need, or if you want to map only some of theEXPOSEd ports.In both environment variables, the container name part is converted to
upper case, and all non-alphanumeric characters are replaced with an
underscore (_).Tox-docker does not attempt to ensure that you have proper permission to
bind theHOST_PORT, that it is not already bound and listening, etc;
if you explicitly list ports, it is your responsibility to ensure that
it can be successfully mapped.linksA multi-line list ofcontainer links, asother-container-nameorother-container-name:alias. If no alias is given, theother-container-nameis used. Within the container, theEXPOSEd
ports of the other container will be available via the alias as hostname.When using links, you must specify containers in the correct start order
in thedockerdirective of your testenv – tox-docker does not attempt
to resolve a valid start order.volumesA multi-line list ofvolumesto make available to the
container, as<type>:<options>:<outside_path_or_name>:<inside_path>.
Thetypemust bebind, and the only supported options arerw(read-write) orro(read-only). Theoutside_path_or_namemust
be a path that exists on the host system. Both theoutside_pathandinside_pathmust be absolute paths.healthcheck_cmd,healthcheck_interval,healthcheck_retries,healthcheck_start_period,healthcheck_timeoutThese set or customize parameters of the containerhealth check. Thehealthcheck_interval,healthcheck_start_period, andhealthcheck_timeoutare specified as a number of seconds.
Thehealtcheck_cmdis an argv list which must name a command and
arguments that can be run within the container; if not specified, any
health check built in to the container is used.If any healthcheck parameters are defined, tox-docker will delay the
test run until the container reports healthy, and will fail the test
run if it never does so (within the parameters specified).Command-Line ArgumentsAll Docker container configuration is specified intox.ini, but some
aspects of tox-docker’s behavior can be changed at run-time:--docker-dont-stop=CONTAINERAfter the test run, don’t stop & remove the namedCONTAINER–
leaving the container running allows manual inspection of it, eg viadocker exec .... May be specified multiple times to leave several
containers running.Container Naming & Parallel RunsSince version 4, tox-docker adds a suffix to the name of running containers,
so that parallel invocations of tox may succeed (eg on a busy CI server).
The details of the name suffix are not specified, and may change in a future
version – you should not rely on the details of the generated name.Even with unique container names, parallel runs may still fail, if you map a
static exposed port number for a container (as the tox host will not let two
processes bind the same port).Example[testenv:integration-tests]deps=pytestcommands=py.test {toxinidir}/testsdocker=dbappserv[docker:db]image=postgres:11-alpine# Environment variables are passed to the container. They are only# available to that container, and not to the testenv, other# containers, or as replacements in other parts of tox.inienvironment=POSTGRES_PASSWORD=hunter2POSTGRES_USER=dbuserPOSTGRES_DB=tox_test_db# The healthcheck ensures that tox-docker won't run tests until the# container is up and the command finishes with exit code 0 (success)healthcheck_cmd=PGPASSWORD=$POSTGRES_PASSWORD psql\--user=$POSTGRES_USER --dbname=$POSTGRES_DB\--host=127.0.0.1 --quiet --no-align --tuples-only\-1 --command="SELECT 1"healthcheck_timeout=1healthcheck_retries=30healthcheck_interval=1healthcheck_start_period=1# Configure a bind-mounted volume on the host to store Postgres' data# NOTE: this is included for demonstration purposes of tox-docker's# volume capability; you probably _don't_ want to do this for real# testing use cases, as this could persist data between test runsvolumes=bind:rw:/my/own/datadir:/var/lib/postgresql/data[docker:appserv]# You can use any value that `docker run` would accept as the imageimage=your-registry.example.org:1234/your-appserv# Within the appserv container, host "db" is linked to the postgres containerlinks=db:db# Use ports to expose specific ports; if you don't specify ports, then all# the EXPOSEd ports defined by the image are mapped to an available# ephemeral port.ports=8080:8080/tcpEnvironment VariablesIf you are running in a Docker-In-Docker environment, you can override the address
used for port checking using the environment variableTOX_DOCKER_GATEWAY. This
variable should be the hostname or ip address used to connect to the container.Version CompatibilityTox-docker requires tox to be run in Python 3.7 or newer, and requires tox
version 3.0 or newer. Older versions of tox-docker may work with older
versions of Python or tox, but these configurations are no longer supported.Change Log4.1.0Drop test support for docker (Python library) 3.x; add test support
for docker 6.x. Other versions may work, but we only support tested
versions.Add support fordockerfileanddockerfile_targetdirectives
to build local images4.0.0Support tox 4 as well as tox 3Drop support for Python 3.6Give running containers a unique name to support concurrent & parallel
tox use cases (thanks @chaitu-tk and @goodtune for inspiration)Add support for image registry URLs that contain a port3.1.0Support docker-py 5.x3.0.0Support tox 3 and newer onlyAutomatically cleans up started docker containers, even if Tox
encounters an error during the test run (thanks @d9pouces)2.0.0Support Python 3.6 and newer onlyMove all container configuration to[docker:container-name]sectionsDon’t infer container health by pinging TCP ports; only the
healthcheck indicates a container’s healthDevelopmentCode StyleTox-docker uses black and isort to enforce style standards on the codebase.
The formatting is orindaily done for you viapre-commit, and is enforced via thetox-estylebuild.
To work on tox-docker locally with pre-commit,pip install -r
dev-requirements.txt`andpre-commitinstallto set up the git hooks;
subsequently, when yougit commit, the formatter will be run. If the
changed files are not conformant, the hook will have reformatted them and
you may need to run pre-commit again. You can runpre-commitrun--files*.pyto manually run the formatters.