Ansible Molecule: testing roles, playbooks and collections with Ansible itself

What Molecule actually tests, and who writes the scenarios

Ansible content is hard to verify because a role only proves itself when it runs against a real host. Molecule exists to close that gap. The README describes it as an Ansible testing framework designed for developing and testing Ansible collections, playbooks, and roles. The unit of work is a scenario: a directory of configuration plus the Ansible playbooks that create a target, converge it, and check the result. Scenarios can target anything Ansible can reach, and the README lists containers, virtual machines, cloud infrastructure, hyperscaler services, APIs, databases and network devices. It also states that Molecule can validate inventory configurations and dynamic inventory sources, which is a less obvious use: you can test that an inventory plugin resolves hosts correctly without touching the workload.

The audience is narrow on purpose. This is for people who already write roles or collections and want a repeatable local and CI loop. If your configuration management is not Ansible, Molecule has nothing to offer, because its scenarios are Ansible playbooks rather than a bespoke test DSL. That constraint is the design: the README says Molecule leverages standard Ansible features including inventory, playbooks, and collections to provide flexible testing workflows. The tests are written in the same language as the thing under test, so anyone who can read a role can read its scenario.

How a scenario runs: drivers, the delegate driver and Ansible's own inventory

Molecule is a Python application with a plugin architecture built on pluggy, which the dependency list in pyproject.toml confirms. The entry point group is molecule.driver, and the pyproject.toml excerpt shows a default driver mapped to molecule.driver.delega, truncated in the file listing. Drivers are the part that creates and destroys the target environment. A container driver stands up a container, a VM driver stands up a VM, and the delegate driver hands the lifecycle to something else, which is how a scenario can target a cloud service or an API that Ansible manages rather than a machine Ansible connects to.

The data flow is deliberately unexotic. Molecule reads scenario configuration, then invokes Ansible with generated inventory and playbooks. Because inventory is standard Ansible inventory, the same group and host variable rules apply, and the same connection plugins apply. The practical consequence is that a scenario is debuggable with the tools you already have: if a converge step fails, you are looking at an Ansible task failure, not a framework-specific error format.

The trade-off is coupling. Molecule's own version support tracks Ansible: the README states plainly that Molecule supports only the latest two major versions of Ansible (N/N-1). If you pin an older ansible-core for a legacy estate, you are outside the supported matrix, and the dependency line in pyproject.toml is equally explicit, requiring ansible-core>=2.15.0 with 2.17.* excluded. That exclusion is worth noting: a whole minor series is skipped rather than merely untested.

Installing Molecule and running a first scenario

Molecule is distributed on PyPI as molecule, and pyproject.toml requires Python 3.10 or newer. The README gives the command line invocation in two forms, and both are worth knowing because the module form sidesteps PATH problems in CI images.

molecule ...
python3 -m molecule ...  # python module calling method

The README does not spell out a pip install line for end users, but the package name is molecule and the console script is registered in pyproject.toml as molecule = "molecule.__main__:main". Install it into a virtual environment alongside the ansible-core version you intend to support.

python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -U setuptools pip
python3 -m pip install molecule

That last command is the one to check carefully: because the project supports only N/N-1, let pip resolve ansible-core rather than pinning a version by hand unless you know it is inside the supported window. The README's contributor path installs tox instead, which is for working on Molecule itself rather than using it.

git clone https://github.com/ansible/molecule && cd molecule
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -U setuptools pip tox

Once installed, the README's command forms are the entry point for every subsequent step. A scenario is defined by its own directory of configuration, and the driver you select determines what gets created. The README does not print a full scenario file in the documentation available, so the safest first move is to run the command line against an existing scenario in your repository and read the generated configuration, rather than hand-writing one from a guessed schema. What you should see is Ansible output: the create step bringing up the target, the converge step applying your role, and the verification steps reporting task results.

Where Molecule is the wrong tool

