added unit test details for resource modules (#65891)

* added unit test details for resource modules

1 files changed, 87 insertions, 0 deletions

diff --git a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst
index 09227b63ac..b0e12190bd 100644
--- a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst
+++ b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst
@@ -375,3 +375,90 @@ The tests rely on a role generated by the resource module builder. After changes
                    -e structure=role \
                    -e model=models/myos/interfaces/myos_interfaces.yml \
                    site.yml
+
+
+.. _testing_resource_modules:
+
+
+Unit testing Ansible network resource modules
+=============================================
+
+
+This section walks through an example of how to develop unit tests for Ansible network resource
+modules.
+
+See :ref:`testing_units` and :ref:`testing_units_modules` for general documentation on Ansible unit tests for modules.
+Please read those pages first to understand unit tests and why and when you should use them.
+
+.. note::
+
+   The structure of the unit tests matches
+   the structure of the code base, so the tests that reside in the :file:`test/units/modules/network` directory
+   are organized by module groups.
+
+Using mock objects to unit test Ansible network resource modules
+----------------------------------------------------------------
+
+
+Mock objects (from https://docs.python.org/3/library/unittest.mock.html) can be very
+useful in building unit tests for special or difficult cases, but they can also
+lead to complex and confusing coding situations.  One good use for mocks would be to
+simulate an API. The ``mock`` Python package is bundled with Ansible (use
+``import units.compat.mock``).
+
+You can mock the device connection and output from the device as follows:
+
+.. code-block:: python
+
+   self.mock_get_config = patch('ansible.module_utils.network.common.network.Config.get_config')
+   self.get_config = self.mock_get_config.start()
+
+   self.mock_load_config = patch('ansible.module_utils.network.common.network.Config.load_config')
+   self.load_config = self.mock_load_config.start()
+
+   self.mock_get_resource_connection_config = patch('ansible.module_utils.network.common.cfg.base.get_resource_connection')
+   self.get_resource_connection_config = self.mock_get_resource_connection_config.start()
+
+   self.mock_get_resource_connection_facts = patch('ansible.module_utils.network.common.facts.facts.get_resource_connection')
+   self.get_resource_connection_facts = self.mock_get_resource_connection_facts.start()
+
+   self.mock_edit_config = patch('ansible.module_utils.network.eos.providers.providers.CliProvider.edit_config')
+   self.edit_config = self.mock_edit_config.start()
+
+   self.mock_execute_show_command = patch('ansible.module_utils.network.eos.facts.l2_interfaces.l2_interfaces.L2_interfacesFacts.get_device_data')
+   self.execute_show_command = self.mock_execute_show_command.start()
+
+The facts file of the module now includes a new method, ``get_device_data``. Call ``get_device_data`` here to emulate the device output.
+
+
+Mocking device data
+-----------------------
+
+To mock fetching results from devices or provide other complex data structures that
+come from external libraries, you can use ``fixtures`` to read in pre-generated data. The text files for this pre-generated data live in ``test/units/modules/network/PLATFORM/fixtures/``. See for example the `eos_l2_interfaces.cfg file <https://github.com/ansible/ansible/blob/devel/test/units/modules/network/eos/fixtures/eos_l2_interfaces_config.cfg>`_.
+
+Load data using the ``load_fixture`` method and set this data as the return value of the
+``get_device_data`` method in the facts file:
+
+.. code-block:: python
+
+    def load_fixtures(self, commands=None, transport='cli'):
+        def load_from_file(*args, **kwargs):
+            return load_fixture('eos_l2_interfaces_config.cfg')
+        self.execute_show_command.side_effect = load_from_file
+
+See the unit test file `test_eos_l2_interfaces
+<https://github.com/ansible/ansible/blob/devel/test/units/modules/network/eos/test_eos_l2_interfaces.py>`_
+for a practical example.
+
+
+.. seealso::
+
+   :ref:`testing_units`
+       Ansible unit tests documentation
+   :ref:`testing_units`
+       Deep dive into developing unit tests for Ansible modules
+   :ref:`testing_running_locally`
+       Running tests locally including gathering and reporting coverage data
+   :ref:`developing_modules_general`
+       Get started developing a module