Added a style guide for iris pytest (#5785)

* Added a draft style guide for iris pytest

* most review comments

* refactored documentation

* fixed doclinks

* reslolved review comments

* removed excess pages

* conversion checklist

* pre-lunch changes

* majority review requests, rough reshuffle of Test Categories

* further reshuffle of Test Categories

* review stuffies

* fixed a coup of review comments

* fixed a doctest failures

* reworded function and class intros

---------

Co-authored-by: Martin Yeo <[email protected]>

docs/src/developers_guide/contributing_pytest_conversions.rst

@@ -0,0 +1,56 @@
+.. include:: ../common_links.inc
+
+.. _contributing_pytest_conversions:
+
+*******************************************
+Converting From ``unittest`` to ``pytest``
+*******************************************
+
+Conversion Checklist
+--------------------
+.. note::
+    Please bear in mind the following checklist is for general use; there may be
+    some cases which require extra context or thought before implementing these changes.
+
+#. Before making any manual changes, run https://github.com/dannysepler/pytestify
+   on the file. This does a lot of the brunt work for you!
+#. Check for references to :class:`iris.tests.IrisTest`. If a class inherits
+   from this, remove the inheritance. Inheritance is unnecessary for
+   pytest tests, so :class:`iris.tests.IrisTest` has been deprecated
+   and its convenience methods have been moved to the
+   :mod:`iris.tests._shared_utils` module.
+#. Check for references  to ``unittest``. Many of the functions within unittest
+   are also in pytest, so often you can just change where the function is imported
+   from.
+#. Check for references to ``self.assert``. Pytest has a lighter-weight syntax for
+   assertions, e.g. ``assert x == 2`` instead of ``assertEqual(x, 2)``. In the
+   case of custom :class:`~iris.tests.IrisTest` assertions, the majority of these
+   have been replicated in
+   :mod:`iris.tests._shared_utils`, but with snake_case instead of camelCase.
+   Some :class:`iris.tests.IrisTest` assertions have not been converted into
+   :mod:`iris.tests._shared_utils`, as these were deemed easy to achieve via
+   simple ``assert ...`` statements.
+#. Check for references to ``setUp()``. Replace this with ``_setup()`` instead.
+   Ensure that this is decorated with ``@pytest.fixture(autouse=True)``.
+
+   .. code-block:: python
+
+      @pytest.fixture(autouse=True)
+      def _setup(self):
+         ...
+
+#. Check for references to ``@tests``. These should be changed to ``@_shared_utils``.
+#. Check for references to ``with mock.patch("...")``. These should be replaced with
+   ``mocker.patch("...")``. Note, ``mocker.patch("...")`` is NOT a context manager.
+#. Check for ``np.testing.assert...``. This can usually be swapped for
+   ``_shared_utils.assert...``.
+#. Check for references to ``super()``. Most test classes used to inherit from
+   :class:`iris.tests.IrisTest`, so references to this should be removed.
+#. Check for references to ``self.tmp_dir``. In pytest, ``tmp_path`` is used instead,
+   and can be passed into functions as a fixture.
+#. Check for ``if __name__ == 'main'``. This is no longer needed with pytest.
+#. Check for ``mock.patch("warnings.warn")``. This can be replaced with
+   ``pytest.warns(match=message)``.
+#. Check the file against https://github.com/astral-sh/ruff , using ``pip install ruff`` ->
+   ``ruff check --select PT <file>``.
+

docs/src/developers_guide/contributing_running_tests.rst

@@ -87,7 +87,7 @@ experimental dependency not being present.
       SKIPPED [1] lib/iris/tests/unit/util/test_demote_dim_coord_to_aux_coord.py:29: Test(s) require external data.
       
    All Python decorators that skip tests will be defined in
-   ``lib/iris/tests/__init__.py`` with a function name with a prefix of
+   ``lib/iris/tests/_shared_utils.py`` with a function name with a prefix of
    ``skip_``.
 
 You can also run a specific test module.  The example below runs the tests for

docs/src/developers_guide/contributing_testing_index.rst

@@ -6,9 +6,9 @@ Testing
 .. toctree::
    :maxdepth: 3
 
-   contributing_testing
-   testing_tools
+   contributing_tests
    contributing_graphics_tests
    contributing_running_tests
    contributing_ci_tests
    contributing_benchmarks
+   contributing_pytest_conversions