Deep Jest / Vitest coverage analysis

Companion reference for js-unit-tests Step 5. Consult when the team needs PR-time coverage signal that is both local-runnable and CI-gateable: provider choice, reporter selection for downstream consumers, per-file coverageThreshold rules, and parsing the per-file JSON output.

Pick the provider

Per jest-config (opens in new window), on coverageProvider:

"Indicates which provider should be used to instrument code for coverage. Allowed values are babel (default) or v8."

/** @type {import('jest').Config} */
module.exports = {
  coverageProvider: 'v8',   // or 'babel'
};

Each provider has a different ignore-comment syntax (jest-config (opens in new window)): babel uses /* istanbul ignore next */, v8 uses /* c8 ignore next */. Don't mix; switching providers requires updating ignore comments across the codebase.

Choose coverageReporters

Per jest-config (opens in new window), "Any istanbul reporter can be used." Defaults are ["clover", "json", "lcov", "text"]. The useful ones:

Pragmatic default for a CI + SaaS + local-dev setup:

coverageReporters: ['lcov', 'json', 'text-summary', 'html']

Per-file thresholds (the gate-correctness pattern)

Per jest-config (opens in new window), coverageThreshold accepts global, glob, or path-specific rules:

coverageThreshold: {
  global: { branches: 50, functions: 50, lines: 50, statements: 50 },
  './src/components/': { branches: 40, statements: 40 },
  './src/reducers/**/*.js': { statements: 90 },
  './src/api/very-important-module.js': {
    branches: 100, functions: 100, lines: 100, statements: 100,
  },
},

The pattern is lower the global, raise the critical paths. A 50% global keeps refactors flowing; a 100% per-file rule on a payment-processing module catches any drop immediately.

"Jest will fail if thresholds aren't met." (jest-config (opens in new window))

"Negative numbers = maximum uncovered entities allowed."

The negative-number form suits legacy modules: statements: -10 allows up to 10 uncovered statements, letting the team ratchet down over time without an aspirational percentage.

Verify the gate fires: run npx jest --coverage with a critical-path file left below its threshold and confirm Jest exits non-zero. If it exits 0, check that collectCoverageFrom includes the file and the coverageThreshold path key matches, then re-run.

Scope collectCoverageFrom

Per jest-config (opens in new window): "An array of glob patterns indicating which files should have coverage collected, even if they have no tests."

collectCoverageFrom: [
  'src/**/*.{js,jsx,ts,tsx}',
  '!src/**/*.d.ts',
  '!src/**/*.stories.{js,ts,tsx}',
  '!src/index.js',
],

Without this, coverage only counts files a test imported - files with no test at all disappear from the report and coverage looks artificially high. Always set it for an honest denominator.

Parse the JSON output

The json reporter writes coverage/coverage-final.json, keyed by absolute path:

{
  "/abs/path/src/checkout/cart.ts": {
    "statementMap": { "0": { "start": {}, "end": {} } },
    "s": { "0": 42, "1": 42, "2": 0 },
    "f": { "0": 42, "1": 0 },
    "b": { "0": [42, 0] }
  }
}

s = per-statement hit counts; f = per-function; b = per-branch arm.

// scripts/parse_jest_coverage.js
import { readFileSync } from 'node:fs';

const data = JSON.parse(readFileSync('coverage/coverage-final.json', 'utf8'));

for (const [absPath, file] of Object.entries(data)) {
  const stmts = Object.values(file.s);
  const stmtPct = (stmts.filter(c => c > 0).length / stmts.length) * 100;

  const fns = Object.values(file.f);
  const fnPct = (fns.filter(c => c > 0).length / fns.length) * 100;

  // Branch coverage: each entry is an array of arm hit counts.
  const branchEntries = Object.values(file.b);
  const branchTotal = branchEntries.flat().length;
  const branchHit = branchEntries.flat().filter(c => c > 0).length;
  const brPct = branchTotal === 0 ? 100 : (branchHit / branchTotal) * 100;

  console.log({ path: absPath, stmtPct, fnPct, brPct });
}

coverage-summary.json (from the json-summary reporter) is the pre-aggregated version when per-statement detail isn't needed.

Vitest equivalent

