Karma Chrome Launcher

karma-chrome-launcher is the most widely used Karma launcher package, providing Chrome, ChromeHeadless, and related configurations. This lesson covers installing, configuring, and troubleshooting it.

Installing and Using karma-chrome-launcher

karma-chrome-launcher provides launcher configurations for the entire Chrome family: Chrome (visible window), ChromeHeadless (no window, ideal for CI and terminals), ChromeCanary, and Edge (Chromium-based Edge, on supported platforms).

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

// karma.conf.js
config.set({
  browsers: ['ChromeHeadless']
});

This is the single most common launcher setup in modern Karma configurations, since headless Chrome works reliably in both local terminals and CI.

Common Chrome Launcher Names

Chrome            // visible window, useful for local debugging
ChromeHeadless     // no window, standard for CI and automated runs
ChromeCanary        // Chrome Canary build, if installed
Edge                 // Chromium-based Edge (where supported)

ChromeHeadless is the standard default for automated (non-interactive) runs.
Chrome (visible) is primarily useful when you want to watch tests execute or open devtools.
Karma looks for a standard Chrome/Chromium install path automatically before falling back to CHROME_BIN.
Chromium (the open-source base of Chrome) also works and is common on Linux CI images.

Chrome Launcher Cheat Sheet

Configuration snippets you'll reach for constantly.

Need	Configuration
Basic headless run	`browsers: ['ChromeHeadless']`
Point at a custom binary	`process.env.CHROME_BIN = '/path/to/chrome'`
No-sandbox for containers	`customLaunchers: { CI: { base: 'ChromeHeadless', flags: ['--no-sandbox'] } }`
Visible debugging window	`browsers: ['Chrome']`
Disable GPU (some CI images)	add `'--disable-gpu'` to `flags`

The --no-sandbox Flag in Containers

Chrome's sandboxing model frequently conflicts with the restricted permissions inside Docker containers and some CI runners, producing a launch failure. The standard, widely documented fix is a custom launcher that adds --no-sandbox (and often --disable-gpu) to ChromeHeadless.

customLaunchers: {
  ChromeHeadlessCI: {
    base: 'ChromeHeadless',
    flags: ['--no-sandbox', '--disable-gpu', '--disable-dev-shm-usage']
  }
},
browsers: ['ChromeHeadlessCI']

--disable-dev-shm-usage avoids a separate, common /dev/shm crash in memory-constrained containers.

Troubleshooting CHROME_BIN

When Karma can't find a Chrome binary automatically, it throws a clear launch error naming the browser it tried to start. Setting CHROME_BIN (or process.env.CHROME_BIN inside the config file itself) resolves the vast majority of these cases.

// Inside karma.conf.js, before config.set():
if (process.env.CHROMIUM_BIN) {
  process.env.CHROME_BIN = process.env.CHROMIUM_BIN;
}

// Or directly on the command line before running:
export CHROME_BIN=$(which chromium-browser)

Common Mistakes

Not adding --no-sandbox in Docker/CI environments, resulting in cryptic Chrome launch failures.
Assuming ChromeHeadless and Chrome behave identically in every case — some rendering/timing differences exist.
Setting CHROME_BIN to a directory instead of the actual binary file path.
Forgetting --disable-gpu on some minimal CI images where GPU acceleration paths are unavailable.

Key Takeaways

karma-chrome-launcher provides Chrome, ChromeHeadless, ChromeCanary, and Edge launcher configurations.
ChromeHeadless is the standard choice for CI and other non-interactive runs.
--no-sandbox is the most common flag needed to run Chrome successfully inside containers.
CHROME_BIN is the standard escape hatch when Karma can't automatically locate a Chrome/Chromium binary.

Pro Tip

Keep a dedicated ChromeHeadlessCI custom launcher in every project's karma.conf.js, even if you don't currently run in Docker. The moment someone containerizes CI later, the fix is already in place instead of becoming a surprise debugging session.