0
# karma-browserify
1

2
karma-browserify is a fast browserify integration plugin for Karma that handles large projects with ease. It provides a preprocessor that combines test files and dependencies into browserified bundles, utilizing watchify for incremental bundling during development. The plugin supports comprehensive browserify configuration options including transforms, plugins, external dependencies, and custom bundle configuration.
3

4
## Package Information
5

6
- **Package Name**: karma-browserify
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev karma-browserify browserify watchify`
10

11
## Core Imports
12

13
The package integrates with Karma through plugin registration:
14

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

27
## Basic Usage
28

29
```javascript
30
// karma.conf.js
31
module.exports = function(config) {
32
  config.set({
33
    frameworks: ['browserify', 'jasmine'],
34
    files: ['test/**/*.js'],
35
    preprocessors: {
36
      'test/**/*.js': ['browserify']
37
    },
38
    browserify: {
39
      debug: true,
40
      transform: ['brfs']
41
    }
42
  });
43
};
44
```
45

46
## Architecture
47

48
karma-browserify is built around several key components:
49

50
- **Framework Integration**: Registers with Karma as a framework and preprocessor
51
- **Bundle Management**: Creates and manages temporary browserify bundles
52
- **Incremental Building**: Uses watchify for fast incremental rebuilds during development
53
- **File Processing**: Preprocesses individual test files and bundles them efficiently
54
- **Configuration API**: Supports all browserify options plus additional plugin-specific settings
55

56
## Capabilities
57

58
### Framework Registration
59

60
Registers browserify framework with Karma to enable browserify bundling in test suites.
61

62
```javascript { .api }
63
// Automatically registered when included in frameworks array
64
frameworks: ['browserify', 'jasmine']
65
```
66

67
### Test File Preprocessing
68

69
Preprocesses individual CommonJS test files for browserify bundling.
70

71
```javascript { .api }
72
// Configure in karma.conf.js
73
preprocessors: {
74
  'test/**/*.js': ['browserify']
75
}
76
```
77

78
### Bundle Preprocessing
79

80
Handles the main browserify bundle creation and management.
81

82
```javascript { .api }
83
// Internal preprocessor for *.browserify.js files
84
// Automatically configured by the plugin
85
```
86

87
### Browserify Configuration
88

89
Complete browserify configuration support through the browserify config object.
90

91
```javascript { .api }
92
interface BrowserifyConfig {
93
  /** Enable source maps for debugging */
94
  debug?: boolean;
95
  /** Array of browserify transforms */
96
  transform?: (string | [string, any])[];
97
  /** Array of browserify plugins */
98
  plugin?: (string | [string, any])[];
99
  /** Custom bundle configuration function */
100
  configure?: (bundle: BrowserifyBundle) => void;
101
  /** Debounce delay for bundling operations (default: 700ms) */
102
  bundleDelay?: number;
103
  /** Custom require name for external requires (default: 'require') */
104
  externalRequireName?: string;
105
  /** File extensions to process */
106
  extensions?: string[];
107
  /** Base directory for relative paths */
108
  basedir?: string;
109
  /** Additional browserify options */
110
  [key: string]: any;
111
}
112
```
113

114
**Usage Example:**
115

116
```javascript
117
browserify: {
118
  debug: true,
119
  transform: ['reactify', 'coffeeify', 'brfs'],
120
  extensions: ['.js', '.jsx', '.coffee'],
121
  configure: function(bundle) {
122
    bundle.on('prebundle', function() {
123
      bundle.external('foobar');
124
    });
125
  }
126
}
127
```
128

129
### Watchify Configuration
130

131
Configuration for watchify (used during autoWatch mode).
132

133
```javascript { .api }
134
interface WatchifyConfig {
135
  /** Enable polling for file changes */
136
  poll?: boolean;
137
  /** Polling interval in milliseconds */
138
  pollInterval?: number;
139
  /** Additional watchify options */
140
  [key: string]: any;
141
}
142
```
143

144
**Usage Example:**
145

146
```javascript
147
watchify: {
148
  poll: true,
149
  pollInterval: 1000
150
}
151
```
152

153
### Transform Configuration
154

155
Support for browserify transforms with options.
156

157
```javascript { .api }
158
// Simple transform array
159
transform: ['reactify', 'coffeeify', 'brfs']
160

161
// Transform with options
162
transform: [
163
  ['reactify', { 'es6': true }],
164
  'coffeeify',
165
  'brfs'
166
]
167
```
168

169
### Plugin Configuration
170

171
Support for browserify plugins with options.
172

173
```javascript { .api }
174
// Simple plugin array
175
plugin: ['stringify']
176

177
// Plugin with options
178
plugin: [
179
  ['stringify', { extensions: ['.txt', '.html'] }]
180
]
181
```
182

183
### Custom Bundle Configuration
184

185
Advanced bundle configuration through the configure function.
186

187
```javascript { .api }
188
configure: function(bundle) {
189
  // Configure externals
190
  bundle.on('prebundle', function() {
191
    bundle.external('lodash');
192
    bundle.external('jquery');
193
  });
194
  
195
  // Add transforms programmatically
196
  bundle.once('prebundle', function() {
197
    bundle.transform('babelify').plugin('proxyquireify/plugin');
198
  });
199
}
200
```
201

202
### Bundle Events
203

204
Events emitted by the browserify bundle instance.
205

206
```javascript { .api }
207
// Emitted before bundling operation
208
bundle.on('prebundle', function() {
209
  // Configure externals, transforms, etc.
210
});
211

212
// Emitted after bundling completion
213
bundle.on('bundled', function(err, content) {
214
  // Handle bundle completion
215
});
216

