Configure Karma with ChromeHeadless for CI/CD Test Execution

Desired outcome

Run your JavaScript unit tests with Karma using ChromeHeadless so that the test suite executes in a CI/CD pipeline without requiring a graphical display.

Prerequisites

1. Node.js (≥12) and npm installed on the build agent or local machine.
2. A project with existing Karma‑compatible tests (Jasmine, Mocha, etc.).
3. Google Chrome or Chromium binary available in the environment where Karma will launch the browser.
4. Basic familiarity with editing a karma.conf.js file.

Procedure

1. Install required npm packages

From the project root, run:

# Install Karma core and the ChromeHeadless launcher
npm install --save-dev karma karma-chrome-launcher
# Install your test framework if not already present (example: Jasmine)
npm install --save-dev jasmine karma-jasmine

These commands modify node_modules and the package.json devDependencies. Ensure you have write permission to the project directory.
2. Create or edit karma.conf.js
Add a configuration that selects the ChromeHeadless launcher, sets the test framework, and enables single‑run mode for CI.
module.exports = function(config) {
  config.set({
    // Base path used to resolve files and exclude patterns
    basePath: '',
    
    // Test framework(s) to use
    frameworks: ['jasmine'],
    
    // Files to include in the test run
    files: [
      'src/**/*.js',
      'test/**/*.spec.js'
    ],
    
    // Preprocess matching files before serving them to the browser
    preprocessors: {},
    
    // Launch Chrome in headless mode
    browsers: ['ChromeHeadless'],
    
    // Optional: increase timeout if the browser takes longer to start
    browserDisconnectTimeout: 10000,
    browserDisconnectTolerance: 3,
    
    // Run once and exit (CI friendly)
    singleRun: true,
    
    // Reporter to output results
    reporters: ['progress'],
    
    // Port for the Karma web server (default 9876)
    port: 9876,
    
    // Enable colors in the output
    colors: true,
    
    // Log level: config.LOG_DISABLE, config.LOG_ERROR, config.LOG_WARN, config.LOG_INFO, config.LOG_DEBUG
    logLevel: config.LOG_INFO,
    
    // Enable auto‑watch for local development (ignored when singleRun:true)
    autoWatch: false
  });
};

3. Verify Chrome binary availability
Karma will attempt to locate google-chrome or chromium-browser in the system PATH. If the binary is not found, you can explicitly point to it:
customLaunchers: {
  ChromeHeadlessCI: {
    base: 'ChromeHeadless',
    flags: ['--no-sandbox', '--disable-dev-shm-usage']
  }
},
browsers: ['ChromeHeadlessCI']

The flags --no-sandbox and --disable-dev-shm-usage are often required in Docker containers or restricted CI agents.
4. Run the test suite
Execute Karma from the project directory:
npx karma start karma.conf.js

Observe the console output for the connection message and test results.
Expected checks

After starting, the output should contain a line similar to:
"ChromeHeadless …: Connected on socket …"
Test results are reported by the chosen reporter (e.g., "… specs, 0 failures" for Jasmine).
When singleRun: true is set, the process exits with code 0 on success or a non‑zero code on failure.
If you added the ChromeHeadlessCI launcher, verify that the flags appear in the Chrome process list (you can inspect with ps aux | grep chrome on the agent).

Recovery options
Browser not found
If Karma reports "Cannot start ChromeHeadless", ensure:

Chrome/Chromium is installed (which google-chrome returns a path).
The user running Karma has execute permission on the binary.
In containerized environments, add the required flags (--no-sandbox) as shown above.

Test hangs or disconnects
Increase browserDisconnectTimeout and browserDisconnectTolerance values, or check console output for JavaScript errors that prevent the test page from loading.
Memory pressure
Large test suites may cause the browser to consume excessive memory. Monitor memory usage on the agent and consider splitting tests into multiple Karma runs or enabling the browserNoActivityTimeout flag.
Limitations
Karma does not bundle browsers; you must provide a compatible Chrome/Chromium binary. The headless launcher cannot be used for tests that rely on visual UI interactions (e.g., screenshot comparisons) without additional tooling. In some minimal CI images, the required libraries for Chrome may be missing, leading to startup failures; installing dependencies like libgconf-2-4 or fonts-liberation may be necessary.
Practical verification
After a successful run, you can confirm the exit code with:
echo $?

A value of 0 indicates all tests passed and Karma shut down cleanly. Any other value signals a failure; consult the Karma output for details.