Diagnosing Karma Test Runner Failures with ChromeHeadless and autoWatch

Recognizable Condition

When running Karma tests you may see one of the following symptoms:

• Karma reports "Chrome could not be launched" even though ChromeHeadless is installed.
• The test runner hangs or restarts repeatedly when autoWatch is enabled, never exiting.
• No test results appear in the console or CI logs.
• Karma aborts with "Failed to load script" messages during test compilation.
• The server starts but no browsers attach, yielding a "No browsers started" error.
• Tests pass locally but fail in CI due to stale cache or version mismatches.

Cause & Diagnostic Table

Symptom	Likely Cause
Chrome could not be launched	Chrome binary path mis‑resolved or missing from PATH; architecture mismatch.
Tests hang/restart with autoWatch	Stale watched files or a background process keeping the watcher active.
No results emitted	Reporter missing, misnamed, or throwing an error; custom reporter not tested.
Failed to load script	Preprocessor (webpack/Babel) syntax error or unsupported language feature.
No browsers started	Browser launcher missing or misnamed in browsers array.
CI‑only failures	Stale Karma cache, outdated test harness, or version mismatch with Angular CLI.

Ordered Checks

1. Verify Chrome binary location:

   # Run in the project root
   which chrome   # or which google-chrome
   karma start --single-run --log-level=debug
   

   Look for a log line similar to Chrome binary at /usr/bin/google-chrome. If the path differs from the which output, correct it in karma.conf.js under customLaunchers or ensure the binary is on PATH.
2. Check autoWatch behavior:

   karma start --single-run
   

   If the process does not exit, examine the debug log for repeated Watching messages. Temporarily set autoWatch: false and re‑run to confirm the hang is watcher‑related.
3. Inspect reporter configuration:

   # In karma.conf.js
   reporters: ['progress']   # replace custom reporter temporarily
   

   Run the tests again. If output appears, the original custom reporter is faulty; fix or remove it.
4. Validate preprocessor pipeline:

   # Example for webpack
   npm run build   # or the script that invokes webpack/babel
   

   Ensure no compilation errors are reported before starting Karma.
5. Confirm browser launcher presence:

   # In karma.conf.js
   browsers: ['ChromeHeadless']
   

   Run karma start --browsers ChromeHeadless. If you still see "No browsers started", verify that the karma-chrome-launcher package is installed and that the launcher name matches exactly.
6. Check for stale cache or version mismatches:

   rm -rf node_modules/.cache/karma
   npm install   # reinstalls exact versions
   karma start --single-run
   

   If using Angular, ensure @angular-devkit/build-angular version matches the Angular CLI version specified in package.json.

Fixes Tied to Findings

• Chrome launch failure – Add or correct the chromeBinary property in a custom launcher:

  customLaunchers: {
    ChromeHeadless: {
      base: 'ChromeHeadless',
      flags: ['--no-sandbox']
    }
  }
  

  Ensure the binary path is absolute if PATH cannot be relied upon.
• autoWatch hang – Disable watcher in CI and use a file‑watch exclusion list:

  autoWatch: process.env.CI ? false : true,
  exclude: ['node_modules/**', 'dist/**']
  

• Missing reporter output – Replace the custom reporter with a known‑good one or fix its implementation; verify locally before committing.
• Preprocessor syntax error – Update webpack/Babel config to support the language features used in test files (e.g., add @babel/preset-env or appropriate loader).
• No browsers started – Install the launcher if missing:

  npm install --save-dev karma-chrome-launcher
  

  Then ensure the launcher name is exactly ChromeHeadless in the browsers array.
• CI‑only failures – Clear Karma cache and align dependency versions; consider adding a ci script that sets autoWatch: false and runs karma start --single-run.

Escalation Criteria

1. If after applying the above checks the Chrome binary still cannot be launched, verify the OS architecture (e.g., ARM vs x86) and obtain a compatible Chrome build.
2. When autoWatch continues to cause infinite loops despite autoWatch: false, inspect for external processes that may be touching watched files (e.g., IDE indexers) and consider narrowing the watched glob.
3. If a custom reporter is required and continues to fail after local testing, capture its error output and treat it as a separate bug; fallback to the built‑in reporters for CI until resolved.
4. For persistent preprocessor failures, run the build step in isolation and consult the respective tool’s documentation; if the error is unrelated to Karma, address it in the webpack/Babel configuration.
5. Should the "No browsers started" error persist after confirming launcher installation, check for SELinux/AppArmor or container restrictions that block the Chrome sandbox; adjust security policies or run with --no-sandbox as a temporary measure.

Verification

After each fix, run the following command to confirm the symptom is resolved:

karma start --single-run --log-level=info

Look for:

• A line indicating Chrome launched successfully.
• The test runner exiting with a summary (e.g., Chrome Headless 115.0.0.0 (Linux 0.0.0): Executed 12 of 12 SUCCESS).
• No hanging or repeated restart messages.

If the output matches expectations, the issue is considered resolved for the current environment.