0
# Karma Jasmine
1

2
Karma Jasmine is a Karma plugin that provides an adapter for the Jasmine testing framework. It enables developers to run Jasmine tests in browsers through Karma's automated testing infrastructure, with support for test filtering, sharding, debugging, and comprehensive error reporting.
3

4
## Package Information
5

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

11
## Core Imports
12

13
This package is configured as a Karma plugin and does not export functions for direct import. Instead, it registers itself with Karma's plugin system when installed.
14

15
## Basic Usage
16

17
Configure karma-jasmine in your Karma configuration:
18

19
```javascript
20
// karma.conf.js
21
module.exports = function(config) {
22
  config.set({
23
    frameworks: ['jasmine'],
24
    
25
    files: [
26
      'src/**/*.js',
27
      'test/**/*.spec.js'
28
    ],
29
    
30
    // Optional jasmine-specific configuration
31
    client: {
32
      jasmine: {
33
        random: true,
34
        seed: '4321',
35
        oneFailurePerSpec: true,
36
        failFast: true,
37
        timeoutInterval: 1000
38
      }
39
    }
40
  });
41
};
42
```
43

44
Run tests with optional filtering:
45

46
```bash
47
# Run all tests
48
karma start
49

50
# Run tests matching a pattern
51
karma start &
52
karma run -- --grep=<pattern>
53
```
54

55
## Architecture
56

57
Karma Jasmine operates through several key components:
58

59
- **Plugin Framework**: Registers with Karma as both a framework and reporter plugin
60
- **Jasmine Integration**: Configures and initializes Jasmine testing environment in browser contexts
61
- **Test Filtering**: Supports pattern-based filtering, debug mode, and parallel execution (sharding)
62
- **Custom Reporter**: Provides enhanced error reporting with stack trace filtering and debug URLs
63
- **Boot System**: Modified Jasmine boot loader optimized for Karma's test running environment
64

65
## Capabilities
66

67
### Framework Registration
68

69
Karma Jasmine registers itself as a framework plugin that Karma can use to run Jasmine tests.
70

71
```javascript { .api }
72
// Main module export structure
73
module.exports = {
74
  'framework:jasmine': ['factory', initJasmine],
75
  'reporter:karma-jasmine': ['factory', InjectKarmaJasmineReporter]
76
};
77

78
/**
79
 * Initializes Jasmine framework for Karma
80
 * @param {Array} files - Karma files configuration array
81
 */
82
function initJasmine(files);
83

84
/**
85
 * Creates reporter for enhanced debugging and error reporting
86
 * @param {boolean} singleRun - Karma singleRun configuration
87
 * @returns {Object} Reporter with onSpecComplete handler
88
 */
89
function InjectKarmaJasmineReporter(singleRun);
90
```
91

92
### Test Configuration
93

94
Configuration options that can be passed to Jasmine through Karma's client configuration.
95

96
```javascript { .api }
97
// Available jasmine configuration options
98
interface JasmineConfig {
99
  /** Enable random test execution order */
100
  random?: boolean;
101
  /** Seed value for random test order (string or number) */
102
  seed?: string | number;
103
  /** Stop execution after first failure per spec */
104
  oneFailurePerSpec?: boolean;
105
  /** Stop execution on first test failure */
106
  failFast?: boolean;
107
  /** Default timeout interval for async tests in milliseconds */
108
  timeoutInterval?: number;
109
  /** Custom spec filter function */
110
  specFilter?: (spec: any) => boolean;
111
}
112

113
// Client configuration structure
114
interface KarmaClientConfig {
115
  jasmine?: JasmineConfig;
116
  args?: string[];
117
  shardIndex?: number;
118
  totalShards?: number;
119
}
120
```
121

122
### Test Filtering and Pattern Matching
123

124
Support for running subsets of tests using various filtering mechanisms.
125

126
```javascript { .api }
127
/**
128
 * Extract grep pattern from client arguments
129
 * @param {Array|string} clientArguments - Karma client arguments
130
 * @returns {string} Grep pattern or empty string
131
 */
132
function getGrepOption(clientArguments);
133

134
/**
135
 * Create regular expression from filter pattern
136
 * @param {string} filter - Filter pattern (supports regex syntax)
137
 * @returns {RegExp} Compiled regular expression
138
 */
139
function createRegExp(filter);
140

141
/**
142
 * Filter specs based on grep pattern
143
 * @param {Object} clientConfig - Client configuration
144
 * @param {Array} specs - Array of spec objects
145
 * @returns {Array|undefined} Filtered specs or undefined if no pattern
146
 */
147
function getGrepSpecsToRun(clientConfig, specs);
148

149
/**
150
 * Get single spec for debug mode
151
 * @param {Object} location - Browser location object
152
 * @param {Array} specs - Array of spec objects  
153
 * @returns {Array|undefined} Single spec for debugging or undefined
154
 */
155
function getDebugSpecToRun(location, specs);
156

157
/**
158
 * Get specs for current shard in parallel execution
159
 * @param {Array} specs - Array of spec objects
160
 * @param {Object} clientConfig - Client configuration with shard info
161
 * @returns {Array|undefined} Subset of specs for current shard
162
 */
163
function getShardedSpecsToRun(specs, clientConfig);
164
```
165

166
### Debug Support
167

168
Functionality for debugging individual test failures with enhanced URLs and logging.
169

