wbrawner/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ansible/docs/docsite/rst/dev_guide/testing_running_locally.rst

150 lines
5.1 KiB
ReStructuredText
Raw Normal View History

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
2017-04-28 08:08:26 +00:00
***************
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs.
2017-04-14 00:46:21 +00:00
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
2017-04-28 08:08:26 +00:00
***************
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs.
2017-04-14 00:46:21 +00:00
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
2017-04-28 08:08:26 +00:00
.. contents:: Topics
This page describes how to:
* 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.
2017-04-14 00:46:21 +00:00
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.
Setup
=====
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
2017-04-28 08:08:26 +00:00
The code and tests are in the same GitHub repository, to get a local copy do
#. Fork the `ansible/ansible <https://github.com/ansible/ansible/>`_ repository on GitHub.
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs.
2017-04-14 00:46:21 +00:00
#. Clone your fork: ``git clone git@github.com:USERNAME/ansible.git``
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
2017-04-28 08:08:26 +00:00
#. Install the optional ``argcomplete`` package for tab completion (highly recommended)::
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs.
2017-04-14 00:46:21 +00:00
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
2017-04-28 08:08:26 +00:00
pip install argcomplete
activate-global-python-argcomplete
# Restart your shell to complete global activation.
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs.
2017-04-14 00:46:21 +00:00
#. Configure your environment to run from your clone (once per shell): ``. hacking/env-setup``
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
2017-04-28 08:08:26 +00:00
#. ``ansible``, ``ansible-playbook`` and ``ansible-test`` will now be in your ``PATH``
Expand test documentation. (#23598) * Replace test README.md with new README.rst. * Add compile and sanity README.rst docs.
2017-04-14 00:46:21 +00:00
Test Environments
=================
Most ``ansible-test`` commands support running in one or more isolated test environments to simplify testing.
Local
-----
The ``--local`` option runs tests locally without the use of an isolated test environment.
This is the default behavior.
Recommended for ``compile`` tests.
See the `command requirements directory <runner/requirements/>`_ for the requirements for each ``ansible-test`` command.
Requirements files are named after their respective commands.
See also the `constraints <runner/requirements/constraints.txt>`_ applicable to all commands.
Use the ``--requirements`` option to automatically install ``pip`` requirements relevant to the command being used.
Docker
------
The ``--docker`` option runs tests in a docker container.
Recommended for ``integration`` tests.
This option accepts an optional docker container image.
See the `list of supported docker images <runner/completion/docker.txt>`_ for options.
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.
Tox
---
The ``--tox`` option run tests in a ``tox`` managed Python virtual environment.
Recommended for ``windows-integration`` and ``units`` tests.
The following Python versions are supported:
* 2.6
* 2.7
* 3.5
* 3.6
By default, test commands will run against all supported Python versions when using ``tox``.
Use the ``--python`` option to specify a single Python version to use for test commands.
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
2017-04-28 08:08:26 +00:00
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.
2017-04-14 00:46:21 +00:00
General Usage
=============
Tests are run with the ``ansible-test`` command.
Consult ``ansible-test --help`` for usage information not covered here.
Use the ``--explain`` option to see what commands will be executed without actually running them.
Running Tests
=============
There are four main categories of tests, each in their own directory.
* `compile <compile/>`_ - Python syntax checking for supported versions. Examples:
* ``ansible-test compile`` - Check syntax for all supported versions.
* ``ansible-test compile --python 3.5`` - Check only Python 3.5 syntax.
* `sanity <sanity/>`_ - Static code analysis and general purpose script-based tests. Examples:
* ``ansible-test sanity --tox --python 2.7`` - Run all sanity tests on Python 2.7 using ``tox``.
* ``ansible-test sanity --test pep8`` - Run the ``pep8`` test without ``tox``.
* `integration <integration/>`_ - Playbook based tests for modules and core engine functionality. Examples:
* ``ansible-test integration ping --docker`` - Run the ``ping`` module test using ``docker``.
* ``ansible-test windows-integration windows/ci/`` - Run all Windows tests covered by CI.
* `units <units/>`_ - API oriented tests using mock interfaces for modules and core engine functionality. Examples:
* ``ansible-test units --tox`` - Run all unit tests on all supported Python versions using ``tox``.
* ``ansible-test units --tox --python 2.7 test/units/vars/`` - Run specific tests on Python 2.7 using ``tox``.
Consult each of the test directories for additional details on usage and requirements.
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.
Reference in a new issue Copy permalink