Unit Tests — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# Unit Tests

Unit tests are small isolated tests that target a specific library or module.

Topics

- Unit Tests
  - Available Tests
  - Running Tests
  - Installing dependencies
  - Extending unit tests
    - Fixtures files
    - Code Coverage

## Available Tests

Unit tests can be found in test/units, notice that the directory structure matches that of `lib/ansible/`

## Running Tests

Unit tests can be run across the whole code base by doing:

    cd /path/to/ansible/source
    source hacking/env-setup
    ansible-test units --tox

Against a single file by doing:

    ansible-test units --tox apt

Or against a specific Python version by doing:

    ansible-test units --tox --python 2.7 apt

For advanced usage see the online help:

    ansible-test units --help

## Installing dependencies

`ansible-test` has a number of dependencies , for `units` tests we suggest using `tox`

The dependencies can be installed using the `--requirements` argument, which will install all the required dependencies needed for unit tests. For example:

    ansible-test units --tox --python 2.7 --requirements apache2_module

Note

tox version requirement

When using `ansible-test` with `--tox` requires tox >= 2.5.0

The full list of requirements can be found at test/runner/requirements. Requirements files are named after their respective commands. See also the constraints applicable to all commands.

## Extending unit tests

Warning

What a unit test isn’t

If you start writing a test that requires external services then you may be writing an integration test, rather than a unit test.

### Fixtures files

To mock out fetching results from devices, you can use `fixtures` to read in pre-generated data.

Text files live in `test/units/modules/network/PLATFORM/fixtures/`

Data is loaded using the `load_fixture` method

See eos_banner test for a practical example.

### Code Coverage

Most `ansible-test` commands allow you to collect code coverage, this is particularly useful when to indicate where to extend testing.

To collect coverage data add the `--coverage` argument to your `ansible-test` command line:

    ansible-test units --coverage apt
    ansible-test coverage html

Results will be written to `test/results/reports/coverage/index.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