This document describes the current stable version of pytest_celery (1.0). For development docs, go here.
Tox Environments¶
- Release:
1.0
- Date:
Apr 29, 2024
Tox is used to manage the development environments, which are defined in the tox.ini file.
To see all possible environments, run:
tox -av
This guide will explain the different environments and how they are used.
tox¶
There are three test environments:
unit: Run the unit tests. Does not require docker.
integration: Run the integration tests. Requires docker.
smoke: Run the smoke tests. Requires docker. Simulates a production environment for the plugin.
requires =
tox>4
tox-gh-actions
envlist =
{py38,py39,py310,py311,py312}-unit
{py38,py39,py310,py311,py312}-integration
{py38,py39,py310,py311,py312}-smoke
suicide_timeout = 1
Execution¶
To run the tests, use:
tox -e py3<version>-<env>
Where <version> is the python version and <env> is the environment to run.
For example,
To run the unit tests with python 3.12, use:
tox -e py312-unit
To run the integration tests with python 3.12, use:
tox -e py312-integration
To run the smoke tests with python 3.12, use:
tox -e py312-smoke
gh-actions¶
This section refers to the GitHub Actions configuration with tox-gh-actions.
python =
3.8: py38-unit, py38-integration, py38-smoke
3.9: py39-unit, py39-integration, py39-smoke
3.10: py310-unit, py310-integration, py310-smoke
3.11: py311-unit, py311-integration, py311-smoke
3.12: py312-unit, py312-integration, py312-smoke
testenv¶
These configurations are used to define the base settings for the tox environments.
Note
The convention is to use the latest python version as the default.
description = Run tests using {basepython}
skip_install = true
allowlist_externals = poetry, pytest, bash, tox
setenv =
PYTHONUNBUFFERED = 1
PYTHONDONTWRITEBYTECODE = 1
commands_pre =
poetry install -E "all" --with test
commands =
unit: poetry run pytest tests/unit/ --maxfail=3 {posargs}
integration: poetry run pytest tests/integration/ --exitfirst --dist=loadscope {posargs}
smoke: poetry run pytest tests/smoke/ --exitfirst --dist=loadscope {posargs}
basepython =
3.8: py38
3.9: py39
3.10: py310
3.11: py311
3.12: py312
mypy: py312
lint: py312
clean: py312
xdist: py312
parallel: py312
docs: py312
docs-livehtml: py312
docs-apidoc: py312
usedevelop = True
xdist¶
This environment is used to run all the tests in parallel using pytest-xdist.
description = Run tests using {basepython} with xdist
setenv =
PYTHONUNBUFFERED = 1
PYTHONDONTWRITEBYTECODE = 1
commands_pre =
poetry install -E "all" --with test
commands =
poetry run pytest tests --exitfirst \
-n auto --dist=loadscope \
--reruns 5 --rerun-except AssertionError \
{posargs}
Execution¶
To run this environment, use:
tox -e xdist
parallel¶
This environment is used to run the tests in parallel using both tox and pytest-xdist.
It will run the test environments in parallel using the -p auto option from tox, and then run each environment itself in
parallel using pytest-xdist with the -n auto option.
It is slightly more efficient than the xdist tox environment, but less stable due to high resource usage.
description = Run unit, integration and smoke tests using {basepython} in parallel
setenv =
PYTHONUNBUFFERED = 1
PYTHONDONTWRITEBYTECODE = 1
commands_pre =
poetry install -E "all" --with test
commands =
tox -e py312-unit,py312-integration,py312-smoke -p auto -o -- --exitfirst \
-n auto --dist=loadscope \
--reruns 5 --reruns-delay 60 --rerun-except AssertionError \
{posargs}
Execution¶
To run this environment, use:
tox -e parallel
mypy¶
Standard mypy linting.
description = Run mypy using {basepython}
commands_pre =
poetry install -E "all" --only dev
poetry run mypy --install-types --non-interactive
commands =
poetry run mypy --config-file pyproject.toml
Execution¶
To run this environment, use:
tox -e mypy
lint¶
Standard linting including doc linting.
Note
Does not include mypy linting.
description = Run code+doc lint using {basepython}
allowlist_externals = poetry, make
commands_pre =
poetry install -E "all" --with dev,docs
commands =
poetry run pre-commit {posargs:run --all-files --show-diff-on-failure}
make -C ./docs apicheck
make -C ./docs linkcheck
make -C ./docs configcheck
Execution¶
To run this environment, use:
tox -e lint
To run just the pre-commit locally (without tox, without doc), use:
pre-commit run --show-diff-on-failure --color=always --all-files
clean¶
Cleans the environment from artifacts and temporary files.
Tip
Very useful for cleaning up docker artifacts when stopping tests in the middle of execution.
description = Clean up build and test artifacts using {basepython}
allowlist_externals = poetry, pytest, bash, find, make
commands_pre =
pip install -U cleanpy
commands =
cleanpy .
make -C ./docs clean
bash -c 'files=$(find . -name "*.coverage*" -type f); if [ -n "$files" ]; then echo "Removed coverage file(s):"; echo "$files" | tr " " "\n"; rm $files; fi'
bash -c 'containers=$(docker ps -aq --filter label=creator=pytest-docker-tools); if [ -n "$containers" ]; then echo "Removed Docker container(s):"; docker rm -f $containers; fi'
bash -c 'networks=$(docker network ls --filter name=pytest- -q); if [ -n "$networks" ]; then echo "Removed Docker network(s):"; docker network rm $networks; fi'
bash -c 'volumes=$(docker volume ls --filter name=pytest- -q); if [ -n "$volumes" ]; then echo "Removed Docker volume(s):"; docker volume rm $volumes; fi'
Execution¶
To run this environment, use:
tox -e clean
docs¶
Builds the documentation.
description = Build docs using {basepython}
allowlist_externals = poetry, make
commands_pre =
poetry install -E "all" --with docs
commands =
make -C ./docs html
Execution¶
To run this environment, use:
tox -e docs
docs-livehtml¶
Builds the documentation and serves it locally at http://0.0.0.0:7010/
Supports hot-reloading.
description = Build docs using {basepython} and serve in http://0.0.0.0:7010
allowlist_externals = poetry, make
commands_pre =
poetry install -E "all" --with docs
commands =
make -C ./docs livehtml
Execution¶
To run this environment, use:
tox -e docs-livehtml
docs-apidoc¶
Generates the API Documentation.
Tip
If you added a new file to the plugin’s source code, you need to run this environment to update the documentation. It will find the new files and add them to the documentation automatically.
Note
This environment is idempotent and will result in the same output if run multiple times.
description = Regenerate API Reference doc section using {basepython}
allowlist_externals = poetry, make
commands_pre =
poetry install -E "all" --with docs
commands =
make -C ./docs apidoc
Execution¶
To run this environment, use:
tox -e docs-apidoc