Vitest uses the same Istanbul / V8 stack with vitest --coverage:

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text-summary', 'lcov', 'json', 'html'],
      include: ['src/**/*.{ts,tsx}'],
      thresholds: {
        global: { branches: 50, functions: 50, lines: 50, statements: 50 },
        'src/api/**/*.ts': { branches: 100, functions: 100, lines: 100, statements: 100 },
      },
    },
  },
});

Key naming differences vs Jest: collectCoverageFrom → coverage.include; coverageReporters → coverage.reporter; coverageThreshold → coverage.thresholds. Output formats and PR-gating logic are identical.

CI shape

- name: Run tests with coverage
  run: npx jest --coverage --coverageReporters=lcov,json,text-summary

- name: Show summary in CI log
  run: cat coverage/coverage-summary.json

- name: Upload to dashboard
  if: always()
  uses: codecov/codecov-action@v4
  with:
    files: coverage/lcov.info
    token: ${{ secrets.CODECOV_TOKEN }}

--coverage activates collectCoverage: true; --coverageReporters overrides config-side reporter selection.

Anti-patterns

Limitations

• Source-map fidelity affects the V8 provider. Files through multiple transforms (Babel + TS + bundler) may show wrong paths or partial coverage; switch to babel if so.
• Coverage doesn't equal correctness. A 100%-covered if (x) {} (empty body) measures as covered but tests nothing.
• Async branches are tricky. The resolved path may show covered while the rejection arm is missed unless tests explicitly throw.
• Multi-project (projects: [...]) coverage is per-project. Aggregate via each project's --coverageDirectory + a combiner script.

References

• jest-config (opens in new window) - collectCoverage, coverageProvider, coverageReporters, coverageThreshold, collectCoverageFrom.
• lcov-analysis (qa-test-reporting) - the LCOV file Jest emits feeds this parser for cross-tool diffing; also the home for Cobertura-consuming pipelines.
• coverage-diff-reporter (qa-test-reporting) - PR-comment formatter built on the parsed Jest output.
• test-coverage-targeter (qa-test-reporting) - picks which uncovered branches to target, given the Jest output.

Migrating a legacy Jasmine / Karma suite to Jest

Companion reference for js-unit-tests. Consult when a legacy Jasmine codebase (typically AngularJS-era, often paired with Karma for in-browser runs) should move to Jest. Context: Karma has been in maintenance-only mode since 2023, AngularJS reached end-of-life in January 2022, and new Angular projects use Jest or Vitest - Karma + Jasmine setups are explicitly legacy.

Jest's API descends from Jasmine (describe, it, beforeEach, expect(...).toBe(...), spies all originated there), so migration is mostly mechanical.

Automated path: jest-codemods

The jest-codemods (opens in new window) package handles ~80% of the syntax transformations:

npx jest-codemods

Point it at the spec directory and review the diff - it rewrites Jasmine spy/matcher calls into their Jest equivalents.

Manual steps for the remainder

