diff-cover-js

Diff-aware test coverage for JavaScript/TypeScript projects. Reports coverage only for lines you changed, not the entire file.

The JS/TS equivalent of the Python diff-cover tool — same algorithm, same CLI flags, no Python required.

The problem it solves

Standard coverage tools measure the whole file. If you add 10 lines to a 500-line file and cover all 10, Jest reports ~2% coverage. diff-cover-js reports 100% — because all your changed lines are covered.

Installation

npm install -g diff-cover-js

Requirements

• Node.js >= 16
• A lcov.info file generated by your test runner (Jest produces one with the lcov reporter)
• A git repository with the base branch available locally

Usage

diff-cover-js \
  --lcov coverage/lcov.info \
  --compare-branch origin/main \
  --fail-under 80

Generate HTML + JSON reports

diff-cover-js \
  --lcov coverage/lcov.info \
  --compare-branch origin/main \
  --fail-under 80 \
  --format html:reports/diff-cover.html,json:reports/diff-cover.json,markdown

Use a config file instead of flags

Create .diff-cover-js.json in your project root:

{
  "lcov": "coverage/lcov.info",
  "compareBranch": "origin/main",
  "failUnder": 80,
  "format": "html:reports/diff-cover.html,json"
}

Then just run:

diff-cover-js

CLI flags

| Flag | Default | Description | |------|---------|-------------| | --lcov <path> | — | Path to lcov.info coverage file | | --compare-branch <ref> | — | Git branch or ref to compare against (e.g. origin/main, FETCH_HEAD) | | --fail-under <percent> | 0 | Exit code 1 if diff coverage is below this | | --format <formats> | — | Output formats: html, json, markdown — with optional paths | | --exclude <globs...> | — | Additional glob patterns to exclude on top of the built-in defaults | | --no-default-excludes | off | Skip the built-in test/spec/.d.ts file exclusions entirely | | --strict | off | Treat files missing from coverage data as 0% covered | | --diff-range-notation <...∣..> | ... | Git diff range notation (symmetric ... or simple ..) | | -q, --quiet | off | Only print the final percentage, suppress the full report | | -c, --config-file <path> | auto | Path to config file (auto-discovered if omitted) |

Default excluded patterns

These file patterns are excluded from diff coverage by default (test/spec files and type declarations). Use --no-default-excludes to opt out entirely, or just use --exclude to add more patterns on top.

**/*.test.ts    **/*.test.tsx    **/*.test.js    **/*.test.jsx
**/*.spec.ts    **/*.spec.tsx    **/*.spec.js    **/*.spec.jsx
**/__tests__/**
**/__mocks__/**
**/*.d.ts

Note: The Python diff-cover tool has no built-in default exclusions — it relies on explicit --exclude flags. The default exclusions here are a JS-ecosystem convenience. Pass --no-default-excludes to match the Python tool's behavior exactly.

Jest setup

Add lcov to your Jest coverage reporters:

// jest.config.js
module.exports = {
  collectCoverage: true,
  coverageDirectory: 'coverage',
  coverageReporters: ['lcov', 'text'],
};

How it works

1. Runs git diff <compare-branch>...HEAD --unified=0 to get the exact lines you added
2. Reads lcov.info to get per-line hit counts for instrumented files
3. Cross-references: for each added line, is it in the coverage data and was it executed?
4. Non-executable lines (blank lines, comments, type declarations) are automatically skipped — they don't count for or against coverage
5. Reports the percentage of your added executable lines that were covered

Output formats

Console (default)

────────────────────────────────────────────────────────────────
  diff-cover-js  ·  Diff Coverage Report

  ✓  src/utils/foo.ts
       100% diff coverage  (5/5 coverable changed lines)

  ✗  src/services/bar.ts
        60% diff coverage  (3/5 coverable changed lines)
       Missing lines: 42, 45

────────────────────────────────────────────────────────────────
  Overall diff coverage: 72%
  8/10 coverable changed lines covered
────────────────────────────────────────────────────────────────

HTML — table with per-file coverage % and missing line ranges
JSON — structured output for CI dashboards and PR comment bots
Markdown — for posting in PR descriptions

Differences from Python diff-cover

| Feature | diff-cover (Python) | diff-cover-js | |---------|---------------------|---------------| | lcov support | ✓ | ✓ | | HTML report | ✓ | ✓ | | JSON report | ✓ | ✓ | | Markdown report | ✓ | ✓ | | Config file | TOML (pyproject.toml) | JSON (.diff-cover-js.json) | | Code snippets in HTML | ✓ (via Pygments) | planned | | diff-quality (lint violations) | ✓ | planned | | Cobertura XML input | ✓ | not planned (lcov only) | | Runtime | Python | Node.js |

License

MIT