Running Karma Unit Tests in Headless Chrome with Custom Launch Flags

\n

Problem: Tests stall in CI because Chrome opens a UI window

\n

When Karma launches Chrome for unit tests, the default launcher tries to open a visible browser window. In headless CI environments this either fails or wastes resources, slowing down the pipeline.

\n\n

Thesis: Use the HeadlessChrome launcher from karma‑chrome‑launcher with custom flags

\n

The karma-chrome-launcher plugin provides a ChromeHeadless launcher that runs Chromium without a UI. You can further tune it with Chrome flags such as --no-sandbox or --disable-gpu to match the constraints of your runner.

\n\n

Installing the plugin

\n

\n
1. Open a terminal in the project root (you need write permission to create node_modules and to install packages).
\n
2. Run:
\n

\n

npm i -D karma karma-chrome-launcher jasmine jasmine-core

\n

This installs Karma, the Chrome launcher, and a test framework as dev dependencies.

\n\n

Configuring karma.conf.js

\n

Create or edit karma.conf.js in the project root:

\n

module.exports = function(config) {\n  config.set({\n    frameworks: ['jasmine'],\n    files: ['test/**/*.spec.js'],\n    browsers: ['ChromeHeadless'],\n    customLaunchers: {\n      ChromeHeadless: {\n        base: 'ChromeHeadless',\n        flags: ['--no-sandbox', '--disable-gpu']\n      }\n    },\n    singleRun: true,\n    autoWatch: false\n  });\n};\n

\n

The browsers array tells Karma to use the launcher named ChromeHeadless. The customLaunchers block defines that launcher, inheriting from the plugin’s base and adding the flags you need.

\n\n

Running the tests

\n

Execute the test suite from the same terminal:

\n

npx karma start --single-run

\n

Karma will launch Chromium in headless mode, run the specs, and print results to the console. You should see a line similar to:

\n

Chrome Headless 112.0.5615.49 (Linux 0.0.0) ...

\n

No browser window appears, confirming the headless launch.

\n\n

Trade‑off and limitation

\n

\n
• Security: The --no-sandbox flag is often required in container‑based CI (e.g., Docker) but reduces the isolation guarantees of Chrome. Evaluate whether your runner already provides sufficient isolation (e.g., user namespaces, VM) before adding it.
\n
• Binary dependency: The launcher expects a chrome or chromium executable in the PATH. On minimal CI images you may need to install it first, e.g., apt-get install -y chromium-browser on Debian‑based systems.
\n
• Plugin version: Versions of karma-chrome-launcher older than 2.2.0 may not recognise newer Chrome flags. Keep the plugin updated (npm outdated karma-chrome-launcher) to match your Chrome version.
\n

\n\n

Practical verification

\n

After the run, check two things:

\n

\n
1. The output contains the string Chrome Headless (or HeadlessChrome) indicating the correct launcher.
\n
2. No graphical browser window popped up on the machine running the command (you can verify by observing the desktop or, in a CI log, by the absence of any GUI‑related error).
\n

\n

If either check fails, revisit the customLaunchers flags or ensure a Chrome binary is installed.

\n\n

Actionable closing

\n

Add the karma-chrome-launcher dependency and the configuration snippet above to your repository. Commit the updated package.json and karma.conf.js. In your CI pipeline, run npx karma start --single-run as part of the test stage. Monitor the launcher line in the logs to confirm headless execution, and periodically update the plugin and Chrome binary to stay compatible.