# Testing Ansible

Topics

- Testing Ansible
  - Requirements
  - Test Environments
    - Remote
    - Environment Variables
  - Interactive Shell
  - Code Coverage

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 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 Ansible). 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