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 342822cc4..76f0693ce 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,66 +1,34 @@ -# Getting Started Guide +# Getting Started With Molecule -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. +Molecule is a testing framework built specifically to test Ansible roles and playbooks within a collection. -!!! note - - 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]'`. +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. -## Create a collection and test with molecule - -One of the recommended ways to create a collection is to place it -under the `collections/ansible_collections` directory. - -To create a collection, use the `ansible-galaxy` tool. -`ansible-galaxy collection init .` -Example: `ansible-galaxy collection init foo.bar` - -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. - -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. - -Also, create an ansible configuration `ansible.cfg` file under the `extensions` directory. -Add the `collections_path` to this configuration file. - -![Collection Structure and ansible config file collections path](images/collection_structure_and_ansible_cfg.png) +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 -create.yml destroy.yml molecule.yml converge.yml verify.yml +create.yml destroy.yml molecule.yml converge.yml ``` - `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. +- `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 @@ -92,7 +60,7 @@ create.yml destroy.yml 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 @@ -117,75 +85,81 @@ 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: - -```bash -$ molecule converge -``` +## Create a playbook inside the collection -If we want to manually inspect the instance afterwards, we can run: +Under the collection, we can create a directory named `playbooks` +and create a new playbook file under it. +Example: `my_playbook.yml` -```bash -$ molecule login ``` +--- +- 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 -We now have a free hand to experiment with the instance state. +``` -Finally, we can exit the instance and destroy it with: +## Adding Molecule to the Collection -```bash -$ molecule destroy -``` +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. -!!! note +Also, create an ansible configuration `ansible.cfg` file under the `extensions` directory. +Add the `collections_path` to this configuration file. - 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 ``` ``` @@ -217,3 +191,44 @@ Molecule full lifecycle sequence 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/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.