{"id":6269,"library":"tox-ansible","title":"tox-ansible","description":"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.","status":"active","version":"26.3.0","language":"en","source_language":"en","source_url":"https://github.com/ansible/tox-ansible","tags":["ansible","tox","testing","ci/cd","automation","python-plugin","ansible-collections"],"install":[{"cmd":"pip install tox-ansible","lang":"bash","label":"Install tox-ansible"}],"dependencies":[{"reason":"Core testing framework, tox-ansible is a plugin for it.","package":"tox","optional":false},{"reason":"Provides pytest integration for Ansible content.","package":"pytest-ansible","optional":false},{"reason":"Used for unit and integration tests.","package":"pytest","optional":false},{"reason":"Used for parallel test execution.","package":"pytest-xdist","optional":false},{"reason":"YAML parsing for configuration and Ansible content.","package":"pyyaml","optional":false},{"reason":"Handles collection installation, ansible-core versioning, and Python dependency resolution within test environments.","package":"ansible-dev-environment","optional":false}],"imports":[{"note":"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.","symbol":"tox-ansible (plugin)","correct":"tox is invoked from the command line; tox-ansible is loaded as a plugin automatically."}],"quickstart":{"code":"touch tox-ansible.ini\ntox list --ansible --conf tox-ansible.ini\ntox -e sanity-py3.11-2.14 --ansible --conf tox-ansible.ini","lang":"bash","description":"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`."},"warnings":[{"fix":"Consult community resources and GitHub issues for clarification. Experiment with configurations carefully and incrementally.","message":"The documentation for tox-ansible has been noted as vague and difficult to follow, often leading to assumptions and guesswork when configuring tests.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that your testing environment's PYTHONPATH correctly includes the path to your Ansible collection, or investigate specific pytest-ansible configurations.","message":"Users have reported difficulties running pytest unit tests successfully without explicitly setting the PYTHONPATH to include the collection path.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Minimize overrides where possible. If custom configurations are necessary, thoroughly test them against new Python and Ansible versions, especially when upgrading dependencies.","message":"Overriding default tox-ansible configurations for integration tests might introduce fragility, potentially breaking when the underlying matrix of Python and Ansible versions changes.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For integration tests requiring specific environments, consider using custom Docker images or more explicit environment definitions to ensure stability across container updates.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}