tox-ansible

26.3.0 · active · verified Tue Apr 14

tox-ansible is a utility designed to simplify the testing of Ansible content collections. Implemented as a tox plugin, it provides a streamlined way to test Ansible content across various Python interpreters and Ansible versions. It leverages tox for environment management, ansible-test sanity for sanity checks, and pytest for unit and integration tests. The current version is 26.3.0, and it follows a regular release cadence, often aligning with other Ansible development tools.

Warnings

gotcha The documentation for tox-ansible has been noted as vague and difficult to follow, often leading to assumptions and guesswork when configuring tests.
Fix: Consult community resources and GitHub issues for clarification. Experiment with configurations carefully and incrementally.
gotcha Users have reported difficulties running pytest unit tests successfully without explicitly setting the PYTHONPATH to include the collection path.
Fix: Ensure that your testing environment's PYTHONPATH correctly includes the path to your Ansible collection, or investigate specific pytest-ansible configurations.
gotcha Overriding default tox-ansible configurations for integration tests might introduce fragility, potentially breaking when the underlying matrix of Python and Ansible versions changes.
Fix: Minimize overrides where possible. If custom configurations are necessary, thoroughly test them against new Python and Ansible versions, especially when upgrading dependencies.
gotcha Avoid using specific Python versions (e.g., `py39`) directly in the `envlist` for CI/CD pipelines. This can introduce bugs if the default Python version used for testing changes in the CI/CD environment.
Fix: Use generic environment names like `py` for unit tests and rely on tox-ansible's dynamic environment generation for version matrix testing. For CI/CD, ensure the base Python interpreter is consistent or explicitly defined outside the tox `envlist`.
gotcha When running integration tests using `ansible-test` with default Docker containers, tests can unexpectedly fail due to updates in the base container (e.g., OS version changes), especially if your software has specific OS dependencies.
Fix: For integration tests requiring specific environments, consider using custom Docker images or more explicit environment definitions to ensure stability across container updates.

Install

pip install tox-ansible Install tox-ansible

Imports

tox-ansible (plugin)
```
tox is invoked from the command line; tox-ansible is loaded as a plugin automatically.
```
tox-ansible is a tox plugin and is not typically imported directly in Python code. Its functionality is exposed via the 'tox' command-line interface.

Quickstart

To get started, create an empty `tox-ansible.ini` file in the root of your Ansible collection. Then, list the dynamically generated Ansible testing environments using `tox list --ansible --conf tox-ansible.ini`. To run tests in a specific environment, like `sanity-py3.11-2.14`, execute `tox -e sanity-py3.11-2.14 --ansible --conf tox-ansible.ini`. You can also run all tests of a specific type (e.g., `unit`) across all available environments using `tox -f unit --ansible -p auto --conf tox-ansible.ini`.

touch tox-ansible.ini
tox list --ansible --conf tox-ansible.ini
tox -e sanity-py3.11-2.14 --ansible --conf tox-ansible.ini

view raw JSON →