A free-range, grass-fed plugin for dependably running tests using docker containers when a local version of a given Python is not available.

• Run tox targets for any version of Python which has a docker image
  • includes pypy
  • exclues Jython

It is intended to provide podman compatibility in the future, but as of now, tox-in-docker uses docker exclusively

Tox-in-docker is currently not distributed. We intend to distribute it via PyPI

Until then, you may check out this repo, and pip install . in it.

You may configure this plugin to use docker even when the project's tox configuration doesn't specify it. We may support more configuration in the future (e.g. docker config, base images), but for now, you may enable or force test execution in docker. This configuration will be overridden by any explicitly set configuration in the project configuration file.

global.in_docker: if this is true, all environments which don't have a locally available Python executable will always run in a container, if possible. Note that this will be overridden by global.always_in_docker

global.always_in_docker: if this is true, all environments will all always run in docker.

Missing Pythons will always be run in docker (unless explicitly disabled by the project).

[global]
in_docker = true

⚠️ No official Jython docker images exist, so there are no defaults for jython environments.

If no images are provided but use_docker is True, a default image either from python or pypy will be used based off of python name, e.g:

A docker image on which to run tests. Any test which has in_docker enabled and does not have this specified will use the default images.

If you wish to override general testenv settings (from the [testenv] section in tox.ini) in order to not define an image for a test (if you wish to not run that test in a container, or if you wish to define a docker build dir for a factor), you may use the string 'None' as a value for docker_image.

e.g., in this test, py37 will run in python:3.7, spam will run in python:latest, py38 will run in a bulit container, and frop will not run in a container at all

[tox]
minversion = 3.7
isolated_build = true
envlist =
    py37
    py38
    frop
    spam

[testenv]
in_docker = true
docker_image = default

commands =
    echo nope

whitelist_externals =
  echo
  cat

[testenv:py38]
docker_image = None
docker_build_dir = tests/docker
commands =
  echo horp
  cat /baz

[testenv:frop]
in_container = false

⚠️ Images used must have:

• bash
• pip
• an appropriate Python for the test in question

A list of paths, relative to the repo root, of files and folders to copy back to the source workspace. This is useful for things like coverage reports and HTML reports, etc.

• --in_container: ⚠️ This option is not meant for direct use. This is the option that tox-in-docker uses to revert to default/other behavior for the build (once in the container).
• --ignore_in_container: ⚠️ This option is not meant for direct use. Using this flag will override the behavior of the --in_container option.

Contributions are very welcome. please ensure that test coverage (by percent of statements, not count of statements) is, at minimum, what it was prior to your work.

https://taskfile.dev/installation/

Python typically ships with the venv module, but some built-in/OS-provided Pythons do not include this.

OS-packaged Pythons do not include some modules which are properly a part of the Python stdlib. In order to do development tasks, you must have the venv module.

Note that you can replace python3 with a minor version, e.g. python3.10.

sudo apt install python3-venv

Tests may be run via task with task test This runs tests with tox. If you wish to pass arguments to tox, such as environment specifiers (e.g. -e py39), you may pass any arguments you wish after a double hyphen.

For example, if you wish to only test CPython3.9 and CPython3.10:

task test -- -e py39 -e py10

Development and testing tooling is run with task.

Distributed under the terms of the BSD 2 clause license, tox-in-docker is free and open source software.

If you encounter any problems, please file an issue along with a detailed description.