molecule

Initialize new role with Molecule

$ molecule init role [role_name]

$ molecule init scenario

$ molecule test

$ molecule create

$ molecule converge

$ molecule verify

$ molecule login

$ molecule destroy

molecule command [--scenario-name name] [--driver-name driver] [options]

Molecule is a testing framework for Ansible roles. It creates test instances, runs playbooks against them, verifies results, and cleans up - enabling test-driven infrastructure development.
A scenario defines how to test a role: which driver creates instances, which playbooks run, and which verifier checks results. Default scenarios use Docker but Podman, Vagrant, and cloud providers are supported.
The test sequence runs: lint, cleanup, destroy, dependency, syntax, create, prepare, converge, idempotence, verify, cleanup, destroy. Individual stages can run separately during development.
Verification typically uses Ansible's assert module or Testinfra for Python-based tests. Tests check that the role achieved the desired state: files exist, services run, configurations are correct.
Idempotence testing runs the playbook twice, failing if changes occur on the second run. This ensures roles are properly idempotent.
CI integration works with GitHub Actions, GitLab CI, and other platforms. The test command returns appropriate exit codes for automation.

init role NAME

Create new Ansible role with Molecule.

Add scenario to existing role.

Run full test sequence.

Create instances.

Run playbook.

Run verification tests.

Destroy instances.

Login to instance shell.

List instances and status.

Run linters.

Run cleanup playbook.

Target scenario.

Driver: docker, podman, delegated, vagrant.

Run against all scenarios.

Run scenarios in parallel.

When to destroy: always, never, passing.

Docker/Podman required for containerized testing. Some roles need privileged containers. Windows testing is limited. Large test matrices can be slow. Cloud drivers incur costs. Systemd in containers needs special setup.

Molecule was created by Cisco engineers and released around 2015 to improve Ansible role testing. Red Hat later adopted the project. It replaced ad-hoc testing approaches with a structured framework, becoming the de facto standard for Ansible role testing.

ansible(1), ansible-lint(1), testinfra(1), docker(1)