Porting Guide

Porting your existing role from Molecule to Molecule v2.


Molecule ships with a conversion script. This conversion script converts a molecule v1 vagrant driver config into a molecule v2 vagrant config. The script handles the creation of the initial directory structure, migration and cleanup of files.


The script is fairly crude, and only supports Vagrant at the time of this writing. The authors will be adding additional functionality as additional roles are migrated to v2.

$ contrib/convert.py /path/to/v1/role/molecule.yml


  1. In the basedir of your existing role, create a new default scenario. This scenario is equivalent to your existing Molecule v1 setup.

$ cd $role-name
$ molecule init scenario -r $role-name -s default -d $driver-name
  1. Move existing Testinfra tests to the new scenario’s test directory located at molecule/default/tests/test_default.py.

  2. If necessary port existing Serverspec tests to Testinfra. A Testinfra skeleton has been created at molecule/default/tests/test_default.py.

  3. Port role’s existing molecule.yml to the new format located in the scenario’s directory at molecule/default/molecule.yml.

  4. Port role’s existing playbook.yml to the new location in the scenario’s directory at molecule/default/playbook.yml.

  5. Cleanup

$ rm -rf .molecule/
$ rm -rf molecule.yml
$ rm -rf playbook.yml
$ rm -rf tests/
  1. Test

$ molecule test