Molecule — Testing Framework for Ansible Roles and Collections

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/