updated unit test related terms

doc/source/ch06_unittest.rst

@@ -18,29 +18,50 @@ Here we show an example unit test on ``csst_proto.top_level_interface.flip_image
 Run unit tests
 --------------
 
-To run unit tests
+Unit tests should be based on the standard library ``unittest``,
+while ``doctest`` is not recommended and should not be used.
+The import mode we use here is ``importlib``.
+Several packages should be installed before you run unit tests.
+They are
 
-.. code-block:: bash
-
-    pytest --import-mode=importlib
+- ``pytest``: a tool to collect unit tests and run them
+- ``coverage``: coverage statistics
+- ``pytest-cov``: a plugin to provide ``--cov`` parameter for ``pytest``
 
-To run unit tests with coverage
+To run unit tests collected from directory ``.``, and calculate coverage for source code in directory ``csst_proto``,
 
 .. code-block:: bash
 
-    coverage run -m pytest --import-mode=importlib
+    coverage run -m pytest --cov=csst_proto . --import-mode=importlib --cov-report=html --cov-report=term-missing
 
-To display the coverage report
+You will see messages like below
 
-.. code-block:: bash
+.. code-block:: plain
 
-    coverage report
+    ============================ test session starts ============================
+    platform darwin -- Python 3.9.7, pytest-7.1.3, pluggy-0.13.1
+    rootdir: /Users/cham/CsstProjects/csst_proto
+    plugins: anyio-2.2.0, asdf-2.13.0, cov-4.0.0
+    collected 4 items
 
-To generate the coverage report in html format
+    tests/test_demos.py .                                                 [ 25%]
+    tests/test_flip_image.py ...                                          [100%]
+
+    ---------- coverage: platform darwin, python 3.9.7-final-0 -----------
+    Name                                Stmts   Miss  Cover   Missing
+    -----------------------------------------------------------------
+    csst_proto/__init__.py                  3      0   100%
+    csst_proto/demo.py                      8      3    62%   56-57, 60
+    csst_proto/flip_image.py               21      0   100%
+    csst_proto/top_level_interface.py       3      0   100%
+    -----------------------------------------------------------------
+    TOTAL                                  35      3    91%
+    Coverage HTML written to dir htmlcov
+
+    ============================= 4 passed in 0.73s =============================
 
-.. code-block:: bash
 
-    coverage html
+The coverage info is shown, and a coverage report in html format will be generated in directory ``htmlcov``.
 
 .. _unittest: https://docs.python.org/3.9/library/unittest.html
 .. _doctest: https://docs.python.org/3.9/library/doctest.html

doc/source/ch09_build.rst

@@ -67,7 +67,7 @@ The build log includes 6 sections.
 An example of test summary is at the end of build log (the attached ``build.zip``).
 If all checks/tests/validations passed, you will see a section as below.
 
-.. code-block::
+.. code-block:: plain
 
     ===================== TEST SUMMARY =====================
     Test passed!
@@ -85,20 +85,21 @@ Unit test coverage report
 The ``build log`` also contains a section of unit test coverage report.
 An example is below.
 
-.. code-block::
+.. code-block:: plain
 
-    Name                                Stmts   Miss  Cover
-    -------------------------------------------------------
+    ---------- coverage: platform darwin, python 3.9.7-final-0 -----------
+    Name                                Stmts   Miss  Cover   Missing
+    -----------------------------------------------------------------
     csst_proto/__init__.py                  3      0   100%
-    csst_proto/demo.py                      8      3    62%
-    csst_proto/flip_image.py               13      0   100%
+    csst_proto/demo.py                      8      3    62%   56-57, 60
+    csst_proto/flip_image.py               21      0   100%
     csst_proto/top_level_interface.py       3      0   100%
-    tests/test_demos.py                     5      0   100%
-    tests/test_flip_image.py                8      0   100%
-    -------------------------------------------------------
-    TOTAL                                  40      3    92%
+    -----------------------------------------------------------------
+    TOTAL                                  35      3    91%
 
-This means the overall unit test coverage is 92%.
+
+This means the overall unit test coverage is 91%.
+The missing terms are also shown in the last column.
 You can also find a detailed coverage report in ``html`` format in the attached ``htmlcov.zip``.