From 665f9d89c94c524b1d2b82bc362cbc6951e8c5ca Mon Sep 17 00:00:00 2001 From: KB-perByte Date: Mon, 6 Nov 2023 16:43:03 +0530 Subject: [PATCH 1/5] test --- src/tox_ansible/plugin.py | 6 ++++-- tox-ansible.ini | 0 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 tox-ansible.ini diff --git a/src/tox_ansible/plugin.py b/src/tox_ansible/plugin.py index 940a95b..c648f20 100644 --- a/src/tox_ansible/plugin.py +++ b/src/tox_ansible/plugin.py @@ -15,7 +15,7 @@ from typing import TYPE_CHECKING, List, TypeVar import yaml - +# import q from tox.config.loader.memory import MemoryLoader from tox.config.loader.section import Section from tox.config.loader.str_convert import StrConvert @@ -114,7 +114,9 @@ def tox_add_option(parser: ToxParser) -> None: "--gh-matrix", action="store_true", default=False, + # choices=["all", "sanity", "integration", "unit"], help="Emit a github matrix", + # type=str, ) parser.add_argument( @@ -155,7 +157,7 @@ def tox_add_core_config( global TOX_WORK_DIR # pylint: disable=global-statement # noqa: PLW0603 TOX_WORK_DIR = state.conf.work_dir env_list = add_ansible_matrix(state) - + # q(state.conf.options.gh_matrix) if not state.conf.options.gh_matrix: return diff --git a/tox-ansible.ini b/tox-ansible.ini new file mode 100644 index 0000000..e69de29 From 77528c37750ae830f9df06940e30ce6e680046e1 Mon Sep 17 00:00:00 2001 From: KB-perByte Date: Mon, 6 Nov 2023 18:30:18 +0530 Subject: [PATCH 2/5] add attributes --- src/tox_ansible/plugin.py | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/src/tox_ansible/plugin.py b/src/tox_ansible/plugin.py index c648f20..5cdfbf8 100644 --- a/src/tox_ansible/plugin.py +++ b/src/tox_ansible/plugin.py @@ -15,7 +15,6 @@ from typing import TYPE_CHECKING, List, TypeVar import yaml -# import q from tox.config.loader.memory import MemoryLoader from tox.config.loader.section import Section from tox.config.loader.str_convert import StrConvert @@ -110,13 +109,18 @@ def tox_add_option(parser: ToxParser) -> None: :param parser: The tox CLI parser. """ + parser.add_argument( + "--matrix-scope", + default="all", + choices=["all", "sanity", "integration", "unit"], + help="Emit a github matrix specific to scope mentioned", + ) + parser.add_argument( "--gh-matrix", action="store_true", default=False, - # choices=["all", "sanity", "integration", "unit"], help="Emit a github matrix", - # type=str, ) parser.add_argument( @@ -157,11 +161,11 @@ def tox_add_core_config( global TOX_WORK_DIR # pylint: disable=global-statement # noqa: PLW0603 TOX_WORK_DIR = state.conf.work_dir env_list = add_ansible_matrix(state) - # q(state.conf.options.gh_matrix) + if not state.conf.options.gh_matrix: return - generate_gh_matrix(env_list=env_list) + generate_gh_matrix(env_list=env_list, section=state.conf.options.matrix_scope) sys.exit(0) @@ -258,14 +262,17 @@ def add_ansible_matrix(state: State) -> EnvList: return env_list -def generate_gh_matrix(env_list: EnvList) -> None: +def generate_gh_matrix(env_list: EnvList, section: str) -> None: """Generate the github matrix. :param env_list: The environment list. + :param section: The test section to be generated. """ results = [] for env_name in env_list.envs: + if section != "all" and not env_name.startswith(section): + continue candidates = [] factors = env_name.split("-") for factor in factors: From 03606c95b65f5f4f0869dfac6304bb50db71fb68 Mon Sep 17 00:00:00 2001 From: KB-perByte Date: Mon, 6 Nov 2023 19:01:29 +0530 Subject: [PATCH 3/5] tweak --- .gitignore | 3 +++ README.md | 32 ++++++++++++++++---------------- tox-ansible.ini | 0 3 files changed, 19 insertions(+), 16 deletions(-) delete mode 100644 tox-ansible.ini diff --git a/.gitignore b/.gitignore index b58ef2b..9bccfff 100644 --- a/.gitignore +++ b/.gitignore @@ -161,3 +161,6 @@ cython_debug/ # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. #.idea/ + +# VS Code specific files +.vscode/ \ No newline at end of file diff --git a/README.md b/README.md index 8a4549e..6a9b8b2 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,13 @@ ## Introduction -`tox-ansible` is a utility designed to simplify the testing of ansible content collections. +`tox-ansible` is a utility designed to simplify the testing of Ansible content collections. -Implemented as `tox` plugin, `tox-ansible` provides a simple way to test ansible content collections across multiple python interpreter and ansible versions. +Implemented as `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 allows for more control over the testing process. +`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. +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. @@ -41,7 +41,7 @@ touch tox-ansible.ini tox list --ansible --conf tox-ansible.ini ``` -A list of dynamically generated ansible environments will be displayed: +A list of dynamically generated Ansible environments will be displayed: ``` @@ -60,7 +60,7 @@ unit-py3.11-devel -> Unit tests for ansible.scm using ansible-core de unit-py3.11-milestone -> Unit tests for ansible.scm using ansible-core milestone and python 3.11 ``` -These represent the testing environments that are available. 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. +These represent the testing environments that are available. 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: @@ -87,7 +87,7 @@ 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 you system, e.g.: +Note: The specific Python interpreter will need to be pre-installed on your system, e.g.: ```bash sudo dnf install python3.9 @@ -101,7 +101,7 @@ tox config --ansible --conf tox-ansible.ini ## 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 is available: +`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 @@ -111,7 +111,7 @@ skip = devel ``` -This will skip tests in any environment that use ansible 2.9 or the devel branch. The list of strings are used for a simple string in string comparison of environment names. +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. ## Overriding the configuration @@ -149,7 +149,7 @@ The behavior of the `ansible-test` (for `sanity-*` environments) or `pytest` (fo tox -f sanity --ansible --conf tox-ansible.ini -- --test validate-modules -vvv ``` -The arguments after the `--` will be passed to the `ansible-test` command. Thus in this example only the `validate-modules` sanity test will run, but with an increased verbosity. +The arguments after the `--` will be passed to the `ansible-test` command. Thus in this example, only the `validate-modules` sanity test will run, but with an increased verbosity. Same can be done to pass arguments to the `pytest` commands for the `unit-*` and `integration-*` environments: @@ -159,13 +159,13 @@ tox -e unit-py3.11-2.15 --ansible --conf tox-ansible.ini -- --junit-xml=tests/ou ## Usage in a CI/CD pipeline -The repo contains a github workflow that can be used in a github actions CI/CD pipeline. The workflow will run all tests across all available environments, unless limited by the `skip` option in the `tox-ansible.ini` file. +The repo contains a GitHub workflow that can be used in a GitHub actions CI/CD pipeline. The workflow will run all tests across all available environments unless limited by the `skip` option in the `tox-ansible.ini` file. Each environment will be run in a separate job. The workflow will run all jobs in parallel. -The github matrix is dynamically created by `tox-ansible` using the `--gh-matrix` and `--ansible` flags. The list of environments is converted to a list of entries in json format and added the file specified by the "GITHUB_OUTPUT" environment variable. The workflow will read this file and use it to create the matrix. +The GitHub matrix is dynamically created by `tox-ansible` using the `--gh-matrix` and `--ansible` flags. The list of environments is converted to a list of entries in json format and added to the file specified by the "GITHUB_OUTPUT" environment variable. The workflow will read this file and use it to create the matrix. -A sample use of the github workflow might look like this: +A sample use of the GitHub workflow might look like this: ```yaml name: Test collection @@ -201,7 +201,7 @@ Sample `json` ## Testing molecule scenarios -Although the `tox-ansible` plugin does not have functionality specific to molecule, it can be a powerful tool to run `molecule` scenarios across a matrix of ansible and python versions. +Although the `tox-ansible` plugin does not have functionality specific to molecule, it can be a powerful tool to run `molecule` scenarios across a matrix of Ansible and Python versions. This can be accomplished by presenting molecule scenarios as integration tests available through `pytest` using the [pytest-ansible](https://github.com/ansible-community/pytest-ansible) plugin, which is installed when `tox-ansible` is installed. @@ -272,14 +272,14 @@ This approach provides the flexibility of running the `molecule` scenarios direc ## How does it work? -`tox` will, by default, create a python virtual environment for a given environment. `tox-ansible` adds ansible collection specific build and test logic to tox. The collection is copied into the virtual environment created by tox, built, and installed into the virtual environment. The installation of the collection will include the collection's collection dependencies. `tox-ansible` will also install any python dependencies from a `test-requirements.txt` (or `requirements-test.txt`) and `requirements.txt` file. The virtual environment's temporary directory is used, so the copy, build and install steps are performed with each test run ensuring the current collection code is used. +`tox` will, by default, create a Python virtual environment for a given environment. `tox-ansible` adds Ansible collection specific build and test logic to tox. The collection is copied into the virtual environment created by tox, built, and installed into the virtual environment. The installation of the collection will include the collection's collection dependencies. `tox-ansible` will also install any Python dependencies from a `test-requirements.txt` (or `requirements-test.txt`) and `requirements.txt` file. The virtual environment's temporary directory is used, so the copy, build and install steps are performed with each test run ensuring the current collection code is used. `tox-ansible` also sets the `ANSIBLE_COLLECTIONS_PATH` environment variable to point to the virtual environment's temporary directory. This ensures that the collection under test is used when running tests. The `pytest-ansible-units` pytest plugin injects the `ANSIBLE_COLLECTIONS_PATH` environment variable into the collection loader so ansible-core can locate the collection. `pytest` is ued to run both the `unit` and `integration tests`. `ansible-test sanity` is used to run the `sanity` tests. -For a full configuration examples for each of the sanity, integration, and unit tests including the commands being run and the environments variables being set and passed, see the following: +For full configuration examples for each of the sanity, integration, and unit tests including the commands being run and the environment variables being set and passed, see the following: - [integration](docs/integration.ini) - [sanity](docs/sanity.ini) diff --git a/tox-ansible.ini b/tox-ansible.ini deleted file mode 100644 index e69de29..0000000 From 77dfccdd5978c0e65c661a18079e1c444146a29b Mon Sep 17 00:00:00 2001 From: KB-perByte Date: Mon, 6 Nov 2023 19:12:14 +0530 Subject: [PATCH 4/5] add some documentation --- .gitignore | 2 +- README.md | 36 +++++++++++++++++++++++++++++++++++- 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 9bccfff..d114c67 100644 --- a/.gitignore +++ b/.gitignore @@ -163,4 +163,4 @@ cython_debug/ #.idea/ # VS Code specific files -.vscode/ \ No newline at end of file +.vscode/ diff --git a/README.md b/README.md index 6a9b8b2..97166b7 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ unit-py3.11-devel -> Unit tests for ansible.scm using ansible-core de unit-py3.11-milestone -> Unit tests for ansible.scm using ansible-core milestone and python 3.11 ``` -These represent the testing environments that are available. 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. +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: @@ -99,6 +99,40 @@ To review the specific commands and configuration for each of the integration, s 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: From db9aa58332852f9c01dac8618d66f6d027661f23 Mon Sep 17 00:00:00 2001 From: KB-perByte Date: Mon, 6 Nov 2023 19:13:57 +0530 Subject: [PATCH 5/5] revert empty line --- src/tox_ansible/plugin.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/tox_ansible/plugin.py b/src/tox_ansible/plugin.py index 5cdfbf8..3ffcd1f 100644 --- a/src/tox_ansible/plugin.py +++ b/src/tox_ansible/plugin.py @@ -15,6 +15,7 @@ from typing import TYPE_CHECKING, List, TypeVar import yaml + from tox.config.loader.memory import MemoryLoader from tox.config.loader.section import Section from tox.config.loader.str_convert import StrConvert