Molecule

Molecule is the standard harness for testing a role against a real, disposable target. From one command it spins up a fresh container or cloud instance, applies the role to it, verifies the result, proves idempotency, and tears the target down. It is a community project, not part of ansible-core, installed separately with pip install molecule molecule-plugins — and it is how you test the larkspur_web role against a clean Ubuntu 22.04 box instead of against your already-configured laptop.

The whole point is a throwaway target you did not set up. A green Molecule run proves the role builds the end state from nothing, because the box started with nothing — no residue from a previous run, no package the warm dev machine happened to already have. That is a stronger claim than "it ran clean here," and the rest of this topic is how Molecule makes it.

The Throwaway Target

Per run, Molecule creates an ephemeral host — a geerlingguy/docker-ubuntu2204-ansible container, a Podman container, or an EC2 instance — applies the role, and then destroys it. Because the target starts clean every time, "it works" means the role itself produces the state, not some leftover from a run you have forgotten. The disposability is the feature: a target you cannot accidentally pre-warm is a target whose result you can trust.

This is the precise gap that a green run on your laptop cannot close. Your laptop already has the package installed, the user created, the directory present — so a role that silently depends on that residue passes for you and fails on the first fresh node. Molecule removes the residue by removing the host, every single run.

The Scenario Layout

A role under Molecule gets a molecule/ directory holding one or more scenarios. The default scenario, molecule/default/, contains three files: molecule.yml (the driver, the platforms, and provisioner config), converge.yml (the playbook that applies the role under test), and verify.yml (the assertions that decide whether the converged target is right). Extra scenarios — molecule/podman/, molecule/rhel/ — test other targets or other settings alongside the default.

driver:
  name: docker
platforms:
  - name: larkspur-web-instance
    image: geerlingguy/docker-ubuntu2204-ansible:latest
    command: /lib/systemd/systemd   # systemd-capable image so the service task is honest
    cgroupns_mode: host
    privileged: true
provisioner:
  name: ansible
verifier:
  name: ansible           # run verify.yml; testinfra is the other choice (topic 72)

The converge.yml below is the playbook Molecule applies to that target — it simply includes the role under test, exactly as a real playbook would. Keeping it minimal matters: the converge play exercises the role, nothing more, so a failure points at the role and not at scenario glue.

- name: Converge
  hosts: all
  become: true
  tasks:
    - name: Apply the larkspur_web role
      ansible.builtin.include_role:
        name: larkspur_web

The Sequence: converge / idempotence / verify / destroy

Molecule exposes the lifecycle as discrete subcommands. molecule converge applies the role to the live target. molecule idempotence runs converge a second time and fails on any changed. molecule verify runs the checks in verify.yml. molecule destroy tears the target down. Each one does exactly one thing, which is what lets you call them individually while iterating.

The combined command molecule test runs the full sequence as one gated pipeline: create, then converge, then idempotence, then verify, then destroy. Any step failing fails the whole run, and the target is destroyed at the end regardless — so molecule test is the honest gate, because it forces a clean create and a real teardown around the converge and the checks.

# inner loop: apply once, iterate without recreating the target
molecule converge

# the second-run gate: re-converge and fail on any changed
molecule idempotence

# run the assertions in verify.yml against the converged host
molecule verify

# the full honest gate: create -> converge -> idempotence -> verify -> destroy
molecule test

Drivers

The driver decides what the target actually is. docker and podman give you fast, cheap, OS-pinned containers — the default for role unit tests, and enough to exercise the larkspur_web role's package, template, and config logic. A cloud or delegated driver stands up a real VM or instance, which you need when the role touches kernel modules, drives systemd in ways a container fakes badly, or calls real cloud APIs.

The split is honest about what each can prove. A container covers the parts of larkspur_web that are filesystem and package work; a VM covers the parts a container cannot run truthfully. A service task that is green against a container's faked init can still fail on a real host, so any role whose correctness depends on real service management wants a systemd-capable image or a VM driver, not a bare container.

Inner Loop vs Full Run

During development you run molecule converge repeatedly. It applies the role to the existing target without recreating it, so iterating on a template or a task is fast — edit, converge, look at the result, repeat, all against the same warm container. This is the inner loop, optimized for speed, and you live in it while the role is taking shape.

Before you push, you run the full molecule test, which always destroys and recreates the target. That recreation is the point: the inner loop's warm container may have accumulated state across a dozen converges, hiding a create-time bug like a missing dependency the warm box already had. The full run starts from clean and is the gate; the inner loop is for going fast, the full run for being sure.