Coverage formatter fix (#635)

Author: connectdotz

CHANGELOG.md

@@ -6,6 +6,7 @@ Bug-fixes within the same version aren't needed
 ## Master
 
 * use assertion's fullName in TestResult instead of the source test name - @connectdotz
+* consolidated and simplified coverage formatter parsing logic; added overlay color customization; change coverage formatter/colors will take effect without restarting vscode; updated coverage help in README. - @connectdotz
 -->
 
 ### 4.0.0-alpha.1

README.md

@@ -15,9 +15,11 @@ Content
   - [How to start Jest?](#how-to-start-jest)
   - [How do I debug tests?](#how-do-i-debug-tests)
     - [Notes for troubleshooting](#notes-for-troubleshooting)
-  - [How do I show code coverage?](#how-do-i-show-code-coverage)
+  - [Coverage](#coverage)
+    - [How do I show code coverage?](#how-do-i-show-code-coverage)
+    - [How to customize coverage overlay](#how-to-customize-coverage-overlay)
+    - [Understand the coverage overlay](#understand-the-coverage-overlay)
   - [Inspiration](#inspiration)
-  - [Wanted](#wanted)
   - [Troubleshooting](#troubleshooting)
     - [start jest from non-root folder](#start-jest-from-non-root-folder)
     - [use extension in multiroot environment](#use-extension-in-multiroot-environment)
@@ -93,7 +95,8 @@ Starting with debugging is possible by clicking on the `debug` CodeLense above a
 In contrast to previous versions of this plugin the debug settings are now independent from VS Code's `jest.pathToJest` and `jest.pathToConfig` setting. If you had to modify one of these, you pretty surely have to create a custom debug configuration and modify its path. This especially includes cases, in which `jest` isn't at its default location.
 
 
-## How do I show code coverage?
+## Coverage
+### How do I show code coverage?
 
 Starting from [v3.1](https://github.com/jest-community/vscode-jest/releases/tag/v3.1.0), code coverage can be easily turned on/off at runtime without customization. 
 
@@ -105,29 +108,48 @@ The coverage mode, along with watch mode, are shown in StatusBar:
 
 _(The initial coverage mode is `off` but can be changed by adding `"jest.showCoverageOnLoad": true` in settings.)_ 
 
-<!--
-### TODO: Change overlay format
-Use a setting that's one of "", "", etc.
-```json
-{
-    "jest.?": ""
-}
-```
 
-Screenshots:
-* Default
-* Gutters
--->
+### How to customize coverage overlay
+Coverage overlay determines how the coverage info is shown to users. This extension provides 2 customization points: 
+1. coverage style via `jest.coverageFormatter` 
+2. the coverage color scheme via `jest.coverageColors`.
 
-## Inspiration
+**Coverage Style**
+Use `jest.coverageFormatter` to choose from the following, for example `"jest.coverageFormatter": "GutterFormatter"`. 
 
-I'd like to give a shout out to [Wallaby.js](https://wallabyjs.com), which is a significantly more comprehensive and covers a lot more editors, if this extension interests you - check out that too.
+- **DefaultFormatter**: high light uncovered and partially-covered code inlilne as well as on the right overview ruler. (this is the default)
+![coverage-DefaultFormatter.png](./images/coverage-DefaultFormatter.png)
+- **GutterFormatter**: render coverage status in the gutter as well as the overview ruler. 
 
+![coverage-GutterFormatter.png](./images/coverage-GutterFormatter.png)
 
-## Wanted
+  _(Note, there is an known issue in vscode (microsoft/vscode#5923) that gutter decorators could interfere with debug breakpoints visibility. Therefore, you probably want to disable coverage before debugging or switch to DefaultFormatter)_
 
-Someone to take responsibility for ensuring that the default setup for create-react-app is always working. All the current authors use TypeScript and React/React Native and so have very little familiarity with changes to CRA. _Apply via PRs :D_.
+**Coverage Colors**
+Besides the formatter, user can also customize the color via `jest.coverageColors` to change color for 3 coverage categories: `"uncovered", "covered", or "partially-covered"`, for example:
+```
+  "jest.coverageColors": {
+    "uncovered": "rgba(255,99,71, 0.2)",
+    "partially-covered": "rgba(255,215,0, 0.2)",
+  }
+```
+the default color scheme below, note the opacity might differ per formatter:
+```
+"jest.coverageColors": {
+    "covered": "rgba(9, 156, 65, 0.4)",
+    "uncovered": "rgba(121, 31, 10, 0.4)",
+    "partially-covered": "rgba(235, 198, 52, 0.4)",
+  }
+```
+### Understand the coverage overlay
+Depends on the formatter you choose, there are 3 types of coverage you might see in your source code, distinguished by colors:
+- "covered": if the code is covered. Marked as <span style="color:green">"green"</span> by default. 
+- "not-covered": if the code is not covered. Marked as <span style="color:red">"red"</span> by default.
+- "partially-covered": Usually this mean the branch (such as if, switch statements) only partially tested. Marked as <span style="color:yellow">"yellow"</span> by default.
+  - _Please note, istanbuljs (the library jest used to generate coverage info) reports switch branch coverage with the first "case" statement instead of the "switch" statement._
+## Inspiration
 
+I'd like to give a shout out to [Wallaby.js](https://wallabyjs.com), which is a significantly more comprehensive and covers a lot more editors, if this extension interests you - check out that too.
 
 ## Troubleshooting
 

images/coverage-DefaultFormatter.png

@@ -123,6 +123,11 @@
           "default": "DefaultFormatter",
           "scope": "resource"
         },
+        "jest.coverageColors": {
+          "description": "Coverage indicator color override",
+          "type": "object",
+          "scope": "resource"
+        },
         "jest.enableCodeLens": {
           "description": "Whether codelens for debugging should show",
           "type": "boolean",

images/coverage-GutterFormatter.png

@@ -5,6 +5,11 @@ import { GutterFormatter } from './Formatters/GutterFormatter';
 import * as vscode from 'vscode';
 import { hasDocument } from '../editor';
 
+export type CoverageStatus = 'covered' | 'partially-covered' | 'uncovered';
+export type CoverageColors = {
+  [key in CoverageStatus]?: string;
+};
+
 export class CoverageOverlay {
   static readonly defaultVisibility = false;
   static readonly defaultFormatter = 'DefaultFormatter';
@@ -15,21 +20,22 @@ export class CoverageOverlay {
     context: vscode.ExtensionContext,
     coverageMapProvider: CoverageMapProvider,
     enabled: boolean = CoverageOverlay.defaultVisibility,
-    coverageFormatter: string = CoverageOverlay.defaultFormatter
+    coverageFormatter: string = CoverageOverlay.defaultFormatter,
+    colors?: CoverageColors
   ) {
     this._enabled = enabled;
     switch (coverageFormatter) {
       case 'GutterFormatter':
-        this.formatter = new GutterFormatter(context, coverageMapProvider);
+        this.formatter = new GutterFormatter(context, coverageMapProvider, colors);
         break;
 
       default:
-        this.formatter = new DefaultFormatter(coverageMapProvider);
+        this.formatter = new DefaultFormatter(coverageMapProvider, colors);
         break;
     }
   }
 
-  get enabled() {
+  get enabled(): boolean {
     return this._enabled;
   }
 
@@ -38,18 +44,23 @@ export class CoverageOverlay {
     this.updateVisibleEditors();
   }
 
-  toggleVisibility() {
+  /** give formatter opportunity to dispose the decorators */
+  dispose(): void {
+    this.formatter.dispose();
+  }
+
+  toggleVisibility(): void {
     this._enabled = !this._enabled;
     this.updateVisibleEditors();
   }
 
-  updateVisibleEditors() {
+  updateVisibleEditors(): void {
     for (const editor of vscode.window.visibleTextEditors) {
       this.update(editor);
     }
   }
 
-  update(editor: vscode.TextEditor) {
+  update(editor: vscode.TextEditor): void {
     if (!hasDocument(editor)) {
       return;
     }

package.json

@@ -1,13 +1,113 @@
 import { CoverageMapProvider } from '../CoverageMapProvider';
 import * as vscode from 'vscode';
+import { CoverageColors, CoverageStatus } from '../CoverageOverlay';
+import { FileCoverage } from 'istanbul-lib-coverage';
 
+export type CoverageRanges = {
+  [status in CoverageStatus]?: vscode.Range[];
+};
+
+type FunctionCoverageByLine = { [line: number]: number };
 export abstract class AbstractFormatter {
   protected coverageMapProvider: CoverageMapProvider;
+  protected colors?: CoverageColors;
 
-  constructor(coverageMapProvider: CoverageMapProvider) {
+  constructor(coverageMapProvider: CoverageMapProvider, colors?: CoverageColors) {
     this.coverageMapProvider = coverageMapProvider;
+    this.colors = colors;
   }
 
   abstract format(editor: vscode.TextEditor);
+  /** remove decoractors for the given editor */
   abstract clear(editor: vscode.TextEditor);
+  /** dispose decoractors for all editors */
+  abstract dispose();
+
+  /**
+   * returns rgba color string similar to istanbul html report color scheme
+   * @param status
+   * @param opacity
+   */
+  getColorString(status: CoverageStatus, opacity: number): string {
+    if (opacity > 1 || opacity < 0) {
+      throw new Error(`invalid opacity (${opacity}): value is not between 0 - 1`);
+    }
+
+    switch (status) {
+      case 'covered':
+        return this.colors?.[status] ?? `rgba(9, 156, 65, ${opacity})`; // green
+      case 'partially-covered':
+        return this.colors?.[status] ?? `rgba(235, 198, 52, ${opacity})`; // yellow
+      case 'uncovered':
+        return this.colors?.[status] ?? `rgba(121, 31, 10, ${opacity})`; // red
+      default:
+        throw new Error(`unrecognized status: ${status}`);
+    }
+  }
+
+  private getFunctionCoverageByLine(fileCoverage: FileCoverage): FunctionCoverageByLine {
+    const lineCoverage: FunctionCoverageByLine = {};
+    Object.entries(fileCoverage.fnMap).forEach(([k, { decl }]) => {
+      const hits = fileCoverage.f[k];
+      for (let idx = decl.start.line; idx <= decl.end.line; idx++) {
+        lineCoverage[idx] = hits;
+      }
+    });
+    return lineCoverage;
+  }
+  /**
+   * mapping the coverage map to a line-based coverage ranges
+   * @param editor
+   */
+  lineCoverageRanges(
+    editor: vscode.TextEditor,
+    onNoCoverageInfo?: () => CoverageStatus
+  ): CoverageRanges {
+    const ranges: CoverageRanges = {};
+    const fileCoverage = this.coverageMapProvider.getFileCoverage(editor.document.fileName);
+    if (!fileCoverage) {
+      return ranges;
+    }
+    const lineCoverage = fileCoverage.getLineCoverage();
+    const branchCoveravge = fileCoverage.getBranchCoverageByLine();
+    const funcCoverage = this.getFunctionCoverageByLine(fileCoverage);
+
+    // consolidate the coverage by line
+    for (let line = 1; line <= editor.document.lineCount; line++) {
+      const zeroBasedLineNumber = line - 1;
+      const lc = lineCoverage[line];
+      const bc = branchCoveravge[line];
+      const fc = funcCoverage[line];
+      let status: CoverageStatus;
+      if (fc != null) {
+        status = fc > 0 ? 'covered' : 'uncovered';
+      } else if (bc != null) {
+        switch (bc.coverage) {
+          case 100:
+            status = 'covered';
+            break;
+          case 0:
+            status = 'uncovered';
+            break;
+          default:
+            status = 'partially-covered';
+            break;
+        }
+      } else if (lc != null) {
+        status = lc > 0 ? 'covered' : 'uncovered';
+      } else if (onNoCoverageInfo) {
+        status = onNoCoverageInfo();
+      } else {
+        continue;
+      }
+
+      const range = new vscode.Range(zeroBasedLineNumber, 0, zeroBasedLineNumber, 0);
+      if (ranges[status] != null) {
+        ranges[status].push(range);
+      } else {
+        ranges[status] = [range];
+      }
+    }
+    return ranges;
+  }
 }

src/Coverage/CoverageOverlay.ts

@@ -1,78 +1,40 @@
 import { AbstractFormatter } from './AbstractFormatter';
 import * as vscode from 'vscode';
-import { FileCoverage } from 'istanbul-lib-coverage';
-import { isValidLocation } from './helpers';
-
-const uncoveredBranch = vscode.window.createTextEditorDecorationType({
-  backgroundColor: 'rgba(216,134,123,0.4)',
-  overviewRulerColor: 'rgba(216,134,123,0.8)',
-  overviewRulerLane: vscode.OverviewRulerLane.Left,
-});
-
-const uncoveredLine = vscode.window.createTextEditorDecorationType({
-  isWholeLine: true,
-  backgroundColor: 'rgba(216,134,123,0.4)',
-  overviewRulerColor: 'rgba(216,134,123,0.8)',
-  overviewRulerLane: vscode.OverviewRulerLane.Left,
-});
+import { CoverageMapProvider } from '../CoverageMapProvider';
+import { CoverageColors } from '../CoverageOverlay';
 
 export class DefaultFormatter extends AbstractFormatter {
-  format(editor: vscode.TextEditor) {
-    const fileCoverage = this.coverageMapProvider.getFileCoverage(editor.document.fileName);
-    if (!fileCoverage) {
-      return;
-    }
-
-    this.formatBranches(editor, fileCoverage);
-    this.formatUncoveredLines(editor, fileCoverage);
-  }
-
-  formatBranches(editor: vscode.TextEditor, fileCoverage: FileCoverage) {
-    const ranges = [];
-
-    Object.keys(fileCoverage.b).forEach((branchIndex) => {
-      fileCoverage.b[branchIndex].forEach((hitCount, locationIndex) => {
-        if (hitCount > 0) {
-          return;
-        }
-
-        const branch = fileCoverage.branchMap[branchIndex].locations[locationIndex];
-        if (!isValidLocation(branch)) {
-          return;
-        }
-
-        // If the value is `null`, then set it to the first character on its
-        // line.
-        const endColumn = branch.end.column || 0;
-
-        ranges.push(
-          new vscode.Range(
-            branch.start.line - 1,
-            branch.start.column,
-            branch.end.line - 1,
-            endColumn
-          )
-        );
-      });
+  readonly uncoveredLine: vscode.TextEditorDecorationType;
+  readonly partiallyCoveredLine: vscode.TextEditorDecorationType;
+
+  constructor(coverageMapProvider: CoverageMapProvider, colors?: CoverageColors) {
+    super(coverageMapProvider, colors);
+    this.partiallyCoveredLine = vscode.window.createTextEditorDecorationType({
+      isWholeLine: true,
+      backgroundColor: this.getColorString('partially-covered', 0.4),
+      overviewRulerColor: this.getColorString('partially-covered', 0.8),
+      overviewRulerLane: vscode.OverviewRulerLane.Left,
+    });
+    this.uncoveredLine = vscode.window.createTextEditorDecorationType({
+      isWholeLine: true,
+      backgroundColor: this.getColorString('uncovered', 0.4),
+      overviewRulerColor: this.getColorString('uncovered', 0.8),
+      overviewRulerLane: vscode.OverviewRulerLane.Left,
     });
-
-    editor.setDecorations(uncoveredBranch, ranges);
   }
 
-  formatUncoveredLines(editor: vscode.TextEditor, fileCoverage: FileCoverage) {
-    const lines = fileCoverage.getUncoveredLines();
-
-    const ranges = [];
-    for (const oneBasedLineNumber of lines) {
-      const zeroBasedLineNumber = Number(oneBasedLineNumber) - 1;
-      ranges.push(new vscode.Range(zeroBasedLineNumber, 0, zeroBasedLineNumber, 0));
-    }
-
-    editor.setDecorations(uncoveredLine, ranges);
+  format(editor: vscode.TextEditor): void {
+    const coverageRanges = this.lineCoverageRanges(editor);
+    editor.setDecorations(this.uncoveredLine, coverageRanges['uncovered'] ?? []);
+    editor.setDecorations(this.partiallyCoveredLine, coverageRanges['partially-covered'] ?? []);
   }
 
-  clear(editor: vscode.TextEditor) {
-    editor.setDecorations(uncoveredLine, []);
-    editor.setDecorations(uncoveredBranch, []);
+  clear(editor: vscode.TextEditor): void {
+    editor.setDecorations(this.uncoveredLine, []);
+    editor.setDecorations(this.partiallyCoveredLine, []);
+  }
+  dispose(): void {
+    this.partiallyCoveredLine.dispose();
+    this.uncoveredLine.dispose();
   }
 }