tox-ansible

What it is and what it does

tox-ansible is a tox plugin that generates and manages test environments for Ansible collections, automating the matrix of Python versions and Ansible releases you want to validate against. Instead of manually configuring tox environments for each combination, you declare your test scope in pyproject.toml and the plugin dynamically creates sanity, unit, and integration test environments. It delegates the actual testing to ansible-test (for sanity checks) and pytest (for unit and integration tests), leaving environments intact after runs so you can debug failures locally—and ensuring test outcomes match your CI/CD pipeline.

The plugin uses tox to create isolated virtual environments in .tox/, pyyaml and tomli to parse configuration, and pytest-xdist to parallelize test execution. You control which Python versions and Ansible versions to test via simple configuration flags like skip, coverage, and downstream (to include AAP-supported cores). CalVer versioning (YY.MM.MICRO) means releases track the month they ship, and the plugin is actively maintained with support for Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Use it for:

• Test an Ansible collection against multiple Ansible versions and Python interpreters in a single command.
• Run sanity checks on collection code without manually invoking ansible-test, letting tox manage the environment.
• Generate coverage reports for unit tests across collection plugins, with 0% coverage shown for untested files.
• Reproduce CI/CD test failures locally by running the same tox environment names and configurations.
• Skip specific test environments or enable downstream AAP-certified Ansible cores via configuration flags.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A tox plugin that orchestrates testing of Ansible collections across multiple Python versions and Ansible releases, using ansible-test, pytest, and tox to manage environments.

Yes. If you maintain or test Ansible collections, this plugin eliminates manual environment setup and matrix configuration. Low install friction, active maintenance, no security vulnerabilities, and MIT licensing. The only gotcha is pre-installing the Python versions you want to test—a standard requirement for any multi-version testing tool.

Install

tox-ansible on PyPI

pip install tox-ansible

uv add tox-ansible

poetry add tox-ansible

Installing tox-ansible

Before you install

Low friction: pure Python wheel with no compiled dependencies. Active maintenance—released 2 days ago with last commit 2026-08-14. Requires Python >=3.10 and tox >=4.2, plus six runtime test dependencies (pytest, pytest-ansible, pytest-xdist, pyyaml, tomli, tox).

License in practice

MIT license (permissive) imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install tox-ansible

# Add to pyproject.toml:
# [tool.tox]
# requires = ["tox>=4.2"]
# [tool.tox-ansible]

# Then run:
tox list --ansible
tox -e sanity-py3.11-2.14 --ansible

Requires tox >=4.2, Python >=3.10, and the specific Python interpreters you want to test against (e.g., python3.11, python3.12) pre-installed on your system.

Verify before relying

• Whether pytest-ansible and pytest-xdist are automatically installed as transitive deps or must be manually added to your test environment.
• Performance characteristics when running tests in parallel across many Ansible versions and Python interpreters.
• Whether coverage reports work correctly with PyPy in addition to CPython.

Package facts

Evidence: tox_ansible-26.8.0-py3-none-any.whl

Keywords: ansible, collections, tox

Tags

More Utilities packages