Karma TypeScript Preprocessor

Common errors

• ERROR [preprocessor]: Can not load "typescript" preprocessor!

  cause The `karma-typescript-preprocessor` package or its dependency `typescript` is not installed, or Karma cannot find the preprocessor definition.
  fix Ensure `karma-typescript-preprocessor` is installed: `npm install --save-dev karma-typescript-preprocessor`. Also, verify that `typescript` is installed as a dependency (`npm install --save-dev typescript`). Check your `karma.conf.js` to confirm `preprocessors: { '**/*.ts': ['typescript'] }` is correctly configured.

• TSxxxx: Cannot find name '...' / Property '...' does not exist on type '...'.

  cause The TypeScript compiler version or configuration used by the preprocessor (version 0.4.0) is incompatible with your project's TypeScript code, or it's missing `@types` declarations. This preprocessor is very old and likely struggles with modern TS syntax or libraries.
  fix Review the `typescriptPreprocessor.options` in `karma.conf.js` to ensure `target`, `module`, and other compiler options align with your project. If using modern TypeScript, consider migrating to a more up-to-date Karma TypeScript preprocessor like `karma-typescript`.

• ReferenceError: define is not defined / require is not defined

  cause This error typically occurs when the `module` option in `typescriptPreprocessor.options` is set to `amd` or `commonjs` respectively, but the test environment (browser) lacks the corresponding module loader.
  fix If targeting browsers without a module loader, set `module: 'none'` or ensure an AMD/CommonJS loader (e.g., RequireJS for AMD, a bundler for CommonJS) is included in your Karma `files` array before your compiled test code.

Warnings

• breaking This package has been abandoned for approximately seven years and is no longer maintained. It will not support modern TypeScript features (e.g., decorators, newer ES versions, module resolution changes) or recent Karma versions, which itself has been deprecated. Using it with current ecosystems is likely to lead to compilation errors or unexpected behavior.
  Fix: Migrate to an actively maintained alternative like `karma-typescript` which provides broader support for modern TypeScript, bundling, and coverage.
• gotcha The default TypeScript `target` is 'ES3', which is extremely outdated. If not explicitly configured, compiled output will be for an ancient JavaScript environment, potentially breaking modern code or tests.
  Fix: Always explicitly set the `target` option in `typescriptPreprocessor.options` to an appropriate modern ECMAScript version (e.g., 'ES2015', 'ESNext') that matches your project's requirements.
• gotcha Source maps are inlined as data-URIs when `sourceMap: true` is enabled. While convenient for simple debugging, this might increase file size or complicate integration with advanced debugging tools that expect external `.map` files.
  Fix: Be aware of the inlined source map behavior. For complex setups or specific debugging workflows, consider if `karma-typescript-preprocessor` is the right choice, as other preprocessors might offer external source map generation.
• breaking The `module` option in `typescriptPreprocessor.options` defaults to `amd` if omitted. This assumes an AMD loader (like RequireJS) is present in your test environment. If your project uses CommonJS or ES Modules and no AMD loader, your tests will likely fail to load or execute.
  Fix: Set `module: 'commonjs'` or `module: 'esnext'` if your project or test environment uses those module systems. Ensure your Karma setup correctly handles module loading for the chosen option.
• gotcha As an abandoned package, `karma-typescript-preprocessor` presents a supply chain security risk. It will not receive patches for newly discovered vulnerabilities in its own code or its transitive dependencies.
  Fix: Evaluate the risk and consider migrating to actively maintained alternatives. If continued use is unavoidable, ensure thorough security scanning of your project's dependencies.

Install

• npm install karma-typescript-preprocessor npm
• yarn add karma-typescript-preprocessor yarn
• pnpm add karma-typescript-preprocessor pnpm

Imports

• preprocessors configuration
  wrong:

  import { TypescriptPreprocessor } from 'karma-typescript-preprocessor';

  correct:

  config.set({
    preprocessors: {
      '**/*.ts': ['typescript']
    }
  });

  This package is a Karma plugin, configured in `karma.conf.js`. The preprocessor is referenced by its short name, 'typescript', not the full package name.
• typescriptPreprocessor configuration object

  config.set({
    typescriptPreprocessor: {
      options: { target: 'ES5' },
      transformPath: function(path) {
        return path.replace(/\.ts$/, '.js');
      }
    }
  });

  This object holds compiler options and file transformation logic specific to the preprocessor.

Quickstart

Demonstrates a complete `karma.conf.js` setup for `karma-typescript-preprocessor`, including file patterns, preprocessor declaration, and custom TypeScript compiler options like `target` and `module`.

/**
 * karma.conf.js
 * Configuration for karma-typescript-preprocessor.
 */
module.exports = function(config) {
  config.set({
    // Base path that will be used to resolve all relative paths for files and exclude.
    basePath: '',

    // Frameworks to use
    // available frameworks: https://npmjs.org/browse/keyword/karma-framework
    frameworks: ['jasmine'], // Example: using Jasmine testing framework

    // List of files / patterns to load in the browser
    files: [
      'src/**/*.ts', // Your TypeScript source files
      'test/**/*.ts' // Your TypeScript test files
    ],

    // Preprocess matching files before serving them to the browser
    // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
    preprocessors: {
      '**/*.ts': ['typescript']
    },

    // Configuration for the TypeScript preprocessor
    typescriptPreprocessor: {
      options: {
        sourceMap: true, // (optional) Generates corresponding .map file.
        target: 'ES5',  // (optional) Specify ECMAScript target version: 'ES3' (default), or 'ES5'
        module: 'amd', // (optional) Specify module code generation: 'commonjs' or 'amd'
        noImplicitAny: true, // (optional) Warn on expressions and declarations with an implied 'any' type.
        removeComments: true // (optional) Do not emit comments to output.
      },
      // Function to transform filenames, e.g., .ts to .js
      transformPath: function(path) {
        return path.replace(/\.ts$/, '.js');
      }
    },

    // Test results reporter to use
    // possible values: 'dots', 'progress'
    // available reporters: https://npmjs.org/browse/keyword/karma-reporter
    reporters: ['progress'],

    // Web server port
    port: 9876,

    // Enable / disable colors in the output (reporters and logs)
    colors: true,

    // Level of logging
    // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG
    logLevel: config.LOG_INFO,

    // Enable / disable watching file and executing tests whenever any file changes
    autoWatch: true,

    // Start these browsers
    // available browser launchers: https://npmjs.org/browse/keyword/karma-launcher
    browsers: ['Chrome'],

    // Continuous Integration mode
    // if true, Karma captures browsers, runs the tests and exits
    singleRun: false,

    // Concurrency level
    // how many browser should be started simultaneous
    concurrency: Infinity
  });
};