Add example of using docker collection using default driver

.github/workflows/tox.yml

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

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!}
+```

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

molecule/docker/tasks/create-fail.yml

@@ -0,0 +1,13 @@
+- name: Retrieve container log
+  ansible.builtin.command:
+    cmd: >-
+      {% raw %}
+      docker logs
+      {% endraw %}
+      {{ item.stdout_lines[0] }}
+  changed_when: false
+  register: logfile_cmd
+
+- name: Display container log
+  ansible.builtin.fail:
+    msg: "{{ logfile_cmd.stderr }}"

src/molecule/test/b_functional/test_command.py

@@ -343,3 +343,12 @@ def test_podman() -> None:
         ).returncode
         == 0
     )
+
+
+def test_docker() -> None:
+    assert (
+        run_command(
+            ["molecule", "test", "--scenario-name", "docker"],
+        ).returncode
+        == 0
+    )