Diagnosing Karma Browser-Launch Failures in CI & Local Workflows

Problem: Karma Tests Hang or Report Disconnected in CI

You execute karma start in a continuous integration pipeline or on a headless workstation. The Karma server starts and reports a browser, but tests never begin or finish with a Disconnected status. The process may also hang indefinitely if singleRun is not configured.

Diagnostic Table: Condition to Likely Cause

Ordered Checks

1. Verify the Chrome/Chromium binary. Run google-chrome --headless --version or chromium --version in the CI shell. If the command is not found or returns an error, Karma cannot launch a browser. Install the binary or set the CHROME_BIN environment variable to its absolute path.

2. Confirm the browsers array matches installed launchers. In karma.conf.js, the browsers list (e.g., "ChromeHeadless") must correspond to a launcher package in node_modules such as karma-chrome-launcher. Run npm list karma-chrome-launcher to verify the package is present.

3. Inspect debug logs for launch attempts. Start Karma with logLevel: DEBUG. Look for lines indicating the browser was launched and captured, or repeated attempt messages without success. If you see Attempting to launch Chrome followed quickly by Disconnected, the binary path or flags may be misconfigured.

4. Check singleRun and autoWatch settings. In CI, set singleRun: true so Karma exits after tests complete. Leaving it false causes the process to wait for manual browser capture, which pipelines do not expect. Similarly, autoWatch: true is intended for local development; disable it in CI pipelines.

5. Add container-specific flags if needed. On Linux running as root or in Docker, Chrome often requires the --no-sandbox flag to start. You can inject it via customLaunchers in karma.conf.js:

   customLaunchers: {"chrome-ci": {"base": "ChromeHeadless", "flags": ["--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage"]}}

   Then update the browsers array to reference the custom launcher: ["chrome-ci"].

Fixes Tied to Findings

• Missing binary: Install Chrome or Chromium, or set CHROME_BIN=/opt/chrome/chrome (or wherever the binary lives) in the environment before running Karma.
• Mismatched browsers array: Align the array value with the installed launcher package name, or rename the custom launcher entry to match what karma-chrome-launcher expects.
• Repeated failed launch attempts: Correct CHROME_BIN or fix the browsers value after inspecting the DEBUG output.
• Container launches failing: Add --no-sandbox via customLaunchers flags (see example above) or the Docker/CI runner's runtime flags. Note: --no-sandbox reduces Chrome isolation and should only be used in trusted CI containers, not on general developer workstations.
• Tests hang because singleRun: false: Change to true for CI, or manually capture a browser by opening the Karma server address printed in the terminal if you need interactive debugging.

Escalation Criteria

If none of the ordered checks resolve the issue, gather the following before escalating:

• Full karma start output with logLevel: DEBUG
• Output of google-chrome --headless --version or chromium --version
• Karma and Node.js versions (npm list karma and node --version)
• Operating system and container runtime details (e.g., Docker version, Kubernetes node labels)

At this point, the problem may involve an unsupported Chrome version, a custom launcher plugin, or a permission issue outside Karma's default configuration.