Porting to Molecule 2.4.x and Testinfra 1.7.1

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

The following instructions were applicable during the porting to new

Molecule and Testinfra version. The transition made was:

- Molecule 1.25.0 to Molecule 2.4.0.

- Testinfra 1.5.5 to Testinfra 1.7.1.

Instructions hold only some historical value.

For each role perform the following steps:

1. Go to role directory::

     workon majic-ansible-roles

     cd roles/ROLE_NAME

2. Create default scenario::

     molecule init scenario -s default -d vagrant -r ROLE_NAME

3. Remove unneded files::

     rm molecule/default/INSTALL.rst

4. Move all tests into new location::

     rm -rf molecule/default/tests/

     git mv tests molecule/default/

5. Port the old ``molecule.yml`` configuration into

   ``molecule/default/molecule.yml``.

   1. A good starting template for new Molecule configuration file

      would be::

        ---

        dependency: {}

        driver:

          name: vagrant

          provider:

            name: virtualbox

        lint:

          name: yamllint

        platforms:

          - name: helper

            box: debian/contrib-jessie64

            memory: 512

            cpus: 1

            interfaces:

              - auto_config: true

                ip: 10.31.127.2

                network_name: private_network

                type: static

          - name: parameters-mandatory-jessie64

            groups:

              - parameters-mandatory

            box: debian/contrib-jessie64

            memory: 256

            cpus: 1

            interfaces:

              - auto_config: true

                ip: 10.31.127.3

                network_name: private_network

                type: static

          - name: parameters-optional-jessie64

            groups:

              - parameters-optional

            box: debian/contrib-jessie64

            memory: 256

            cpus: 1

            interfaces:

              - auto_config: true

                ip: 10.31.127.4

                network_name: private_network

                type: static

          - name: parameters-mandatory-stretch64

            groups:

              - parameters-mandatory

            box: debian/contrib-stretch64

            memory: 256

            cpus: 1

            interfaces:

              - auto_config: true

                ip: 10.31.127.5

                network_name: private_network

                type: static

          - name: parameters-optional-stretch64

            groups:

              - parameters-optional

            box: debian/contrib-stretch64

            memory: 256

            cpus: 1

            interfaces:

              - auto_config: true

                ip: 10.31.127.6

                network_name: private_network

                type: static

        provisioner:

          name: ansible

          config_options:

            ssh_connection:

              pipelining: "True"

          lint:

            name: ansible-lint

        scenario:

          name: default

        verifier:

          name: testinfra

          lint:

            name: flake8

   2. Ensure to define additional hosts for different platforms (as

      supported by the role). If only a single platform is supported,

      still perform the rename.

   3. Make sure the IP addresses are not coliding.

   4. Make sure to add hosts to correct groups that will correspond to

      groups within ``playbook.yml``.

   5. Remove old Molecule configuration::

        git rm molecule.yml

6. Move the old playbook into new location::

     rm molecule/default/playbook.yml

     git mv playbook.yml molecule/default/playbook.yml

7. Update the playbook:

   1. Move idempotent parts of ``molecule/default/playbook.yml`` into

      ``molecule/default/prepare.yml``. Only the role-related set-up

      should remain.

      .. warning::

         Don't forget to add the ``become: yes`` to tasks.

   2. Update IP address information where necessary. Especially

      important in case of multiple Debian versions.

8. Update tests to use correct fixtures and Ansible inventory::

     sed -i -e 's/Ansible(/host.ansible(/g;s/File(/host.file(/g;s/Group(/host.group(/g;s/LocalCommand(/local.run(/g;s/Package(/host.package(/g;s/PipPackage(/host.pip_package(/g;s/Service(/host.service(/g;s/Socket(/host.socket(/g;s/Sudo(/host.sudo(/g;s/User(/host.user(/g;s/Command(/host.run(/g' molecule/default/tests/test_*.py

     sed -i -r -e 's/^(def test.*)\(.*\):/\1(host):/' molecule/default/tests/test_*.py

     sed -i -e "s#'.molecule/ansible_inventory'#'.molecule/ansible_inventory.yml'#" molecule/default/tests/test_*.py

9. Start fixing the tests:

   1. Locate all instances of ``local.run``, and ensure the ``local``

      variable is initialised once prior to use in each test.

      Commands can be found with::

        grep 'local.run' molecule/default/tests/test_*.py

      Snippet to insert::

        local = host.get_host("local://")

   2. Run linting checks, fixing any ensuing issues along the way::

        molecule lint

   3. Bring-up the machines, fixing any ensuing issues along the way::

        molecule converge

   4. Run idempotency test, fixing any ensuing issues along the way::

        molecule idempotence

   5. Figure out how to fix IP parametrisation of IPs in case of

      multiple (old) platforms, e.g. when having same machines with

      multiple debian versions. Good way to identify such tests::

        grep -ri 10.31 molecule/default/tests/test_*.py

   6. Figure out how to fix hostname parametrisation in case of

      multiple (old) platforms, e.g. when having same machines with

      multiple debian versions. Good way to identify such tests::

        grep -ri parameters- molecule/default/tests/test_*.py

   7. Run tests, fixing any ensuing issues along the way::

        molecule verify

   8. Perform one more relatively fast verification that things work

      fine::

        molecule lint && molecule idempotence && molecule verify

   9. Check the number of defined tests against number of tests

      performed. Keep in mind some tests are run for multiple

      machines, and refer to each test file to see what hosts will get

      loaded::

        grep -c 'def test_' molecule/default/tests/test_*

   10. Run the full test suite to ensure everything works correctly::

         molecule test

10. Verify and commit the changes. Template commit message::

      MAR-128: Upgraded tests for ROLE_NAME role:

      - Switch to new Molecule configuration.

      - Updated set-up playbook to use become: yes.

      - Moved some preparatory steps outside of the main playbook (eases

        idempotence tests).

      - Updated tests to reference the yml inventory file.

      - Updated tests to use new fixture (host instead of individual ones).

      - Switched to extracting IP address instead of hard-coding it in a

        couple of tests.