Karma Adapter for RequireJS

Common errors

• Uncaught Error: Script error for: [module name]

  cause RequireJS failed to load a module, often due to an incorrect path in `require.config` or the file not being served by Karma.
  fix Verify `baseUrl` in `test-main.js` and `paths` configuration. Ensure the module's file pattern is listed in `karma.conf.js` `files` array with `included: false`, and that `test-main.js` is included last. Check browser console for network errors (404s).

• Executed 0 of 0 ERROR

  cause Karma is running but not finding any tests, typically because RequireJS isn't correctly bootstrapping the tests or test files aren't being loaded.
  fix Ensure `test-main.js` is the last entry in `karma.conf.js` `files` array (and *not* `included: false`). Verify `test-main.js`'s `deps` array correctly identifies your spec files (e.g., `allTestFiles`) and that `window.__karma__.start` is called in the `callback`.

• There is no timestamp for /base/src/app.js!

  cause Karma internal error related to serving files, often when `basePath` or file patterns are misconfigured relative to the project root and `test-main.js`.
  fix Double-check `basePath` in `karma.conf.js` and ensure that file patterns like `{pattern: 'src/**/*.js', included: false}` correctly resolve to existing files. Review the `baseUrl` in `test-main.js` to ensure it matches the server's path (e.g., starting with `/base/`). Karma serves files under `/base`.

Warnings

• breaking The underlying Karma test runner is officially deprecated by the Angular team, and RequireJS itself is largely superseded by ES6 modules and modern bundlers (e.g., Webpack, Vite). This `karma-requirejs` package is unmaintained, meaning no new features, bug fixes, or compatibility updates will be provided.
  Fix: For new projects, consider modern alternatives like Web Test Runner, Jest, or Vitest. For existing projects, evaluate migrating away from RequireJS and Karma.
• gotcha Correctly configuring the `files` array in `karma.conf.js` is critical. Application and test files intended for RequireJS loading must be listed with `included: false`. Only the `test-main.js` file (which bootstraps RequireJS) should be included directly and must be the last entry.
  Fix: Ensure all RequireJS-managed files use `{pattern: 'path/**/*.js', included: false}`. The `test-main.js` file should be listed last, e.g., `'test/test-main.js'`.
• gotcha RequireJS's `baseUrl` in `test-main.js` must accurately map to the Karma server's `/base` directory. Incorrect relative paths or `baseUrl` settings will result in 'Script error' messages, as RequireJS won't find your modules.
  Fix: Set `baseUrl` in `test-main.js` to start with `/base/`, e.g., `baseUrl: '/base/src'`. Double-check all module paths defined in `require.config` relative to this `baseUrl`.
• gotcha Being last updated in 2016, this plugin may have compatibility issues with newer versions of Node.js, modern browser environments, or other Karma plugins that rely on more recent JavaScript features or promise implementations.
  Fix: Test thoroughly in your target environments. If encountering unexpected errors, consider pinning older Node.js versions or replacing `karma-requirejs` with a more modern testing setup.

Install

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

Imports

• frameworks

  module.exports = function(config) { config.set({ frameworks: ['jasmine', 'requirejs'] }); };

  The 'requirejs' string is added to the frameworks array in `karma.conf.js` to enable the plugin.
• files
  wrong:

  files: ['src/**/*.js', 'test/test-main.js']

  correct:

  files: [{pattern: 'src/**/*.js', included: false}, 'test/test-main.js']

  RequireJS-managed files must have `included: false` in `karma.conf.js` to prevent Karma from loading them directly via script tags. `test-main.js` must be the last entry and `included: true` (default).
• require.config

  require.config({ baseUrl: '/base/src', deps: allTestFiles, callback: window.__karma__.start });

  This configuration is placed in a separate `test-main.js` file, defining RequireJS's `baseUrl` (relative to Karma's `/base` directory), listing test dependencies, and initiating Karma's test run.

Quickstart

This quickstart demonstrates the core configuration for Karma with RequireJS. It includes a `karma.conf.js` that sets up the RequireJS framework and correctly identifies files to be loaded via RequireJS, along with a `test-main.js` file that configures RequireJS module paths and then dynamically loads and starts the tests.

/* karma.conf.js */
module.exports = function(config) {
  config.set({
    basePath: '',
    frameworks: ['jasmine', 'requirejs'],
    files: [
      // All application and test files need to be available but NOT included as script tags
      // except for test-main.js which bootstraps RequireJS
      {pattern: 'lib/**/*.js', included: false},
      {pattern: 'src/**/*.js', included: false},
      {pattern: 'test/**/*Spec.js', included: false},
      // test-main.js must be the last file and included normally
      'test/test-main.js'
    ],
    exclude: [
      'src/main.js' // Exclude the main application entry point if it starts the app automatically
    ],
    preprocessors: {},
    reporters: ['progress'],
    port: 9876,
    colors: true,
    logLevel: config.LOG_INFO,
    autoWatch: true,
    browsers: ['Chrome'],
    singleRun: false,
    concurrency: Infinity
  });
};

/* test/test-main.js */
var allTestFiles = [];
var TEST_REGEXP = /(spec|test)\.js$/i;

// Get a list of all the test files to include
Object.keys(window.__karma__.files).forEach(function(file) {
  if (TEST_REGEXP.test(file)) {
    // Normalize paths to RequireJS module names.
    // If you require sub-dependencies of test files to be loaded as-is (requiring file extension)
    // then do not normalize the paths.
    allTestFiles.push(file.replace(/\/base\//, '').replace(/\.js$/, ''));
  }
});

require.config({
  // Karma serves files under /base, which is the basePath from your config file
  baseUrl: '/base/src',

  paths: {
    // Define your module paths here, e.g., for libraries or common components
    'jquery': '../lib/jquery',
    'underscore': '../lib/underscore'
  },

  shim: {
    'underscore': {
      exports: '_'
    },
    'jquery': {
      exports: '$'
    }
  },

  // Dynamically load all test files
  deps: allTestFiles,

  // We have to kickoff Karma, as it is asynchronous
  callback: window.__karma__.start
});