Molecule's supported Ansible window is the first hard boundary. N/N-1 means an estate pinned to an older major version cannot use the current release, and the pyproject.toml dependency excludes the 2.17 series outright. If your organisation standardises on an Ansible version outside that window, upgrading Molecule means upgrading Ansible, which is a much larger change than adopting a test runner.

The second boundary is the driver. Molecule itself does not create containers or virtual machines. It delegates. The pyproject.toml excerpt shows only the default driver entry point, and the README does not enumerate which platform drivers ship where. If no published molecule.driver entry point exists for your target platform, a scenario for that platform is not something you can write today. That matters most for teams whose test target is a proprietary appliance or an internal platform: you may need to write and maintain the driver yourself, and the README does not document that path in the documentation available.

The third case is scope. Molecule is not a configuration drift detector and not a compliance scanner. It creates a target, runs your content against it, and reports. If what you actually need is continuous verification of already-running production hosts, a scenario-based framework that builds its own throwaway targets is the wrong shape, and the README makes no claim to cover that.

Molecule versus Testinfra-style assertion libraries

The topics list for the repository includes testinfra, which points at the usual comparison. Testinfra is an assertion library: you write Python tests that inspect a host over a connection, and you bring your own mechanism for creating that host and for applying the configuration under test. Molecule is the other half. It owns the lifecycle, the inventory and the converge step, and its verification stage is where an assertion library plugs in.

The difference in approach shows up when a test fails. With a bare assertion library you get a Python traceback about a file mode or a package version, and you reconstruct how the host reached that state. With Molecule the failure sits inside a scenario whose create and converge steps are themselves Ansible runs, so you can re-run the converge step alone and watch the tasks that produced the state. That is a real debugging advantage, and it costs you the freedom to test hosts that Molecule did not create.

Neither is a superset. A team already running a container-based integration harness with its own fixtures gets little from adding Molecule on top, because Molecule would duplicate the lifecycle work. A team whose tests are currently a shell script that spins up a container and runs ansible-playbook gains structure, a supported driver interface, and a configuration format that other Ansible developers already recognise.

Maintenance, releases and the MIT licence

The repository is not archived, and the most recent release listed is v26.9.0, dated 2026-09-22, with v26.8.0 on 2026-08-12 and v26.6.0 on 2026-06-30 before it. The version scheme is calendar-based, and the recent cadence is roughly monthly. The last push to the default branch was on 2026-09-22, the same day as the most recent release. That is the maintenance evidence available: frequent tagged releases and a default branch that moves with them. The README notes the project was created by Retr0h and is now community-maintained as part of the Ansible by Red Hat project, so the governance sits with the wider Ansible community rather than a single author.

Upgrade cost is dominated by the Ansible version window rather than by Molecule's own API. Because only N/N-1 is supported, a Molecule upgrade can force an ansible-core upgrade, and that is where breakage usually originates: module deprecations, connection plugin changes, collection requirement shifts. The dependency floor is ansible-core>=2.15.0 with the 2.17 series excluded, so a jump across those lines deserves a read of the release notes at https://github.com/ansible/molecule/releases before it lands in CI. The changelog URL is declared in pyproject.toml under [project.urls].

Licensing is MIT for the code, as stated in the README and in the pyproject.toml license field. The logo is separate: the README says it is licensed under Creative Commons NoDerivatives 4.0, and that other uses require contacting the project. If you mirror the logo in internal documentation, that is a different permission from the code licence. This is a description of what the files say, not legal advice; check with your own counsel for anything beyond reading the terms.

Editorial conclusion

Adopt Molecule if your team already writes Ansible and wants scenario-based verification that runs through the same inventory and playbook machinery as production. Do not adopt it if you need unsupported Ansible versions, since the project supports only N/N-1, or if you expect a driver for a platform that has no published molecule.driver entry point. Before committing, run molecule --version against your pinned ansible-core, confirm a driver entry point exists for your target platform, and check that your CI image can run the container or VM backend your scenario needs.

Frequently asked questions

Official sources

1. ansible/molecule on GitHub
2. License: MIT
3. Project website
4. README
5. Releases