Usage

Quick Start

Install Molecule using pip:

$ pip install ansible
$ pip install docker-py
$ pip install molecule --pre

Create a new role:

$ molecule init role --role-name foo
--> Initializing new role foo...
Initialized role in /tmp/foo successfully.

Or Create a new scenario in an existing role:

$ cd foo
$ molecule init scenario --role-name foo --scenario-name new-scenario
--> Initializing new scenario new-scenario...
Initialized scenario in /tmp/foo/molecule/new-scenario successfully.
  1. Update the role with needed functionality and tests.
  2. Install the dependencies by following the instructions in INSTALL.rst included in the role’s scenario directory.
  3. Now test it.
$ cd foo
$ molecule test
--> Test matrix

└── default
    ├── destroy
    ├── dependency
    ├── syntax
    ├── create
    ├── converge
    ├── idempotence
    ├── lint
    ├── side_effect
    ├── verify
    └── destroy
--> Scenario: 'default'
--> Action: 'destroy'

    PLAY [Destroy] *****************************************************************

    TASK [Destroy molecule instance(s)] ********************************************
    ok: [localhost] => (item=(censored due to no_log))

    PLAY RECAP *********************************************************************
    localhost                  : ok=1    changed=0    unreachable=0    failed=0


--> Scenario: 'default'
--> Action: 'dependency'
--> Scenario: [default]
--> Dependency: [galaxy]
Skipping, missing the requirements file.
--> Scenario: 'default'
--> Action: 'syntax'

    playbook: /Users/jodewey/git/molecule_2/test/scenarios/foo/molecule/default/playbook.yml

--> Scenario: 'default'
--> Action: 'create'

    PLAY [Create] ******************************************************************

    TASK [Create Dockerfiles from image names] *************************************
    changed: [localhost] => (item=(censored due to no_log))

    TASK [Build an Ansible compatible image] ***************************************
    changed: [localhost] => (item=(censored due to no_log))

    TASK [Create molecule instance(s)] *********************************************
    changed: [localhost] => (item=(censored due to no_log))

    PLAY RECAP *********************************************************************
    localhost                  : ok=3    changed=3    unreachable=0    failed=0


--> Scenario: 'default'
--> Action: 'converge'

    PLAY [Converge] ****************************************************************

    TASK [Gathering Facts] *********************************************************
    ok: [instance]

    PLAY RECAP *********************************************************************
    instance                   : ok=1    changed=0    unreachable=0    failed=0


--> Scenario: 'default'
--> Action: 'idempotence'
Idempotence completed successfully.
--> Scenario: 'default'
--> Action: 'lint'
--> Executing Yamllint on files found in /Users/jodewey/git/molecule_2/test/scenarios/foo/...
Lint completed successfully.
--> Executing Flake8 on files found in /Users/jodewey/git/molecule_2/test/scenarios/foo/molecule/default/tests/...
Lint completed successfully.
--> Executing Ansible Lint on /Users/jodewey/git/molecule_2/test/scenarios/foo/molecule/default/playbook.yml...
Lint completed successfully.
--> Scenario: 'default'
--> Action: 'side_effect'
Skipping, side effect playbook not configured.
--> Scenario: 'default'
--> Action: 'verify'
--> Executing Testinfra tests found in /Users/jodewey/git/molecule_2/test/scenarios/foo/molecule/default/tests/...
    ============================= test session starts ==============================
    platform darwin -- Python 2.7.13, pytest-3.0.7, py-1.4.33, pluggy-0.4.0
    rootdir: /Users/jodewey/git/molecule_2, inifile: pytest.ini
    plugins: testinfra-1.6.0, verbose-parametrize-1.2.2, mock-1.6.0, helpers-namespace-2016.7.10, cov-2.4.0
collected 1 itemss

    tests/test_default.py .

    ============================ pytest-warning summary ============================
    WP1 None Module already imported so can not be re-written: testinfra
    ================= 1 passed, 1 pytest-warnings in 5.31 seconds ==================
