0
# Karma Sourcemap Loader
1

2
Karma Sourcemap Loader is a Karma preprocessor plugin that automatically locates and loads existing JavaScript source maps during test execution. It enables proper debugging and code coverage collection when Karma is used as part of a larger build process where compilation/transpilation occurs in previous steps.
3

4
## Package Information
5

6
- **Package Name**: karma-sourcemap-loader
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install karma-sourcemap-loader --save-dev`
10

11
## Core Imports
12

13
The package exports a Karma DI module that needs to be included in your Karma configuration:
14

15
```javascript
16
// karma.conf.js
17
module.exports = function(config) {
18
  config.set({
19
    plugins: ['karma-sourcemap-loader'],
20
    preprocessors: {
21
      '**/*.js': ['sourcemap']
22
    }
23
  });
24
};
25
```
26

27
For programmatic usage requiring the factory function:
28

29
```javascript
30
const karmaSourcemapLoader = require('karma-sourcemap-loader');
31
// karmaSourcemapLoader exports: { 'preprocessor:sourcemap': ['factory', createSourceMapLocatorPreprocessor] }
32
```
33

34
## Basic Usage
35

36
```javascript
37
// karma.conf.js
38
module.exports = function(config) {
39
  config.set({
40
    plugins: ['karma-sourcemap-loader'],
41
    
42
    // Apply sourcemap preprocessing to JavaScript files
43
    preprocessors: {
44
      '**/*.js': ['sourcemap'],
45
      'dist/**/*.js': ['sourcemap']
46
    },
47
    
48
    // Optional configuration
49
    sourceMapLoader: {
50
      // Load only files with sourceMappingURL comment
51
      onlyWithURL: false,
52
      
53
      // Enable strict error handling
54
      strict: false
55
    }
56
  });
57
};
58
```
59

60
## Architecture
61

62
Karma Sourcemap Loader integrates with Karma's preprocessing pipeline:
63

64
- **DI Integration**: Registers as 'preprocessor:sourcemap' in Karma's dependency injection system
65
- **File Processing**: Processes JavaScript files to locate and load source maps
66
- **Source Map Support**: Handles both inline (base64, URL-encoded) and external source maps
67
- **Path Remapping**: Provides flexible source path transformation capabilities
68
- **Error Handling**: Offers both strict and lenient error handling modes
69

70
## Capabilities
71

72
### Karma DI Module Export
73

74
The main export providing Karma dependency injection integration.
75

76
```javascript { .api }
77
module.exports = {
78
  'preprocessor:sourcemap': ['factory', createSourceMapLocatorPreprocessor]
79
};
80
```
81

82
### Preprocessor Factory
83

84
Creates and configures the sourcemap preprocessor instance.
85

86
```javascript { .api }
87
/**
88
 * Creates a sourcemap preprocessor instance
89
 * @param {object} logger - Karma logger instance  
90
 * @param {karmaSourcemapLoader.Config} config - Karma configuration object
91
 * @returns {karmaSourcemapLoader.Preprocessor} - Configured preprocessor function
92
 */
93
function createSourceMapLocatorPreprocessor(logger, config);
94

95
/**
96
 * Karma DI injection array specifying the dependencies for the factory function
97
 */
98
createSourceMapLocatorPreprocessor.$inject = ['logger', 'config'];
99
```
100

101
### Preprocessor Function
102

103
The main preprocessing function that handles sourcemap loading and processing.
104

105
```javascript { .api }
106
/**
107
 * Processes a file to locate and load source maps
108
 * @param {string} content - File content to process
109
 * @param {karmaSourcemapLoader.File} file - Karma file object
110
 * @param {function} done - Completion callback function
111
 * @returns {void}
112
 */
