molecule

Create a new Ansible role

$ molecule init role --role-name [role_name]

$ molecule test

$ molecule create

$ molecule converge

$ molecule matrix converge

$ molecule login

molecule command [options]

init []
    Initializes a new Ansible role skeleton or a new scenario within an existing role, complete with default Molecule configuration files.

test [-s ]
    Executes the full test sequence for a role or specific scenario. This typically includes linting, creating instances, converging the role, checking idempotence, verifying the outcome, and destroying the instances.

converge [-s ]
    Runs the Ansible playbook specified in the scenario's converge.yml, applying the role to the test instance(s). This is a core step for applying the role's changes.

verify [-s ]
    Executes the verification tests (e.g., Python Pytest scripts) defined in the scenario's verify.yml. This checks if the role achieved the expected state after convergence.

destroy [-s ]
    Tears down and removes the test instance(s) provisioned for a given scenario, cleaning up the environment.

create [-s ]
    Provisions and starts the test instance(s) according to the scenario's configuration. This is often an implicit first step for converge or test.

lint [-s ]
    Performs static analysis (linting) on the Ansible content and Molecule configuration files to identify potential issues and enforce coding standards.

login [] [-s ]
    Establishes an SSH connection to a specific test instance, allowing for interactive debugging and inspection.

list [-s ]
    Displays a list of available scenarios, instances, or other relevant information within the current role directory.

-s | --scenario
    A global option to specify which particular scenario to operate on. If omitted, Molecule typically defaults to the default scenario.

The molecule command is a powerful command-line utility designed to help test Ansible roles effectively and reproducibly. It ensures that roles are idempotent, function across various platforms, and behave as expected before deployment. Molecule achieves this by providing a structured approach to defining test scenarios, provisioning temporary test environments (using 'drivers' like Docker, Vagrant, or cloud providers), and orchestrating a sequence of testing steps.

These steps typically include linting Ansible content, creating virtual instances, converging the Ansible role on these instances, verifying the desired state (often using a Python-based test framework like Pytest), and finally destroying the test environment. By automating the entire testing lifecycle, Molecule significantly improves the quality and reliability of Ansible roles, accelerates development cycles, and provides developers with high confidence in their automation code.

molecule is not a standard Linux command bundled with most distributions. It requires Python and pip for installation. Its effective use also necessitates an understanding of Ansible, YAML, and typically a virtualization or containerization solution like Docker or Vagrant. Initial setup and configuration can have a learning curve.

Molecule uses 'drivers' to provision and manage the test environments. Common drivers include docker (for container-based testing), vagrant (for VM-based testing), podman, and various cloud drivers (e.g., azure, ec2, openstack) for testing roles in specific cloud environments. The chosen driver dictates how test instances are created and managed.

A 'scenario' in Molecule defines a specific testing configuration for an Ansible role. A role can have multiple scenarios (e.g., 'default', 'centos7', 'ubuntu20-docker', 'cloud-test'). Each scenario has its own molecule.yml configuration file and associated playbooks/tests, allowing comprehensive testing across different operating systems, Python versions, or specific use cases without modifying the role itself.

Initially developed as a community project to address the growing need for robust testing of Ansible roles, molecule gained significant traction due to its comprehensive approach to role verification. It was later adopted and further developed by Red Hat, becoming an official component of the Ansible ecosystem. Its evolution, particularly through versions 3 and 4, introduced greater flexibility in driver support (e.g., Docker, Podman, cloud providers) and a more modular scenario-based testing workflow, solidifying its position as the de facto standard for Ansible role testing.

ansible(1), ansible-lint(1), pytest(1), docker(1), vagrant(1)