Verifier completed successfully.
--> Scenario: 'default'
--> Action: 'destroy'

    PLAY [Destroy] *****************************************************************

    TASK [Destroy molecule instance(s)] ********************************************
    changed: [localhost] => (item=(censored due to no_log))

    PLAY RECAP *********************************************************************
    localhost                  : ok=1    changed=1    unreachable=0    failed=0

Check

class molecule.command.check.Check

Target the default scenario:

>>> molecule check

Targeting a specific scenario:

>>> molecule check --scenario-name foo

Executing with debug:

>>> molecule --debug check

Converge

Converge will execute the sequence necessary to converge the instances.

class molecule.command.converge.Converge

Target the default scenario:

>>> molecule converge

Targeting a specific scenario:

>>> molecule converge --scenario-name foo

Executing with debug:

>>> molecule --debug converge

Create

class molecule.command.create.Create

Target the default scenario:

>>> molecule create

Targeting a specific scenario:

>>> molecule create --scenario-name foo

Targeting a specific driver:

>>> molecule converge --driver-name foo

Executing with debug:

>>> molecule --debug create

Dependency

class molecule.command.dependency.Dependency

Target the default scenario:

>>> molecule dependency

Targeting a specific scenario:

>>> molecule dependency --scenario-name foo

Executing with debug:

>>> molecule --debug dependency

Destroy

class molecule.command.destroy.Destroy

Target the default scenario:

>>> molecule destroy

Target all scenarios:

>>> molecule destroy --all

Targeting a specific scenario:

>>> molecule destroy --scenario-name foo

Targeting a specific driver:

>>> molecule converge --driver-name foo

Executing with debug:

>>> molecule --debug destroy

Idempotence

class molecule.command.idempotence.Idempotence

Target the default scenario:

>>> molecule idempotence

Targeting a specific scenario:

>>> molecule idempotence --scenario-name foo

Executing with debug:

>>> molecule --debug idempotence

Init

class molecule.command.init.role.Role

Initialize a new role:

>>> molecule init role --role-name foo
class molecule.command.init.scenario.Scenario

Initialize a new scenario:

>>> molecule init scenario --scenario-name default --role-name foo
class molecule.command.init.template.Template

Initialize a new role from a Cookiecutter URL:

>>> molecule init template --url https://example.com/user/cookiecutter-repo

Lint

class molecule.command.lint.Lint

Target the default scenario:

>>> molecule lint

Targeting a specific scenario:

>>> molecule lint --scenario-name foo

Executing with debug:

>>> molecule --debug lint

List

class molecule.command.list.List

Target all scenarios:

>>> molecule list

Targeting a specific scenario:

>>> molecule list --scenario-name foo

Machine readable output:

>>> molecule list --format plain
>>> molecule list --format yaml

Executing with debug:

>>> molecule --debug list

Login

class molecule.command.login.Login

Targeting the only running host:

>>> molecule login

Targeting a specific running host:

>>> molecule login --host hostname

Targeting a specific running host and scenario:

>>> molecule login --host hostname --scenario-name foo

Executing with debug:

>>> molecule --debug login

Side Effect

class molecule.command.side_effect.SideEffect

This action has side effects and not enabled by default. See the provisioners documentation for further details.

Target the default scenario:

>>> molecule side-effect

Targeting a specific scenario:

>>> molecule side-effect --scenario-name foo

Executing with debug:

>>> molecule --debug side-effect

Syntax

class molecule.command.syntax.Syntax

Target the default scenario:

>>> molecule syntax

Targeting a specific scenario:

>>> molecule syntax --scenario-name foo

Executing with debug:

>>> molecule --debug syntax

Test

Test will execute the sequence necessary to test the instances.

class molecule.command.test.Test

Target the default scenario:

>>> molecule test

Target all scenarios:

>>> molecule test --all

Targeting a specific scenario:

>>> molecule test --scenario-name foo

Targeting a specific driver:

>>> molecule converge --driver-name foo

Executing with debug:

>>> molecule --debug test

Verify

class molecule.command.verify.Verify

Target the default scenario:

>>> molecule verify

Targeting a specific scenario:

>>> molecule verify --scenario-name foo

Executing with debug:

>>> molecule --debug verify