113
function karmaSourcemapLoaderPreprocessor(content, file, done);
114
```
115

116
### Configuration Options
117

118
Configuration is provided through the `sourceMapLoader` property in Karma config.
119

120
```javascript { .api }
121
interface SourceMapLoaderConfig {
122
  /** Map of path prefixes to replace in source paths */
123
  remapPrefixes?: Record<string, string>;
124
  
125
  /** Custom function to remap source paths */
126
  remapSource?: (source: string) => string | false | null | undefined;
127
  
128
  /** Set or compute sourceRoot value */
129
  useSourceRoot?: string | ((file: karmaSourcemapLoader.File) => string | false | null | undefined);
130
  
131
  /** Only process files with sourceMappingURL comment */
132
  onlyWithURL?: boolean;
133
  
134
  /** Enable strict error handling mode */
135
  strict?: boolean;
136
}
137
```
138

139
**Configuration Examples:**
140

141
```javascript
142
// Path prefix remapping
143
sourceMapLoader: {
144
  remapPrefixes: {
145
    '/myproject/': '../src/',
146
    '/otherdep/': '../node_modules/otherdep/'
147
  }
148
}
149

150
// Custom source remapping function
151
sourceMapLoader: {
152
  remapSource(source) {
153
    if (source.startsWith('/myproject/')) {
154
      return '../src/' + source.substring(11);
155
    }
156
    return source;
157
  }
158
}
159

160
// Fixed sourceRoot value
161
sourceMapLoader: {
162
  useSourceRoot: '/sources'
163
}
164

165
// Dynamic sourceRoot computation
166
sourceMapLoader: {
167
  useSourceRoot(file) {
168
    return '/sources/' + path.dirname(file.originalPath);
169
  }
170
}
171

172
// Conditional loading and strict mode
173
sourceMapLoader: {
174
  onlyWithURL: true,  // Only load maps for files with sourceMappingURL
175
  strict: true        // Fail tests on missing/invalid source maps
176
}
177
```
178

179
### Source Map Processing
180

181
The preprocessor handles multiple source map formats and locations.
182

183
```javascript { .api }
184
// Source map formats supported:
185
// 1. Inline base64-encoded JSON
186
//    //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjoz...
187

188
// 2. Inline URL-encoded JSON  
189
//    //# sourceMappingURL=data:application/json,{"version":3,...}
190

191
// 3. External source map files
192
//    //# sourceMappingURL=bundle.js.map
193

194
// 4. Automatic external lookup (filename + .map)
195
//    bundle.js -> bundle.js.map (when no sourceMappingURL found)
196

197
// 5. Direct .map file processing
198
//    Processes .map files directly when they are preprocessed
199
```
200

201
### Error Handling Modes
202

203
The preprocessor provides two error handling approaches.
204

205
```javascript { .api }
206
// Non-strict mode (default)
207
// - Logs warnings for missing/invalid source maps
208
// - Continues processing without failing tests
209
// - Suitable for development environments
210

