Ansible Pilot

Ansible Role and Collection Testing With Molecule

Elevating Ansible Development through Systematic Testing and Iterative Refinement in Molecule Scenarios

December 3, 2023
Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons


Molecule, the testing framework for Ansible roles and playbooks, introduces powerful functionality through its concept of scenarios. Think of a scenario as a test suite for roles or playbooks within an Ansible collection. This article delves into Molecule scenarios, their layout, and how to harness their capabilities for efficient testing and development.

Ansible Collection

Adding Molecule to your Ansible collection is a straightforward process that enhances your development and testing workflow. Start by creating a new directory within your collection named “extensions.” Navigate to this newly created directory using the command line and then initialize a new default Molecule scenario with the following:

cd <path to your collection>/extensions/
molecule init scenario

This step sets the foundation for incorporating Molecule into your collection, allowing you to seamlessly integrate testing and development practices. The newly created scenario within the “extensions” directory becomes a pivotal component in orchestrating Molecule’s testing lifecycle for your Ansible roles and playbooks.

Understanding the Scenario Layout

The scenario layout is crucial for organizing Molecule’s testing components. Within the molecule/default folder, several key files play distinct roles:

Inspecting the molecule.yml Configuration

The molecule.yml file is pivotal for configuring Molecule. It’s a YAML file with keys representing high-level components:

  1. Dependency Manager: Molecule defaults to using the Galaxy development guide to resolve role dependencies.
  2. Platforms Definitions: Specifies instances to create, their names, and group assignments. Useful for testing roles against multiple distributions.
  3. Provisioner: Molecule’s Ansible provisioner manages instance lifecycles based on this configuration.
  4. Scenario Definition: Controls the sequence order of scenarios.
  5. Verifier Framework: Defaults to using Ansible, providing a way to write state-checking tests on the target instance.

Running a Full Test Sequence

Molecule offers commands for manually managing instance, scenario, development, and testing tools. Alternatively, automate these tasks within a scenario sequence using molecule test. The full lifecycle sequence includes dependency resolution, cleanup, instance creation, preparation, convergence, idempotence, side effect, verification, and final cleanup.

Usage: molecule [OPTIONS] COMMAND [ARGS]...

  Molecule aids in the development and testing of Ansible roles.

  To enable autocomplete for a supported shell execute command below after replacing
  SHELL with either bash, zsh, or fish:

      eval "$(_MOLECULE_COMPLETE=SHELL_source molecule)"

  --debug / --no-debug    Enable or disable debug mode. Default is disabled.
  -v, --verbose           Increase Ansible verbosity level. Default is 0.
  -c, --base-config TEXT  Path to a base config (can be specified multiple times). If
                          provided, Molecule will first load and deep merge the
                          configurations in the specified order, and deep merge each
                          scenario's molecule.yml on top. By default Molecule is
                          looking for '.config/molecule/config.yml' in current VCS
                          repository and if not found it will look in user home.
  -e, --env-file TEXT     The file to read variables from when rendering molecule.yml.
  --help                  Show this message and exit.

  check        Use the provisioner to perform a Dry-Run (destroy, dependency,...
  cleanup      Use the provisioner to cleanup any changes made to external systems...
  converge     Use the provisioner to configure instances (dependency, create,...
  create       Use the provisioner to start the instances.
  dependency   Manage the role's dependencies.
  destroy      Use the provisioner to destroy the instances.
  drivers      List drivers.
  idempotence  Use the provisioner to configure the instances and parse the output...
  init         Initialize a new scenario.
  list         List status of instances.
  login        Log in to one instance.
  matrix       List matrix of steps used to test instances.
  prepare      Use the provisioner to prepare the instances into a particular...
  reset        Reset molecule temporary folders.
  side-effect  Use the provisioner to perform side-effects to the instances.
  syntax       Use the provisioner to syntax check the role.
  test         Test (dependency, cleanup, destroy, syntax, create, prepare,...
  verify       Run automated tests against instances.

Testing the Collection Role

The converge.yml file, created during initialization, is a playbook to run your role from start to finish. Modify as needed, but it’s an excellent starting point for Molecule novices. Create an isolated test environment and utilize it for live development with molecule converge. This command stops after the converge action, enabling iterative testing while making changes to your collection or the converge play.

As an example, consider testing the role with the following code in converge.yml:

- name: Include a role from a collection
  hosts: localhost
  gather_facts: false
    - name: Testing role
        tasks_from: main.yml

Run molecule converge to execute the steps in the default scenario while maintaining the infrastructure for ongoing development and testing. This iterative process ensures a robust and reliable Ansible automation workflow.

The Best Resources For Ansible


Video Course

Printed Book



In conclusion, Molecule scenarios provide an indispensable framework for testing and developing Ansible roles and playbooks within collections. By understanding the scenario layout and leveraging key files like create.yml, destroy.yml, and molecule.yml, developers gain a systematic approach to testing their automation workflows. The flexibility offered by scenarios allows for sequential execution of multiple tests, enhancing the overall reliability of Ansible content collections.

The molecule.yml configuration file acts as the orchestrator, defining dependencies, platforms, provisioners, scenarios, and verifiers. This comprehensive configuration empowers developers to tailor testing environments to their specific needs, including testing against multiple distributions and defining state-checking tests.

Automating the full test sequence with molecule test streamlines the testing lifecycle, encompassing dependency resolution, instance management, convergence, idempotence, and verification. This automation ensures consistent and repeatable testing, fostering a robust development process.

The live development capabilities offered by Molecule, exemplified by the molecule converge command, allow developers to iterate on their roles efficiently. This iterative process, coupled with the ability to make changes and rerun tests seamlessly, enhances the agility and responsiveness of Ansible content collection development.

As Ansible continues to evolve, Molecule remains a critical tool in the toolkit of automation developers. Its scenarios provide a structured and efficient way to validate and refine roles and playbooks, contributing to the creation of reliable and resilient automation solutions. Embrace Molecule scenarios, and unlock the full potential of testing and developing Ansible content collections with confidence.

Subscribe to the YouTube channel, Medium, and Website, X (formerly Twitter) to not miss the next episode of the Ansible Pilot.


Learn the Ansible automation technology with some real-life examples in my

My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps

BUY the Complete PDF BOOK to easily Copy and Paste the 250+ Ansible code

Want to keep this project going? Please donate

Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons
Follow me

Subscribe not to miss any new releases