Skip to content



  • We are interested in various different kinds of improvement for Molecule; please feel free to raise an Issue if you would like to work on something major to ensure efficient collaboration and avoid duplicate effort.
  • Create a topic branch from where you want to base your work.
  • Make sure you have added tests for your changes.
  • Although not required, it is good to sign off commits using git commit --signoff, and agree that usage of --signoff constitutes agreement with the terms of DCO 1.1.
  • Run all the tests to ensure nothing else was accidentally broken.
  • Reformat the code by following the formatting section below.
  • Submit a pull request.

Code Of Conduct

Please see our Code of Conduct document.

Pull Request and Governance

  • If your PRs get stuck join us on IRC or add to the working group agenda.
  • The code style is what is enforced by CI, everything else is off-topic.
  • All PRs must be reviewed by one other person. This is enforced by GitHub. Larger changes require +2.


Molecule has an extensive set of unit and functional tests. Molecule uses Tox factors to generate a matrix of python x Ansible x unit/functional tests. Manual setup required as of this time.


Tests will be skipped when the driver's binary is not present.

Install the test framework Tox.

$ python3 -m pip install tox

Running the test suite

Run all tests, including linting and coverage reports. This should be run prior to merging or submitting a pull request.

$ tox

List available scenarios

List all available scenarios. This is useful to target specific Python and Ansible version for the functional and unit tests.

$ tox -av


Run all unit tests with coverage.

$ tox -e py

Run all unit tests for a specific version of Python.

$ tox -e py311


Linting is performed by a combination of linters.

Run all the linters (some perform changes to conform the code to the style rules).

$ tox -e lint


Generate the documentation, using mkdocs.

$ tox -e docs

Updating Dependencies

Dependencies need to be updated by hand in:

  • .config/
  • .pre-commit-config.yaml (2 places)


Based on the good work of John Dewey (@retr0h) and other contributors. Active member list can be seen at Molecule working group.