How does Jest 30's coverageThreshold read a positive versus a negative number, and how are global, path and glob keys applied?
answer
- percentage floor or uncovered ceiling
- four metric keys
- directory pooled, glob per file
- global takes what is left
- missing path is an error
basics
~20 sA positive coverageThreshold value is a minimum percentage; a negative one is the most uncovered items allowed. A directory key pools its files, a glob key checks each file alone, and global covers the files no other key matched.
solid answer
~40 s`coverageThreshold` takes keys `global`, a directory or file path, or a glob, each holding any of `statements`, `branches`, `functions` and `lines`. A positive number is a minimum percentage; a negative number is a maximum count of uncovered items, so `statements: -10` fails when more than ten statements are uncovered. A directory or file path key combines the matching files into one figure, while a glob key checks every matching file on its own. `global` applies to the files no path or glob key matched, and to all covered files if every file was matched. A path key with no covered files reports `Coverage data for ... was not found.` When any check misses, Jest prints a line per miss and fails the run even if every test passed.
code
javascript · 10 linesconst {defineConfig} = require('jest');
module.exports = defineConfig({
collectCoverageFrom: ['src/**/*.js'],
coverageThreshold: {
global: {lines: 50, statements: -3},
'./src/billing/': {branches: 80},
'./src/billing/*.js': {functions: 90},
},
});go deeper
Recall the four metric keys and that a positive number is a minimum percentage while a negative number caps the uncovered count.
Explain how directory keys pool files, glob keys check each file, and global covers what no other key matched.
Show you can set a stricter floor on a critical folder without letting it distort the global figure, and read each failure line.
Weigh where per-folder floors earn their maintenance cost and where a single global floor is enough for the team.
## What the option is `coverageThreshold` sets **minimum coverage that a Jest 30 run must reach**. It has no default; without it, coverage is reported but never judged. When any configured check misses, Jest prints one line per miss in red after the coverage table and marks the run as failed, even when every test passed. The thresholds are read only on a coverage run, so they need `--coverage` or `collectCoverage: true`. Each key holds an object with up to four metrics: `statements`, `branches`, `functions` and `lines`. Leave a metric out and it is not checked. ## Positive and negative numbers The sign changes the meaning: - A **positive** number is the **minimum percentage**. `branches: 80` fails when branch coverage for that group is below 80%. The failure reads `Jest: Coverage for branches (75%) does not meet "global" threshold (80%)`. - A **negative** number is the **maximum count of uncovered items**. `statements: -10` fails when more than ten statements are uncovered. The failure reads `Jest: Uncovered count for statements (12) exceeds global threshold (10)`. The count form suits a small module where one missed statement swings the percentage by several points, or a legacy area where the team wants "no more uncovered code than today" expressed as a number of items rather than a ratio. ## The three kinds of key | Key | Example | How files are grouped | How the check runs | |---|---|---|---| | `global` | `global` | files no other key matched | one combined figure | | directory or file path | `'./src/billing/'` | files whose path starts with it | one combined figure for the group | | glob | `'./src/billing/*.js'` | files the glob matches | each file checked on its own | Three rules follow from the reporter's code and the documentation's note: 1. **Path keys pool.** Every covered file under `./src/billing/` is merged, and the merged figure must meet the limits. One well-tested file can carry a weak neighbour. 2. **Glob keys do not pool.** Each matching file must meet the limits by itself, and a failure names the individual file. Use a glob when every file in a folder should meet the floor alone. 3. **Global takes the rest.** The `global` key applies to covered files that no path or glob key matched. If every covered file was matched by some path or glob, `global` falls back to all covered files. A file matched by both a path key and a glob key is checked under both. A path key that matches no covered file is an error in its own right: `Jest: Coverage data for ./src/payments/ was not found.` That catches a stale key left behind after a directory was renamed. ## The reserved example A team whose service sat at 92% line coverage shipped a bug from an untested error branch, and now adds floors. A plausible first config keeps a modest global floor and a stricter one where the money moves: - `global: {lines: 85, branches: 75}` for everything else; - `'./src/billing/': {branches: 90}` for the billing folder as a whole; - `'./src/billing/*.js': {functions: 100}` so that no exported billing function is left without a test, file by file. Because the billing files are matched by the path and glob keys, they no longer count toward `global`, so the global figure describes the rest of the service honestly. ## Practical details - The thresholds are computed over the same coverage map the report shows, so they depend on `collectCoverageFrom`. Without it, untested modules are absent and every floor is easier to meet. - `coverageThreshold` is a global option. In a configuration that uses `projects`, put it in the root config; inside a project entry it is not applied. - Jest also feeds the `global` percentages into the HTML report's colour bands, so a file shown in the top band meets the global floor for that metric. - Which failures should block a merge, and how the run's exit status is wired into a pipeline, is a separate subject from what this option checks.
- When would you choose a glob key over a directory key for the same folder?When each file must meet the floor on its own. A directory key merges the files, so a large well-tested module can hide a small untested one. A glob key checks each matching file separately and names the file that missed, at the cost of failing on any single weak file.
- What does a negative value buy you over a percentage?It caps the absolute number of uncovered statements, branches, functions or lines. In a tiny module one missed item can move the percentage by ten points, and in a large one a percentage can hide dozens of new gaps. A count states exactly how much uncovered code is tolerated.
- Why might a threshold pass locally and fail when another developer runs the suite?The figures come from whatever was covered in that run. Running a subset of tests, or relying on the default of only loaded files instead of `collectCoverageFrom`, changes the coverage map and therefore the numbers. Thresholds are only comparable across runs with the same file scope and test set.
- A negative coverageThreshold value means a percentage that may drop by that many points.
- A glob key pools its matching files into one figure, like a directory key.
- The global threshold always applies to every covered file, even ones a path key matched.
- Missing a threshold only prints a warning when all tests pass.
- A coverageThreshold key for a folder with no covered files is silently skipped.