Karma Watch Mode

Karma can either stay open and rerun your tests automatically as you edit files, or run once and exit with a pass/fail code. This lesson explains the two settings that control that behavior and when to use each.

autoWatch and singleRun

autoWatch (default true) tells Karma to keep a file watcher active on everything matched by files, and to trigger a fresh test run whenever a watched file changes. singleRun (default false) tells Karma to run the suite exactly once, then shut down every browser and exit with a process exit code.

These two settings are usually set to opposite values depending on context: local development wants autoWatch: true, singleRun: false for fast feedback, while CI wants singleRun: true (with autoWatch effectively irrelevant, since the process exits immediately after one pass).

// Local development
config.set({
  autoWatch: true,
  singleRun: false
});

// CI
config.set({
  autoWatch: false,
  singleRun: true
});

Most projects branch on an environment variable rather than maintaining two full separate config files just for this.

Overriding via CLI Flags

karma start                          # uses config file values
karma start --single-run             # force singleRun: true for this run
karma start --no-single-run          # force singleRun: false for this run
karma start --auto-watch             # force autoWatch: true
karma start --no-auto-watch          # force autoWatch: false

CLI flags override whatever is written in karma.conf.js, without needing to edit the file.
This is exactly how many package.json scripts implement both a test and test:ci command from one config.
--single-run is the flag most CI pipelines pass explicitly, even if the config file default is already true.
Watch mode reruns the entire browser suite, not just changed files, unless additional tooling narrows the scope.

Watch Mode Cheat Sheet

Quick reference for the four combinations of these two settings.

autoWatch	singleRun	Behavior
`true`	`false`	Stays open, reruns on every file change (typical local dev)
`false`	`false`	Stays open, but never reruns automatically (rare)
`true` or `false`	`true`	Runs once, exits with a code (typical CI)
`true`	`true`	Effectively same as above; process exits before watching matters

How Karma Detects File Changes

Karma watches every file matched by the files array (and preprocessors, transitively) using filesystem watchers. When a matched file changes, Karma triggers a fresh run across all currently connected browsers, without restarting the browser processes themselves — which is what keeps reruns fast.

Only files matched by files (directly or via included: true entries) are watched.
Browsers stay open between reruns in watch mode; only the test execution repeats.
Preprocessing (e.g. TypeScript compilation) reruns on the changed file before tests execute again.
restartOnFileChange (rare) forces a full browser restart instead of a lightweight rerun.

A Common npm Script Pattern

Rather than maintaining two config files, most projects keep one karma.conf.js with development-friendly defaults and override behavior for CI purely through CLI flags in a dedicated script.

// package.json
{
  "scripts": {
    "test": "karma start",
    "test:ci": "karma start --single-run --browsers ChromeHeadless"
  }
}

Common Mistakes

Leaving singleRun: false in a CI pipeline, causing the job to hang indefinitely waiting for a run that never exits.
Assuming watch mode reruns only the changed spec file — it reruns the entire matched suite by default.
Not passing --browsers ChromeHeadless in CI while the config's default browser list still includes a visible browser.
Confusing autoWatch (rerun on change) with singleRun (exit after one run) — they solve different problems.

Key Takeaways

autoWatch controls whether Karma reruns tests automatically on file changes.
singleRun controls whether Karma exits after one pass, which is what CI pipelines require.
Both settings can be overridden via CLI flags without editing karma.conf.js.
Browsers stay open across watch-mode reruns, keeping the feedback loop fast.

Pro Tip

If a CI job appears to hang on the Karma step with no error, check singleRun first. It's one of the most common causes of a stuck 'test' job in continuous integration.