From 9a3b2f0a5c758374208680fe715328a45fa068a1 Mon Sep 17 00:00:00 2001
From: Peter Bittner <django@bittner.it>
Date: Sun, 11 Feb 2024 17:08:01 +0100
Subject: [PATCH] Explain how to use `coverage run` (docs)

Fixes #152
---
 docs/testcoverage.rst | 117 +++++++++++++++++++++++++++---------------
 1 file changed, 75 insertions(+), 42 deletions(-)

diff --git a/docs/testcoverage.rst b/docs/testcoverage.rst
index 3c245f9..ffba2db 100644
--- a/docs/testcoverage.rst
+++ b/docs/testcoverage.rst
@@ -1,21 +1,50 @@
 Test Coverage
 =============
 
-You can integrate Coverage.py with behave-django to find out the test coverage of your code.
+You can integrate `Coverage.py`_ with behave-django to find out the test coverage
+of your code.
 
-Dependencies
-------------
+There are two ways to do this.  The simple (and obvious one) is via invocation
+through the ``coverage`` CLI.  Alternatively, you can integrate Coverage in the
+``environment.py`` file of your BDD test setup as shown below.
 
-At First, you should install Coverage.py dependency
+Prerequisites
+-------------
+
+Obviously, you need to install Coverage to measure code coverage, e.g.
+
+.. code-block:: bash
+
+    $ pip install coverage[toml]
+
+Invoke via ``coverage``
+-----------------------
+
+Instead of using ``python manage.py``, you simply use
+``coverage run manage.py`` to invoke your BDD tests, e.g.
 
 .. code-block:: bash
 
-    $ pip install coverage
+    $ coverage run manage.py behave
+
+Afterwards, you can display a coverage report in your terminal to understand
+which lines your tests are missing, e.g.
+
+.. code-block:: bash
+
+    $ coverage report --show-missing
+
+.. tip::
+
+    A Django project setup with coverage configured in ``pyproject.toml`` and
+    executed by Tox is show-cased in the `Painless CI/CD Copier template for
+    Django`_.
 
-Environment.py
---------------
+Integrate via ``environment.py``
+--------------------------------
 
-In ``environment.py``, add the code snippet below in the ``before_all`` function to start measuring test coverage:
+In ``environment.py``, add the code snippet below in the ``before_all`` function
+to start measuring test coverage:
 
 .. code-block:: python
 
@@ -37,50 +66,54 @@ You can save the coverage result on html format.
         cov.save()
         cov.html_report(directory="./cov")
 
-
 You can check the test coverage on the web with the following command.
 
 .. code-block:: bash
 
     $ python -m http.server --directory ./cov
-    
-Warning for behave-django
--------------------------
 
-Internally, the time before_all is executed seems to be later than the time when django loads the modules set in each app.
+.. warning::
 
-So sometimes it is necessary to reload django app's modules for accurate test coverage measurement.
+    Internally, the time ``before_all`` is executed seems to be later than the
+    time when django loads the modules set in each app.
 
-Like this:
+    So sometimes it is necessary to reload django app's modules for accurate
+    test coverage measurement.
 
-.. code-block:: python
+    Like this:
 
-    import inspect
-    import importlib
-    
-    def reload_modules():
-      import your_app1
-      import your_app2
-
-      for app in [your_app1, your_app2]:
-          members = inspect.getmembers(app)
-          modules = map(
-              lambda keyval: keyval[1],
-              filter(lambda keyval: inspect.ismodule(keyval[1]), members),
-          )
-          for module in modules:
-              try:
-                  importlib.reload(module)
-              except:
-                  continue
+    .. code-block:: python
 
-.. code-block:: python
+        import inspect
+        import importlib
 
-    def before_all(context):
-      # cov
-      cov = coverage.Coverage()
-      cov.start()
-      context.cov = cov
+        def reload_modules():
+        import your_app1
+        import your_app2
+
+        for app in [your_app1, your_app2]:
+            members = inspect.getmembers(app)
+            modules = map(
+                lambda keyval: keyval[1],
+                filter(lambda keyval: inspect.ismodule(keyval[1]), members),
+            )
+            for module in modules:
+                try:
+                    importlib.reload(module)
+                except:
+                    continue
+
+    .. code-block:: python
+
+        def before_all(context):
+        # cov
+        cov = coverage.Coverage()
+        cov.start()
+        context.cov = cov
+
+        # modules
+        reload_modules()
 
-      # modules
-      reload_modules()
+.. _Coverage.py: https://coverage.readthedocs.io/
+.. _Painless CI/CD Copier template for Django:
+    https://gitlab.com/painless-software/cicd/app/django