Alicia Cozine 4264be2b18 Remove more docs build errors (#45364 )

* orphans testing pages to avoid not-in-toctree errors

* orphans various pages pending reorg

* adds module_utils and special_vars to main TOC

* uses a glob for scenario_guide TOC

* normalize and Sentence-case headings on community pages, typos

* re-orgs community TOC, adds all pages to toctree

* removes scenario guides index page

* adds style guide to community index

* basic update to style guide

* fix typo that created a new error

* removes not-in-toctree from ignore errors list

* leave removing files for future cleanup task

2018-09-11 17:51:47 +01:00

3.3 KiB

Raw Blame History

orphan

Testing Ansible

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

3.3 KiB Raw Blame History