ceb474bb9e
Batch of docs backports: * docs: Clarify include_task v import_tasks with conditionals (#43856) (cherry picked from commit6be42a2a0e) * Add single quotes around package name (#45152) (cherry picked from commit0d81386144) * prefer ansible_facts namespace and dict notation (#44980) (cherry picked from commit44510448b0) * fix cherrypick conflict - scenario_guides * Update implicit_localhost.rst (#45455) (cherry picked from commitf68cd1acc6) * updated fbsd install instructions (#45309) (cherry picked from commite9c2695ce7) * Change "Defaulting Undefined Variables" (#41379) (cherry picked from commite35c4be1c1) * adds license details to dev guide pages (#45574) (cherry picked from commit6e68d77f6d) * FAQ: fix a typo, add link to 'vars' lookup (#42412) (cherry picked from commit95649dc793) * Fix link and toctree (#45595) (cherry picked from commit6999bf318f) * Improve the local toctree (and title) (#45590) (cherry picked from commitafea00fa9f) * Add undocumented configuration parameter and explain in porting guide (#36059) (cherry picked from commita892a6ef03) * Simplify PPA installation for Ubuntu (#45690) (cherry picked from commit78e9f452a5) * adding git+ssh uri scheme (#36025) (cherry picked from commit84a4257774) * Add workaround for non-standard kerberos environments (#41465) (cherry picked from commit4e532e0ad9) * Restore license agreement (#45809) (cherry picked from commitf430f60541) * partial cherry-pick - lenovo doc update PR 45483
88 lines
3.3 KiB
ReStructuredText
88 lines
3.3 KiB
ReStructuredText
:orphan:
|
|
|
|
.. _testing_running_locally:
|
|
|
|
***************
|
|
Testing Ansible
|
|
***************
|
|
|
|
.. contents:: Topics
|
|
|
|
This document describes how to:
|
|
|
|
* Run tests locally using ``ansible-test``
|
|
* Extend
|
|
|
|
Requirements
|
|
============
|
|
|
|
There are no special requirements for running ``ansible-test`` on Python 2.7 or later.
|
|
The ``argparse`` package is required for Python 2.6.
|
|
The requirements for each ``ansible-test`` command are covered later.
|
|
|
|
|
|
Test Environments
|
|
=================
|
|
|
|
Most ``ansible-test`` commands support running in one or more isolated test environments to simplify testing.
|
|
|
|
|
|
Remote
|
|
------
|
|
|
|
The ``--remote`` option runs tests in a cloud hosted environment.
|
|
An API key is required to use this feature.
|
|
|
|
Recommended for integration tests.
|
|
|
|
See the `list of supported platforms and versions <https://github.com/ansible/ansible/blob/devel/test/runner/completion/remote.txt>`_ for additional details.
|
|
|
|
Environment Variables
|
|
---------------------
|
|
|
|
When using environment variables to manipulate tests there some limitations to keep in mind. Environment variables are:
|
|
|
|
* Not propagated from the host to the test environment when using the ``--docker`` or ``--remote`` options.
|
|
* Not exposed to the test environment unless whitelisted in ``test/runner/lib/util.py`` in the ``common_environment`` function.
|
|
* Not exposed to the test environment when using the ``--tox`` option unless whitelisted in ``test/runner/tox.ini`` by the ``passenv`` definition.
|
|
|
|
Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --tox``. However, using the ``--docker`` option would
|
|
require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set
|
|
and the tests executed. This is useful for debugging tests inside a container by following the
|
|
:ref:`Debugging AnsibleModule-based modules <debugging_ansiblemodule_based_modules>` instructions.
|
|
|
|
Interactive Shell
|
|
=================
|
|
|
|
Use the ``ansible-test shell`` command to get an interactive shell in the same environment used to run tests. Examples:
|
|
|
|
* ``ansible-test shell --docker`` - Open a shell in the default docker container.
|
|
* ``ansible-test shell --tox --python 3.6`` - Open a shell in the Python 3.6 ``tox`` environment.
|
|
|
|
|
|
Code Coverage
|
|
=============
|
|
|
|
Code coverage reports make it easy to identify untested code for which more tests should
|
|
be written. Online reports are available but only cover the ``devel`` branch (see
|
|
:doc:`testing`). For new code local reports are needed.
|
|
|
|
Add the ``--coverage`` option to any test command to collect code coverage data. If you
|
|
aren't using the ``--tox`` or ``--docker`` options which create an isolated python
|
|
environment then you may have to use the ``--requirements`` option to ensure that the
|
|
correct version of the coverage module is installed
|
|
|
|
ansible-test units --coverage apt
|
|
ansible-test integration --coverage aws_lambda --tox --requirements
|
|
ansible-test coverage html
|
|
|
|
|
|
Reports can be generated in several different formats:
|
|
|
|
* ``ansible-test coverage report`` - Console report.
|
|
* ``ansible-test coverage html`` - HTML report.
|
|
* ``ansible-test coverage xml`` - XML report.
|
|
|
|
To clear data between test runs, use the ``ansible-test coverage erase`` command. For a full list of features see the online help::
|
|
|
|
ansible-test coverage --help
|