ansible/docs/docsite/rst/dev_guide/testing_running_locally.rst

***************
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.


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
=============

Add the ``--coverage`` option to any test command to collect code coverage data.

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.
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 8 years ago			`***************`
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs. 8 years ago			`Testing Ansible`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 8 years ago			`***************`
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs. 8 years ago
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 8 years ago			`.. contents:: Topics`

Minor testing docs improvements (#24103) Fix a few formatting issues spotted post review. Also reapply missing commit 8 years ago			`This document describes how to:`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 8 years ago
			* Run tests locally using ``ansible-test``
			`* Extend`
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs. 8 years ago
			`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.`

Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 8 years ago			See the `list of supported platforms and versions <https://github.com/ansible/ansible/blob/devel/test/runner/completion/remote.txt>`_ for additional details.
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs. 8 years ago

			`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`
			`=============`

			Add the ``--coverage`` option to any test command to collect code coverage data.

			`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.