Vitest Coverage and CI for Angular: Providers, Thresholds, and the Karma Gap

Coverage is a builder option, not a config file#

With Karma, coverage meant karma-coverage wired into karma.conf.js: a reporter block, an istanbul output directory, thresholds in a check object. The Vitest builder moves all of that into angular.json under architect.test.options. There is no coverage config file to maintain for the common case. You set coverage: true and the keys next to it.

The flag is ng test --coverage, and the docs are explicit that coverage is a first-class CLI feature. The one dependency you add is @vitest/coverage-v8. Its own help text tells you the default state: If not specified, the coverage configuration from a runner configuration file will be used if present. Otherwise, coverage is disabled by default. So coverage is off until you ask for it, on the flag or in the file.

The reporter names are the istanbul set you already know from Karma: text, text-summary, html, lcov, lcovonly, cobertura, json, json-summary. The lcov and cobertura ones are the two a CI dashboard ingests, so those are the ones worth pinning in the committed config rather than passing on the command line.

# angular.json -> projects.<name>.architect.test.options
# Requires: npm i -D @vitest/coverage-v8
{
  "builder": "@angular/build:unit-test",
  "options": {
    "coverage": true,
    "coverageReporters": ["text-summary", "lcov", "cobertura"],
    "coverageThresholds": {
      "statements": 80,
      "branches": 80,
      "functions": 80,
      "lines": 80
    }
  }
}

The gap: the provider choice is not yours to make here#

This is the one place the Angular surface is narrower than it looks, and it is worth knowing before you promise a team an istanbul report. Vitest has two coverage providers: v8 (the default) collects coverage at runtime through node:inspector and runs your source as-is, while istanbul instruments the source files and runs on any JavaScript runtime. They differ in real ways: v8 cannot limit collection to specific modules, and only v8 needs a V8-based runtime.

The Angular code coverage page documents exactly one provider package, @vitest/coverage-v8. There is no coverageProvider option in the builder. Switching to istanbul is a raw-Vitest setting, coverage.provider: 'istanbul', which means a vitest.config.ts reached through the runnerConfig option. And the migration guide is blunt about that file: the Angular team does not support its contents or third-party plugins. You can do it; you are off the supported path when you do.

My read: stay on v8 unless you have a concrete reason not to. Since Vitest 3.2 the v8 provider uses AST-based remapping that the docs say produces reports identical to istanbul, so the old accuracy argument for switching is mostly gone. I would only reach for istanbul if I needed its module-scoped instrumentation, and I would treat that runnerConfig file as something the team owns and reviews, not a default to copy from a blog.

Thresholds that actually fail the build#

A coverage number nobody enforces is decoration. The point of coverageThresholds is that it turns coverage into a gate: the Angular docs state plainly that if your coverage drops below the configured floor when you run your tests, the command will fail. That non-zero exit is what makes the gate real in CI, and it is the behavior karma-coverage's check block gave you, now expressed in angular.json.

The four keys are statements, branches, functions, and lines, each a percentage. I do not pick 80 because it is a good number; I pick the floor the suite already clears today, commit it, and ratchet it up as coverage improves. A threshold set above where you are is just a red build on day one, which trains the team to pass --no-coverage and defeats the point.

One caution specific to the move from Karma. Coverage percentages shift when the provider or the included file set changes, so the number you enforced under karma-coverage is not guaranteed to be the number Vitest reports for the same code. Measure first on the new runner, then set the threshold from that measurement.

# See the real number Vitest reports for your code, then set the floor from it.
ng test --coverage --coverage-reporters text-summary --no-watch

# Narrow the included set if vendored or generated files skew the percentage.
ng test --coverage --coverage-include "src/app/**/*.ts" --no-watch

What changes on the CI runner#

The mechanical CI difference from Karma is that you no longer fight a browser launcher. The Vitest builder runs in jsdom by default, so there is no headless-Chrome flag to babysit. What you do still want is run-once behavior and a machine-readable report.

Run mode is mostly automatic. Vitest starts in run mode when process.env.CI is set, and falls back to run mode when stdin is not a TTY, so a plain ng test on most CI providers already runs once and exits. I still pass --no-watch explicitly in the CI command. Relying on environment detection is the kind of implicit behavior that turns into a hung pipeline the day you run the same command in a context that happens to look interactive.

For the report, the test execution reporters include junit, the format Jenkins, GitLab, and Azure Pipelines parse natively for per-test results. Coverage and test results are two separate streams: --reporters junit is the test outcome, --coverage-reporters cobertura (or lcov) is the coverage your dashboard reads. The Karma-era --no-watch --no-progress pair collapses to the run-mode default plus the reporters you actually need.

Watch locally, isolate by default#

Locally the default is the opposite of CI, and that is what you want. The --watch flag defaults to true in a TTY, so a bare ng test at your desk re-runs on save. There is no separate --watch invocation to remember; the terminal context decides.

Two Vitest defaults are worth knowing because they explain both the speed and the occasional flake. The default pool is forks, and test files run in parallel across worker processes, which is most of why the suite feels faster than Karma. Within a single file, tests still run sequentially. Isolation is on by default: each file gets a fresh environment. That isolation is also a knob. Disabling it (--no-isolate, or test.isolate: false in a Vitest config) is faster but lets state bleed across files, so it is a CI speed lever I would only pull after the suite is green and I have a measurement that says it helps.