Unit Tests¶

Structuring Unit Tests¶

Ansible drives unit tests through pytest. This means that tests can either be written a simple functions which are included in any file name like test_<something>.py or as classes.

Here is an example of a function:

#this function will be called simply because it is called test_*()

def test_add()
    a = 10
    b = 23
    c = 33
    assert a + b = c

Here is an example of a class:

import unittest:

class AddTester(unittest.TestCase)

    def SetUp()
        self.a = 10
        self.b = 23

    # this function will
    def test_add()
      c = 33
      assert self.a + self.b = c

   # this function will
    def test_subtract()
      c = -13
      assert self.a - self.b = c

Both methods work fine in most circumstances; the function-based interface is simpler and quicker and so that’s probably where you should start when you are just trying to add a few basic tests for a module. The class-based test allows more tidy set up and tear down of pre-requisites, so if you have many test cases for your module you may want to refactor to use that.

Assertions using the simple assert function inside the tests will give give full information on the cause of the failure with a trace-back of functions called during the assertion. This means that plain asserts are recommended over other external assertion libraries.

A number of the unit test suites include functions that are shared between several modules, especially in the networking arena. In these cases a file is created in the same directory, which is then included directly.

Module test case common code¶

Keep common code as specific as possible within the test/units/ directory structure. For example, if it’s specific to testing Amazon modules, it should be in test/units/modules/cloud/amazon/. Don’t import common unit test code from directories outside the current or parent directories.

Don’t import other unit tests from a unit test. Any common code should be in dedicated files that aren’t themselves tests.

Fixtures files¶

To mock out fetching results from devices, or provide other complex datastructures that come from external libraries, 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.

If you are simulating APIs you may find that python placebo is useful. See doc:testing_units_modules for more information.

Code Coverage For New or Updated Unit Tests¶

New code will be missing from the codecov.io coverage reports (see Testing Ansible), so local reporting is needed. 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. See testing_units_running_locally for more information about generating coverage reports.