170
```javascript { .api }
171
/**
172
 * Generate debug URL for re-running specific test
173
 * @param {string} description - Test description/name
174
 * @returns {string} Debug URL with spec parameter
175
 */
176
function debugUrl(description);
177

178
/**
179
 * Parse URL query parameters into object
180
 * @param {Object} location - Browser location object with search property
181
 * @returns {Object} Parsed query parameters as key-value pairs
182
 */
183
function parseQueryParams(location);
184
```
185

186
### Error Handling and Stack Trace Processing
187

188
Enhanced error reporting with cleaned stack traces and relevant error information.
189

190
```javascript { .api }
191
/**
192
 * Format failed test step with cleaned stack trace
193
 * @param {Object} step - Step object with stack and message properties
194
 * @returns {string} Formatted error message with relevant stack info
195
 */
196
function formatFailedStep(step);
197

198
/**
199
 * Determine if stack entry is external to jasmine/karma frameworks
200
 * @param {string} entry - Error stack entry line
201
 * @returns {boolean} True if external to testing frameworks
202
 */
203
function isExternalStackEntry(entry);
204

205
/**
206
 * Filter stack traces to show only relevant entries
207
 * @param {Array} stack - Array of stack frame strings
208
 * @returns {Array} Filtered array of relevant stack entries
209
 */
210
function getRelevantStackFrom(stack);
211
```
212

213
### Karma Reporter Integration
214

215
Custom reporter that integrates with Karma's result reporting system and provides enhanced test result handling.
216

217
```javascript { .api }
218
/**
219
 * Custom Jasmine reporter for Karma integration
220
 * @param {Object} tc - Karma test context/runner
221
 * @param {Object} jasmineEnv - Jasmine environment instance
222
 */
223
function KarmaReporter(tc, jasmineEnv);
224

225
/**
226
 * Spec filter for controlling which tests run
227
 * @param {Object} clientConfig - Karma client configuration
228
 * @param {Object} jasmineEnv - Jasmine environment instance
229
 */
230
function KarmaSpecFilter(clientConfig, jasmineEnv);
231

232
// KarmaReporter event handlers
233
interface KarmaReporter {
234
  /** Called when Jasmine starts test execution */
235
  jasmineStarted(data: { totalSpecsDefined: number }): void;
236
  /** Called when Jasmine completes all tests */
237
  jasmineDone(result: { order?: any, coverage?: any }): void;
238
  /** Called when a test suite starts */
239
  suiteStarted(result: { description: string }): void;
240
  /** Called when a test suite completes */
241
  suiteDone(result: { description: string, failedExpectations?: any[] }): void;
242
  /** Called when an individual spec starts */
243
  specStarted(): void;
244
  /** Called when an individual spec completes */
245
  specDone(specResult: SpecResult): void;
246
}
247

248
// Test result structure
249
interface SpecResult {
250
  id: string;
251
  description: string;
252
  fullName: string;
253
  status: 'passed' | 'failed' | 'disabled' | 'pending' | 'excluded';
254
  failedExpectations: Array<{
255
    message: string;
256
    stack?: string;
257
    filename?: string;
258
    lineno?: number;
259
  }>;
260
  passedExpectations: any[];
261
  properties?: any;
262
}
263
```
264

265
### Suite Hierarchy Management
266

267
Data structures for managing test suite organization and hierarchy.
268

269
```javascript { .api }
270
/**
271
 * Tree node representing test suite hierarchy
272
 * @param {string} name - Suite name
273
 * @param {SuiteNode} parent - Parent suite node
274
 */
275
function SuiteNode(name, parent);
276

277
interface SuiteNode {
278
  name: string;
279
  parent: SuiteNode | null;
280
  children: SuiteNode[];
281
  /** Add child suite to this node */
282
  addChild(name: string): SuiteNode;
283
}
284

285
/**
286
 * Process suite hierarchy into nested object structure
287
 * @param {Object} suite - Jasmine suite object
288
 * @param {Object} pointer - Target object to populate
289
 */
290
function processSuite(suite, pointer);
291

292
/**
293
 * Get all spec names organized by suite hierarchy
294
 * @param {Object} topSuite - Root Jasmine suite
295
 * @returns {Object} Nested object with suite names and spec arrays
296
 */
297
function getAllSpecNames(topSuite);
298
```
299

300
## Types
301

302
```javascript { .api }
303
// Core configuration interfaces
304
interface KarmaConfig {
305
  frameworks: string[];
306
  files: string[];
307
  client?: {
308
    jasmine?: JasmineConfig;
309
    args?: string[];
310
    shardIndex?: number;
311
    totalShards?: number;
312
  };
313
  singleRun?: boolean;
314
}
315

316
// Test execution result structure  
317
interface TestResult {
318
  id: string;
319
  description: string;
320
  fullName: string;
321
  suite: string[];
322
  success: boolean;
323
  skipped: boolean;
324
  disabled: boolean;
325
  pending: boolean;
326
  time: number;
327
  log: string[];
328
  executedExpectationsCount: number;
329
  passedExpectations: any[];
330
  properties?: any;
331
  debug_url?: string;
332
}
333

334
// Sharding configuration for parallel execution
335
interface ShardConfig {
336
  shardIndex: number;
337
  totalShards: number;
338
}
339

340
// Grep filtering configuration
341
interface GrepConfig {
342
  pattern: string;
343
  flags?: string;
344
}
345
```