The easiest way to get going with role development is to set-up a separate

Python virtual environment with the necessary packages. This can be done by

performing the following steps:

1. Ensure that the following minimum set of packages are installed via

   distribution package manager:

   - `Git <https://git-scm.com/>`_

   - `libffi <https://sourceware.org/libffi/>`_ runtime and development package.

   - `OpenSSL <https://www.openssl.org/>`_ runtime and development package.

   - `pip <https://pypi.python.org/pypi/pip/>`_

   - `virtualenv <https://pypi.python.org/pypi/virtualenv>`_

   - `virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/>`_

   - Development packages for Python.

   On Debian this can be easily done with::

     apt-get install virtualenv virtualenvwrapper git python-pip python-dev \

     libffi-dev libssl-dev

2. In order to be able to run role tests, it is necessary to install `VirtualBox

   <https://www.virtualbox.org/>`_ and `Vagrant <https://www.vagrantup.com/>`_,

   using instructions outlined on their respective websites. It is recommended

   to use latest versions available. At time of this writing the role tests have

3. In order to allow static IPv6 addresses to be allocated to virtual

   machines during testing, it is necessary to explicitly white-list

   the range used by the tests. Once the configuration file has been

   created, however, even the VirtualBox default allowed IPv4 subnet

   needs to be in the configuration explicitly as well.

   Update the VirtulBox configuration file (and make sure it can be

   read by the user running the tests):

   :file:`/etc/vbox/networks.conf`

   ::

     * 192.168.56.0/21

     * fd00::192:168:56:0/116

4. Clone the git repository::

     git clone https://code.majic.rs/majic-ansible-roles/ ~/projects/

5. Create a separate Python virtual environment::

     mkvirtualenv majic-ansible-roles -a ~/projects/majic-ansible-roles/

-----------------------

In order to maintain consistency across different roles and documentation, this

section describes development conventions that should be followed while making

modifications.

Task specifications

~~~~~~~~~~~~~~~~~~~

When writing new and updating existing tasks, keep the following in mind:

- Quote sensibly. If specifying paths (for example ``src``, ``dest``, ``path``

  etc in various models), quote the string to make it stand-out better and to

  avoid breakages.

- Avoid usage of ``set_facts`` task when same functionality can be achieved via

  ``defaults/main.yml``.

- When specifying tasks, use the fully expanded form. Do not use single-line

  form with ``param=value``.

- When specifying ``command`` or ``shell`` tasks, in case a ``creates``

  parameter or such need to be used, specify them as part of task's ``args``

  parameter. E.g.::

    - name: Run command

      args:

        creates: "/etc/mycommand"

- When sepcifying tasks, keep the following ordering between different task

  parameters:

  - ``name``

  - Module and its parameters.

  - ``become``

  - ``become_user``

  - ``when``

  - ``with_items`` / ``with_dict`` / ``with_nested``

  - ``wait_for``

  - ``register``

  - ``changed_when``

  - ``failed_when``

  - ``no_log``

  - ``notify``

  - Task tags.

Running role tests directly

---------------------------

Role tests are implemented using `Molecule <https://molecule.readthedocs.io/>`_,

`Testinfra <https://testinfra.readthedocs.io/en/latest/>`_, `VirtualBox

<https://www.virtualbox.org/>`_ and `Vagrant

<https://www.vagrantup.com/>`_. *Molecule* and *Testinfra* are installed inside

of Pyhton virtual environment, while *VirtualBox* and *Vagrant* need to be

installed distribution-wide, following instructions outlined on their

corresponding websites.

Tests can be run directly for a single role, or for one or more roles using a

dedicated shell script (see below). The shell script can also be used for

generating reports in an automated environment.

In order to run tests for a specific role, perform the following steps:

1. Switch to Python virtual environment::

     workon majic-ansible-roles

2. Change directory::

     cd roles/ROLENAME/

   multiple Debian versions if supported)::

     molecule test

Running role tests via shell script

-----------------------------------

In order to make it easier to run tests for all roles, and eventually produce

reports of such runs, a dedicated shell script is provided for running the

tests.

In order to run tests, perform the following steps:

1. Switch to Python virtual environment::

     workon majic-ansible-roles

2. Make sure you are within the root directory of Git repository.

3. Run tests for all roles and generate report::

     ./scripts/run_tests.sh -r all