Karma Launchers

What a Launcher Plugin Does

A launcher plugin implements the mechanics of starting one specific kind of browser process: locating its binary, building the correct command-line flags, pointing it at the Karma server's URL, and tearing it down cleanly when the run finishes. karma-chrome-launcher handles this for every Chrome-family browser (Chrome, ChromeHeadless, ChromeCanary, Edge); karma-firefox-launcher handles it for Firefox.

Karma ships no launchers built in — every single browser, including the very common ChromeHeadless, requires installing its launcher package explicitly.

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

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

ChromeHeadless is a launcher configuration name provided by karma-chrome-launcher, not a built-in Karma concept.

Base Launchers vs. customLaunchers

// Using a launcher's built-in configuration directly:
browsers: ['ChromeHeadless']

// Extending a launcher's base configuration with custom flags:
customLaunchers: {
  ChromeHeadlessNoSandbox: {
    base: 'ChromeHeadless',
    flags: ['--no-sandbox', '--disable-gpu']
  }
},
browsers: ['ChromeHeadlessNoSandbox']

• A launcher package exports one or more base launcher configurations (like ChromeHeadless).
• customLaunchers lets you extend a base configuration with additional flags, without writing a plugin.
• The base key names which built-in launcher configuration to start from.
• Custom launcher names are your own choice — they don't need to match any built-in naming convention.

Launcher Cheat Sheet

The most common launcher packages and what they provide.

The Launcher Lifecycle

A launcher plugin's responsibilities extend beyond just starting a process. It also monitors the browser's connection state, handles crashes and unexpected disconnects, and ensures the browser process is fully killed when a run ends — important for avoiding orphaned browser processes on CI machines.

• Start: locate the binary and launch it with the right flags, pointed at the Karma server URL.
• Monitor: track connection state and respond to unexpected disconnects.
• Retry/report: surface capture failures clearly instead of hanging silently.
• Kill: terminate the browser process cleanly at the end of the run or on Ctrl+C.

Environment Variable Overrides

Most launcher packages respect an environment variable pointing at a non-standard binary location, which is the standard fix when a CI image's browser lives somewhere the launcher doesn't automatically check.

export CHROME_BIN=/usr/bin/chromium
export FIREFOX_BIN=/usr/lib/firefox/firefox
karma start --single-run

Check the specific launcher package's README for its exact expected variable name — most Chrome-family launchers use CHROME_BIN.

Common Mistakes

• Assuming any browser name is 'built into' Karma itself rather than provided by an installed launcher package.
• Writing a fully custom launcher plugin when customLaunchers with a base and extra flags would be enough.
• Not cleaning up orphaned browser processes after abnormal Karma exits (e.g. Ctrl+C during a hung run).
• Forgetting that customLaunchers entries need a real base launcher to extend — they can't exist standalone.

Key Takeaways

• Launcher plugins handle starting, monitoring, and killing specific browser processes.
• No browser (including ChromeHeadless) is built into Karma — every one requires an installed launcher package.
• customLaunchers extends a base launcher configuration with extra flags without writing a full plugin.
• Environment variables like CHROME_BIN are the standard way to point launchers at non-standard binary locations.