diff --git a/docs/examples.md b/docs/examples.md index 4a86f1ba7..ffdccb64c 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -275,8 +275,8 @@ platforms: ## Monolith Repo -Molecule is generally used to test roles in isolation. However, it can -also test roles from a monolith repo. +Molecule is generally used to test playbooks or roles in isolation. +However, it can also test them from a monolith repo. ```bash $ tree monolith-repo -L 3 --prune @@ -296,7 +296,7 @@ monolith-repo ``` The role initialized with Molecule (baz in this case) would simply -reference the dependent roles via it's `converge.yml` or meta +reference the dependent roles via its `converge.yml` or meta dependencies. Molecule can test complex scenarios leveraging this technique. diff --git a/docs/getting-started.md b/docs/getting-started.md index 7198dd633..76f0693ce 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,51 +1,39 @@ -# Getting Started Guide +# Getting Started With Molecule -The following guide will step through an example of developing and -testing a new Ansible role. After reading this guide, you should be -familiar with the basics of how to use Molecule and what it can offer. +Molecule is a testing framework built specifically to test Ansible roles and playbooks within a collection. -!!! note +Molecule aims to test your Ansible roles and playbooks in isolation +as it launches an environment to run your playbook and then performs tests over it. +You can then run your playbook over different instance types and versions to verify if it still runs. - In order to complete this guide by hand, you will need to additionally - install [Docker](https://docs.docker.com/). Molecule requires an - external Python dependency for the Docker driver which is provided when - installing Molecule using `pip install 'molecule-plugins[docker]'`. +Before moving to test the playbooks or roles, the sections below provide information related to Scenarios. ## Molecule Scenarios -You will notice one new folder which is the `molecule` folder. - -In this folder there is a single `root_scenario` called `default`. - -Scenarios are the starting point for a lot of powerful functionality -that Molecule offers. For now, we can think of a scenario as a test -suite for your newly created role. You can have as many scenarios as you -like and Molecule will run one after the other. +Scenarios are the starting point for a lot of powerful functionality that Molecule offers. +For now, we can think of a scenario as a test suite for roles or playbooks within a collection. +You can have as many scenarios as you like and Molecule will run one after the other. ## The Scenario Layout -Within the `molecule/default` folder, we find a number of files and +Within the `molecule/default` folder, we find several files and directories: ```bash $ ls -INSTALL.rst molecule.yml converge.yml verify.yml +create.yml destroy.yml molecule.yml converge.yml ``` -- `INSTALL.rst` contains instructions on what additional software or - setup steps you will need to take in order to allow Molecule to - successfully interface with the driver. -- `molecule.yml` is the central configuration entrypoint for Molecule. +- `create.yml` is a playbook file used for creating the instances + and storing data in instance-config +- `destroy.yml` has the Ansible code for destroying the instances + and removing them from instance-config +- `molecule.yml` is the central configuration entry point for Molecule per scenario. With this file, you can configure each tool that Molecule will employ when testing your role. - `converge.yml` is the playbook file that contains the call for your role. Molecule will invoke this playbook with `ansible-playbook` and run it against an instance created by the driver. -- `verify.yml` is the Ansible file used for testing as Ansible is the - default [verifier](configuration.md#verifier). This allows you to - write specific tests against the state of the container after your - role has finished executing. Other verifier tools are available - Note that [testinfra](https://testinfra.readthedocs.io/en/latest/) was the default verifier prior to molecule version 3. !!! note @@ -72,7 +60,7 @@ INSTALL.rst molecule.yml converge.yml verify.yml ## Inspecting the `molecule.yml` The `molecule.yml` is for configuring Molecule. It is a -[YAML](https://yaml.org/) file whose keys represent the high level +[YAML](https://yaml.org/) file whose keys represent the high-level components that Molecule provides. These are: - The [dependency](configuration.md#dependency) manager. Molecule @@ -97,75 +85,98 @@ components that Molecule provides. These are: checking tests (such as deployment smoke tests) on the target instance. -## Run test sequence commands - -Let's create the first Molecule managed instance with the Docker -driver. +The following guide will step through an example of developing and +testing a new Ansible collection. After reading this guide, you should be +familiar with the basics of how to use Molecule and what it can offer. -First, ensure that [Docker](https://docs.docker.com/) is running with -the typical sanity check: +## Create a collection -```bash -$ docker run hello-world -``` +One of the recommended ways to create a collection is to place it +under the `collections/ansible_collections` directory. -Now, we can tell Molecule to create an instance with: +To create a collection, use the `ansible-galaxy` tool. +`ansible-galaxy collection init .` +Example: `ansible-galaxy collection init foo.bar` -```bash -$ molecule create -``` +After a collection is created, it would be under +`collections/ansible_collections//` +See [Collection structure](https://docs.ansible.com/ansible/5/dev_guide/developing_collections_structure.html#collection-structure) for details on the collection directory structure. -We can verify that Molecule has created the instance and they're up and -running with: +## Create a role inside the collection -```bash -$ molecule list -``` +To initialize a role inside a collection we can again use `ansible-galaxy` tool under the `roles` directory. +`ansible-galaxy role init .` +Example: `ansible-galaxy collection init my_role` -Now, let's add a task to our `tasks/main.yml` like so: +Once the role is created, add a task under `my_role/tasks/main.yml`. -```yaml -- name: Molecule Hello World! +``` +--- +- name: Task is running from within the role ansible.builtin.debug: - msg: Hello, World! + msg: "This is a task from my_role." ``` -We can then tell Molecule to test our role against our instance with: +## Create a playbook inside the collection -```bash -$ molecule converge -``` +Under the collection, we can create a directory named `playbooks` +and create a new playbook file under it. +Example: `my_playbook.yml` -If we want to manually inspect the instance afterwards, we can run: +``` +--- +- name: Test new role from within this playbook + hosts: localhost + gather_facts: false + tasks: + - name: Testing role + ansible.builtin.include_role: + name: foo.bar.my_role + tasks_from: main.yml -```bash -$ molecule login ``` -We now have a free hand to experiment with the instance state. +## Adding Molecule to the Collection -Finally, we can exit the instance and destroy it with: +Inside the collection, create a directory named `extensions` +and initialize `molecule scenario` under this directory using +the command: `molecule init scenario ` +`scenario_name` is optional, if not provided, will create +a `default` scenario. -```bash -$ molecule destroy -``` +Also, create an ansible configuration `ansible.cfg` file under the `extensions` directory. +Add the `collections_path` to this configuration file. -!!! note - - If Molecule reports any errors, it can be useful to pass the `--debug` - option to get more verbose output. +![Collection Structure and ansible config file collections path](images/collection_structure_and_ansible_cfg.png) ## Run a full test sequence Molecule provides commands for manually managing the lifecycle of the instance, scenario, development and testing tools. However, we can also tell Molecule to manage this automatically within a -`root_scenario` sequence. +scenario sequence. The full lifecycle sequence can be invoked with: ```bash -$ molecule test +molecule test +``` + +``` +Molecule full lifecycle sequence +└── default + ├── dependency + ├── cleanup + ├── destroy + ├── syntax + ├── create + ├── prepare + ├── converge + ├── idempotence + ├── side_effect + ├── verify + ├── cleanup + └── destroy ``` !!! note @@ -180,3 +191,44 @@ $ molecule test only. It is useful if you want to test one platform docker image. [galaxy development guide]: https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html + +## Test the collection playbook or role + +So you now have an isolated test environment, and can also use it for live development, by running `molecule converge`. +It will run through the same steps as above but will stop after the converge action. +Then you can make changes to your collection or the Converge play, and then run molecule converge again (and again) until you're done with your development work. + +One of the default files created as part of the initialization is the `converge.yml` file. +This file is a playbook created to run your role from start to finish. +This can be modified if needed but is a good place to start if you have never used Molecule before. + +To test the playbook from a collection, +let's add a task to our role under `tasks/main.yml` file like so: + +``` +--- +- name: Include a playbook from a collection + ansible.builtin.import_playbook: foo.bar.my_playbook + +``` + +Similarly, if we want to test only the role instead of a playbook in `converge.yml` file: + +``` +--- +- name: Include a role from a collection + hosts: localhost + gather_facts: false + tasks: + - name: Testing role + ansible.builtin.include_role: + name: foo.bar.my_role + tasks_from: main.yml + +``` + +```bash +molecule converge +``` + +The above command will run this specific playbook for us. diff --git a/docs/images/collection_structure_and_ansible_cfg.png b/docs/images/collection_structure_and_ansible_cfg.png new file mode 100644 index 000000000..fd4cd334c Binary files /dev/null and b/docs/images/collection_structure_and_ansible_cfg.png differ diff --git a/docs/next.md b/docs/next.md index 09ea39b17..c9eba6a8a 100644 --- a/docs/next.md +++ b/docs/next.md @@ -7,13 +7,16 @@ reduce the amount of magic and just rely on ansible core features. # Implemented changes - `roles-path` and `collections-paths` are no longer configurable for - dependencies. Users are expected to make use of [`ansible.cfg`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html) file to + dependencies. Users are expected to make use of [ansible.cfg](https://docs.ansible.com/ansible/latest/reference_appendices/config.html) file to alter them when needed. - `molecule init` command is now only available to create a scenario using `molecule init scenario`. Users will no longer be able to create a role. - Instead, users can make use of [`ansible-galaxy`](https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html#) to [create a role](https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html#creating-roles-for-galaxy). + Instead, users can make use of [ansible-galaxy](https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html) to create a collection or role. + +- From v6, `testinfra` is now an optional dependency. + It will be removed in the next major release(v7). # Planned changes diff --git a/docs/usage.md b/docs/usage.md index 79e1d42c7..ded9c0001 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -63,3 +63,51 @@ Matrix will display the subcommand's ordered list of actions, which can be changed in [scenario](configuration.md#scenario) configuration. + +## Test sequence commands + +We can tell Molecule to create an instance with: + +```bash +molecule create +``` + +We can verify that Molecule has created the instance and they're up and +running with: + +```bash +molecule list +``` + +Now, let's add a task to our role under `tasks/main.yml` file like so: + +```yaml +- name: Molecule Hello World! + ansible.builtin.debug: + msg: Hello, World! +``` + +We can then tell Molecule to test our role against our instance with: + +```bash +molecule converge +``` + +If we want to manually inspect the instance afterward, we can run: + +```bash +molecule login +``` + +We now have a free hand to experiment with the instance state. + +Finally, we can exit the instance and destroy it with: + +```bash +molecule destroy +``` + +!!! note + + If Molecule reports any errors, it can be useful to pass the `--debug` + option to get more verbose output.