Karma browser launcher configuration for environment parity

Direct answer

Pin the same Chrome/Chromium binary across local machines and CI; Karma does not synchronize browser versions itself. Then define a headless customLauncher in karma.conf.js with explicit chromeFlags, singleRun: true, and autoWatch: false for CI runs.

Confirmed facts versus likely explanation

Confirmed facts

• Karma launcher names such as Chrome and ChromeHeadless resolve to the installed browser binary; they do not install or version a browser.
• Karma has no built-in mechanism to lock or synchronize browser versions across environments.
• customLaunchers in karma.conf.js lets you define chromeFlags for each target.
• singleRun: true and autoWatch: false are appropriate for CI headless execution.

Likely explanation

Inconsistent outcomes between local headed debugging and CI headless runs are most likely caused by mismatched Chrome binaries or by headless-specific flags changing layout and timing, rather than by Karma treating the launchers as separate browser versions.

Configuration steps

1. Install the same Chrome/Chromium version on developer machines and CI, or use a pinned Docker image containing that browser.
2. In karma.conf.js, define a headless custom launcher that reuses the same binary with explicit flags:

module.exports = function (config) {
  config.set({
    browsers: ['ChromeHeadlessCI'],
    customLaunchers: {
      ChromeHeadlessCI: {
        base: 'ChromeHeadless',
        flags: [
          '--headless=new',
          '--no-sandbox',
          '--disable-gpu',
          '--disable-dev-shm-usage'
        ]
      }
    },
    singleRun: true,
    autoWatch: false
  });
};

Use --headless=new only on Chrome 109 or later; on older Chrome, use --headless and verify startup. --no-sandbox and --disable-dev-shm-usage are typically required when CI runs as root or inside containers.

1. Run headed locally with a separate launcher if needed, but keep the browser binary identical:

ChromeLocalDebug: {
  base: 'Chrome',
  flags: []
}

Verification

• Run google-chrome --version or chromium-browser --version on every machine and CI agent; versions must match.
• Add a temporary test that logs navigator.userAgent to confirm the launched instance matches the expected baseline.

Missing diagnostic detail: What Chrome/Chromium binary and version is installed on your CI runners? This determines whether to pin a system package, a Docker image, or a Karma launcher binary path.

Assumptions and uncertainty

Assumes Karma 6.x with karma-chrome-launcher. Flag behavior may differ by Chrome version; --headless=new is unsupported before Chrome 109. Treat launcher flag names as version-dependent until verified against your installed Chrome.