Merge branch 'main' into add_kubevirt_integration_example

.config/requirements-test.txt

@@ -8,6 +8,7 @@ filelock >= 3.9.0
 pexpect >= 4.8.0, < 5
 pytest-mock >= 3.10.0
 pytest-plus >= 0.4.0
+pytest-testinfra >= 7.0.0
 pytest-xdist >= 3.1.0
 pytest >= 7.2.0
 check-jsonschema

.config/requirements.txt

@@ -76,6 +76,7 @@ pymdown-extensions==10.0.1
 pytest==7.4.0
 pytest-mock==3.11.1
 pytest-plus==0.4.0
+pytest-testinfra==8.1.0
 pytest-xdist==3.3.1
 python-dateutil==2.8.2
 python-slugify==8.0.1

.github/workflows/tox.yml

@@ -51,7 +51,7 @@ jobs:
       matrix: ${{ fromJson(needs.pre.outputs.matrix) }}
 
     env:
-      PYTEST_REQPASS: 424
+      PYTEST_REQPASS: 446
     steps:
       - uses: actions/checkout@v3
         with:

.pre-commit-config.yaml

@@ -91,6 +91,7 @@ repos:
           - jsonschema
           - pexpect
           - pytest-mock
+          - pytest-testinfra
   - repo: https://github.com/jazzband/pip-tools
     rev: 6.14.0
     hooks:

docs/ci.md

@@ -401,6 +401,8 @@ won't create any conflict.
 ---
 dependency:
   name: galaxy
+driver:
+  name: docker
 platforms:
   - name: instance1-$TOX_ENVNAME
     image: mariadb
@@ -410,4 +412,6 @@ platforms:
     command: /usr/sbin/init
 provisioner:
   name: ansible
