Karma and Source Maps

Why Source Maps Matter for Karma Debugging

Without source maps, a failure inside a TypeScript file or a webpack-bundled module shows a stack trace pointing at compiled, often unreadable, generated JavaScript — line numbers and variable names that don't match your actual source. A source map is a companion file mapping every position in the generated output back to its original source location, letting tools translate one into the other automatically.

// webpack.test.config.js
module.exports = {
  devtool: 'inline-source-map',   // embeds the map directly in the bundle
  // ...
};

// karma.conf.js
npm install --save-dev karma-sourcemap-loader
config.set({
  preprocessors: {
    'src/**/*.spec.js': ['webpack', 'sourcemap']
  }
});

karma-sourcemap-loader makes Karma aware of source maps produced by an earlier preprocessing step (like webpack), so it can serve them correctly to the browser.

Common Source Map devtool Settings

devtool: 'inline-source-map'   // embedded directly in the bundle (simplest for testing)
devtool: 'source-map'           // separate .map file, more setup but smaller bundles
devtool: 'eval-source-map'        // faster rebuilds, common for local development
devtool: false                     // no source maps at all (never recommended for tests)

• inline-source-map is the simplest option for test builds, since there's no separate file to serve correctly.
• Separate .map files require Karma to actually serve them alongside the bundle, which karma-sourcemap-loader handles.
• Disabling source maps entirely makes any compiled-code failure dramatically harder to debug.
• Source map settings for test builds are usually configured separately from production build settings.

Source Maps Cheat Sheet

Key facts and packages for source-map-aware Karma debugging.

Source Maps for Plain TypeScript Compilation

If you're compiling TypeScript directly (via karma-typescript or ts-loader) rather than only bundling already-compiled JavaScript, the TypeScript compiler itself needs sourceMap: true in tsconfig.json to generate the mapping in the first place.

// tsconfig.spec.json (or tsconfig.json)
{
  "compilerOptions": {
    "sourceMap": true
  }
}

Verifying Source Maps Actually Work

The fastest way to confirm source maps are wired up correctly is to intentionally break a test, then check whether DevTools' Sources panel and the terminal stack trace both point at your real, original source file and line — not a bundled or compiled file.

• Open the Sources panel in DevTools and confirm your actual .ts/.js source files (not bundled output) are listed.
• Set a breakpoint directly in the original source file and confirm it's hit during a run.
• Check that a deliberately broken assertion's stack trace names the correct original file and line number.

Common Mistakes

• Disabling source maps for 'faster' test builds, then losing significant debugging time on every subsequent failure.
• Forgetting sourceMap: true in tsconfig.json even after correctly configuring a bundler's devtool option.
• Using a separate .map file setup without also including karma-sourcemap-loader to serve it correctly.
• Not verifying source maps actually work until well after they were expected to — verify immediately after any pipeline change.

Key Takeaways

• Source maps let stack traces and DevTools show original source instead of compiled/bundled output.
• karma-sourcemap-loader is required for Karma to serve maps generated by an earlier preprocessing step.
• TypeScript projects need sourceMap: true in tsconfig.json in addition to any bundler-level source map setting.
• Verify source maps work immediately after any build pipeline change, not only when a confusing failure forces the question.