# Molecule — Testing Framework for Ansible Roles and Collections

> Test Ansible roles and collections against real instances using Docker, Podman, or cloud providers with automated create, converge, verify, and destroy workflows.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Molecule — Testing Framework for Ansible Roles and Collections

## Quick Use
```bash
pip install molecule molecule-plugins[docker]
# initialize a new role with Molecule scaffolding
molecule init role my_role
cd my_role
# run the full test sequence
molecule test
```

## Introduction
Molecule is the official testing framework for Ansible roles and collections. It automates the process of spinning up test instances, applying your Ansible code, running verification tests, and tearing down the infrastructure, giving confidence that roles work correctly before deploying to production.

## What Molecule Does
- Creates ephemeral test instances using Docker, Podman, Vagrant, or cloud providers
- Applies Ansible roles to test instances with full playbook convergence
- Runs verification steps using Ansible itself or Testinfra for assertion-based checks
- Supports multiple test scenarios per role for different OS families or configurations
- Executes a complete lifecycle: dependency, create, converge, idempotence, verify, destroy

## Architecture Overview
Molecule uses a scenario-based design where each scenario defines a driver (how instances are created), a provisioner (Ansible), platforms (target OS images), and a verifier (how to validate results). The driver plugins handle instance lifecycle through Docker, Podman, delegated SSH, or cloud APIs. Molecule orchestrates the sequence of actions and reports results. Configuration lives in `molecule/default/molecule.yml` within the role directory.

## Self-Hosting & Configuration
- Install via pip alongside driver plugins like `molecule-plugins[docker]` or `molecule-plugins[podman]`
- Scaffold test scenarios with `molecule init scenario` inside an existing role
- Define target platforms in `molecule.yml` specifying container images or VM configurations
- Write verification tests in `molecule/default/verify.yml` using standard Ansible tasks
- Run individual lifecycle phases with `molecule converge`, `molecule verify`, or `molecule destroy`

## Key Features
- Idempotence testing that runs the playbook twice and fails on unexpected changes
- Multi-platform testing across Ubuntu, CentOS, Debian, and other OS families simultaneously
- Testinfra integration for Python-based infrastructure assertions
- Parallel execution of multiple scenarios to reduce test suite runtime
- CI-friendly with structured output and non-zero exit codes on failure

## Comparison with Similar Tools
- **Ansible-lint** — checks playbook style and best practices; Molecule tests actual execution against real instances
- **Terratest** — Go-based infrastructure testing; Molecule is Ansible-native with built-in role lifecycle management
- **Kitchen-Ansible** — Test Kitchen driver for Ansible; Molecule is the official Ansible testing tool with tighter integration
- **Vagrant** — VM provisioning tool; Molecule uses Vagrant as one of many possible drivers while adding test orchestration
- **Testinfra** — Python assertion library for infrastructure; Molecule can use Testinfra as its verifier component

## FAQ
**Q: Can I test Ansible collections with Molecule?**
A: Yes. Molecule supports testing both standalone roles and roles within collections.

**Q: Do I need Docker to use Molecule?**
A: No. Molecule supports multiple drivers including Podman, Vagrant, and delegated SSH for testing on existing hosts.

**Q: How do I test against multiple operating systems?**
A: Define multiple platforms in `molecule.yml` with different container images. Molecule creates and tests all of them in a single run.

**Q: Can Molecule run in CI/CD pipelines?**
A: Yes. Molecule is commonly used in GitHub Actions, GitLab CI, and Jenkins. Use `molecule test` as a CI step with Docker or Podman as the driver.

## Sources
- https://github.com/ansible/molecule
- https://ansible.readthedocs.io/projects/molecule/

---
Source: https://tokrepo.com/en/workflows/molecule-testing-framework-ansible-roles-collections-4b3bf896
Author: AI Open Source