Registry / testing / molecule

molecule

JSON →
library26.8.0pypypi✓ verified 23d ago

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 molecule
INSTALL
IMPORT
SIG · MOLECULE
M
molecule
testingpythonv26.8.0
Install
8.8s avg
Import
5ms
Disk
78MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v26.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
2/3 runs
✓ 9.6s
py 3.11
2/3 runs
✓ 8.8s
py 3.12
2/3 runs
✓ 8.45s
py 3.13
2/3 runs
✓ 8.3s
py 3.9
2/3 runs
2/3 runs
78MB installed
● package 78MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

molecule
import molecule
import subprocess

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.

import os import subprocess # Create a dummy Ansible role directory role_name = "my_test_role" if not os.path.exists(role_name): os.makedirs(os.path.join(role_name, "tasks")) with open(os.path.join(role_name, "tasks", "main.yml"), "w") as f: f.write("---\n- name: Example task\n ansible.builtin.debug:\n msg: 'Hello from Molecule!'") # Change into the role directory os.chdir(role_name) # Initialize a Molecule scenario (using the default Docker driver) # This will create the molecule/default directory and its files print("Initializing Molecule scenario...") subprocess.run(["molecule", "init", "scenario", "--driver-name", "docker", "--scenario-name", "default"], check=True) # Define a simple verify.yml (optional, but good practice) verify_yml_content = '''--- - name: Verify role execution hosts: all gather_facts: false tasks: - name: Check if message was in logs (example) ansible.builtin.command: cat /var/log/ansible_messages.log # Replace with actual verification changed_when: false failed_when: false register: log_output - name: Assert message content ansible.builtin.assert: that: - "'Hello from Molecule!' in log_output.stdout" fail_msg: "Expected message not found in logs." ''' with open(os.path.join("molecule", "default", "verify.yml"), "w") as f: f.write(verify_yml_content) # Run the full Molecule test sequence print("Running full Molecule test sequence...") try: subprocess.run(["molecule", "test"], check=True) print("Molecule test completed successfully.") except subprocess.CalledProcessError as e: print(f"Molecule test failed: {e}") finally: # Clean up (optional, but good for quickstart) print("Cleaning up Molecule resources...") subprocess.run(["molecule", "destroy"], check=False) # destroy if it failed earlier os.chdir("..") # Optionally remove the role directory: shutil.rmtree(role_name)
molecule --version
Debug
Known issues
breakingMolecule v3.1 decoupled its binary dependency on Ansible itself. Docker and Podman drivers became standalone projects, requiring explicit installation (e.g., `pip install molecule-docker`). Users upgrading from pre-3.1 might encounter errors about missing Ansible or drivers if not explicitly installed.
fix
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.
affects: >=3.1.0
breakingMolecule v6.0.0 (Ansible Automation Platform preview) refocused the project to primarily use Ansible itself as the provisioner (delegated driver). It removed the `molecule role init` command in favor of `ansible-galaxy role init` followed by `molecule init scenario`. Support for multiple built-in drivers like Docker/Podman was streamlined, with the delegated driver becoming the default and often the only one present in certain distributions.
fix
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.
affects: >=6.0.0
gotchaMolecule's idempotence checks (`molecule idempotence` or during `molecule test`) rely on Ansible's standard output. If Ansible reports 'changed' tasks, Molecule will report an idempotence failure. This is often due to the underlying Ansible tasks not being truly idempotent, not a Molecule issue directly.
fix
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.
affects: All versions
gotchaYAML syntax errors (e.g., incorrect indentation, mixing tabs and spaces, missing quotes for special characters) are a frequent cause of Molecule failures, as its configuration and playbooks are YAML-based. These can result in cryptic error messages from Ansible or Molecule's parsers.
fix
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.
affects: All versions
gotchaMolecule relies on external tools (e.g., Docker, Podman, Vagrant, Ansible). Issues with these underlying tools (e.g., Docker daemon not running, incorrect Ansible version, missing Python dependencies for drivers) can manifest as Molecule failures, sometimes with vague error messages.
fix
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.
affects: All versions
Upgrade
Version history
26.8.0latest on PyPI · released Aug 12, 2026
Audit
Dependencies
ansible-corerequiredMolecule is an Ansible testing framework and relies on Ansible for provisioning and execution. It supports only the latest two major versions of Ansible (N/N-1).
molecule-pluginsoptionalContains various drivers (e.g., Docker, Podman, Vagrant) for creating test instances.
ansible-lintoptionalUsed by the 'lint' stage for checking Ansible-specific best practices and syntax.
yamllintoptionalUsed by the 'lint' stage for checking YAML formatting and syntax.
testinfraoptionalA common Python testing framework used for writing verification tests in Molecule scenarios.
Agent activity
10 hits · last 30 days
node
6
Amazon
1
Resources
molecule — pip install molecule · libregistry