1. Replace spyOn().and.returnValue() with jest.spyOn().mockReturnValue().
2. Replace jasmine.createSpy() with jest.fn().
3. Replace jasmine.createSpyObj() with manual jest.fn() per method.
4. Replace expect().toBeNan() with expect(Number.isNaN(...)).toBe(true) (matcher renamed).
5. Add jest.config.js with an appropriate testMatch for the existing spec layout (Jasmine's convention is spec/**/*[sS]pec.js).
6. Drop Karma if used - Jest provides its own jsdom environment, so the browser launcher layer is no longer needed.

After migration, follow SKILL.md for Jest configuration, mocking, coverage, and CI.

References

• github.com/skovhus/jest-codemods - automated migration codemods
• jestjs.io/docs/getting-started - Jest setup for the migrated suite

Mocha - pluggable JS test runner (maintenance reference)

Companion reference for js-unit-tests. Consult when maintaining a legacy Mocha codebase, or when a library/tooling project prefers a minimal pluggable runner over Jest/Vitest's batteries-included model. For new projects, prefer Jest or Vitest (see the Choosing section of SKILL.md).

Per mochajs.org (opens in new window):

Mocha is the original mainstream JS test runner. Distinguishing features:

• Pluggable: assertions (Chai / Node assert), mocking (Sinon), coverage (nyc / c8) are separate libraries - pick what you need.
• Two interfaces: BDD (describe/it, default) and TDD (suite/test).
• Reporter ecosystem: spec, json, html, tap, dot, mocha-junit-reporter.
• Parallel mode (Mocha 8+): --parallel flag for multi-process runs.

Install and first test

npm install --save-dev mocha
npm install --save-dev chai sinon nyc   # typical peers

// test/sum.test.js
const { expect } = require('chai');
const { sum } = require('../src/sum');

describe('sum', () => {
  it('adds 1 + 2 to equal 3', () => {
    expect(sum(1, 2)).to.equal(3);
  });
});

Wire "test": "mocha" in package.json. Default test glob: ./test/*.{js,cjs,mjs} plus ./test/**/*.spec.js. Node's built-in node:assert works too when zero extra deps matter.

.mocharc.json configuration

Config files: .mocharc.json, .mocharc.js, .mocharc.yaml, or a mocha key in package.json:

{
  "spec": ["test/**/*.spec.js"],
  "recursive": true,
  "require": ["ts-node/register", "./test/setup.js"],
  "reporter": "spec",
  "timeout": 5000,
  "parallel": true,
  "jobs": 4,
  "ui": "bdd",
  "extension": ["js", "ts"]
}

Key options: parallel + jobs (multi-process, Mocha 8+); ui: 'bdd' (default) vs 'tdd'; recursive (nested test dirs); require (preload TS support / setup).

Async patterns

Per mocha (opens in new window), three approaches - callback (done), returned promise, and async/await (preferred):

it('async/await', async () => {
  const result = await doAsyncWork();
  expect(result).to.equal(42);
});

The async function MUST return (or await) - otherwise the promise's rejection isn't surfaced to Mocha and tests pass-by-accident.

Hooks, exclusivity, and skipping

before / after (once per describe block) and beforeEach / afterEach (per test) all accept async bodies. it.only / describe.only run exclusively; it.skip / xit skip. Forbid committed .only via eslint-plugin-mocha's mocha/no-exclusive-tests rule.

Coverage with nyc / c8

{
  "extends": "@istanbuljs/nyc-config-typescript",
  "all": true,
  "check-coverage": true,
  "branches": 80, "lines": 80, "functions": 80, "statements": 80,
  "include": ["src/**/*.{js,ts}"],
  "reporter": ["text", "lcov", "html"]
}

Run nyc mocha (Istanbul instrumentation), or c8 mocha (Node's built-in V8 coverage; faster, no instrumentation). check-coverage + thresholds make the run fail below the floor.

Parallel mode and root hooks

Per parallel mode (opens in new window) (Mocha 8+): mocha --parallel --jobs 4. Tests must be independent - shared state across describe blocks breaks parallel runs.

Root hooks stop working in parallel mode. "Each test file gets its own instance of Mocha", so a root hook defined in file A "will not be present" in file B (mocha-par (opens in new window)). The serial-era pattern - --file ./test/setup.js installing a top-level before - does not carry over. Two supported replacements (root hook plugins (opens in new window)):

// test/hooks.js - loaded with `mocha --require test/hooks.js`
export const mochaHooks = {
  beforeEach() { /* runs in every worker, before every test */ },
};

// once per run, not per worker ([global fixtures][mocha-gf]):
export const mochaGlobalSetup = async () => { /* seed */ };
export const mochaGlobalTeardown = async () => { /* tear down */ };

CI integration

- run: npm ci
- run: npx mocha --reporter mocha-junit-reporter --reporter-option mochaFile=./test-results/junit.xml
# Or with coverage:
- run: npx c8 --reporter lcov mocha
- uses: codecov/codecov-action@v4
  with: { files: ./coverage/lcov.info }

mocha-junit-reporter emits JUnit XML for junit-xml-analysis (qa-test-reporting).

Anti-patterns

Limitations

• No bundled assertions / mocking / coverage - more setup vs Jest/Vitest.
• Watch mode less polished than Vitest's; snapshots need third-party mocha-chai-jest-snapshot.
• ESM support workable but historically rough; pin a recent Mocha version.

References

• mocha (opens in new window) - official site; mochajs.org/api - API reference
• chaijs.com - Chai assertions; sinonjs.org - Sinon mocking
• istanbul.js.org / github.com/bcoe/c8 - coverage tools
• github.com/michaelleeallen/mocha-junit-reporter - JUnit XML reporter