dev_guidelines: initiate a paragraph about unit-tests (ansible-collec…

…tions#1156)

dev_guidelines: initiate a paragraph about unit-tests

Add some basic information regarding the unit-testing and initiate a list
guidelines. More will come later.

Reviewed-by: Mark Chappell <None>
Reviewed-by: Jill R <None>
Reviewed-by: Alina Buzachis <None>
Reviewed-by: Gonéri Le Bouder <goneri@lebouder.net>

docs/docsite/rst/dev_guidelines.rst

@@ -1048,3 +1048,57 @@ Where one of these reasons apply you should open a pull request proposing the mi
 Unsupported integration tests will not be automatically run by CI.  However, the
 necessary policies should be available so that the tests can be manually run by
 someone performing a PR review or writing a patch.
+
+Unit-tests for AWS plugins
+==========================
+
+Why do we need unit-tests when we've got functional tests
+---------------------------------------------------------
+
+Unit-tests are much faster and more suitable to test corner cases. They also don't depend on a third party service
+and thus, a failure is less likely to be a false positive.
+
+
+How to keep my code simple?
+---------------------------
+
+Ideally, you should break up your code in tiny functions. Each function should have a limited number of parameters
+and a low amount of cross dependencies with the rest of the code (low coupling):
+
+- Don't pass a large data structure to a function if it only uses one field. This clarifies the inputs of your
+  function (the contract) and also reduces the risk of an unexpected transformation of the data structure
+  from within the function.
+- The boto client object is complex and can be source of unwanted side-effect. It's better to isolate the calls
+  in dedicated functions. These functions will have their own unit-tests.
+- Don't pass the ``module`` object when you only need the read a couple of parameters from ``module.params``.
+  Pass the parameter directly to your function. By doing so, you're explicit about the function's inputs
+  (the contract) and you reduce potential side-effect.
+
+Unit-tests guidelines
+---------------------
+
+Ideally, all the ``module_utils`` should be covered by unit-tests. However we acknowledge that writing unit-tests may
+be challenging and we also accept contribution with no unit-test. Generally speaking, unit-tests are recommended and likely to speed up the PR reviews.
+
+- Our tests are run with ``pytest`` and we use the features it provides such as Fixtures, Parametrization.
+- The use of ``unittest.TestCase`` is discouraged for the sake of consistency and simplicity.
+- Unit-tests should run fine without any network connection.
+- It's not necessary to mock all the boto3/botocore calls (``get_paginator()``, ``paginate()``, etc). It's often better to just set-up a function that wraps these calls and mock the result.
+- Simplicity prevails. Tests should be short and cover a limited set of features.
+
+Pytest is well documented and you will find some example in its `how-to guides <https://docs.pytest.org/en/latest/how-to/index.html>`_
+
+How to run my unit-tests
+------------------------
+
+In our CI, the testing is done by ``ansible-test``. You can run the tests locally with the following command:
+
+.. code-block:: shell
+
+    $ ansible-test units --docker
+
+We also provide a ``tox`` configuration which allow you to run one specific test faster. In this example, we focus on the tests for the ``s3_object`` module:
+
+.. code-block:: shell
+
+    $ tox -e py3 -- tests/unit/plugins/modules/test_s3_object.py