feat: add statement and branch coverage percentages to JSON report (#2090)

Ryuta1005 · nedbat · web-flow · commit 557dd15f75bc · 2025-11-18T05:47:34.000-05:00
* feat: add Statement/Branch coverage stats to JSON report

* test: update JSON report tests for Statement/Branch coverage stats

* Docs: Update FAQ for new JSON report metrics

* update the changelog

---------

Co-authored-by: Ned Batchelder &lt;ned@nedbatchelder.com&gt;
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -28,6 +28,9 @@ Unreleased
   Otsuka for the `discussion <issue 2081_>`_ and the `implementation
   <pull 2085_>`_.
 
+- The JSON report now include separate coverage totals for statements and
+  branches, thanks to `Ryuta Otsuka <pull 2090_>`_.
+
 - Fix: ``except*`` clauses were not handled properly under the "sysmon"
   measurement core, causing KeyError exceptions as described in `issue 2086`_.
   This is now fixed.
@@ -47,6 +50,7 @@ Unreleased
 .. _issue 2083: https://github.com/coveragepy/coveragepy/issues/2083
 .. _pull 2085: https://github.com/coveragepy/coveragepy/pull/2085
 .. _issue 2086: https://github.com/coveragepy/coveragepy/issues/2086
+.. _pull 2090: https://github.com/coveragepy/coveragepy/pull/2090
 .. _issue 2091: https://github.com/coveragepy/coveragepy/issues/2091
 
 
diff --git a/coverage/jsonreport.py b/coverage/jsonreport.py
@@ -51,6 +51,8 @@ def make_summary(self, nums: Numbers) -> JsonObj:
             "percent_covered_display": nums.pc_covered_str,
             "missing_lines": nums.n_missing,
             "excluded_lines": nums.n_excluded,
+            "percent_statements_covered": nums.pc_statements,
+            "percent_statements_covered_display": nums.pc_statements_str,
         }
 
     def make_branch_summary(self, nums: Numbers) -> JsonObj:
@@ -60,6 +62,8 @@ def make_branch_summary(self, nums: Numbers) -> JsonObj:
             "num_partial_branches": nums.n_partial_branches,
             "covered_branches": nums.n_executed_branches,
             "missing_branches": nums.n_missing_branches,
+            "percent_branches_covered": nums.pc_branches,
+            "percent_branches_covered_display": nums.pc_branches_str,
         }
 
     def report(self, morfs: Iterable[TMorf] | None, outfile: IO[str]) -> float:
diff --git a/doc/faq.rst b/doc/faq.rst
@@ -116,7 +116,9 @@ did not execute all of their exits.
 
 The :ref:`JSON report <cmd_json>` includes more data that can be used to
 re-calculate the total percentage. Individual files have a ``summary`` key,
-and the report as a whole has a ``totals`` key that include items like these:
+and the report as a whole has a ``totals`` key that include items like these.
+The ``percent_statements_covered`` value is always included, and when branch
+coverage is measured there are matching branch values:
 
 .. code-block:: json
 
@@ -130,7 +132,11 @@ and the report as a whole has a ``totals`` key that include items like these:
         "num_partial_branches": 5,
         "num_statements": 114,
         "percent_covered": 10.76923076923077,
-        "percent_covered_display": "11"
+        "percent_covered_display": "11",
+        "percent_statements_covered": 7.894736842105263,
+        "percent_statements_covered_display": "8",
+        "percent_branches_covered": 31.25,
+        "percent_branches_covered_display": "31"
     }
 
 The total percentage is calculated as::
diff --git a/tests/test_json.py b/tests/test_json.py
@@ -129,6 +129,10 @@ def test_branch_coverage(self) -> None:
                 "missing_branches": 3,
                 "percent_covered": 57.142857142857146,
                 "percent_covered_display": "57",
+                "percent_statements_covered": 62.5,
+                "percent_statements_covered_display": "62",
+                "percent_branches_covered": 50.0,
+                "percent_branches_covered_display": "50",
             },
         }
         expected_result = {
@@ -151,6 +155,10 @@ def test_branch_coverage(self) -> None:
                 "percent_covered_display": "57",
                 "covered_branches": 3,
                 "missing_branches": 3,
+                "percent_statements_covered": 62.5,
+                "percent_statements_covered_display": "62",
+                "percent_branches_covered": 50.0,
+                "percent_branches_covered_display": "50",
             },
         }
         # With regions, a lot of data is duplicated.
