Metadata-Version: 2.1
Name: tox-ansible
Version: 0.11.0
Summary: Auto-generate environments for molecule role testing
Home-page: https://github.com/greg-hellings/tox-ansible
Author: Greg Hellings
Author-email: greg.hellings@gmail.com
License: GPLv3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Framework :: tox
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
Description-Content-Type: text/markdown

[![CI Builds](https://github.com/greg-hellings/tox-ansible/workflows/CI%20Builds/badge.svg)](https://github.com/greg-hellings/tox-ansible/actions?query=workflow%3A"CI+Builds")
[![codecov](https://codecov.io/gh/greg-hellings/tox-ansible/branch/master/graph/badge.svg)](https://codecov.io/gh/greg-hellings/tox-ansible)
[![PyPI version](https://badge.fury.io/py/tox-ansible.svg)](https://badge.fury.io/py/tox-ansible)

tox-ansible-collection
----------------------

This plugin for tox auto-generates tox environments for running Molecule against roles within an Ansible
Collection. Optionally, you can then elect to filter the environments down to only a subset of them.
The tool is rather well integrated for the official [Molecule](https://github.com/ansible/molecule)
testing tool that integrates with [Ansible](https://github.com/ansible/ansible).

The plugin can also be used in the root of a regular role, but this is not its primary function.

More details
============

This plugin is designed to support auto-discovery of roles and their scenarios in an Ansible collection
repository. When it has done so, the plugin will then create a tox environment, if one does not already
exist, that contains two factors matching against the role and scenario names. For example, if you have
two roles named "user" and "group" and the "user" role has a scenario named "default" while the "group"
role has scenaiors named "default" and "fedora", then this will auto-configure tox environments named
['user-default', 'group-default', 'group-fedora'].

Additional configuration options exsit to expand this matrix automatically. For instance, you can have
it auto-generate version with tox factors for different versions of python (e.g.
['py27-user-default', 'py38-user-default']). Additional options can also be added for different versions
of Ansible (e.g. ['ansible27-user-default', 'ansible28-user-default'])

There are also options to filter the list of environment variables executed, after all the generation
matrix has been realized. The execution can be filtered to limit itself to only a particular role,
only a particular scenario, only scenarios that operate on a particular driver, or any combination of
those.

If an environment already exists that matches both the rolename and scenario factors, then this plugin
will not modify their configuration. Thus, if you need to customize a particular run, then you can do
so, but still take advantage of the filtering options and auto-generation of the environments for other
scenarios.

Configuration
-------------

tox.ini
=======

Any values in the `envlist` will be left in the default envlist by this plugin. So if you want to have
several envs that do things other than run `molecule ...` commands, you can configure those directly
in the tox.ini file.

To add global options to the molecule commands, add the arguments in a line list to the "[ansible]"
section key "molecule\_opts".

To test with the latest versions of Ansible 2.7, 2.8, AND 2.9, add a comma-delimited list to the
"[ansible]" section key "ansible".

requirements.txt
================

If a particular scenario requires a select set of Python packages to be installed in the virtualenv with
molecule and the like, you can add a "requirements.txt" file to the molecule scenario directory, and that
will be appended to the list of built-in scenario requirements.

Examples
--------

## Basic Example

The following Collections structure

```
.
├── galaxy.yml
├── roles
│   ├── my_role
│   │   ├── molecule
│   │   │   ├── otherscenario
│   │   │   │   └── molecule.yml
│   │   │   └── somescenario
│   │   │       └── molecule.yml
│   │   └── tasks
│   │       └── main.yml
│   └── other_role
│       ├── molecule
│       │   ├── basic
│       │   │   └── molecule.yml
│       │   ├── default
│       │   │   └── molecule.yml
│       │   └── somescenario
│       │       └── molecule.yml
│       └── tasks
│           └── main.yml
└── tox.ini
```

With the following tox.ini file:

```ini
[tox]
envlist =
```
Assuming the scenarios are named based on their folder (this plugin will read their
molecule.yml file to determine their actual name), will auto-generat the following
environments:

```bash
$ tox -l
my_role-otherscenario
lint_all
other_role-basic
other_role-default
other_role-somescenario
my_role-somescenario
python
```

Note that the "python" environment is a default behavior of Tox, if there are no
environments specified in the config file. To suppress it, specify at least one element
in the envlist entry within tox.ini

### tox.ini examples
To add arguments to every molecule invocation, add the
following segment to tox.ini. Each argument needs to be on a separate line, which allows
spaces and other special characters to be used without needing shell-style escapes:
```ini
[ansible]
molecule_opts =
    -c
    {toxinidir}/tests/molecule.yml
    --debug
```

To test with ansible versions 2.7.\*, 2.8.\*, and 2.9.\* across every role and scenario:
```ini
[ansible]
ansible = 2.7 2.8 2.9
```

Now the output will look like this:
```bash
$ tox -l
ansible28-other_role-default
ansible28-my_role-otherscenario
ansible27-my_role-otherscenario
ansible29-my_role-somescenario
ansible29-other_role-default
ansible28-lint_all
ansible29-my_role-otherscenario
ansible29-other_role-somescenario
ansible27-other_role-somescenario
ansible28-other_role-somescenario
ansible27-other_role-basic
ansible27-other_role-default
ansible29-other_role-basic
ansible27-my_role-somescenario
ansible28-my_role-somescenario
python
ansible29-lint_all
ansible28-other_role-basic
ansible27-lint_all
```

If you want multiple Python versions, you can also specify that:

```ini
[ansible]
python = 2.7 3.8
```

```bash
$ tox -l
py27-other_role-somescenario
py38-my_role-somescenario
py27-other_role-default
py38-lint_all
py38-other_role-somescenario
py27-other_role-basic
py38-other_role-basic
py38-my_role-otherscenario
py27-my_role-otherscenario
py27-lint_all
py38-other_role-default
py27-my_role-somescenario
python
```

Under the hood
--------------

The plugin will first look for a "galaxy.yml" file in the root of the execution. If it doesn't find this,
then it won't affect your run.

Next, the plugin looks inside of the "roles" directory and finds any subdirectories that contain a file
in the "tasks/main.yml" location. This is, technically, the only file required for an Ansible role.

Inside of every role folder, the plugin then looks for `molecule/*/molecule.yml` files and globs those
together.

It then generates new environments for any discovered (role, scenario) pairs that do not already exist
in the tox environment list (based on a name that includes "{role}-{scenario}")
and adds these to the default execution envlist with a dependency on
Molecule. This list will be expanded by any configured matrix axes with appropriate dependencies and
configurations made. Each one will execute the command "molecule test -s {scenario}" if it passes the
filter step.