217
// Watchify events (during autoWatch)
218
bundle.on('update', function(updatedFiles) {
219
  // Handle file updates
220
});
221

222
bundle.on('log', function(message) {
223
  // Handle log messages
224
});
225
```
226

227
## Types
228

229
### Core Plugin Exports
230

231
```javascript { .api }
232
// Main plugin export object
233
{
234
  'bro': ['type', Bro],
235
  'framework:browserify': ['factory', framework],
236
  'preprocessor:browserify': ['factory', testFilePreprocessor],
237
  'preprocessor:browserify-bundle': ['factory', bundlePreprocessor],
238
  'preprocess': ['factory', createPreprocessor] // Optional
239
}
240
```
241

242
### Bro Class
243

244
```javascript { .api }
245
/**
246
 * Main browserify integration class
247
 * @param {BundleFile} [bundleFile] - Optional bundle file instance
248
 */
249
function Bro(bundleFile) {
250
  /** 
251
   * Framework factory function with dependency injection
252
   * @param {Object} emitter - Event emitter instance
253
   * @param {Object} config - Karma configuration object
254
   * @param {Object} logger - Logger instance
255
   * @returns {BrowserifyBundle} Extended browserify bundle instance
256
   */
257
  this.framework = function(emitter, config, logger) {
258
    // Returns browserify instance with additional methods
259
  };
260
  this.framework.$inject = ['emitter', 'config', 'logger'];
261
  
262
  /** 
263
   * Test file preprocessor factory
264
   * @returns {Function} Preprocessor function (content, file, done) => void
265
   */
266
  this.testFilePreprocessor = function() {
267
    // Returns preprocessor function that processes individual test files
268
  };
269
  this.testFilePreprocessor.$inject = [];
270
  
271
  /** 
272
   * Bundle preprocessor factory with dependency injection
273
   * @param {Object} config - Configuration object containing browserify options
274
   * @returns {Function} Bundle preprocessor function (content, file, done) => void
275
   */
276
  this.bundlePreprocessor = function(config) {
277
    // Returns bundle preprocessor function
278
  };
279
  this.bundlePreprocessor.$inject = ['config'];
280
}
281

282
// Constructor dependency injection
283
Bro.$inject = [];
284
```
285

286
### Bundle File Management
287

288
```javascript { .api }
289
/**
290
 * Manages temporary bundle files
291
 */
292
function BundleFile() {
293
  /** File path of the bundle */
294
  this.location = string;
295
  
296
  /** Creates empty bundle file if it doesn't exist */
297
  this.touch = function() {};
298
  
299
  /** Writes content to bundle file */
300
  this.update = function(content) {};
301
  
302
  /** Removes bundle file from filesystem */
303
  this.remove = function() {};
304
}
305

306
/**
307
 * Generates temporary filename with suffix
308
 * @param {string} suffix - File suffix
309
 * @returns {string} Temporary file path
310
 */
311
BundleFile.getTempFileName = function(suffix) {};
312
```
313

314
### Browserify Bundle Extensions
315

316
```javascript { .api }
317
// Methods added to browserify instance
318
interface ExtendedBrowserifyBundle {
319
  /**
320
   * Bundle individual file and return stub
321
   * @param {Object} file - File object with path property
322
   * @param {Function} done - Callback function(err, stub)
323
   */
324
  bundleFile(file, done): void;
325
  
326
  /**
327
   * Wait for bundle creation to stabilize and invoke callback
328
   * @param {Function} [callback] - Optional callback(err, content)
329
   */
330
  deferredBundle(callback?): void;
331
}
332
```
333

334
## Error Handling
335

336
The plugin handles various error conditions:
337

338
- **Bundle Errors**: Replaced with error template to prevent test failures
339
- **Missing watchify**: Detected and reported when autoWatch is enabled
340
- **Incompatible Karma**: Version compatibility checks for preprocessor API
341
- **Missing Files**: Automatically removed from bundles during rebuilds
342
- **Deprecated prebundle option**: Warns when `prebundle` is used (replaced by `configure`)
343
- **Deprecated watchify config**: Warns when `watchify` is configured in browserify options
344

345
```javascript
346
// Bundle error template (replaces bundle content on error)
347
'throw new Error("bundle error (see logs)");'
348
```
349

350
## Common Configuration Patterns
351

352
### Basic CoffeeScript Support
353

354
```javascript
355
browserify: {
356
  transform: ['coffeeify'],
357
  extensions: ['.js', '.coffee']
358
}
359
```
360

361
### React/JSX Support
362

363
```javascript
364
browserify: {
365
  transform: [['reactify', { 'es6': true }]],
366
  extensions: ['.js', '.jsx']
367
}
368
```
369

370
### External Dependencies
371

372
```javascript
373
browserify: {
374
  configure: function(bundle) {
375
    bundle.on('prebundle', function() {
376
      bundle.external('lodash');
377
      bundle.external('jquery');
378
    });
379
  }
380
}
381
```
382

383
### Source Maps for Debugging
384

385
```javascript
386
browserify: {
387
  debug: true
388
}
389
```
390

391
### Custom Bundling Delay
392

393
```javascript
394
browserify: {
395
  bundleDelay: 1000 // Wait 1 second before bundling (default: 700ms)
396
}
397
```
398

399
## Constants
400

401
```javascript { .api }
402
/**
403
 * Default time to wait for additional file change notifications
404
 * before performing a rebundling operation
405
 */
406
const DEFAULT_BUNDLE_DELAY = 700;
407

408
/**
409
 * Error template used when bundle creation fails
410
 */
411
const BUNDLE_ERROR_TPL = 'throw new Error("bundle error (see logs)");';
412
```