karma.conf.js Explained

The Shape of karma.conf.js

Every karma.conf.js file exports one function. Karma calls that function once, at startup, passing in a config object with helper methods (like config.set()) and constants (like config.LOG_INFO). Inside the function, you build up a single options object and hand it to config.set().

Because it's a real JavaScript file (not JSON or YAML), you can use conditionals, environment variables, and require() freely — a common pattern is branching on process.env.CI to change browsers or reporters between local development and continuous integration.

module.exports = function(config) {
  const isCI = !!process.env.CI;

  config.set({
    basePath: '',
    frameworks: ['jasmine'],
    files: ['src/**/*.spec.js'],
    browsers: [isCI ? 'ChromeHeadlessCI' : 'Chrome'],
    singleRun: isCI,
    customLaunchers: {
      ChromeHeadlessCI: {
        base: 'ChromeHeadless',
        flags: ['--no-sandbox']
      }
    }
  });
};

Because the file is plain JavaScript, branching logic like this isCI check is completely normal and encouraged.

Commonly Used config.set() Options

config.set({
  basePath: '',            // resolves relative paths
  frameworks: [],          // e.g. ['jasmine']
  files: [],                // files/patterns to load
  exclude: [],               // patterns to exclude
  preprocessors: {},         // transform files before serving
  reporters: [],              // e.g. ['progress']
  port: 9876,                  // server port
  colors: true,                 // colorized terminal output
  logLevel: config.LOG_INFO,    // verbosity
  browsers: [],                  // e.g. ['ChromeHeadless']
  autoWatch: true,               // rerun on file changes
  singleRun: false,               // exit after one run
  concurrency: Infinity            // parallel browser limit
});

• config.LOG_INFO, config.LOG_DEBUG, etc. are constants provided on the config object itself.
• Every option has a sensible internal default; you only need to override what your project requires.
• Order inside config.set() doesn't matter functionally, but grouping related options improves readability.
• You can call config.set() more than once if you build the object incrementally, though most projects call it once.

karma.conf.js Options Cheat Sheet

The options you'll touch in almost every project.

How Karma Finds and Loads the Config File

By default, karma start looks for karma.conf.js in the current working directory. You can point it at a different file explicitly, which is how many projects maintain separate configs for local development versus CI.

karma start                     # uses ./karma.conf.js
karma start karma.ci.conf.js    # uses an explicit alternate file
karma start config/karma.conf.js

Sharing Logic Between Config Files

For projects that need meaningfully different local vs. CI behavior, a common pattern is a base config file that exports shared settings, imported and extended by environment-specific files.

// karma.base.conf.js
module.exports = {
  frameworks: ['jasmine'],
  files: ['src/**/*.spec.js']
};

// karma.ci.conf.js
const base = require('./karma.base.conf.js');
module.exports = function(config) {
  config.set({
    ...base,
    browsers: ['ChromeHeadlessCI'],
    singleRun: true
  });
};

This keeps shared settings in one place while letting CI-specific settings live separately and explicitly.

Common Mistakes

• Forgetting the file must export a function, not a plain options object.
• Calling config.set() with an incomplete object and assuming Karma merges deeply where it actually replaces top-level keys.
• Duplicating an entire config for CI instead of sharing common settings and only overriding what differs.
• Not checking process.env.CI (or an equivalent flag) when local and CI environments genuinely need different browsers.

Key Takeaways

• karma.conf.js exports a function that receives a config object and calls config.set().
• Because it's plain JavaScript, conditional logic based on environment variables is a normal, supported pattern.
• Karma looks for ./karma.conf.js by default, but any file path can be passed explicitly to karma start.
• Splitting shared vs. environment-specific settings into separate files keeps larger configs maintainable.