211
// Strict mode (strict: true)
212
// - Throws errors for missing/invalid source maps  
213
// - Fails the test run immediately
214
// - Suitable for CI/CD environments requiring complete source map coverage
215
```
216

217
## Types
218

219
```javascript { .api }
220
// Types from karmaSourcemapLoader module
221
declare module karmaSourcemapLoader {
222
  interface File {
223
    /** Current file path */
224
    path: string;
225
    /** Original file path before preprocessing */
226
    originalPath: string;
227
    /** Loaded source map object (set by preprocessor) */
228
    sourceMap?: SourceMap;
229
  }
230

231
  interface Config {
232
    /** Plugin-specific configuration */
233
    sourceMapLoader?: {
234
      /** Map of path prefixes to replace in source paths */
235
      remapPrefixes?: Record<string, string>;
236
      /** Custom function to remap source paths */
237
      remapSource?: (source: string) => string | false | null | undefined;
238
      /** Set or compute sourceRoot value */
239
      useSourceRoot?: string | ((file: File) => string | false | null | undefined);
240
      /** Only process files with sourceMappingURL comment */
241
      onlyWithURL?: boolean;
242
      /** Enable strict error handling mode */
243
      strict?: boolean;
244
    };
245
  }
246

247
  interface Preprocessor {
248
    /** Process file content and load source maps */
249
    (content: string, file: File, done: (result: string | Error) => void): void;
250
  }
251

252
  interface SourceMap {
253
    /** Array of source file paths */
254
    sources: string[];
255
    /** Base path for resolving source files */
256
    sourceRoot?: string;
257
  }
258
}
259
```
260

261
## Usage Examples
262

263
### Basic Source Map Loading
264

265
```javascript
266
// karma.conf.js
267
module.exports = function(config) {
268
  config.set({
269
    plugins: ['karma-sourcemap-loader'],
270
    
271
    files: [
272
      'dist/**/*.js'
273
    ],
274
    
275
    preprocessors: {
276
      'dist/**/*.js': ['sourcemap']
277
    }
278
  });
279
};
280
```
281

282
### Advanced Path Remapping
283

284
```javascript
285
// karma.conf.js - Complex build setup with multiple remapping strategies
286
module.exports = function(config) {
287
  config.set({
288
    plugins: ['karma-sourcemap-loader'],
289
    
290
    preprocessors: {
291
      'build/**/*.js': ['sourcemap']
292
    },
293
    
294
    sourceMapLoader: {
295
      // First try prefix remapping
296
      remapPrefixes: {
297
        '/webpack:///': '',
298
        '/src/': '../src/',
299
        '/node_modules/': '../node_modules/'
300
      },
301
      
302
      // Then apply custom logic for remaining paths
303
      remapSource(source) {
304
        // Handle webpack-style paths
305
        if (source.startsWith('webpack:///')) {
306
          return source.replace('webpack:///', '');
307
        }
308
        
309
        // Handle relative paths in monorepo
310
        if (source.startsWith('./packages/')) {
311
          return source.replace('./packages/', '../packages/');
312
        }
313
        
314
        return source; // Keep unchanged
315
      },
316
      
317
      // Set sourceRoot for IDE integration
318
      useSourceRoot: function(file) {
319
        // Compute relative path from test output to project root
320
        const relative = path.relative(path.dirname(file.path), process.cwd());
321
        return relative || '.';
322
      },
323
      
324
      // Strict mode for CI
325
      strict: process.env.CI === 'true'
326
    }
327
  });
328
};
329
```
330

331
### Multiple File Type Processing
332

333
```javascript
334
// karma.conf.js - Process both JS and source map files
335
module.exports = function(config) {
336
  config.set({
337
    plugins: ['karma-sourcemap-loader'],
338
    
339
    files: [
340
      'dist/**/*.js',
341
      { pattern: 'dist/**/*.map', included: false, served: true }
342
    ],
343
    
344
    preprocessors: {
345
      // Process JS files to load their source maps
346
      'dist/**/*.js': ['sourcemap'],
347
      
348
      // Also process .map files directly for path remapping
349
      'dist/**/*.map': ['sourcemap']
350
    },
351
    
352
    sourceMapLoader: {
353
      remapPrefixes: {
354
        '/app/': '../src/'
355
      }
356
    }
357
  });
358
};
359
```
360

361
## Error Scenarios
362

363
The preprocessor handles various error conditions based on the `strict` configuration:
364

365
```javascript
366
// Non-strict mode (default) - logs warnings
367
sourceMapLoader: { strict: false }
368
// - Missing external source map: Warning logged, test continues
369
// - Malformed source map JSON: Warning logged, test continues  
370
// - Invalid sourceMappingURL: Warning logged, test continues
371

372
// Strict mode - throws errors
373
sourceMapLoader: { strict: true }
374
// - Missing external source map: Error thrown, test fails
375
// - Malformed source map JSON: Error thrown, test fails
376
// - Invalid sourceMappingURL: Error thrown, test fails
377
```