jamcoupe / karma-commonjs

A Karma plugin. Test CommonJS modules.

@jcoup/karma-commonjs

A Karma plugin that allows testing CommonJS modules in the browser.

Browserify

If you're using Browserify to compile your projects, you should consider karma-browserify which runs Browserify directly. The cost is slightly slower builds (but not too bad, thanks to an incremental loading algorithm) and somewhat messier stack traces. The benefit is support for the full Browserify API and automatic discovery of 'require'd files.

karma-commonjs

1. Provides a lightweight commonjs wrapper around your code
2. Supports Node's require algorithm
3. Only reloads files that change
4. Provides stack traces that point to your original files
5. Requires you to specify files in the Karma config file

karma-browserify

1. Creates a temporary bundle using Browserify
2. Supports the full Browserify API, including transforms, plugins, and shims for Node globals
3. Uses watchify to perform incremental rebuilds
4. Can use source maps to provide useful stack traces
5. Automatically includes required files

Installation

The easiest way is to keep @jcoup/karma-commonjs as a devDependency:

npm install @jcoup/karma-commonjs --save-dev

which should result in the following entry in your package.json:

{
  "devDependencies": {
    "@jcoup/karma-commonjs": "X.X.X"
  }
}

Configuration

// karma.conf.js
module.exports = function(config) {
  config.set({
    frameworks: ['jasmine', 'commonjs'],
    files: [
      // your tests, sources, ...
    ],

    preprocessors: {
      '**/*.js': ['commonjs']
    }
  });
};

Additionally you can specify a root folder (relative to project's directory) which is used to look for required modules:

commonjsPreprocessor: {
  modulesRoot: 'some_folder'  
}

When not specified the root folder defaults to the karma.basePath/node_modules configuration option.

Externals

When external dependencies have prebundled sources. You can specify what file should be included from the root folder

// karma.conf.js
module.exports = function(config) {
  config.set({
    // ...
    commonjsPreprocessor: {
      modulesRoot: 'components',
      externals: {
        'angular': 'angular/angular.min.js'
      }
    },
    // ...
  });
};

This effectively translates any require('angular') statements into require('./components/angular/angular.min.js').

---

For an example project, check out Karma's client tests.

---

For more information on Karma see the homepage.