Molecule for Local Ansible Role Testing

1. The "Why": Moving Up the Ansible Testing Spectrum

Before diving into Molecule, it's helpful to understand where it fits in the broader landscape of automation testing. Not all testing is equal. Manually spinning up an EC2 instance to test a role is slow and error-prone. We need a more structured approach.

Molecule automates the middle-to-upper tiers of this spectrum: it provisions a clean test environment, runs your role, verifies the outcome, checks for idempotency, and tears everything down.

2. Understanding the Molecule Workflow

At its core, Molecule formalizes the manual testing process into a repeatable, automated sequence. It uses a set of configurable components to manage the entire lifecycle of a test.

• Driver: The engine for creating test instances. Common choices are Docker (fast, lightweight), Vagrant (full VMs), and cloud providers like EC2. We will focus on the Docker driver.
• Provisioner: The tool that applies the configuration. This is almost always Ansible.
• Verifier: The framework for asserting the final state of the test instance. Popular options are Testinfra (Python-based tests) and Ansible itself.

When you run molecule test, it executes a default sequence of actions. This diagram shows a typical flow:

Let's see a video that walks through this sequence in detail.

3. Hands-On: Your First Molecule-Managed Role

Theory is great, but let's get our hands dirty. We'll adopt a Test-Driven Development (TDD) workflow: write a test that fails, then write the Ansible code to make it pass.

3.1. Setup and Initialization

First, you'll need to install Molecule and its Docker driver. Make sure you have Docker running on your system.

# It's best practice to use a Python virtual environment
python -m venv venv
source venv/bin/activate




# Install Molecule and the Docker plugin
pip install "molecule[docker]" ansible

Now, let's initialize a new role. This command creates a standard Ansible role structure and adds a molecule/default directory containing the testing boilerplate.

molecule init role my-nginx-role --driver-name docker
cd my-nginx-role

Take a moment to inspect the files inside molecule/default/. The key files are:

• molecule.yml: Configures the driver, platforms (test instances), provisioner, and verifier.
• converge.yml: The playbook Molecule runs to apply your role to the test instance.
• tests/test_default.py: The verification tests written using Testinfra and Pytest.

3.2. Writing a Failing Test

Let's define our goal: this role should install and enable the NGINX web server. Following TDD, we'll write the tests first.

Open molecule/default/tests/test_default.py and replace its contents with this:

import os
import testinfra.utils.ansible_runner

testinfra_hosts = testinfra.utils.ansible_runner.AnsibleRunner(
    os.environ['MOLECULE_INVENTORY_FILE']).get_hosts('all')




# Test 1: Check if the nginx package is installed
def test_nginx_package_installed(host):
    assert host.package("nginx").is_installed




# Test 2: Check if the nginx service is running and enabled
def test_nginx_service_running_and_enabled(host):
    service = host.service("nginx")
    assert service.is_running
    assert service.is_enabled

Our tests are ready. Now, let's run just the verification step. It will fail because we haven't written any Ansible tasks yet.

molecule verify

You should see output from pytest indicating that the tests failed spectacularly. This is expected!

3.3. The Development Loop: Converge, Login, Verify

Running molecule test for every small change is too slow. The professional workflow revolves around the converge command, which leaves the test instance running for inspection and quick iteration.

First, let's add the Ansible tasks to make our tests pass. Edit tasks/main.yml with the following content:

---



# tasks file for my-nginx-role
- name: Install NGINX
  ansible.builtin.package:
    name: nginx
    state: present

- name: Ensure NGINX service is started and enabled
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

Now, let's use the iterative development workflow.

Now, try this workflow yourself:

1. Converge: Run the playbook. Molecule will create the Docker container and apply your role.

   molecule converge
   

2. Login (Optional): If something went wrong, you can get a shell inside the container to debug.

   molecule login
   
   
   
   # Inside the container, you can check things manually
   # > systemctl status nginx
   # > exit
   

3. Verify: Run your Testinfra tests against the running container.

   molecule verify
   

This time, the tests should all pass. You've successfully built and verified your role!

4. Destroy: Once you're done, clean up the environment.

   molecule destroy
   

4. Guaranteeing Idempotency

Correctness is one half of the equation; idempotency is the other. As we've discussed, a well-behaved Ansible role should produce the same state no matter how many times it's run. On the second run and beyond, no tasks should report as "changed".

Molecule has a dedicated idempotence step that automatically checks this for you by running the converge playbook a second time and failing the test if any task reports a change.

To see this in action, run the full test suite on the role you just created.

molecule test

Observe the output. You will see the converge step, followed by the idempotence step. Because we used the package and service modules correctly, the idempotence check will pass.

5. Advanced Testing: Multiple Platforms and Scenarios

Real-world roles often need to support multiple operating systems. Molecule makes this easy. By adding more entries to the platforms section of molecule.yml, you can test your role against different distributions like Ubuntu, CentOS, and Debian simultaneously.

However, testing service management requires Docker images that have an init system (like systemd) running. The default Docker Hub images often don't.

Here's an example of a molecule.yml platforms section configured for multi-OS service testing:

platforms:
  - name: ubuntu2204
    image: "geerlingguy/docker-ubuntu2204-ansible:latest"
    pre_build_image: true
    privileged: true
  - name: rocky9
    image: "geerlingguy/docker-rocky9-ansible:latest"
    pre_build_image: true
    privileged: true

Conclusion

You now have a powerful framework for developing and testing your Ansible automation. This local, rapid feedback loop is essential for building confidence in your code before it gets integrated into a CI/CD pipeline and deployed to production.

Key Takeaways:

• Automated Testing is Essential: You understand that manual testing doesn't scale and that frameworks like Molecule are necessary for professional infrastructure-as-code development.
• Molecule's Workflow: You are familiar with the create, converge, verify, and destroy sequence and know how to use it for both full validation (molecule test) and iterative development (molecule converge).
• Test-Driven Development (TDD): You can write verification tests using Testinfra before writing your Ansible tasks, ensuring your role is built correctly from the start.
• Idempotency is King: You know what idempotency means, how Molecule tests for it, and how to avoid common patterns that cause idempotence failures.
• Multi-Platform Testing: You can configure Molecule to validate your role across multiple Linux distributions.

What's Next?

We've built a high-quality, locally tested Ansible role. The next logical step is to automate its execution in a deployment pipeline. In our next lesson, "Integrate Ansible playbook execution into a CI/CD pipeline with secure credential handling," we will take this tested role and build a workflow in GitHub Actions that runs it automatically, bridging the gap between local development and continuous delivery.