Molecule is an Ansible testing framework designed for developing and testing Ansible collections, playbooks, and roles. It provides support for testing with multiple instances, operating systems, distributions, virtualization providers, test frameworks, and testing scenarios. Molecule encourages an approach that results in consistently developed Ansible content that is well-written, easily understood, and maintained. The current version is 26.4.0, and releases generally align with Ansible development, with major versions introducing significant changes.
pip install moleculeVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates the standard command-line workflow for Molecule, creating a minimal Ansible role, initializing a default Molecule scenario with a Docker driver, and running the full test lifecycle. It includes a basic 'verify.yml' example for illustration. The primary interaction with Molecule is via its command-line interface, even when invoked from Python.
Ensure `ansible-core` is installed, and install specific driver plugins (e.g., `pip install 'molecule[docker]'` or `pip install molecule-docker`) if using them. Review release notes for specific driver changes.
Use `ansible-galaxy role init` first to create the role structure, then navigate into the role and use `molecule init scenario` to add Molecule testing. Adapt `molecule.yml` to the 'delegated' driver paradigm if not using explicit driver plugins. Existing `molecule.yml` files for other drivers may need updates or replacement with corresponding driver plugins.
Ensure Ansible tasks are idempotent. Use Ansible's `changed_when: false` or `check_mode: true` where appropriate, or tag tasks with `molecule-idempotence-notest` to skip them during the idempotence check if they are intentionally not idempotent for testing purposes.
Use a linter (like `yamllint` and `ansible-lint`) regularly as part of your Molecule workflow (`molecule lint`). Configure your editor to use spaces for indentation and highlight YAML syntax issues.
Always verify that the chosen driver is installed and running correctly. Check the `molecule --debug` output for more verbose information on how Molecule interacts with external commands. Use `molecule create`, `molecule converge`, `molecule verify`, `molecule login` individually for debugging specific stages. Always ensure Ansible and driver dependencies are correctly installed, preferably in a Python virtual environment.