@@ -171,6 +179,8 @@ def test_simple_line_coverage(self) -> None:
                 "num_statements": 8,
                 "percent_covered": 62.5,
                 "percent_covered_display": "62",
+                "percent_statements_covered": 62.5,
+                "percent_statements_covered_display": "62",
             },
         }
         expected_result = {
@@ -189,6 +199,8 @@ def test_simple_line_coverage(self) -> None:
                 "num_statements": 8,
                 "percent_covered": 62.5,
                 "percent_covered_display": "62",
+                "percent_statements_covered": 62.5,
+                "percent_statements_covered_display": "62",
             },
         }
         # With regions, a lot of data is duplicated.
@@ -213,6 +225,8 @@ def test_regions_coverage(self) -> None:
                                 "num_statements": 8,
                                 "percent_covered": 87.5,
                                 "percent_covered_display": "88",
+                                "percent_statements_covered": 87.5,
+                                "percent_statements_covered_display": "88",
                             },
                         },
                         "C": {
@@ -226,6 +240,8 @@ def test_regions_coverage(self) -> None:
                                 "num_statements": 0,
                                 "percent_covered": 100.0,
                                 "percent_covered_display": "100",
+                                "percent_statements_covered": 100.0,
+                                "percent_statements_covered_display": "100",
                             },
                         },
                         "D": {
@@ -239,6 +255,8 @@ def test_regions_coverage(self) -> None:
                                 "num_statements": 4,
                                 "percent_covered": 0.0,
                                 "percent_covered_display": "0",
+                                "percent_statements_covered": 0.0,
+                                "percent_statements_covered_display": "0",
                             },
                         },
                     },
@@ -256,6 +274,8 @@ def test_regions_coverage(self) -> None:
                                 "num_statements": 7,
                                 "percent_covered": 100.0,
                                 "percent_covered_display": "100",
+                                "percent_statements_covered": 100.0,
+                                "percent_statements_covered_display": "100",
                             },
                         },
                         "c": {
@@ -269,6 +289,8 @@ def test_regions_coverage(self) -> None:
                                 "num_statements": 1,
                                 "percent_covered": 0.0,
                                 "percent_covered_display": "0",
+                                "percent_statements_covered": 0.0,
+                                "percent_statements_covered_display": "0",
                             },
                         },
                         "D.e": {
@@ -282,6 +304,8 @@ def test_regions_coverage(self) -> None:
                                 "num_statements": 3,
                                 "percent_covered": 0.0,
                                 "percent_covered_display": "0",
+                                "percent_statements_covered": 0.0,
+                                "percent_statements_covered_display": "0",
                             },
                         },
                         "D.f": {
@@ -295,6 +319,8 @@ def test_regions_coverage(self) -> None:
                                 "num_statements": 1,
                                 "percent_covered": 0.0,
                                 "percent_covered_display": "0",
+                                "percent_statements_covered": 0.0,
+                                "percent_statements_covered_display": "0",
                             },
                         },
                     },
@@ -306,6 +332,8 @@ def test_regions_coverage(self) -> None:
                         "num_statements": 12,
                         "percent_covered": 58.333333333333336,
                         "percent_covered_display": "58",
+                        "percent_statements_covered": 58.333333333333336,
+                        "percent_statements_covered_display": "58",
                     },
                 },
             },
@@ -321,6 +349,8 @@ def test_regions_coverage(self) -> None:
                 "num_statements": 12,
                 "percent_covered": 58.333333333333336,
                 "percent_covered_display": "58",
+                "percent_statements_covered": 58.333333333333336,
+                "percent_statements_covered_display": "58",
             },
         }
         self._assert_expected_json_report_with_regions(cov, expected_result)
@@ -348,6 +378,10 @@ def test_branch_regions_coverage(self) -> None:
                                 "num_statements": 8,
                                 "percent_covered": 87.5,
                                 "percent_covered_display": "88",
