How would you set the coverage gate for a Jest 30 monorepo so it catches untested code without the percentage becoming the goal?
answer
- coverage means ran, not asserted
- collectCoverageFrom makes untested files count
- one provider, one baseline
- global ratchet, critical paths higher, legacy frozen
- every ignore comment needs a reason
basics
~20 sCount all source with collectCoverageFrom, keep one coverage provider, and set coverageThreshold as a rising global floor, higher floors on critical paths and negative counts that freeze legacy code. Coverage proves code ran, not that it was checked.
solid answer
~40 sCoverage records what ran, not what was asserted, so the gate should catch untested code without becoming the target. Make everything count: `collectCoverageFrom` over all source, so a file no test loads shows up at 0, with generated code excluded for a written reason. Pick `babel` or `v8` once, because they count differently and their ignore comments differ (`/* istanbul ignore next */` versus `/* c8 ignore next */`). In the root config, `coverageThreshold` then takes three shapes: a `global` floor just under today's number, raised as tests land, which applies to files no other key matches; higher positive floors on critical paths; and negative numbers, the maximum uncovered items, on legacy directories. Emphasise branches, require a reason on every ignore comment, and gate in CI.
code
javascript · 15 linesconst {defineConfig} = require('jest');
module.exports = defineConfig({
projects: ['<rootDir>/packages/*'],
coverageProvider: 'babel', // chosen once; a switch resets the baseline
collectCoverageFrom: [
'packages/*/src/**/*.{ts,tsx}',
'!packages/*/src/generated/**', // generated client, excluded on purpose
],
coverageThreshold: {
global: {branches: 72, lines: 80}, // ratchet: raise as tests land
'./packages/billing/src/': {branches: 90, lines: 95}, // critical path
'./packages/legacy-import/src/': {statements: -120}, // frozen debt
},
});go deeper
Know that coverage shows which code ran during the tests, and that a threshold can fail the run.
Explain collectCoverageFrom, the provider choice, and positive versus negative thresholds.
Read a coverage drop correctly: a provider switch, a new untested file, or a real gap, and fix the right one.
Design the gate: where floors sit, how they rise, how legacy is frozen, and how ignore comments are governed.
## What the gate can and cannot say Jest's coverage counts which statements, branches, functions and lines **ran** during the tests. It cannot tell whether anything was asserted. A test that calls a function and checks nothing still covers it. So a coverage gate catches untested code. It does not prove tested behaviour, and a policy should say so out loud, or the percentage becomes the goal. ## Decisions the policy must make ### 1. What counts Without `collectCoverageFrom`, the report only includes files some test loaded, so a module nobody tests is invisible and the percentage looks better than it is. Set `collectCoverageFrom` to all source, for example `'packages/*/src/**/*.{ts,tsx}'`. Exclude generated and vendored code with negated globs or `coveragePathIgnorePatterns`, and write each exclusion down with its reason. ### 2. Which provider, once `coverageProvider` is `babel` (the default) or `v8`. They count differently, so switching moves every number. Choose one, record the baseline, and treat a provider switch as a reset of the thresholds. Ignore comments differ too: `/* istanbul ignore next */` works with babel and `/* c8 ignore next */` with v8. A switch silently changes which exclusions still apply. ### 3. The threshold shape `coverageThreshold` is set in the root config. In a monorepo run through `projects` it is one gate over the whole run. Its keys let a policy say different things about different code: | Key | Use it for | |---|---| | `global` | a floor a little under today's number, raised as it improves (a ratchet). It applies to files no other key matches | | a path or glob with **positive** numbers | critical code, such as the billing package, held to a higher bar | | a path or glob with **negative** numbers | legacy code: the maximum number of uncovered items, which freezes the debt without inventing a percentage | Emphasise `branches`. A line that ran counts as covered even when one outcome of its condition never happened, and only the branch count and the HTML report show that gap. ### 4. Escape hatches Ignore comments are sometimes right: a defensive branch that cannot happen, or platform glue. Require a reason in the comment and review each one like a disabled lint rule. Otherwise the cheapest way to pass the gate becomes the ignore comment. ### 5. Where it runs Run coverage in the CI job that gates merges. Jest already writes `lcov` among its default reporters, so a check on changed lines, if the team wants one, can read that file without changing Jest. Keep the local default fast, and let developers add `--coverage` when they want it. ## Keeping the number honest - Pair the gate with review questions: what does this test assert, and would it fail if the branch broke? - Raise floors only after real tests land. Never lower one to make a merge pass without an explicit decision. - Read the HTML report for the files a change touched, not the headline percentage. ## The trade-off you are choosing A high global floor is easy to state and easy to game. Per-path floors put the bar where failure is expensive, but someone has to maintain the map. Negative thresholds stop legacy code getting worse without demanding work nobody has scheduled. Most teams combine a modest global ratchet, high floors on a few critical paths, and frozen counts on legacy directories.
- Who may lower a coverage floor, and how should it happen?Lowering a floor is a policy decision, not a way to get one merge through. It goes in its own change with a stated reason, such as well-tested code being deleted or a provider switch resetting the baseline, and is approved by whoever owns the gate. A floor lowered quietly inside a feature change turns the ratchet into a slide.
- A test calls a function and asserts nothing. How does the team catch that when coverage cannot?Review asks of each test what it asserts and whether it would fail if the code broke. On critical paths, mutation testing goes further. A tool such as StrykerJS, which has a Jest runner, changes the code (flips a condition, removes a statement) and reruns the tests; a change no test notices marks code that ran without being checked. It is slow, so teams run it on critical packages or nightly rather than on every merge.
- 100% line coverage means every behaviour is tested.
- Coverage only needs to include files the tests import.
- Switching from babel to v8 keeps the same numbers.
- A failing threshold is fixed by adding ignore comments.
- The global threshold also covers files matched by a path key.
Assumes Jest 30: coverageProvider babel (default) or v8, and coverageThreshold's global key applying to files no path or glob key matches.