A good source of examples are the scenario functional tests.


Molecule can be executed via an Alpine Linux container by leveraging dind (Docker in Docker). Currently, we only build images for the latest version of Ansible and Molecule. In the future we may break this out into Molecule/ Ansible versioned pairs. The images are located on quay.io.

To test a role, change directory into the role to test, and execute Molecule as follows.

docker run --rm -it \
    -v "$(pwd)":/tmp/$(basename "${PWD}"):ro \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -w /tmp/$(basename "${PWD}") \
    quay.io/ansible/molecule:2.20 \
    molecule test

Docker With Non-Privileged User

Default Molecule Docker driver execute Ansible playbooks with root user. If your workflow require non-privileged user, some simple changes to molecule.yaml and Dockerfile.j2 are required.

Append to end off Dockerfile.j2 commands that are creating ansible user with passwordless sudo privileges. Variable SUDO_GROUP depends on distribution wheel is used on centos:7.

# Create `ansible` user with sudo permissions and membership in `DEPLOY_GROUP`
RUN set -xe \
  && groupadd -r ${ANSIBLE_USER} \
  && groupadd -r ${DEPLOY_GROUP} \
  && useradd -m -g ${ANSIBLE_USER} ${ANSIBLE_USER} \
  && usermod -aG ${SUDO_GROUP} ${ANSIBLE_USER} \
  && usermod -aG ${DEPLOY_GROUP} ${ANSIBLE_USER} \
  && sed -i "/^%${SUDO_GROUP}/s/ALL\$/NOPASSWD:ALL/g" /etc/sudoers

Change molecule.yaml file by modifying provisioner block and changing default provisioning user from root to newly created one.

  name: ansible
    name: ansible-lint
        ansible_user: ansible

Now you can test new user with simple task add following TASK to tasks/main.yml it should fail until you uncomment become: yes.

- name: Create apps dir
    path: /opt/examples
    owner: ansible
    group: deployer
    mode: 0775
    state: directory
  # become: yes

Don’t forget to run molecule destroy if image vas already created.

Systemd Container

To start a service which requires systemd, in a non-privileged container, configure molecule.yml with a systemd compliant image, tmpfs, volumes, and command as follows.

  - name: instance
    image: centos:7
    command: /sbin/init
      - /run
      - /tmp
      - /sys/fs/cgroup:/sys/fs/cgroup:ro

Note that centos:7 image contains a seccomp security profile for Docker which enables the use of systemd. When needed, such security profiles can be reused (for example the one available in Fedora):

  - name: instance
    image: debian:stretch
    command: /sbin/init
      - seccomp=path/to/seccomp.json
      - /run
      - /tmp
      - /sys/fs/cgroup:/sys/fs/cgroup:ro

The developer can also opt to start the container with extended privileges, by either giving it SYS_ADMIN capabilites or running it in privileged mode.


Use caution when using privileged mode or SYS_ADMIN capabilities as it grants the container elevated access to the underlying system.

To limit the scope of the extended privileges, grant SYS_ADMIN capabilities along with the same image, command, and volumes as shown in the non-privileged example.

  - name: instance
    image: centos:7
    command: /sbin/init
      - SYS_ADMIN
      - /sys/fs/cgroup:/sys/fs/cgroup:ro

To start the container in privileged mode, set the privileged flag along with the same image and command as shown in the non-privileged example.

  - name: instance
    image: centos:7
    command: /sbin/init
    privileged: True

Monolith Repo

Molecule is generally used to test roles in isolation. However, it can also test roles from a monolith repo.

$ tree monolith-repo -L 3 --prune
├── library
│   └── foo.py
├── plugins
│   └── filters
│       └── foo.py
└── roles
    ├── bar
    │   └── README.md
    ├── baz
    │   └── README.md
    └── foo
        └── README.md

The role initialized with Molecule (baz in this case) would simply reference the dependant roles via it’s playbook.yml or meta dependencies.

Molecule can test complex scenarios leveraging this technique.

$ cd monolith-repo/roles/baz
$ molecule test

Molecule is simply setting the ANSIBLE_* environment variables. To view the environment variables set during a Molecule operation pass the --debug flag.

$ molecule --debug test

ANSIBLE_CONFIG: /private/tmp/monolith-repo/roles/baz/molecule/default/.molecule/ansible.cfg
ANSIBLE_FILTER_PLUGINS: /Users/jodewey/.pyenv/versions/2.7.13/lib/python2.7/site-packages/molecule/provisioner/ansible/plugins/filters:/private/tmp/monolith-repo/roles/baz/plugins/filters:/private/tmp/monolith-repo/roles/baz/molecule/default/.molecule/plugins/filters
ANSIBLE_LIBRARY: /Users/jodewey/.pyenv/versions/2.7.13/lib/python2.7/site-packages/molecule/provisioner/ansible/plugins/libraries:/private/tmp/monolith-repo/roles/baz/library:/private/tmp/monolith-repo/roles/baz/molecule/default/.molecule/library
ANSIBLE_ROLES_PATH: /private/tmp/monolith-repo/roles:/private/tmp/monolith-repo/roles/baz/molecule/default/.molecule/roles

Molecule can be customized any number of ways. Updating the provisioner’s env section in molecule.yml to suit the needs of the developer and layout of the project.

  name: ansible

Vagrant Proxy Settings

One way of passing in proxy settings to the Vagrant provider is using the vagrant-proxyconf plugin and adding the vagrant-proxyconf configurations to ~/.vagrant.d/Vagrantfile.

To install the plugin run:

$ vagrant plugin install vagrant-proxyconf

On linux add the following Vagrantfile to ~/.vagrant.d/Vagrantfile.

Vagrant.configure("2") do |config|
  if Vagrant.has_plugin?("vagrant-proxyconf")
    config.proxy.http     = ENV['HTTP_PROXY']
    config.proxy.https    = ENV['HTTP_PROXY']
    config.proxy.no_proxy = ENV['NO_PROXY']

Sharing Across Scenarios

Playbooks and tests can be shared across scenarios.

$ tree shared-tests
├── molecule
│   ├── centos
│   │   └── molecule.yml
│   ├── resources
│   │   ├── playbooks
│   │   │   ├── Dockerfile.j2
│   │   │   ├── create.yml
│   │   │   ├── destroy.yml
│   │   │   ├── playbook.yml
│   │   │   └── prepare.yml
│   │   └── tests
│   │       └── test_default.py
│   ├── ubuntu
│   │   └── molecule.yml
│   └── ubuntu-upstart
│       └── molecule.yml

Tests can be shared across scenarios. In this example the tests directory lives in a shared location and molecule.yml is points to the shared tests.

name: testinfra
directory: ../resources/tests/
  name: flake8

Running Molecule processes in parallel mode


This functionality should be considered experimental. It is part of ongoing work towards enabling parallelizable functionality across all moving parts in the execution of the Molecule feature set.


Only the following sequences support parallelizable functionality:

  • check_sequence: molecule check --parallel

  • destroy_sequence: molecule destroy --parallel

  • test_sequence: molecule test --parallel

It is currently only available for use with the Docker driver.

It is possible to run Molecule processes in parallel using another tool to orchestrate the parallelization (such as GNU Parallel or Pytest).

When Molecule receives the --parallel flag it will generate a UUID for the duration of the testing sequence and will use that unique identifier to cache the run-time state for that process. The parallel Molecule processes cached state and created instances will therefore not interfere with each other.

Molecule uses a new and separate caching folder for this in the $HOME/.cache/molecule_parallel location. Molecule exposes a new environment variable MOLECULE_PARALLEL which can enable this functionality.