Testing Ansible Code with Molecule

2. Test in the project structure

Any playbook, role, or collection can include a molecule/ directory with test scenarios. The molecule/ directory can also live outside the project, but it is recommended to keep it next to the tested component.

This repository contains Molecule test scenarios for playbooks, roles, and collections. Playbooks and roles are tested by Molecule scenarios stored at the playbook level, while the collection’s tests are embedded in the roles directory.

To get started quickly, you can scaffold a new scenario automatically using molecule init with a scenario and test name. If you omit the name, Molecule will create a default scenario:

molecule init

This generates the following default structure:

molecule/
  default/
    create.yml
    destroy.yml
    molecule.yml
    converge.yml
    verify.yml

The most critical file is molecule.yml, which defines the test scenario (driver, platforms, provisioner, etc.). Your actual verifications, i.e., assertions, are written in verify.yml; this file is the real center of the test. The target system is configured by the converge.yml file. Note that for playbook tests, this file may be omitted, having the playbook call encoded directly in the Molecule definition.

Note

The default scenario included in this repository is only to suppress errors and keep the execution logs clean during your learning path. It is not intended for regular testing and should be used only as a helper. In real tests, you will use the default scenario to better handle container life-cycle.

As mentioned before, for a regular test, the molecule.yml file may be used to carry all necessary elements including the converge stage to handle a call to a standalone playbook. Verify is critical and must be written as it’s the actual test assert code in verify.yml. A minimal example might look like this:

molecule/
  test1/
    molecule.yml
    verify.yml