* Clone `the community.general Git repository <https://github.com/ansible-collections/community.general/>`_ or a fork of it into the directory ``general``::
* Clone `the community.general Git repository <https://github.com/ansible-collections/community.general/>`_ or a fork of it into the directory ``general``:
..code-block:: shell
cd ~/dev/ansible/collections/ansible_collections/community
git clone git@github.com:ansible-collections/community.general.git general
* If you clone from a fork, add the original repository as a remote ``upstream``::
* If you clone from a fork, add the original repository as a remote ``upstream``:
..code-block:: shell
cd ~/dev/ansible/collections/ansible_collections/community/general
@ -20,7 +20,9 @@ You must always execute ``ansible-test`` from the root directory of a collection
Compile and sanity tests
------------------------
To run all compile and sanity tests::
To run all compile and sanity tests:
..code-block:: shell-session
ansible-test sanity --docker default -v
@ -31,15 +33,21 @@ Adding unit tests
You must place unit tests in the appropriate ``tests/unit/plugins/`` directory. For example, you would place tests for ``plugins/module_utils/foo/bar.py`` in ``tests/unit/plugins/module_utils/foo/test_bar.py`` or ``tests/unit/plugins/module_utils/foo/bar/test_bar.py``. For examples, see the `unit tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/unit/>`_.
To run all unit tests for all supported Python versions::
To run all unit tests for all supported Python versions:
..code-block:: shell-session
ansible-test units --docker default -v
To run all unit tests only for a specific Python version::
To run all unit tests only for a specific Python version:
..code-block:: shell-session
ansible-test units --docker default -v --python 3.6
To run only a specific unit test::
To run only a specific unit test:
..code-block:: shell-session
ansible-test units --docker default -v --python 3.6 tests/unit/plugins/module_utils/foo/test_bar.py
@ -59,13 +67,17 @@ For examples, see the `integration tests in community.general <https://github.co
Since integration tests can install requirements, and set-up, start and stop services, we recommended running them in docker containers or otherwise restricted environments whenever possible. By default, ``ansible-test`` supports Docker images for several operating systems. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for all options. Use the ``default`` image mainly for platform-independent integration tests, such as those for cloud modules. The following examples use the ``centos8`` image.
To execute all integration tests for a collection::
To execute all integration tests for a collection:
..code-block:: shell-session
ansible-test integration --docker centos8 -v
If you want more detailed output, run the command with ``-vvv`` instead of ``-v``. Alternatively, specify ``--retry-on-error`` to automatically re-run failed tests with higher verbosity levels.
To execute only the integration tests in a specific directory::
To execute only the integration tests in a specific directory:
Inventory scripts must accept the ``--list`` and ``--host <hostname>`` arguments. Although other arguments are allowed, Ansible will not use them.
Such arguments might still be useful for executing the scripts directly.
When the script is called with the single argument ``--list``, the script must output to stdout a JSON object that contains all the groups to be managed. Each group's value should be either an object containing a list of each host, any child groups, and potential group variables, or simply a list of hosts::
When the script is called with the single argument ``--list``, the script must output to stdout a JSON object that contains all the groups to be managed. Each group's value should be either an object containing a list of each host, any child groups, and potential group variables, or simply a list of hosts:
..code-block:: json
{
"group001": {
"hosts": ["host001", "host002"],
@ -383,12 +385,13 @@ When the script is called with the single argument ``--list``, the script must o
If any of the elements of a group are empty, they may be omitted from the output.
When called with the argument ``--host <hostname>`` (where <hostname> is a host from above), the script must print a JSON object, either empty or containing variables to make them available to templates and playbooks. For example::
When called with the argument ``--host <hostname>`` (where <hostname> is a host from above), the script must print a JSON object, either empty or containing variables to make them available to templates and playbooks. For example:
..code-block:: json
{
"VAR001": "VALUE",
"VAR002": "VALUE",
"VAR002": "VALUE"
}
Printing variables is optional. If the script does not print variables, it should print an empty JSON object.
@ -404,7 +407,9 @@ The stock inventory script system mentioned above works for all versions of Ansi
To avoid this inefficiency, if the inventory script returns a top-level element called "_meta", it is possible to return all the host variables in a single script execution. When this meta element contains a value for "hostvars", the inventory script will not be invoked with ``--host`` for each host. This behavior results in a significant performance increase for large numbers of hosts.
The data to be added to the top-level JSON object looks like this::
The data to be added to the top-level JSON object looks like this:
..code-block:: text
{
@ -424,7 +429,9 @@ The data to be added to the top-level JSON object looks like this::
}
To satisfy the requirements of using ``_meta``, to prevent ansible from calling your inventory with ``--host`` you must at least populate ``_meta`` with an empty ``hostvars`` object.
After the shebang, the UTF-8 coding, the copyright line, the license section, and the ``DOCUMENTATION`` block comes the ``EXAMPLES`` block. Here you show users how your module works with real-world examples in multi-line plain-text YAML format. The best examples are ready for the user to copy and paste into a playbook. Review and update your examples with every change to your module.
Per playbook best practices, each example should include a ``name:`` line::
Per playbook best practices, each example should include a ``name:`` line:
..code-block:: text
EXAMPLES = r'''
- name: Ensure foo is installed
@ -371,7 +373,9 @@ Otherwise, for each value returned, provide the following fields. All fields are
:contains:
Optional. To describe nested return values, set ``type: dict``, or ``type: list``/``elements: dict``, or if you really have to, ``type: complex``, and repeat the elements above for each sub-field.
Here are two example ``RETURN`` sections, one with three simple fields and one with a complex nested field::
Here are two example ``RETURN`` sections, one with three simple fields and one with a complex nested field:
@ -14,17 +14,23 @@ Rebasing the branch used to create your PR will resolve both of these issues.
Configuring your remotes
========================
Before you can rebase your PR, you need to make sure you have the proper remotes configured. These instructions apply to any repository on GitHub, including collections repositories. On other platforms (bitbucket, gitlab), the same principles and commands apply but the syntax may be different. We use the ansible/ansible repository here as an example. In other repositories, the branch names may be different. Assuming you cloned your fork in the usual fashion, the ``origin`` remote will point to your fork::
Before you can rebase your PR, you need to make sure you have the proper remotes configured. These instructions apply to any repository on GitHub, including collections repositories. On other platforms (bitbucket, gitlab), the same principles and commands apply but the syntax may be different. We use the ansible/ansible repository here as an example. In other repositories, the branch names may be different. Assuming you cloned your fork in the usual fashion, the ``origin`` remote will point to your fork:
@ -40,7 +40,9 @@ To add new machines, there is no additional SSL signing server involved, so ther
If there's another source of truth in your infrastructure, Ansible can also connect to that. Ansible can draw inventory, group, and variable information from sources like EC2, Rackspace, OpenStack, and more.
Here's what a plain text inventory file looks like::
Here's what a plain text inventory file looks like:
..code-block:: text
---
[webservers]
@ -62,7 +64,9 @@ Playbooks can finely orchestrate multiple slices of your infrastructure topology
Ansible's approach to orchestration is one of finely-tuned simplicity, as we believe your automation code should make perfect sense to you years down the road and there should be very little to remember about special syntax or features.
When Pull Requests (PRs) are created they are tested using Azure Pipelines, a Continuous Integration (CI) tool. Results are shown at the end of every PR.
When Azure Pipelines detects an error and it can be linked back to a file that has been modified in the PR then the relevant lines will be added as a GitHub comment. For example::
When Azure Pipelines detects an error and it can be linked back to a file that has been modified in the PR then the relevant lines will be added as a GitHub comment. For example:
..code-block:: text
The test `ansible-test sanity --test pep8` failed with the following errors:
@ -71,11 +73,15 @@ When Azure Pipelines detects an error and it can be linked back to a file that h
From the above example we can see that ``--test pep8`` and ``--test validate-modules`` have identified an issue. The commands given allow you to run the same tests locally to ensure you've fixed all issues without having to push your changes to GitHub and wait for Azure Pipelines, for example:
If you haven't already got Ansible available, use the local checkout by running::
If you haven't already got Ansible available, use the local checkout by running:
..code-block:: shell-session
source hacking/env-setup
Then run the tests detailed in the GitHub comment::
Then run the tests detailed in the GitHub comment:
..code-block:: shell-session
ansible-test sanity --test pep8
ansible-test sanity --test validate-modules
@ -126,8 +132,9 @@ Here's how:
other flavors, since some features (for example, package managers such as apt or yum) are specific to those OS versions.
@ -140,7 +147,9 @@ Next, find the pull request you'd like to test and make note of its number. It w
It is important that the PR request target be ``ansible:devel``, as we do not accept pull requests into any other branch. Dot releases are cherry-picked manually by Ansible staff.
Use the pull request number when you fetch the proposed changes and create your branch for testing::
Use the pull request number when you fetch the proposed changes and create your branch for testing:
The example below assumes ``bin/`` is in your ``$PATH``. An easy way to achieve that
is to initialize your environment with the ``env-setup`` command::
is to initialize your environment with the ``env-setup`` command:
..code-block:: shell-session
source hacking/env-setup
ansible-test --help
You can also call ``ansible-test`` with the full path::
You can also call ``ansible-test`` with the full path:
..code-block:: shell-session
bin/ansible-test --help
@ -74,19 +78,27 @@ outside of those test subdirectories. They will also not reconfigure or bounce
Use the ``--docker-no-pull`` option to avoid pulling the latest container image. This is required when using custom local images that are not available for download.
Run as follows for all POSIX platform tests executed by our CI system in a fedora32 docker container::
Run as follows for all POSIX platform tests executed by our CI system in a fedora32 docker container:
Samuel Gaist
3 years ago
committed by