Skip to content

Commit

Permalink
Update documentation (#3975)
Browse files Browse the repository at this point in the history
  • Loading branch information
audgirka authored Jul 25, 2023
1 parent 875f5de commit 0e7cf0c
Show file tree
Hide file tree
Showing 3 changed files with 23 additions and 22 deletions.
22 changes: 11 additions & 11 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@

## Prerun

In order to help Ansible find used modules and roles, molecule will
To help Ansible find used modules and roles, molecule will
perform a prerun set of actions. These involve installing dependencies
from `requirements.yml` specified at project level, install a standalone
from `requirements.yml` specified at the project level, installing a standalone
role or a collection. The destination is `project_dir/.cache` and the
code itself was reused from ansible-lint, which has to do the same
actions. (Note: ansible-lint is not included with molecule.)

This assures that when you include a role inside molecule playbooks,
Ansible will be able to find that role, and that the include is exactly
Ansible will be able to find that role and that the include is exactly
the same as the one you are expecting to use in production.

If for some reason the prerun action does not suits your needs, you can
If for some reason the prerun action does not suit your needs, you can
still disable it by adding `prerun: false` inside the
configuration file.

Expand All @@ -28,7 +28,7 @@ your project, in order to avoid adding it to each scenario.
By default, `Molecule` will check whether the role name follows the name
standard. If not, it will raise an error.

If computed fully qualified role name does not follow current galaxy
If the computed fully qualified role name does not follow current galaxy
requirements, you can ignore it by adding `role_name_check:1` inside the configuration file.

It is strongly recommended to follow the name standard of
Expand All @@ -40,7 +40,7 @@ and

::: molecule.interpolation.Interpolator

There are following environment variables available in `molecule.yml`:
Following are the environment variables available in `molecule.yml`:

MOLECULE_DEBUG

Expand All @@ -57,7 +57,7 @@ MOLECULE_ENV_FILE

MOLECULE_STATE_FILE

: Path to molecule state file, contains state of the instances
: The path to molecule state file contains the state of the instances
(created, converged, etc.). Usually
`~/.cache/molecule/<role-name>/<scenario-name>/state.yml`

Expand Down Expand Up @@ -249,12 +249,12 @@ test_sequence:
`provisioner.playbooks` section of molecule.yml.

`side_effect` can have one or more arguments (separated by spaces) which is
a playbook (plabyooks) to execute. If the argument for `side_effect` is present,
a playbook (playbooks) to execute. If the argument for `side_effect` is present,
it's executed instead. The path to the playbook is relative to the molecule.yml location.
Normal side effect settings (from `provisioner.playbooks`) are ignored for action with
argument.

`verify` without an argument is executing usual tests configured in the verifier section
`verify` without an argument is executing the usual tests configured in the verifier section
of molecule.yml.

If one or more arguments (separated by spaces) are present, each argument is treated
Expand All @@ -263,9 +263,9 @@ The kind of verifier is set in the `verifier` section of molecule.yml and is app
`verify` actions in the scenario.

The path to tests is relative to the molecule.yml file location. The `additional_files_or_dirs`
setting for verifier is ignored if the `verify` action has an argument.
setting for the verifier is ignored if the `verify` action is provided with an argument.

Multiple `side_effect` and `verify` actions can be used to a create a combination
Multiple `side_effect` and `verify` actions can be used to create a combination
of playbooks and tests, for example, for end-to-end playbook testing.

Additional `converge` and `idempotence` actions can be used multiple times:
Expand Down
8 changes: 3 additions & 5 deletions docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,12 +84,10 @@ Molecule will resolve the `INSTANCE_UUID` environment variable when
creating and looking up the instance name. You can confirm all is in
working order by running `molecule list`.

## Can I test Ansible Collections with Molecule?
## Where can I configure my `roles-path` and `collections-paths`?

This is not currently officially supported. Also, collections remain in
"tech preview" status. However, you can take a look at [this blog
post](https://www.jeffgeerling.com/blog/2019/how-add-integration-tests-ansible-collection-molecule)
outlining a workable DIY solution as a stop gap for now.
As of molecule v6, 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.

## Does Molecule support monorepos?

Expand Down
15 changes: 9 additions & 6 deletions docs/next.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,21 @@ 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` 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).

# Planned changes

- Removal of provisioning drivers support and documenting, with examples, how to easily migrate to a self-provisioning approach.
- Removal of testinfra verifier driver and documenting how to call testinfra from inside the converge playbook to keep using the tool.
- Refactoring how dependencies are installed
- Bringing ephemeral directory under scenario folder instead of the current
inconvenient location under `~/.cache/molecule/...`
- Addition of a minimal `ansible.cfg` file under scenario folder that can
be used to tell ansible from where to load testing content. This is to replace
- Addition of a minimal `ansible.cfg` file under the scenario folder that can
be used to tell Ansible from where to load testing content. This is to replace
current Molecule magic around roles, collections and library paths and
test inventory location. Once done you will be able to run molecule playbooks with ansible directly without
test inventory location. Once done you will be able to run molecule playbooks with Ansible directly without
having to define these folders.

0 comments on commit 0e7cf0c

Please sign in to comment.