Skip to content

Ansible Molecule Testing

Ansible Molecule Testing#

Molecule aids in the development and testing of Ansible roles.

Red Hat took over development of Molecule in September 2018d


See the ansible molecule installation notes

pip install --user molecule

Getting Started#

Generate a new role

molecule init role -r my-new-role

To initialise molecule within an existing role

molecule init scenario -r my-role-name

The following folders are generated:

$ ls  defaults/  handlers/  meta/      molecule/  tasks/     vars/
  • molecule/ - contains various scenarios - test suites for created roles. You can have as many scenarios as you want and run one after the other

The scenario default contains:

$ ls
Dockerfile.j2  INSTALL.rst    molecule.yml   playbook.yml   tests/
  • Dockerfile.j2 is the jinja template file used to create a docker image to test your role against
  • INSTALL.rst install instructions on additional software or steps for molecule to interface with the driver
  • molecule.yml central configuration entry point
  • playbook.yml the playbook run against the driver
  • tests/ is the test directory as molecule uses test infra as the default verifier. Allowing you to run specific tests about the state of a container after the playbook is run.


Configures the components

  • dependency - dependency manager (ansible galaxy)
  • driver - the provider of the instance to test against (docker, azure, ec2, linode)
  • lint - enforce best practices when writing yaml
  • platforms - name (distrribution) and the group it belongs to
  • provisioner
  • scenario - control scenario sequence order
  • verifier - package that is doing the state tests (TestInfra)

Running a test sequence#

Using a virtual env in benefitial

Ensure you have everything you need installed in:


Check docker is running with a sanity check:

docker run hello-world

Tell molecule to create the instance

molecule create

Verify that the instance has been created with

molecule list

Add a task to test-role/tasks/main.yml:

- name: Molecule Hello World!
    msg: Hello, World!

Tell molecule to test the role against the instance:

molecule converge

To manually inspect the instance afterwards:

molecule login

Destroy the instance with:

molecule destroy

The --debug option can be used to get more verbose output

Full Test Suite#

To run the full sequence of tests:

molecule test

Tell molecule not to destroy if the test fails: --destroy=never