skip to content

How do you turn on code coverage in a Jest 30 run, and what does Jest write out by default?

level: juniorimportance: must knowfreq 50%

answer

  1. off unless you ask
  2. one flag or one config key
  3. four default reporters
  4. a folder under rootDir
  5. setting the list replaces it

basics

~10 s

Run jest --coverage or set collectCoverage: true. Jest then prints a per-file text table and writes clover, json and lcov reports, the lcov one including an HTML site, into a coverage folder under rootDir.

solid answer

~40 s

Coverage is off by default because instrumenting every executed file slows the run. `jest --coverage` (alias `--collectCoverage`) turns it on for one run, and `collectCoverage: true` turns it on in the config; `--coverage=false` overrides the config for a run. With the default `coverageReporters` of `clover`, `json`, `lcov` and `text`, Jest prints a table with `% Stmts`, `% Branch`, `% Funcs`, `% Lines` and `Uncovered Line #s`, and writes `clover.xml`, `coverage-final.json`, `lcov.info` and a browsable `lcov-report/index.html` into `coverageDirectory`, which resolves to `<rootDir>/coverage` when unset. Setting `coverageReporters` replaces the default list instead of adding to it, so `['text']` alone writes no files. Only files the tests loaded are listed unless `collectCoverageFrom` names more.

code

javascript · 7 lines
javascript
const {defineConfig} = require('jest');

module.exports = defineConfig({
  // left off here; the full-suite script adds --coverage
  collectCoverage: false,
  coverageReporters: ['text-summary', 'lcov'],
});

go deeper

for a junior

Recall the two switches, --coverage and collectCoverage, and that the HTML report sits in the coverage folder under lcov-report.

for a middle

Explain the default reporter set, that coverageReporters replaces rather than extends it, and which files are never instrumented.

for a senior

Show you keep coverage off in watch mode, pick reporters per consumer, and know a default run hides modules no test imports.

for a principal

Frame reporter and output choices as a shared team convention, so local runs and automated runs produce the same files and numbers.

## Turning coverage on Jest 30 does not measure **code coverage** unless asked. Coverage means recording which statements, branches, functions and lines of your source ran while the tests executed. The documentation for `collectCoverage` warns that because coverage "retrofits all executed files with coverage collection statements, it may significantly slow down your tests", which is why the default is `false`. There are two switches, and both reach the same option: 1. **The CLI flag** `--coverage` (alias `--collectCoverage`). It turns coverage on for this run only. It also takes an optional boolean, so `jest --coverage=false` switches it off for one run even when the config file sets it on. 2. **The config key** `collectCoverage: true` in `jest.config.js`, `jest.config.ts` or the `jest` key of `package.json`. Every run of that config then collects coverage. A common habit is to leave `collectCoverage` off in the config, so watch mode stays fast while you edit, and to add `--coverage` to the script that runs the full suite. ## What a default run produces When `coverageReporters` is not set, Jest uses four **reporters**, each an Istanbul report writer: | Reporter | Output | Who reads it | |---|---|---| | `text` | a table printed to the terminal | you, right after the run | | `lcov` | `lcov.info` plus an HTML site in `lcov-report/` | tools that ingest lcov, and you in a browser | | `json` | `coverage-final.json`, the raw per-file data | other tools that merge or post-process coverage | | `clover` | `clover.xml` | tools that read the Clover XML format | The terminal table has one row per file and an `All files` row, with the columns `% Stmts`, `% Branch`, `% Funcs`, `% Lines` and `Uncovered Line #s`. The last column lists line numbers or ranges that no test executed, which is often enough to spot a missed path without opening anything else. ## Changing the reporter set `coverageReporters` takes reporter names, or a `[name, options]` tuple. The key behaviour to remember is that **setting it replaces the four defaults**; it never merges with them. Useful choices: - `text-summary` prints a four-line block (statements, branches, functions, lines) instead of the per-file table. - `json-summary` writes `coverage-summary.json` with only the totals, handy for a badge or a dashboard. - `html` writes the HTML site on its own; `lcovonly` writes `lcov.info` without it. - `['text', {skipFull: true}]` hides rows for files that are already fully covered, which keeps the table readable in a large repository. If you write `coverageReporters: ['text']`, the run prints the table and writes nothing to disk. If you want both a terse terminal and the HTML site, list them both, for example `['text-summary', 'lcov']`. The reporter set is a global option. In a configuration that uses `projects`, set it on the root config rather than inside a project entry. ## Where the files go `coverageDirectory` names the output folder. When it is not set, Jest resolves it to a `coverage` folder under `rootDir`, and `rootDir` itself defaults to the directory holding the config file or `package.json`. Every coverage run writes its reports into it again, so it belongs in the ignore list of your version control rather than in commits. ## Which files appear in the report A default coverage run lists only the source files that the tests actually loaded, and several kinds of file are left out of the count: - the test files themselves (anything matched as a test), unless `forceCoverageMatch` names them; - files under a `__mocks__` directory; - the files named in `setupFiles` and `setupFilesAfterEnv`, and the `globalSetup` and `globalTeardown` modules; - `.json` files; - anything matching `coveragePathIgnorePatterns`, which defaults to `["/node_modules/"]`. A module that no test imports therefore does not appear at all, and the `All files` row looks better than the code base is. The `collectCoverageFrom` option fixes that by naming the source globs to report, including files no test touched. ## Mistakes worth avoiding - Expecting coverage on every run: it is off until `--coverage` or `collectCoverage` turns it on. - Adding `html` to `coverageReporters` and expecting the other defaults to stay. - Hunting for an HTML reporter when `lcov` is already writing one into `lcov-report/`. - Assuming `--coverageProvider=v8` enables coverage; it only chooses how coverage is collected once it is on.

  • How do you keep a short terminal summary but still produce the lcov file for another tool?
    Set `coverageReporters: ['text-summary', 'lcov']`. `text-summary` prints the four totals instead of the per-file table, and `lcov` writes `lcov.info` plus the HTML site in `lcov-report/`. Because the option replaces the defaults, `json` and `clover` are no longer written unless you list them too.
  • If the config sets collectCoverage: true, how do you skip coverage for one quick run?
    Pass `--coverage=false`. The `--coverage` flag accepts an optional boolean that overrides the value set in configuration, so the run skips instrumentation and is faster, while the config file stays unchanged for the full-suite script.
  • Why does the test file itself never appear in the coverage table?
    Jest skips instrumenting files it recognises as tests, along with `__mocks__` files, setup files and `.json` files. If tests live inside source files with a custom extension, `forceCoverageMatch` lists globs for files Jest should instrument despite being test files.

  • Jest collects coverage on every run by default.
  • Adding html to coverageReporters keeps the four default reporters as well.
  • The lcov reporter writes only lcov.info, so the HTML site needs another reporter.
  • Passing --coverageProvider=v8 on its own turns coverage on.
  • The coverage table lists every source file in the repository.