| Name | tox-ansible JSON |
| Version |
24.9.0
JSON |
| download |
| home_page | None |
| Summary | A radical approach to testing ansible content |
| upload_time | 2024-09-11 06:20:15 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
ansible
collections
tox
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# tox-ansible
## Introduction
`tox-ansible` is a utility designed to simplify the testing of Ansible content collections.
Implemented as a `tox` plugin, `tox-ansible` provides a simple way to test Ansible content collections across multiple Python interpreters and Ansible versions.
`tox-ansible` uses familiar python testing tools to perform the actual testing. It uses `tox` to create and manage the testing environments, `ansible-test sanity` to run the sanity tests, and `pytest` to run the unit and integration tests. This eliminated the black box nature of other approaches and allowed for more control over the testing process.
When used on a local development system, each of the environments are left intact after a test run. This allows for easy debugging of failed tests for a given test type, python interpreter and Ansible version.
By using `tox` to create and manage the testing environments, Test outcomes should always be the same on a local development system as they are in a CI/CD pipeline.
`tox` virtual environments are created in the `.tox` directory. These are easily deleted and recreated if needed.
## Talk to us
Need help or want to discuss the project? See our [Contributor guide](https://ansible.readthedocs.io/projects/tox-ansible/contributor_guide/#talk-to-us) join the conversation!
## Installation
Install from pypi:
```bash
pip install tox-ansible
```
## Usage
From the root of your collection, create an empty `tox-ansible.ini` file and list the available environments:
```bash
touch tox-ansible.ini
tox list --ansible --conf tox-ansible.ini
```
A list of dynamically generated Ansible environments will be displayed:
```
default environments:
...
integration-py3.11-2.14 -> Integration tests for ansible.scm using ansible-core 2.14 and python 3.11
integration-py3.11-devel -> Integration tests for ansible.scm using ansible-core devel and python 3.11
integration-py3.11-milestone -> Integration tests for ansible.scm using ansible-core milestone and python 3.11
...
sanity-py3.11-2.14 -> Sanity tests for ansible.scm using ansible-core 2.14 and python 3.11
sanity-py3.11-devel -> Sanity tests for ansible.scm using ansible-core devel and python 3.11
sanity-py3.11-milestone -> Sanity tests for ansible.scm using ansible-core milestone and python 3.11
...
unit-py3.11-2.14 -> Unit tests for ansible.scm using ansible-core 2.14 and python 3.11
unit-py3.11-devel -> Unit tests for ansible.scm using ansible-core devel and python 3.11
unit-py3.11-milestone -> Unit tests for ansible.scm using ansible-core milestone and python 3.11
```
These represent the available testing environments. Each denotes the type of tests that will be run, the Python interpreter used to run the tests, and the Ansible version used to run the tests.
To run tests with a single environment, simply run the following command:
```bash
tox -e sanity-py3.11-2.14 --ansible --conf tox-ansible.ini
```
To run tests with multiple environments, simply add the environment names to the command:
```bash
tox -e sanity-py3.11-2.14,unit-py3.11-2.14 --ansible --conf tox-ansible.ini
```
To run all tests of a specific type in all available environments, use the factor `-f` flag:
```bash
tox -f unit --ansible -p auto --conf tox-ansible.ini
```
To run all tests across all available environments:
```bash
tox --ansible -p auto --conf tox-ansible.ini
```
Note: The `-p auto` flag will run multiple tests in parallel.
Note: The specific Python interpreter will need to be pre-installed on your system, e.g.:
```bash
sudo dnf install python3.10
```
To review the specific commands and configuration for each of the integration, sanity, and unit factors:
```bash
tox config --ansible --conf tox-ansible.ini
```
Generate specific GitHub action matrix as per scope mentioned with `--matrix-scope`:
```bash
tox --ansible --gh-matrix --matrix-scope unit --conf tox-ansible.ini
```
A list of dynamically generated Ansible environments will be displayed specifically for unit tests:
```
[
{
"description": "Unit tests using ansible 2.9 and python 3.8",
"factors": [
"unit",
"py3.8",
"2.9"
],
"name": "unit-py3.8-2.9",
"python": "3.8"
},
...
{
"description": "Unit tests using ansible-core milestone and python 3.12",
"factors": [
"unit",
"py3.12",
"milestone"
],
"name": "unit-py3.12-milestone",
"python": "3.12"
}
]
```
## Configuration
`tox-ansible` should be configured using a `tox-ansible.ini` file. Using a `tox-ansible.ini` file allows for the introduction of the `tox-ansible` plugin to a repository that may already have an existing `tox` configuration without conflicts. If no configuration overrides are needed, the `tox-ansible.ini` file may be empty but should be present. In addition to all `tox` supported keywords the `ansible` section and `skip` keyword are available:
```ini
# tox-ansible.ini
[ansible]
skip =
2.9
devel
```
This will skip tests in any environment that uses Ansible 2.9 or the devel branch. The list of strings is used for a simple string in string comparison of environment names. Here is the [guide] to override `tox-ansible` environment configuration.
[guide]: https://ansible.readthedocs.io/projects/tox-ansible/configuration/#overriding-the-configuration
## Release process
`tox-ansible` is released with [CalVer] scheme version numbers. The particular scheme we are using is `YY.MM.MICRO`, meaning that a release in March 2025 will be named `25.3.0`, and if a patch (ie, non-feature) release is required for that release, it will be named 25.3.1, even if it is released in April. The month will not increment until a new version with features or other significant changes is released. More details about calver release process can be seen [here].
[here]: https://ansible.readthedocs.io/projects/team-devtools/guides/calver/
[CalVer]: https://calver.org/
## Note to version 1.x users
Users of tox-ansible v1 should use the stable/1.x branch because the default branch is a rewrite of the plugin for tox 4.0+ which is not backward compatible with the old plugin.
Version 1 of the plugin had native support for molecule. Please see the "Running molecule scenarios" above for an alternative approach.
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "tox-ansible",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Ansible by Red Hat <info@ansible.com>",
"keywords": "ansible, collections, tox",
"author": null,
"author_email": "\"Bradley A. Thornton\" <bthornto@redhat.com>",
"download_url": "https://files.pythonhosted.org/packages/fd/53/5fb51ae1e9918c311cd9a6821e9324227a7df4133233504397220d33db59/tox_ansible-24.9.0.tar.gz",
"platform": null,
"description": "# tox-ansible\n\n## Introduction\n\n`tox-ansible` is a utility designed to simplify the testing of Ansible content collections.\n\nImplemented as a `tox` plugin, `tox-ansible` provides a simple way to test Ansible content collections across multiple Python interpreters and Ansible versions.\n\n`tox-ansible` uses familiar python testing tools to perform the actual testing. It uses `tox` to create and manage the testing environments, `ansible-test sanity` to run the sanity tests, and `pytest` to run the unit and integration tests. This eliminated the black box nature of other approaches and allowed for more control over the testing process.\n\nWhen used on a local development system, each of the environments are left intact after a test run. This allows for easy debugging of failed tests for a given test type, python interpreter and Ansible version.\n\nBy using `tox` to create and manage the testing environments, Test outcomes should always be the same on a local development system as they are in a CI/CD pipeline.\n\n`tox` virtual environments are created in the `.tox` directory. These are easily deleted and recreated if needed.\n\n## Talk to us\n\nNeed help or want to discuss the project? See our [Contributor guide](https://ansible.readthedocs.io/projects/tox-ansible/contributor_guide/#talk-to-us) join the conversation!\n\n## Installation\n\nInstall from pypi:\n\n```bash\npip install tox-ansible\n```\n\n## Usage\n\nFrom the root of your collection, create an empty `tox-ansible.ini` file and list the available environments:\n\n```bash\ntouch tox-ansible.ini\ntox list --ansible --conf tox-ansible.ini\n```\n\nA list of dynamically generated Ansible environments will be displayed:\n\n```\n\ndefault environments:\n...\nintegration-py3.11-2.14 -> Integration tests for ansible.scm using ansible-core 2.14 and python 3.11\nintegration-py3.11-devel -> Integration tests for ansible.scm using ansible-core devel and python 3.11\nintegration-py3.11-milestone -> Integration tests for ansible.scm using ansible-core milestone and python 3.11\n...\nsanity-py3.11-2.14 -> Sanity tests for ansible.scm using ansible-core 2.14 and python 3.11\nsanity-py3.11-devel -> Sanity tests for ansible.scm using ansible-core devel and python 3.11\nsanity-py3.11-milestone -> Sanity tests for ansible.scm using ansible-core milestone and python 3.11\n...\nunit-py3.11-2.14 -> Unit tests for ansible.scm using ansible-core 2.14 and python 3.11\nunit-py3.11-devel -> Unit tests for ansible.scm using ansible-core devel and python 3.11\nunit-py3.11-milestone -> Unit tests for ansible.scm using ansible-core milestone and python 3.11\n```\n\nThese represent the available testing environments. Each denotes the type of tests that will be run, the Python interpreter used to run the tests, and the Ansible version used to run the tests.\n\nTo run tests with a single environment, simply run the following command:\n\n```bash\ntox -e sanity-py3.11-2.14 --ansible --conf tox-ansible.ini\n```\n\nTo run tests with multiple environments, simply add the environment names to the command:\n\n```bash\ntox -e sanity-py3.11-2.14,unit-py3.11-2.14 --ansible --conf tox-ansible.ini\n```\n\nTo run all tests of a specific type in all available environments, use the factor `-f` flag:\n\n```bash\ntox -f unit --ansible -p auto --conf tox-ansible.ini\n```\n\nTo run all tests across all available environments:\n\n```bash\ntox --ansible -p auto --conf tox-ansible.ini\n```\n\nNote: The `-p auto` flag will run multiple tests in parallel.\nNote: The specific Python interpreter will need to be pre-installed on your system, e.g.:\n\n```bash\nsudo dnf install python3.10\n```\n\nTo review the specific commands and configuration for each of the integration, sanity, and unit factors:\n\n```bash\ntox config --ansible --conf tox-ansible.ini\n```\n\nGenerate specific GitHub action matrix as per scope mentioned with `--matrix-scope`:\n\n```bash\ntox --ansible --gh-matrix --matrix-scope unit --conf tox-ansible.ini\n```\n\nA list of dynamically generated Ansible environments will be displayed specifically for unit tests:\n\n```\n[\n {\n \"description\": \"Unit tests using ansible 2.9 and python 3.8\",\n \"factors\": [\n \"unit\",\n \"py3.8\",\n \"2.9\"\n ],\n \"name\": \"unit-py3.8-2.9\",\n \"python\": \"3.8\"\n },\n ...\n {\n \"description\": \"Unit tests using ansible-core milestone and python 3.12\",\n \"factors\": [\n \"unit\",\n \"py3.12\",\n \"milestone\"\n ],\n \"name\": \"unit-py3.12-milestone\",\n \"python\": \"3.12\"\n }\n]\n```\n\n## Configuration\n\n`tox-ansible` should be configured using a `tox-ansible.ini` file. Using a `tox-ansible.ini` file allows for the introduction of the `tox-ansible` plugin to a repository that may already have an existing `tox` configuration without conflicts. If no configuration overrides are needed, the `tox-ansible.ini` file may be empty but should be present. In addition to all `tox` supported keywords the `ansible` section and `skip` keyword are available:\n\n```ini\n# tox-ansible.ini\n[ansible]\nskip =\n 2.9\n devel\n```\n\nThis will skip tests in any environment that uses Ansible 2.9 or the devel branch. The list of strings is used for a simple string in string comparison of environment names. Here is the [guide] to override `tox-ansible` environment configuration.\n\n[guide]: https://ansible.readthedocs.io/projects/tox-ansible/configuration/#overriding-the-configuration\n\n## Release process\n\n`tox-ansible` is released with [CalVer] scheme version numbers. The particular scheme we are using is `YY.MM.MICRO`, meaning that a release in March 2025 will be named `25.3.0`, and if a patch (ie, non-feature) release is required for that release, it will be named 25.3.1, even if it is released in April. The month will not increment until a new version with features or other significant changes is released. More details about calver release process can be seen [here].\n\n[here]: https://ansible.readthedocs.io/projects/team-devtools/guides/calver/\n[CalVer]: https://calver.org/\n\n## Note to version 1.x users\n\nUsers of tox-ansible v1 should use the stable/1.x branch because the default branch is a rewrite of the plugin for tox 4.0+ which is not backward compatible with the old plugin.\n\nVersion 1 of the plugin had native support for molecule. Please see the \"Running molecule scenarios\" above for an alternative approach.\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A radical approach to testing ansible content",
"version": "24.9.0",
"project_urls": {
"changelog": "https://github.com/ansible/tox-ansible/releases",
"documentation": "https://ansible.readthedocs.io/projects/tox-ansible/",
"homepage": "https://github.com/ansible/tox-ansible",
"repository": "https://github.com/ansible/tox-ansible"
},
"split_keywords": [
"ansible",
" collections",
" tox"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "68117c5ad19518cde4f5c6248acde23dfd82c3df6b5b80af67d8e39d1db13769",
"md5": "633200725854bd85780ba6c87bf5ee34",
"sha256": "7a3f9e31ee623b1bf729401c6ac54f9574d58d46228466c7aa54ad7c7252e43c"
},
"downloads": -1,
"filename": "tox_ansible-24.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "633200725854bd85780ba6c87bf5ee34",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10266,
"upload_time": "2024-09-11T06:20:13",
"upload_time_iso_8601": "2024-09-11T06:20:13.932977Z",
"url": "https://files.pythonhosted.org/packages/68/11/7c5ad19518cde4f5c6248acde23dfd82c3df6b5b80af67d8e39d1db13769/tox_ansible-24.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd535fb51ae1e9918c311cd9a6821e9324227a7df4133233504397220d33db59",
"md5": "32a86a5fe816658f8dee224b3bb2c712",
"sha256": "645032a1ac3d8911d9f43b673c367bf6c68e77b8a4e7667618c89985cd86e0a3"
},
"downloads": -1,
"filename": "tox_ansible-24.9.0.tar.gz",
"has_sig": false,
"md5_digest": "32a86a5fe816658f8dee224b3bb2c712",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 39004,
"upload_time": "2024-09-11T06:20:15",
"upload_time_iso_8601": "2024-09-11T06:20:15.474984Z",
"url": "https://files.pythonhosted.org/packages/fd/53/5fb51ae1e9918c311cd9a6821e9324227a7df4133233504397220d33db59/tox_ansible-24.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 06:20:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ansible",
"github_project": "tox-ansible",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "tox-ansible"
}
