Karma TypeScript Preprocessor and Reporter

Common errors

• Error: Cannot find module 'acorn'

  cause A dependency issue where the 'acorn' package, used for parsing, is not correctly resolved or installed.
  fix Upgrade `karma-typescript` to the latest patch release (e.g., `npm install karma-typescript@latest --save-dev`) or explicitly install `acorn`: `npm install acorn --save-dev`.

• TypeError: Cannot read property 'karmaTypescript' of undefined

  cause The `karma-typescript` plugin is not correctly recognized or initialized by Karma, often due to missing `frameworks` entry.
  fix Ensure `karma-typescript` is listed in the `frameworks` array in your `karma.conf.js`: `frameworks: ["jasmine", "karma-typescript"],`

• Coverage threshold not met, exiting with error code 1.

  cause The configured code coverage percentage was not reached by the tests, causing the process to terminate. This is a deliberate feature.
  fix Adjust the coverage thresholds in your `karma.conf.js` under `karmaTypescript.coverageOptions.threshold`, or set `karmaTypescript.coverageOptions.failOnThresholdNotMet: false` if you do not want failures on unmet thresholds.

• TSxxxx: [TypeScript error message]

  cause A TypeScript compilation error occurred during the test run, indicating issues in your source or test files.
  fix Review the accompanying TypeScript error message and fix the code. Ensure your `tsconfig.json` or `karmaTypescript.compilerOptions` are correctly configured for your project.

Warnings

• breaking karma-typescript versions 5.x require Karma 5.x or 6.x. Earlier versions of Karma may not be fully supported, leading to unexpected behavior or compilation issues.
  Fix: Upgrade Karma to a compatible version (e.g., `npm install karma@^6 --save-dev`) and ensure `typescript` peer dependency is met. Refer to the `peerDependencies` section for exact ranges.
• gotcha Version 5.3.0 of karma-typescript was noted as 'messed up' by the maintainer and was quickly followed by 5.4.0. Users on 5.3.0 might encounter unresolved bugs that were fixed in 5.4.0.
  Fix: Ensure you are using `karma-typescript@5.4.0` or higher to avoid issues present in version 5.3.0. Always check the latest patch releases for bug fixes.
• gotcha Missing or incompatible `acorn` dependency can cause the test run to lock or fail. This has been a recurring bug fix in recent patch versions.
  Fix: Upgrade to `karma-typescript@5.5.2` or newer to ensure the correct `acorn` dependency is available and avoid test run lockups. If issues persist, try `npm install acorn` explicitly.
• gotcha When `singleRun` is set to `false`, karma-typescript might still kill the process if coverage thresholds aren't met. This behavior can be unexpected during watch mode.
  Fix: Update to `karma-typescript@5.4.0` or newer, which includes a fix to prevent the process from being killed when coverage thresholds aren't met in `singleRun: false` mode.

Install

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

Imports

• framework
  wrong:

  require('karma-typescript')

  correct:

  config.set({
    frameworks: ["jasmine", "karma-typescript"],
    // ...
  });

  karma-typescript is configured as a framework and preprocessor, not imported directly into application code. Ensure 'karma-typescript' is included in the `frameworks` array in `karma.conf.js`.
• preprocessor
  wrong:

  preprocessors: { '**/*.ts': require('karma-typescript') }

  correct:

  config.set({
    preprocessors: {
      "**/*.ts": "karma-typescript" // or '*.tsx' for React
    },
    // ...
  });

  Configure karma-typescript as a preprocessor for your TypeScript files in `karma.conf.js`. This tells Karma to compile TypeScript files before tests run.
• reporter
  wrong:

  reporters: ["karma-typescript-reporter"]

  correct:

  config.set({
    reporters: ["progress", "karma-typescript"],
    // ...
  });

  To enable the specialized TypeScript reporter and coverage features, include 'karma-typescript' in the `reporters` array in `karma.conf.js`.

Quickstart

This configuration sets up Karma with Jasmine and karma-typescript to compile and run tests on TypeScript files located in the 'src' directory, producing remapped coverage reports.

module.exports = function(config) {
    config.set({
        basePath: './',
        frameworks: ["jasmine", "karma-typescript"],
        files: [
            "src/**/*.ts" // Use '*.tsx' for React projects
        ],
        preprocessors: {
            "**/*.ts": "karma-typescript" // Use '*.tsx' for React projects
        },
        reporters: ["progress", "karma-typescript"],
        browsers: ["ChromeHeadless"], // Use ChromeHeadless for CI environments
        karmaTypescript: {
            compilerOptions: {
                esModuleInterop: true,
                module: "CommonJS",
                target: "ES5"
            },
            include: ["src/**/*.ts"],
            exclude: ["node_modules"]
        }
    });
};