Molecule, conceptually

Lesson 22 ended with an instruction: run your playbook twice, and demand the second run comes back all ok, changed=0. You did that by hand. Molecule does it for you — plus everything around it. It is the standard test harness for roles. If your new team maintains shared roles, every PR against one likely triggers a molecule run in CI.

You don’t need to author molecule tests. You need to recognise what the tool does, so a red build tells you something. One command — molecule test — drives a full cycle against a disposable target:

create       boot a fresh container or VM
converge     run the role against it
idempotence  run the role AGAIN — must report changed=0
verify       assert the resulting state (testinfra or asserts)
destroy      tear it all down

Walk it once. Create boots a clean instance — usually a container, so every test starts from a blank slate. Converge means “apply the role to it”. When someone says “converge passed but verify didn’t”, this is the phase they mean. Idempotence is the star. Molecule runs the role a second time and fails the build if anything still reports changed. That is lesson 22’s run-twice test, automated and enforced on every PR. Verify checks the actual end state with real assertions (is the package installed, is the service listening), because a role can be idempotent and still wrong. Destroy deletes the instance, so nothing leaks into the next run.

Two current-state facts for the job. First, in current Molecule, linting is a separate step — not part of the default molecule test sequence. That is why a role’s pipeline shows ansible-lint (lesson 37) and molecule as distinct jobs: not redundancy, just the modern split. Second, Molecule supports only the latest two Ansible major versions. A team pinned to an old ansible-core can find its test harness has moved on without it — one more argument for staying current.

A molecule-tested role carries a molecule/ directory alongside tasks/ and defaults/. Spot it and you know the role has a harness and CI will exercise it. You already have the tool: pip install ansible-dev-tools from lesson 37 bundled molecule with the linters and navigator.

So when standup brings “molecule is red on your PR”, your move is mechanical: open the CI log and find which phase failed. Converge failure: the role errored — debug it like any playbook. Idempotence failure: the run-twice test — hunt the task still reporting changed. Verify failure: the role ran clean but built the wrong state. Next stop: AWX and AAP, the names your colleagues drop when playbooks stop being run from laptops.