+                                "percent_statements_covered": 87.5,
+                                "percent_statements_covered_display": "88",
+                                "percent_branches_covered": 100.0,
+                                "percent_branches_covered_display": "100",
                             },
                         },
                         "C": {
@@ -367,6 +401,10 @@ def test_branch_regions_coverage(self) -> None:
                                 "num_statements": 0,
                                 "percent_covered": 100.0,
                                 "percent_covered_display": "100",
+                                "percent_statements_covered": 100.0,
+                                "percent_statements_covered_display": "100",
+                                "percent_branches_covered": 100.0,
+                                "percent_branches_covered_display": "100",
                             },
                         },
                         "D": {
@@ -386,6 +424,10 @@ def test_branch_regions_coverage(self) -> None:
                                 "num_statements": 4,
                                 "percent_covered": 0.0,
                                 "percent_covered_display": "0",
+                                "percent_statements_covered": 0.0,
+                                "percent_statements_covered_display": "0",
+                                "percent_branches_covered": 0.0,
+                                "percent_branches_covered_display": "0",
                             },
                         },
                     },
@@ -410,6 +452,10 @@ def test_branch_regions_coverage(self) -> None:
                                 "num_statements": 7,
                                 "percent_covered": 100.0,
                                 "percent_covered_display": "100",
+                                "percent_statements_covered": 100.0,
+                                "percent_statements_covered_display": "100",
+                                "percent_branches_covered": 100.0,
+                                "percent_branches_covered_display": "100",
                             },
                         },
                         "D.e": {
@@ -429,6 +475,10 @@ def test_branch_regions_coverage(self) -> None:
                                 "num_statements": 3,
                                 "percent_covered": 0.0,
                                 "percent_covered_display": "0",
+                                "percent_statements_covered": 0.0,
+                                "percent_statements_covered_display": "0",
+                                "percent_branches_covered": 0.0,
+                                "percent_branches_covered_display": "0",
                             },
                         },
                         "D.f": {
@@ -448,6 +498,10 @@ def test_branch_regions_coverage(self) -> None:
                                 "num_statements": 1,
                                 "percent_covered": 0.0,
                                 "percent_covered_display": "0",
+                                "percent_statements_covered": 0.0,
+                                "percent_statements_covered_display": "0",
+                                "percent_branches_covered": 100.0,
+                                "percent_branches_covered_display": "100",
                             },
                         },
                         "c": {
@@ -467,6 +521,10 @@ def test_branch_regions_coverage(self) -> None:
                                 "num_statements": 1,
                                 "percent_covered": 0.0,
                                 "percent_covered_display": "0",
+                                "percent_statements_covered": 0.0,
+                                "percent_statements_covered_display": "0",
+                                "percent_branches_covered": 100.0,
+                                "percent_branches_covered_display": "100",
                             },
                         },
                     },
@@ -483,6 +541,10 @@ def test_branch_regions_coverage(self) -> None:
                         "num_statements": 12,
                         "percent_covered": 50.0,
                         "percent_covered_display": "50",
+                        "percent_statements_covered": 58.333333333333336,
+                        "percent_statements_covered_display": "58",
+                        "percent_branches_covered": 0.0,
+                        "percent_branches_covered_display": "0",
                     },
                 },
             },
@@ -502,6 +564,10 @@ def test_branch_regions_coverage(self) -> None:
                 "num_statements": 12,
                 "percent_covered": 50.0,
                 "percent_covered_display": "50",
+                "percent_statements_covered": 58.333333333333336,
+                "percent_statements_covered_display": "58",
+                "percent_branches_covered": 0.0,
+                "percent_branches_covered_display": "0",
             },
         }
         self._assert_expected_json_report_with_regions(cov, expected_result)
@@ -540,6 +606,8 @@ def run_context_test(self, relative_files: bool) -> None:
                 "num_statements": 8,
                 "percent_covered": 62.5,
                 "percent_covered_display": "62.50",
+                "percent_statements_covered": 62.5,
+                "percent_statements_covered_display": "62.50",
             },
         }
         expected_result = {
@@ -558,6 +626,8 @@ def run_context_test(self, relative_files: bool) -> None:
                 "num_statements": 8,
                 "percent_covered": 62.5,
                 "percent_covered_display": "62.50",
+                "percent_statements_covered": 62.5,
+                "percent_statements_covered_display": "62.50",
             },
         }
         # With regions, a lot of data is duplicated.
