Karma CommonJS Plugin

Common errors

• ReferenceError: require is not defined

  cause A file attempting to use `require()` was not processed by the `commonjs` preprocessor, or a required module was not included in Karma's `files` configuration.
  fix Ensure the file (and its dependencies) are listed in `karma.conf.js` within the `files` array and have the `commonjs` preprocessor applied: `preprocessors: { 'path/to/my-module.js': ['commonjs'] }`.

• Error: Cannot find module 'some-module'

  cause The module being `require()`d is not found at the expected path, or the `commonjsPreprocessor.modulesRoot` is incorrectly configured.
  fix Verify the module's path is correct relative to the file requiring it, or adjust the `commonjsPreprocessor.modulesRoot` option in `karma.conf.js` to point to the directory containing your modules.

Warnings

• breaking The underlying Karma test runner is officially deprecated. `karma-commonjs` is not actively maintained and is unlikely to receive updates or security fixes.
  Fix: Consider migrating to modern test runners and module bundlers/transpilers (e.g., Jest, Vitest, Web Test Runner with Rollup/Webpack) which offer native ESM/CJS support and better performance.
• gotcha Unlike bundler-based solutions (e.g., `karma-browserify`), `karma-commonjs` requires you to explicitly specify ALL CommonJS module files in the `files` array and `preprocessors` configuration within `karma.conf.js`. It does not automatically discover `require()`d dependencies.
  Fix: Ensure every file that acts as a CommonJS module (source or test) is listed in the `files` array and associated with the `commonjs` preprocessor. Failing to do so will result in `require` not being defined for undeclared modules.
• gotcha `karma-commonjs` provides a simpler CommonJS wrapping mechanism but lacks the full feature set of a bundler like Browserify. It does not natively support Browserify transforms, plugins, or shims for Node.js core modules.
  Fix: If your project relies on advanced Browserify features, consider using `karma-browserify` instead. For simple CommonJS module testing without complex bundling needs, `karma-commonjs` might suffice but be aware of its limitations.

Install

• npm install karma-commonjs npm
• yarn add karma-commonjs yarn
• pnpm add karma-commonjs pnpm

Imports

• commonjs
  wrong:

  import { commonjs } from 'karma-commonjs';

  correct:

  // karma.conf.js
  module.exports = function(config) {
    config.set({
      frameworks: ['jasmine', 'commonjs'],
      // ...
    });
  };

  This package is a Karma plugin and is configured within `karma.conf.js` using string identifiers, not directly imported into user code. 'commonjs' is added to the 'frameworks' array.
• commonjs preprocessor
  wrong:

  const commonjsPreprocessor = require('karma-commonjs');

  correct:

  // karma.conf.js
  module.exports = function(config) {
    config.set({
      // ...
      preprocessors: {
        '**/*.js': ['commonjs']
      }
    });
  };

  The 'commonjs' string is used as a preprocessor name in `karma.conf.js` to process files as CommonJS modules.
• commonjsPreprocessor.modulesRoot
  wrong:

  config.commonjs.modulesRoot = 'src';

  correct:

  // karma.conf.js
  module.exports = function(config) {
    config.set({
      // ...
      commonjsPreprocessor: {
        modulesRoot: 'src/modules'
      }
    });
  };

  Configuration options for the CommonJS preprocessor are nested under `commonjsPreprocessor` in `karma.conf.js`. The `modulesRoot` specifies where `require` calls should look for modules, defaulting to `karma.basePath/node_modules`.

Quickstart

This configuration demonstrates how to set up Karma with `karma-commonjs` to test CommonJS modules. It includes the `commonjs` framework and preprocessor, along with an example of configuring `modulesRoot`.

const path = require('path');

module.exports = function(config) {
  config.set({
    basePath: '',
    frameworks: ['jasmine', 'commonjs'],
    files: [
      // Your source files (e.g., 'src/**/*.js')
      'test/lib.js',
      'test/**/*.spec.js'
    ],
    exclude: [],
    preprocessors: {
      'test/lib.js': ['commonjs'],
      'test/**/*.spec.js': ['commonjs']
    },
    reporters: ['progress'],
    port: 9876,
    colors: true,
    logLevel: config.LOG_INFO,
    autoWatch: true,
    browsers: ['ChromeHeadless'],
    singleRun: false,
    concurrency: Infinity,
    
    // Optional configuration for commonjsPreprocessor
    commonjsPreprocessor: {
      modulesRoot: path.resolve(__dirname, 'src') // Example: look for required modules in 'src' folder
    }
  });
};

// Example test/lib.js:
// module.exports = { greet: (name) => `Hello, ${name}!` };

// Example test/lib.spec.js:
// const { greet } = require('./lib');
// describe('greet', () => {
//   it('should return a greeting', () => {
//     expect(greet('World')).toBe('Hello, World!');
//   });
// });