Fix typo in documentation (#71652)
Fix typo on the page about unit testing modules,
This commit is contained in:
parent
9fcf1db871
commit
1ad0f666d5
1 changed files with 18 additions and 18 deletions
|
@ -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.
|
||||
|
||||
|
|
Loading…
Reference in a new issue