From e05a56ed196250ecc156689e0ccc304b995a02fa Mon Sep 17 00:00:00 2001
From: Katerina Pilatova <katerina.pilatova@flowup.cz>
Date: Mon, 5 Feb 2024 18:27:10 +0100
Subject: [PATCH] docs(plugin-coverage): improve audit descriptions

---
 e2e/cli-e2e/tests/__snapshots__/collect.e2e.test.ts.snap | 6 +++---
 packages/plugin-coverage/README.md                       | 6 ++++++
 packages/plugin-coverage/src/lib/coverage-plugin.ts      | 4 ++--
 packages/plugin-coverage/src/lib/utils.ts                | 8 ++++++++
 4 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/e2e/cli-e2e/tests/__snapshots__/collect.e2e.test.ts.snap b/e2e/cli-e2e/tests/__snapshots__/collect.e2e.test.ts.snap
index 351634960..2e0fac472 100644
--- a/e2e/cli-e2e/tests/__snapshots__/collect.e2e.test.ts.snap
+++ b/e2e/cli-e2e/tests/__snapshots__/collect.e2e.test.ts.snap
@@ -33,7 +33,7 @@ exports[`CLI collect > should run Code coverage plugin and create report.json 1`
     {
       "audits": [
         {
-          "description": "Branch coverage percentage on the project.",
+          "description": "Measures how many branches were executed after conditional statements in at least one test.",
           "details": {
             "issues": [
               {
@@ -85,7 +85,7 @@ exports[`CLI collect > should run Code coverage plugin and create report.json 1`
           "value": 76,
         },
         {
-          "description": "Function coverage percentage on the project.",
+          "description": "Measures how many functions were called in at least one test.",
           "details": {
             "issues": [
               {
@@ -117,7 +117,7 @@ exports[`CLI collect > should run Code coverage plugin and create report.json 1`
           "value": 60,
         },
         {
-          "description": "Line coverage percentage on the project.",
+          "description": "Measures how many lines of code were executed in at least one test.",
           "details": {
             "issues": [
               {
diff --git a/packages/plugin-coverage/README.md b/packages/plugin-coverage/README.md
index 90699a576..956d3822e 100644
--- a/packages/plugin-coverage/README.md
+++ b/packages/plugin-coverage/README.md
@@ -75,6 +75,12 @@ Measured coverage types are mapped to Code PushUp audits in the following way
 
 Code coverage is a metric that indicates what percentage of source code is executed by unit tests. It can give insights into test effectiveness and uncover parts of source code that would otherwise go untested.
 
+- Statement coverage: Measures how many statements are executed in at least one test.
+- Line coverage: Measures how many lines are executed in at least one test. Unlike statement coverage, any partially executed line counts towards line coverage.
+- Condition coverage: Measures all condition values (`true`/`false`) evaluated for a conditional statement in at least one test.
+- Branch coverage: Measures how many branches are executed as a result of conditional statements (`if`/`else` and other) in at least one test. In case of short-circuit logic, only executed paths are counted in. Unlike condition coverage, it does not ensure all combinations of condition values are tested.
+- Function coverage: Measures how many functions are called in at least one test. Argument values, usage of optional arguments or default values is irrelevant for this metric.
+
 > [!IMPORTANT]
 > Please note that code coverage is not the same as test coverage. Test coverage measures the amount of acceptance criteria covered by tests and is hard to formally verify. This means that code coverage cannot guarantee that the designed software caters to the business requirements.
 
diff --git a/packages/plugin-coverage/src/lib/coverage-plugin.ts b/packages/plugin-coverage/src/lib/coverage-plugin.ts
index 56fc9af3d..f769f101a 100644
--- a/packages/plugin-coverage/src/lib/coverage-plugin.ts
+++ b/packages/plugin-coverage/src/lib/coverage-plugin.ts
@@ -10,7 +10,7 @@ import { capitalize, pluginWorkDir } from '@code-pushup/utils';
 import { name, version } from '../../package.json';
 import { CoveragePluginConfig, coveragePluginConfigSchema } from './config';
 import { lcovResultsToAuditOutputs } from './runner/lcov/runner';
-import { applyMaxScoreAboveThreshold } from './utils';
+import { applyMaxScoreAboveThreshold, coverageDescription } from './utils';
 
 export const RUNNER_OUTPUT_PATH = join(
   pluginWorkDir('coverage'),
@@ -43,7 +43,7 @@ export function coveragePlugin(config: CoveragePluginConfig): PluginConfig {
     (type): Audit => ({
       slug: `${type}-coverage`,
       title: `${capitalize(type)} coverage`,
-      description: `${capitalize(type)} coverage percentage on the project.`,
+      description: coverageDescription[type],
     }),
   );
 
diff --git a/packages/plugin-coverage/src/lib/utils.ts b/packages/plugin-coverage/src/lib/utils.ts
index b9df7c1c0..723915384 100644
--- a/packages/plugin-coverage/src/lib/utils.ts
+++ b/packages/plugin-coverage/src/lib/utils.ts
@@ -1,4 +1,12 @@
 import type { AuditOutputs } from '@code-pushup/models';
+import { CoverageType } from './config';
+
+export const coverageDescription: Record<CoverageType, string> = {
+  branch:
+    'Measures how many branches were executed after conditional statements in at least one test.',
+  line: 'Measures how many lines of code were executed in at least one test.',
+  function: 'Measures how many functions were called in at least one test.',
+};
 
 /**
  * Since more code coverage does not necessarily mean better score, this optional override allows for defining custom coverage goals.