+verifier:
+  name: testinfra
 ```

docs/configuration.md

@@ -4,18 +4,18 @@
 
 ## Prerun
 
-In order to help Ansible find used modules and roles, molecule will
+To help Ansible find used modules and roles, molecule will
 perform a prerun set of actions. These involve installing dependencies
-from `requirements.yml` specified at project level, install a standalone
+from `requirements.yml` specified at the project level, installing a standalone
 role or a collection. The destination is `project_dir/.cache` and the
 code itself was reused from ansible-lint, which has to do the same
 actions. (Note: ansible-lint is not included with molecule.)
 
 This assures that when you include a role inside molecule playbooks,
-Ansible will be able to find that role, and that the include is exactly
+Ansible will be able to find that role and that the include is exactly
 the same as the one you are expecting to use in production.
 
-If for some reason the prerun action does not suits your needs, you can
+If for some reason the prerun action does not suit your needs, you can
 still disable it by adding `prerun: false` inside the
 configuration file.
 
@@ -28,7 +28,7 @@ your project, in order to avoid adding it to each scenario.
 By default, `Molecule` will check whether the role name follows the name
 standard. If not, it will raise an error.
 
-If computed fully qualified role name does not follow current galaxy
+If the computed fully qualified role name does not follow current galaxy
 requirements, you can ignore it by adding `role_name_check:1` inside the configuration file.
 
 It is strongly recommended to follow the name standard of
@@ -40,7 +40,7 @@ and
 
 ::: molecule.interpolation.Interpolator
 
-There are following environment variables available in `molecule.yml`:
+Following are the environment variables available in `molecule.yml`:
 
 MOLECULE_DEBUG
 
@@ -57,7 +57,7 @@ MOLECULE_ENV_FILE
 
 MOLECULE_STATE_FILE
 
-: Path to molecule state file, contains state of the instances
+: The path to molecule state file contains the state of the instances
 (created, converged, etc.). Usually
 `~/.cache/molecule/<role-name>/<scenario-name>/state.yml`
 
@@ -249,12 +249,12 @@ test_sequence:
 `provisioner.playbooks` section of molecule.yml.
 
 `side_effect` can have one or more arguments (separated by spaces) which is
-a playbook (plabyooks) to execute. If the argument for `side_effect` is present,
+a playbook (playbooks) to execute. If the argument for `side_effect` is present,
 it's executed instead. The path to the playbook is relative to the molecule.yml location.
 Normal side effect settings (from `provisioner.playbooks`) are ignored for action with
 argument.
 
-`verify` without an argument is executing usual tests configured in the verifier section
+`verify` without an argument is executing the usual tests configured in the verifier section
 of molecule.yml.
 
 If one or more arguments (separated by spaces) are present, each argument is treated
@@ -263,9 +263,9 @@ The kind of verifier is set in the `verifier` section of molecule.yml and is app
 `verify` actions in the scenario.
 
 The path to tests is relative to the molecule.yml file location. The `additional_files_or_dirs`
-setting for verifier is ignored if the `verify` action has an argument.
+setting for the verifier is ignored if the `verify` action is provided with an argument.
 
-Multiple `side_effect` and `verify` actions can be used to a create a combination
+Multiple `side_effect` and `verify` actions can be used to create a combination
 of playbooks and tests, for example, for end-to-end playbook testing.
 
 Additional `converge` and `idempotence` actions can be used multiple times:
@@ -294,3 +294,7 @@ Molecule handles role testing by invoking configurable verifiers.
 ### Ansible
 
 ::: molecule.verifier.ansible.Ansible
+
+### Testinfra
+
+::: molecule.verifier.testinfra.Testinfra

docs/docker.md

@@ -0,0 +1,41 @@
+# Using docker containers
+
+Below you can see a scenario that is using docker containers as test hosts.
+When you run `molecule test --scenario docker` the `create`, `converge` and
+`destroy` steps will be run one after another.
+
+This example is using Ansible playbooks and it does not need any molecule
+plugins to run. You can fully control which test requirements you need to be
+installed.
+
+## Config playbook
+
+```yaml title="molecule.yml"
+{!../molecule/docker/molecule.yml!}
+```
+
+```yaml title="requirements.yml"
+{!../molecule/docker/requirements.yml!}
+```
+
+## Create playbook
+
+```yaml title="create.yml"
+{!../molecule/docker/create.yml!}
+```
+
+```yaml title="tasks/create-fail.yml"
+{!../molecule/docker/tasks/create-fail.yml!}
+```
+
+## Converge playbook
+
+```yaml title="converge.yml"
+{!../molecule/docker/converge.yml!}
+```
+
+## Destroy playbook
+
+```yaml title="destroy.yml"
+{!../molecule/docker/destroy.yml!}
+```

docs/examples.md

@@ -359,6 +359,15 @@ shared-tests
 
 Tests and playbooks can be shared across scenarios.
 
+In this example the `tests` directory lives in a shared
+location and `molecule.yml` points to the shared tests.
+
+```yaml
+verifier:
+  name: testinfra
+  directory: ../resources/tests/
+```
+
 In this second example the actions `create`,
 `destroy`, `converge` and `prepare`
 are loaded from a shared directory.

docs/faq.md

@@ -84,12 +84,10 @@ Molecule will resolve the `INSTANCE_UUID` environment variable when
 creating and looking up the instance name. You can confirm all is in
 working order by running `molecule list`.
 
-## Can I test Ansible Collections with Molecule?
+## Where can I configure my `roles-path` and `collections-paths`?
 
-This is not currently officially supported. Also, collections remain in
-"tech preview" status. However, you can take a look at [this blog
-post](https://www.jeffgeerling.com/blog/2019/how-add-integration-tests-ansible-collection-molecule)
-outlining a workable DIY solution as a stop gap for now.
+As of molecule v6, users are expected to make use of [`ansible.cfg`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html) file to
+alter them when needed.
 
 ## Does Molecule support monorepos?
 

docs/getting-started.md

@@ -44,7 +44,8 @@ INSTALL.rst  molecule.yml  converge.yml  verify.yml
 - `verify.yml` is the Ansible file used for testing as Ansible is the
   default [verifier](configuration.md#verifier). This allows you to
   write specific tests against the state of the container after your
-  role has finished executing.
+  role has finished executing. Other verifier tools are available
+  Note that [testinfra](https://testinfra.readthedocs.io/en/latest/) was the default verifier prior to molecule version 3.
 
 !!! note
 

docs/next.md

@@ -7,20 +7,21 @@ reduce the amount of magic and just rely on ansible core features.
 # Implemented changes
 
 - `roles-path` and `collections-paths` are no longer configurable for
-  dependencies. Users are expected to make use of `ansible.cfg` file to
+  dependencies. Users are expected to make use of [`ansible.cfg`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html) file to
   alter them when needed.
-- testinfra verifier driver was removed but current users should be able to
-  keep calling their testinfra tests by using `command` or `shell` ansible
-  modules from within `verify.yml` playbook.
+
+- `molecule init` command is now only available to create a scenario
+  using `molecule init scenario`.
+  Users will no longer be able to create a role.
+  Instead, users can make use of [`ansible-galaxy`](https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html#) to [create a role](https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html#creating-roles-for-galaxy).
 
 # Planned changes
 
-- Removal of provisioning drivers support and documenting, with examples, how to easily migrate to a self-provisioning approach.
 - Refactoring how dependencies are installed
 - Bringing ephemeral directory under scenario folder instead of the current
   inconvenient location under `~/.cache/molecule/...`
-- Addition of a minimal `ansible.cfg` file under scenario folder that can
-  be used to tell ansible from where to load testing content. This is to replace
+- Addition of a minimal `ansible.cfg` file under the scenario folder that can
+  be used to tell Ansible from where to load testing content. This is to replace
   current Molecule magic around roles, collections and library paths and
-  test inventory location. Once done you will be able to run molecule playbooks with ansible directly without
+  test inventory location. Once done you will be able to run molecule playbooks with Ansible directly without
   having to define these folders.

mkdocs.yml

@@ -61,6 +61,7 @@ nav:
       - configuration.md
       - ci.md
   - Examples:
+      - docker.md
       - podman.md
   - examples.md
   - faq.md

molecule/docker/converge.yml

@@ -0,0 +1,29 @@
+- name: Fail if molecule group is missing
+  hosts: localhost
+  tasks:
+    - name: Print some info
+      ansible.builtin.debug:
+        msg: "{{ groups }}"
+
+    - name: Assert group existence
+      ansible.builtin.assert:
+        that: "'molecule' in groups"
+        fail_msg: |
+          molecule group was not found inside inventory groups: {{ groups }}
+
+- name: Converge
+  hosts: molecule
+  # We disable gather facts because it would fail due to our container not
+  # having python installed. This will not prevent use from running 'raw'
+  # commands. Most molecule users are expected to use containers that already
+  # have python installed in order to avoid notable delays installing it.
+  gather_facts: false
+  tasks:
+    - name: Check uname
+      ansible.builtin.raw: uname -a
+      register: result
+      changed_when: false
+
+    - name: Print some info
+      ansible.builtin.assert:
+        that: result.stdout | regex_search("^Linux")

molecule/docker/create.yml

@@ -0,0 +1,79 @@
+- name: Create
+  hosts: localhost
+  gather_facts: false
+  vars:
+    molecule_inventory:
+      all:
+        hosts: {}
+        molecule: {}
+  tasks:
+    - name: Create a container
+      community.docker.docker_container:
+        name: "{{ item.name }}"
+        image: "{{ item.image }}"
+        state: started
+        command: sleep 1d
+        log_driver: json-file
+      register: result
+      loop: "{{ molecule_yml.platforms }}"
+
+    - name: Print some info
+      ansible.builtin.debug:
+        msg: "{{ result.results }}"
+
+    - name: Fail if container is not running
+      when: >
+        item.container.State.ExitCode != 0 or
+        not item.container.State.Running
+      ansible.builtin.include_tasks:
+        file: tasks/create-fail.yml
+      loop: "{{ result.results }}"
+      loop_control:
+        label: "{{ item.container.Name }}"
+
+    - name: Add container to molecule_inventory
+      vars:
+        inventory_partial_yaml: |
+          all:
+            children:
+              molecule:
+                hosts:
+                  "{{ item.name }}":
+                    ansible_connection: community.docker.docker
+      ansible.builtin.set_fact:
+        molecule_inventory: >
+          {{ molecule_inventory | combine(inventory_partial_yaml | from_yaml) }}
+      loop: "{{ molecule_yml.platforms }}"
+      loop_control:
+        label: "{{ item.name }}"
+
+    - name: Dump molecule_inventory
+      ansible.builtin.copy:
+        content: |
+          {{ molecule_inventory | to_yaml }}
+        dest: "{{ molecule_ephemeral_directory }}/inventory/molecule_inventory.yml"
+        mode: 0600
+
+    - name: Force inventory refresh
+      ansible.builtin.meta: refresh_inventory
+
+    - name: Fail if molecule group is missing
+      ansible.builtin.assert:
+        that: "'molecule' in groups"
+        fail_msg: |
+          molecule group was not found inside inventory groups: {{ groups }}
+      run_once: true # noqa: run-once[task]
+
+# we want to avoid errors like "Failed to create temporary directory"
+- name: Validate that inventory was refreshed
+  hosts: molecule
+  gather_facts: false
+  tasks:
+    - name: Check uname
+      ansible.builtin.raw: uname -a
+      register: result
+      changed_when: false
+
+    - name: Display uname info
+      ansible.builtin.debug:
+        msg: "{{ result.stdout }}"

molecule/docker/destroy.yml

@@ -0,0 +1,19 @@
+- name: Destroy molecule containers
+  hosts: molecule
+  gather_facts: false
+  tasks:
+    - name: Stop and remove container
+      delegate_to: localhost
+      community.docker.docker_container:
+        name: "{{ inventory_hostname }}"
+        state: absent
+        auto_remove: true
+
+- name: Remove dynamic molecule inventory
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Remove dynamic inventory file
+      ansible.builtin.file:
+        path: "{{ molecule_ephemeral_directory }}/inventory/molecule_inventory.yml"
+        state: absent

molecule/docker/molecule.yml

@@ -0,0 +1,7 @@
+dependency:
+  name: galaxy
+  options:
+    requirements-file: requirements.yml
+platforms:
+  - name: molecule-ubuntu
+    image: ubuntu:18.04

molecule/docker/requirements.yml

@@ -0,0 +1,2 @@
+collections:
+  - community.docker