diff --git a/docs/docsite/rst/dev_guide/testing_units_modules.rst b/docs/docsite/rst/dev_guide/testing_units_modules.rst index 51bfa3f46a5..88763eb0a14 100644 --- a/docs/docsite/rst/dev_guide/testing_units_modules.rst +++ b/docs/docsite/rst/dev_guide/testing_units_modules.rst @@ -15,8 +15,8 @@ Introduction This document explains why, how and when you should use unit tests for Ansible modules. The document doesn't apply to other parts of Ansible for which the recommendations are -normally closer to the Python standard. There is basic documentation for Ansible unit -tests in the developer guide :ref:`testing_units`. This document should +normally closer to the Python standard. There is basic documentation for Ansible unit +tests in the developer guide :ref:`testing_units`. This document should be readable for a new Ansible module author. If you find it incomplete or confusing, please open a bug or ask for help on Ansible IRC. @@ -24,12 +24,12 @@ What Are Unit Tests? ==================== Ansible includes a set of unit tests in the :file:`test/units` directory. These tests primarily cover the -internals but can also can cover Ansible modules. The structure of the unit tests matches +internals but can also cover Ansible modules. The structure of the unit tests matches the structure of the code base, so the tests that reside in the :file:`test/units/modules/` directory are organized by module groups. Integration tests can be used for most modules, but there are situations where -cases cannot be verified using integration tests. This means that Ansible unit test cases +cases cannot be verified using integration tests. This means that Ansible unit test cases may extend beyond testing only minimal units and in some cases will include some level of functional testing. @@ -40,13 +40,13 @@ Why Use Unit Tests? Ansible unit tests have advantages and disadvantages. It is important to understand these. Advantages include: -* Most unit tests are much faster than most Ansible integration tests. The complete suite +* Most unit tests are much faster than most Ansible integration tests. The complete suite of unit tests can be run regularly by a developer on their local system. * Unit tests can be run by developers who don't have access to the system which the module is designed to work on, allowing a level of verification that changes to core functions haven't broken module expectations. * Unit tests can easily substitute system functions allowing testing of software that - would be impractical. For example, the ``sleep()`` function can be replaced and we check + would be impractical. For example, the ``sleep()`` function can be replaced and we check that a ten minute sleep was called without actually waiting ten minutes. * Unit tests are run on different Python versions. This allows us to ensure that the code behaves in the same way on different Python versions. @@ -62,7 +62,7 @@ implementation problem between the internal code tested and the actual result delivered to the user Normally the Ansible integration tests (which are written in Ansible YAML) provide better -testing for most module functionality. If those tests already test a feature and perform +testing for most module functionality. If those tests already test a feature and perform well there may be little point in providing a unit test covering the same area as well. When To Use Unit Tests @@ -85,13 +85,13 @@ Providing quick feedback Example: A single step of the rds_instance test cases can take up to 20 - minutes (the time to create an RDS instance in Amazon). The entire - test run can last for well over an hour. All 16 of the unit tests + minutes (the time to create an RDS instance in Amazon). The entire + test run can last for well over an hour. All 16 of the unit tests complete execution in less than 2 seconds. The time saving provided by being able to run the code in a unit test makes it worth creating a unit test when bug fixing a module, even if those tests do not often identify -problems later. As a basic goal, every module should have at least one unit test which +problems later. As a basic goal, every module should have at least one unit test which will give quick feedback in easy cases without having to wait for the integration tests to complete. @@ -110,9 +110,9 @@ Example: Another related use is in the situation where an API has versions which behave differently. A programmer working on a new version may change the module to work with the -new API version and unintentionally break the old version. A test case +new API version and unintentionally break the old version. A test case which checks that the call happens properly for the old version can help avoid the -problem. In this situation it is very important to include version numbering in the test case +problem. In this situation it is very important to include version numbering in the test case name (see `Naming unit tests`_ below). Providing specific design tests @@ -134,9 +134,9 @@ of the code, such as installing all of the packages supplied as arguments to the How to unit test Ansible modules ================================ -There are a number of techniques for unit testing modules. Beware that most +There are a number of techniques for unit testing modules. Beware that most modules without unit tests are structured in a way that makes testing quite difficult and -can lead to very complicated tests which need more work than the code. Effectively using unit +can lead to very complicated tests which need more work than the code. Effectively using unit tests may lead you to restructure your code. This is often a good thing and leads to better code overall. Good restructuring can make your code clearer and easier to understand. @@ -158,7 +158,7 @@ Use of Mocks Mock objects (from https://docs.python.org/3/library/unittest.mock.html) can be very useful in building unit tests for special / difficult cases, but they can also -lead to complex and confusing coding situations. One good use for mocks would be in +lead to complex and confusing coding situations. One good use for mocks would be in simulating an API. As for 'six', the 'mock' python package is bundled with Ansible (use ``import units.compat.mock``). @@ -203,7 +203,7 @@ API definition with unit test cases ----------------------------------- API interaction is usually best tested with the function tests defined in Ansible's -integration testing section, which run against the actual API. There are several cases +integration testing section, which run against the actual API. There are several cases where the unit tests are likely to work better. Defining a module against an API specification @@ -214,7 +214,7 @@ an API that Ansible uses but which are beyond the control of the user. By writing a custom emulation of the calls that return data from the API, we can ensure that only the features which are clearly defined in the specification of the API are -present in the message. This means that we can check that we use the correct +present in the message. This means that we can check that we use the correct parameters and nothing else. @@ -522,7 +522,7 @@ Traps for maintaining Python 2 compatibility ============================================ If you use the ``mock`` library from the Python 2.6 standard library, a number of the -assert functions are missing but will return as if successful. This means that test cases should take great care *not* use +assert functions are missing but will return as if successful. This means that test cases should take great care *not* use functions marked as _new_ in the Python 3 documentation, since the tests will likely always succeed even if the code is broken when run on older versions of Python.