These steps assume a Linux work environment with ``git`` installed.
These steps assume a Linux work environment with ``git`` installed.
1. Install and start ``docker`` or ``podman`` with the ``docker`` executable shim. This insures tests run properly isolated and in the exact environments as in CI. The latest ``ansible-core`` development version also supports the ``podman`` CLI program.
1. Install and start ``docker`` or ``podman``. This ensures tests run properly isolated and in the same environment as in CI.
2. :ref:`Install Ansible or ansible-core <installation_guide>`. You need the ``ansible-test`` utility which is provided by either of these packages.
2. :ref:`Install Ansible or ansible-core <installation_guide>`. You need the ``ansible-test`` utility which is provided by either of these packages.
@ -155,11 +155,9 @@ See :ref:`module_contribution` for some general guidelines about Ansible module
Test your changes
Test your changes
=================
=================
If using the ``docker`` CLI program, the host must be configured to use cgroupsv1 (this is not required for ``podman``). This can be done by adding ``systemd.unified_cgroup_hierarchy=0`` to the kernel boot arguments (requires bootloader config update and reboot).
1. Install ``flake8`` (``pip install flake8``, or install the corresponding package on your operating system).
1. Install ``flake8`` (``pip install flake8``, or install the corresponding package on your operating system).
1. Run ``flake8`` against a changed file:
2. Run ``flake8`` against a changed file:
..code-block:: bash
..code-block:: bash
@ -169,7 +167,7 @@ Test your changes
This shows unused imports, which are not shown by sanity tests, as well as other common issues.
This shows unused imports, which are not shown by sanity tests, as well as other common issues.
Optionally, you can use the ``--max-line-length=160`` command-line argument.
Optionally, you can use the ``--max-line-length=160`` command-line argument.
2. Run sanity tests:
3. Run sanity tests:
..code-block:: bash
..code-block:: bash
@ -178,7 +176,7 @@ Test your changes
If they failed, look at the output carefully - it is informative and helps to identify a problem line quickly.
If they failed, look at the output carefully - it is informative and helps to identify a problem line quickly.
Sanity failings usually relate to incorrect code and documentation formatting.
Sanity failings usually relate to incorrect code and documentation formatting.
2. Switch to the directory where the ``ansible-core`` source resides:
..code-block:: shell
cd ~/dev/ansible
3. Add ``ansible-core`` programs to your ``PATH``:
..code-block:: shell
source hacking/env-setup
..note::
You can skip this step if you only need to run ``ansible-test``, and not other ``ansible-core`` programs.
In that case, simply run ``bin/ansible-test`` from the root of the ``ansible-core`` source.
..caution::
If you have an installed version of ``ansible-core`` and are trying to run ``ansible-test`` from your ``PATH``,
make sure the program found by your shell is the one from the ``ansible-core`` source:
..code-block:: shell
which ansible-test
Commands
========
The most commonly used test commands are:
* ``ansible-test sanity`` - Run sanity tests (mostly linters and static analysis).
* ``ansible-test integration`` - Run integration tests.
* ``ansible-test units`` - Run unit tests.
Run ``ansible-test --help`` to see a complete list of available commands.
..note::
For detailed help on a specific command, add the ``--help`` option after the command.
Environments
============
Most ``ansible-test`` commands support running in one or more isolated test environments to simplify testing.
Most ``ansible-test`` commands support running in one or more isolated test environments to simplify testing.
Containers
----------
Containers are recommended for running sanity, unit and integration tests, since they provide consistent environments.
Unit tests will be run with network isolation, which avoids unintentional dependencies on network resources.
The ``--docker`` option runs tests in a container using either Docker or Podman.
..note::
If both Docker and Podman are installed, Docker will be used.
To override this, set the environment variable ``ANSIBLE_TEST_PREFER_PODMAN`` to any non-empty value.
Choosing a container
^^^^^^^^^^^^^^^^^^^^
Without an additional argument, the ``--docker`` option uses the ``default`` container.
To use another container, specify it immediately after the ``--docker`` option.
..note::
The ``default`` container is recommended for all sanity and unit tests.
To see the list of supported containers, use the ``--help`` option with the ``ansible-test`` command you want to use.
..note::
The list of available containers is dependent on the ``ansible-test`` command you are using.
You can also specify your own container.
When doing so, you will need to indicate the Python version in the container with the ``--python`` option.
Custom containers
"""""""""""""""""
When building custom containers, keep in mind the following requirements:
* The ``USER`` should be ``root``.
* Use an ``init`` process, such as ``systemd``.
* Include ``sshd`` and accept connections on the default port of ``22``.
* Include a POSIX compatible ``sh`` shell which can be found on ``PATH``.
* Include a ``sleep`` utility which runs as a subprocess.
* Include a supported version of Python.
* Avoid using the ``VOLUME`` statement.
Docker and SELinux
^^^^^^^^^^^^^^^^^^
Using Docker on a host with SELinux may require setting the system in permissive mode.
Consider using Podman instead.
Docker Desktop with WSL2
^^^^^^^^^^^^^^^^^^^^^^^^
These instructions explain how to use ``ansible-test`` with WSL2 and Docker Desktop *without*``systemd`` support.
Remote
..note::
------
The ``--remote`` option runs tests in a cloud hosted environment.
If your WSL2 environment includes ``systemd`` support, these steps are not required.
An API key is required to use this feature.
Recommended for integration tests.
Configuration requirements
""""""""""""""""""""""""""
See the `list of supported platforms and versions <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/remote.txt>`_ for additional details.
1. Open Docker Desktop and go to the **Settings** screen.
2. On the the **General** tab:
Environment Variables
a. Uncheck the **Start Docker Desktop when you log in** checkbox.
---------------------
b. Check the **Use the WSL 2 based engine** checkbox.
3. On the **Resources** tab under the **WSL Integration** section:
a. Enable distros you want to use under the **Enable integration with additional distros** section.
4. Click **Apply and restart** if changes were made.
Setup instructions
""""""""""""""""""
..note::
If all WSL instances have been stopped, these changes will need to be re-applied.
1. Verify Docker Desktop is properly configured (see :ref:`Configuration requirements`).
2. Quit Docker Desktop if it is running:
a. Right click the **Docker Desktop** taskbar icon.
b. Click the **Quit Docker Desktop** option.
3. Stop any running WSL instances with the command:
..code-block:: shell
wsl --shutdown
4. Verify all WSL instances have stopped with the command:
..code-block:: shell
wsl -l -v
5. Start a WSL instance and perform the following steps as ``root``:
a. Verify the ``systemd`` subsystem is not registered:
a. Check for the ``systemd`` cgroup hierarchy with the following command:
..code-block:: shell
grep systemd /proc/self/cgroup
b. If any matches are found, re-check the :ref:`Configuration requirements` and follow the
:ref:`Setup instructions` again.
b. Mount the ``systemd`` cgroup hierarchy with the following commands:
..code-block:: shell
mkdir /sys/fs/cgroup/systemd
mount cgroup -t cgroup /sys/fs/cgroup/systemd -o none,name=systemd,xattr
6. Start Docker Desktop.
You should now be able to use ``ansible-test`` with the ``--docker`` option.
Linux cgroup configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^
..note::
These changes will need to be re-applied each time the container host is booted.
For certain container hosts and container combinations, additional setup on the container host may be required.
In these situations ``ansible-test`` will report an error and provide additional instructions to run as ``root``:
..code-block:: shell
mkdir /sys/fs/cgroup/systemd
mount cgroup -t cgroup /sys/fs/cgroup/systemd -o none,name=systemd,xattr
If you are using rootless Podman, an additional command must be run, also as ``root``.
Make sure to substitute your user and group for ``{user}`` and ``{group}`` respectively:
..code-block:: shell
chown -R {user}:{group} /sys/fs/cgroup/systemd
Podman
""""""
When using Podman, you may need to stop existing Podman processes after following the :ref:`Linux cgroup configuration`
instructions. Otherwise Podman may be unable to see the new mount point.
You can check to see if Podman is running by looking for ``podman`` and ``catatonit`` processes.
Remote virtual machines
-----------------------
Remote virtual machines are recommended for running integration tests not suitable for execution in containers.
The ``--remote`` option runs tests in a cloud hosted ephemeral virtual machine.
..note::
An API key is required to use this feature, unless running under an approved Azure Pipelines organization.
To see the list of supported systems, use the ``--help`` option with the ``ansible-test`` command you want to use.
..note::
The list of available systems is dependent on the ``ansible-test`` command you are using.
Python virtual environments
---------------------------
Python virtual environments provide a simple way to achieve isolation from the system and user Python environments.
They are recommended for unit and integration tests when the ``--docker`` and ``--remote`` options cannot be used.
The ``--venv`` option runs tests in a virtual environment managed by ``ansible-test``.
Requirements are automatically installed before tests are run.
Composite environment arguments
-------------------------------
The environment arguments covered in this document are sufficient for most use cases.
However, some scenarios may require the additional flexibility offered by composite environment arguments.
The ``--controller`` and ``--target`` options are alternatives to the ``--docker``, ``--remote`` and ``--venv`` options.
..note::
When using the ``shell`` command, the ``--target`` option is replaced by three platform specific options.
Add the ``--help`` option to your ``ansible-test`` command to learn more about the composite environment arguments.
Additional Requirements
=======================
Some ``ansible-test`` commands have additional requirements.
You can use the ``--requirements`` option to automatically install them.
..note::
When using a test environment managed by ``ansible-test`` the ``--requirements`` option is usually unnecessary.
Environment variables
=====================
When using environment variables to manipulate tests there some limitations to keep in mind. Environment variables are:
When using environment variables to manipulate tests there some limitations to keep in mind. Environment variables are:
@ -51,16 +336,15 @@ When using environment variables to manipulate tests there some limitations to k
and the tests executed. This is useful for debugging tests inside a container by following the
and the tests executed. This is useful for debugging tests inside a container by following the
Matt Clay
2 years ago
committed by