From a359bf5c30717ecf48d834c4ff1ccc0c52669a08 Mon Sep 17 00:00:00 2001
From: Jay Fitzgerald <34140133+ni-jfitzger@users.noreply.github.com>
Date: Wed, 27 Sep 2023 17:36:01 -0500
Subject: [PATCH] Update coverage rc files (#2022)

* Add comments to coverage_system_tests.rc

* Add clarity to coverage_unit_tests.rc

* further clarify unit tests coverage

* reorganize unit test omissions

* omit  */nidigital/enums.py from unit test coverage
I don't believe there's anything special about these enums that we shouldn't just fall back on nifake unit test coverage

* Explain */niscope/measurement_stat.py omission

* add pb2 omissions

* Add grpc_session_options.py omissions

* Omit history_ram_cycle_information.py from unit tests

* Don't omit session.py from system test coverage

* Remove mention of session.py in coverage_system_tests.rc omit list
---
 tools/coverage_system_tests.rc | 15 ++++++-
 tools/coverage_unit_tests.rc   | 73 +++++++++++++++++++++++-----------
 2 files changed, 62 insertions(+), 26 deletions(-)

diff --git a/tools/coverage_system_tests.rc b/tools/coverage_system_tests.rc
index 477c877d0..9398eeae8 100644
--- a/tools/coverage_system_tests.rc
+++ b/tools/coverage_system_tests.rc
@@ -1,12 +1,23 @@
+; This file controls what modules are examined for code coverage in our system tests.
+
 [run]
 omit =
+    ; Common code, so covered by nifake unit tests.
+    ; Some modules don't even exercise all of _attributes.py and _converters.py, making parts unreachable in system tests.
     */__init__.py
     */_attributes.py
     */_converters.py
+    */errors.py
     */_library_singleton.py
     */_visatype.py
+
+    ; Although the enum names and values vary between modules, all enums are mostly the same. nifake unit tests cover the various kinds that we use.
     */enums.py
-    */errors.py
-    */session.py
 
+    ; Most of the lines in *_pb2.py are only used for the pure-Python implementation of protobuf, and the default implementation nowadays is the upb C implementation.
+    */*pb2.py
+
+    ; *_pb2_grpc.py defines a stub, a servicer, and an "experimental API", and we only use the stub.
+    ; If our system test coverage of the stub_interpreter is okay, we should be in good shape.
+    */*_pb2_grpc.py
 
diff --git a/tools/coverage_unit_tests.rc b/tools/coverage_unit_tests.rc
index eccc5febe..4e3ca2d4c 100644
--- a/tools/coverage_unit_tests.rc
+++ b/tools/coverage_unit_tests.rc
@@ -1,35 +1,60 @@
+; This file controls what modules are examined for code coverage in our unit tests.
+; See https://coverage.readthedocs.io/en/latest/source.html#source
+
 [run]
+; Fileset is restricted to include matches, first
+; Unfortunately, all of these patterns will be ignored, because we pass --source, when running the unit tests.
+include =
+    ; nifake is tested entirely by unit tests. Its sole purpose is to test code that is common to all APIs
+    */nifake/*
+    ; System testing is preferred, but some published modules have code that's easier to test with a unit test
+    */nidcpower/lcr_load_compensation_spot.py
+    */nidcpower/lcr_measurement.py
+    */nidigital/session.py
+    */nimodinst/session.py
+    */niscope/waveform_info.py
+    */nitclk/session.py
+    build/*
+; Any include matches that match omit patterns are removed
 omit =
+    ; Covered by system tests
     */_library*
+
+    ; Everthing below here needs to be explicitly excluded because "include" is ignored.
+
+    ; All private modules are covered by nifake unit tests, except for interpreter modules, which are covered by system tests.
     */nidcpower/_*
+    */nidigital/_*
+    */nimodinst/_*
+    */niscope/_*
+    */nitclk/_*
+
+    ; Common code, so covered by nifake unit tests
     */nidcpower/enums.py
     */nidcpower/errors.py
-    */nidcpower/session.py
-    */nidigital/__init__.py
-    */nidigital/_attributes.py
-    */nidigital/_converters.py
-    */nidigital/_visatype.py
+    */nidigital/enums.py
     */nidigital/errors.py
-    */nimodinst/__init__.py
-    */nimodinst/_converters.py
-    */nimodinst/_visatype.py
     */nimodinst/errors.py
-    */niscope/_*
     */niscope/enums.py
     */niscope/errors.py
-    */niscope/measurement_stats.py
-    */niscope/session.py
-    */nitclk/__init__.py
-    */nitclk/_attributes.py
-    */nitclk/_converters.py
-    */nitclk/_visatype.py
     */nitclk/errors.py
-include =
-    */nifake/*
-    */nidcpower/lcr_load_compensation_spot.py
-    */nidcpower/lcr_measurement.py
-    */nidigital/session.py
-    */nimodinst/session.py
-    */niscope/waveform_info.py
-    */nitclk/session.py
-    build/*
+
+    ; See the include section; these modules don't have unit tests covering session.py
+    */nidcpower/session.py
+    */niscope/session.py
+
+    ; Covered by System tests
+    */nidigital/history_ram_cycle_information.py
+    */niscope/measurement_stats.py
+
+    ; Most of the lines in *_pb2.py are only used for the pure-Python implementation of protobuf, and the default implementation nowadays is the upb C implementation.
+    */*pb2.py
+
+    ; *_pb2_grpc.py defines a stub, a servicer, and an "experimental API", and we only use the stub.
+    ; If our system test coverage of the stub_interpreter is okay, we should be in good shape.
+    */*_pb2_grpc.py
+
+    ; grpc_session_options.py is tested by system tests and nifake unit tests
+    */nidcpower/grpc_session_options.py
+    */nidigital/grpc_session_options.py
+    */niscope/grpc_session_options.py