Why antsibull-nox?

antsibull-nox is designed to simplify the process of testing Ansible collections through a common interface for various tools.

Tool landscape

The CLI tool ansible-test, which is part of ansible-core, is the main way to test collections. (Note that ansible-test is included in the ansible-core package, and unrelated to the PyPI package called ansible-test.) Many collections also run ansible-lint to check roles and integration tests. molecule is another tool that collections run to test roles or even modules and plugins.

In addition these tools, there are many other tools that can test collections. For example, antsibull-docs includes a collection documentation linter. Many collections also have stricter Python linting than the pylint and pep8 checks that ansible-test offers. Likewise, tools such as black are often used with collections to format code. Some other collections use license checkers such as reuse or spell checkers such as codespell.

Running all these tools on collections can be non-trivial because collections do not contain Python packages directly. Instead, at runtime, Ansible dynamically makes collections available as a Python package named ansible_collections that is outside the root directory of each collection. Another factor that increases the complexity of testing collections with a combination of multiple tools is that every tool has its own set of dependencies that you need to install.

Benefits of antsibull-nox

antsibull-nox is built specifically for the structure of Ansible collections unlike many other test runners, such as tox, nox, pre-commit.com.

The common interface that antsibull-nox provides also makes it easier for you and your contributors to run tests locally. There is no need to install several different tools and figure out how to run them correctly. You can simply run a single nox command to execute all tests after installing antsibull-nox. You don't even need to bother with installation; just run either pipx run noxfile.py or uv run noxfile.py.