If you’re looking to move a little faster, see the Quick Start Guide.
The following guide will step through an example of developing and testing a new Ansible role. After reading this guide, you should be familiar with the basics of how to use Molecule and what it can offer.
In order to complete this guide by hand, you will need to additionally
install Docker. Molecule requires an external Python dependency for the
Docker driver which is provided when installing Molecule using
Molecule uses galaxy under the hood to generate conventional role layouts. If you’ve ever worked with Ansible roles before, you’ll be right at home. If not, please review the Roles guide to see what each folder is responsible for.
To generate a new role with Molecule, simply run:
$ molecule init role -r my-new-role
You should then see a
my-new-role folder in your current directory.
For future reference, if you want to initialize Molecule within an
existing role, you would use the
molecule init scenario -r
You will notice one new folder which is the
In this folder is a single Scenario called
Scenarios are the starting point for a lot of powerful functionality that Molecule offers. For now, we can think of a scenario as a test suite for your newly created role. You can have as many scenarios as you like and Molecule will run one after the other.
molecule/default folder, we find a number of files and
$ ls Dockerfile.j2 INSTALL.rst molecule.yml playbook.yml tests
INSTALL.rstcontains instructions on what additional software or setup steps you will need to take in order to allow Molecule to successfully interface with the driver.
molecule.ymlis the central configuration entrypoint for Molecule. With this file, you can configure each tool that Molecule will employ when testing your role.
playbook.ymlis the playbook file that contains the call site for your role. Molecule will invoke this playbook with
ansible-playbookand run it against an instance created by the driver.
testsis the tests directory created because Molecule uses TestInfra as the default Verifier. This allows you to write specific tests against the state of the container after your role has finished executing. Other verifier tools are available.
molecule.yml is for configuring Molecule. It is a YAML file whose
keys represent the high level components that Molecule provides. These are:
The Dependency manager. Molecule uses std:doc:galaxy <galaxy/dev_guide> by default to resolve your role dependencies.
The Platforms definitions. Molecule relies on this to know which instances to create, name and to which group each instance belongs. If you need to test your role against multiple popular distributions (CentOS, Fedora, Debian), you can specify that in this section.
The Provisioner. Molecule only provides an Ansible provisioner. Ansible manages the life cycle of the instance based on this configuration.
The Scenario definition. Molecule relies on this configuration to control the scenario sequence order.
Let’s create the first Molecule managed instance with the Docker driver.
First, ensure that Docker is running with the typical sanity check:
$ docker run hello-world
Now, we can tell Molecule to create an instance with:
$ molecule create
We can verify that Molecule has created the instance and they’re up and running with:
$ molecule list
Now, let’s add a task to our
tasks/main.yml like so:
- name: Molecule Hello World! debug: msg: Hello, World!
We can then tell Molecule to test our role against our instance with:
$ molecule converge
If we want to manually inspect the instance afterwards, we can run:
$ molecule login
We now have a free hand to experiment with the instance state.
Finally, we can exit the instance and destroy it with:
$ molecule destroy
If Molecule reports any errors, it can be useful to pass the
option to get more verbose output.
Molecule provides commands for manually managing the lifecyle of the instance, scenario, development and testing tools. However, we can also tell Molecule to manage this automatically within a Scenario sequence.
The full lifecycle sequence can be invoked with:
$ molecule test
It can be particularly useful to pass the
--destroy=never flag when
molecule test so that you can tell Molecule to run the full
sequence but not destroy the instance if one step fails.