0
# Jasmine Spec Reporter
1

2
Jasmine Spec Reporter is a customizable real-time console spec reporter for the Jasmine testing framework, designed to enhance the visual presentation of test results in command-line interfaces. It offers extensive configuration options for formatting test output, including colored displays, custom themes, execution metrics, and various display processors that can be tailored to different testing environments.
3

4
## Package Information
5

6
- **Package Name**: jasmine-spec-reporter
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install jasmine-spec-reporter --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import { SpecReporter, DisplayProcessor, StacktraceOption } from "jasmine-spec-reporter";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { SpecReporter, DisplayProcessor, StacktraceOption } = require("jasmine-spec-reporter");
21
```
22

23
**Note:** The `parse` function from the configuration parser is available internally but not exported in the main module. Configuration parsing is handled automatically when passing a configuration object to the SpecReporter constructor.
24

25
## Basic Usage
26

27
```typescript
28
import { SpecReporter } from "jasmine-spec-reporter";
29

30
// Clear default reporters and add the spec reporter
31
jasmine.getEnv().clearReporters();
32
jasmine.getEnv().addReporter(new SpecReporter({
33
  spec: {
34
    displayPending: true,
35
    displayDuration: true,
36
    displayStacktrace: "none"
37
  },
38
  summary: {
39
    displayDuration: false,
40
    displaySuccessful: true
41
  }
42
}));
43
```
44

45
## Architecture
46

47
Jasmine Spec Reporter is built around several key components:
48

49
- **SpecReporter**: Main reporter class that implements Jasmine's CustomReporter interface
50
- **Configuration System**: Comprehensive configuration options for customizing output appearance
51
- **Display Processors**: Modular system for customizing how different parts of the output are formatted
52
- **Theme System**: Color and styling management using the colors package
53
- **Execution Metrics**: Performance tracking and timing information
54

55
## Capabilities
56

57
### Main Reporter
58

59
The primary reporter class that integrates with Jasmine's reporting system.
60

61
```typescript { .api }
62
class SpecReporter implements jasmine.CustomReporter {
63
  /**
64
   * Creates a new SpecReporter instance
65
   * @param configuration - Optional configuration object to customize reporter behavior
66
   */
67
  constructor(configuration?: Configuration);
68
  
69
  /**
70
   * Called when Jasmine starts running tests
71
   * @param suiteInfo - Information about the test suite including total specs defined
72
   */
73
  jasmineStarted(suiteInfo: jasmine.SuiteInfo): void;
74
  
75
  /**
76
   * Called when Jasmine finishes running tests
77
   * @param runDetails - Details about the test run including execution order and global errors
78
   */
79
  jasmineDone(runDetails: jasmine.RunDetails): void;
80
  
81
  /**
82
   * Called when a test suite starts
83
   * @param result - Suite result information
84
   */
85
  suiteStarted(result: CustomReporterResult): void;
86
  
87
  /**
88
   * Called when a test suite finishes
89
   * @param result - Suite result information including any failed expectations
90
   */
91
  suiteDone(result: CustomReporterResult): void;
92
  
93
  /**
94
   * Called when an individual spec starts
95
   * @param result - Spec result information
96
   */
97
  specStarted(result: CustomReporterResult): void;
98
  
99
  /**
100
   * Called when an individual spec finishes
101
   * @param result - Spec result information including status and execution details
102
   */
103
  specDone(result: CustomReporterResult): void;
104
}
105
```
106

107
**Usage Example:**
108

109
```typescript
110
import { SpecReporter } from "jasmine-spec-reporter";
111

112
const reporter = new SpecReporter({
113
  spec: {
114
    displayErrorMessages: true,
115
    displayStacktrace: "pretty",
116
    displaySuccessful: true,
117
    displayFailed: true,
118
    displayPending: true,
119
    displayDuration: true
120
  },
121
  colors: {
122
    enabled: true,
123
    successful: "green",
124
    failed: "red",
125
    pending: "yellow"
126
  }
127
});
128

129
jasmine.getEnv().clearReporters();
130
jasmine.getEnv().addReporter(reporter);
131
```
132

133
### Configuration System
134

135
Comprehensive configuration options for customizing the reporter's output appearance and behavior.
136

137
```typescript { .api }
138
/**
139
 * Parse and merge configuration with default values
140
 * @param conf - Optional user configuration to merge with defaults
141
 * @returns Complete configuration object with merged values
142
 */
143
function parse(conf?: Configuration): Configuration;
144

145
class Configuration {
146
  suite?: {
147
    displayNumber?: boolean;
148
  };
149
  spec?: {
150
    displayErrorMessages?: boolean;
151
    displayStacktrace?: StacktraceOption;
152
    displaySuccessful?: boolean;
153
    displayFailed?: boolean;
154
    displayPending?: boolean;
155
    displayDuration?: boolean;
156
  };
157
  summary?: {
158
    displayErrorMessages?: boolean;
159
    displayStacktrace?: StacktraceOption;
160
    displaySuccessful?: boolean;
161
    displayFailed?: boolean;
162
    displayPending?: boolean;
163
    displayDuration?: boolean;
164
  };
165
  colors?: {
166
    enabled?: boolean;
167
    successful?: string;
168
    failed?: string;
169
    pending?: string;
170
    prettyStacktraceFilename?: string;
171
    prettyStacktraceLineNumber?: string;
172
    prettyStacktraceColumnNumber?: string;
173
    prettyStacktraceError?: string;
174
  };
175
  prefixes?: {
176
    successful?: string;
177
    failed?: string;
178
    pending?: string;
179
  };
180
  stacktrace?: {
181
    filter?(stacktrace: string): string;
182
  };
183
  customProcessors?: (typeof DisplayProcessor)[];
184
  customOptions?: any;
185
  print?: (log: string) => void;
186
}
187

188
enum StacktraceOption {
189
  NONE = "none",
190
  RAW = "raw",
191
  PRETTY = "pretty"
192
}
193
```
194

195
**Configuration Example:**
196

197
```typescript
198
const config: Configuration = {
199
  suite: {
200
    displayNumber: true
201
  },
202
  spec: {
203
    displayErrorMessages: true,
204
    displayStacktrace: StacktraceOption.PRETTY,
205
    displaySuccessful: false,
206
    displayFailed: true,
207
    displayPending: true,
208
    displayDuration: true
209
  },
210
  summary: {
211
    displayErrorMessages: false,
212
    displayStacktrace: StacktraceOption.NONE,
213
    displaySuccessful: false,
214
    displayFailed: true,
215
    displayPending: false,
216
    displayDuration: true
217
  },
218
  colors: {
219
    enabled: true,
220
    successful: "green",
221
    failed: "red",
222
    pending: "cyan",
223
    prettyStacktraceFilename: "magenta",
224
    prettyStacktraceLineNumber: "yellow",
225
    prettyStacktraceColumnNumber: "yellow",
226
    prettyStacktraceError: "red"
227
  },
228
  prefixes: {
229
    successful: "✓ ",
230
    failed: "✗ ",
231
    pending: "- "
232
  },
233
  stacktrace: {
234
    filter: (stacktrace: string) => stacktrace.replace(/\\/g, "/")
235
  },
236
  print: (log: string) => process.stdout.write(log + "\n")
237
};
238

239
const reporter = new SpecReporter(config);
240
```
241

242
**Default Configuration Values:**
243

244
```typescript
245
const defaultConfiguration: Configuration = {
246
  colors: {
247
    enabled: true,
248
    failed: "red",
249
    pending: "yellow",
250
    successful: "green",
251
    prettyStacktraceFilename: "cyan",
252
    prettyStacktraceLineNumber: "yellow",
253
    prettyStacktraceColumnNumber: "yellow",
254
    prettyStacktraceError: "red"
255
  },
256
  prefixes: {
257
    failed: "✗ ",        // "× " on Windows
258
    pending: "* ",
259
    successful: "✓ "     // "√ " on Windows
260
  },
261
  spec: {
262
    displayDuration: false,
263
    displayErrorMessages: true,
264
    displayFailed: true,
265
    displayPending: false,
266
    displayStacktrace: StacktraceOption.NONE,
267
    displaySuccessful: true
268
  },
269
  suite: {
270
    displayNumber: false
271
  },
272
  summary: {
273
    displayDuration: true,
274
    displayErrorMessages: true,
275
    displayFailed: true,
276
    displayPending: true,
277
    displayStacktrace: StacktraceOption.NONE,
278
    displaySuccessful: false
279
  }
280
};
281
```
282

283
### Custom Display Processors
284

285
Base class and system for creating custom display processors to control output formatting.
286

287
```typescript { .api }
288
class DisplayProcessor {
289
  protected configuration: Configuration;
290
  protected theme: Theme;
291
  
292
  /**
293
   * Creates a new display processor instance
294
   * @param configuration - Reporter configuration
295
   * @param theme - Color theme instance
296
   */
297
  constructor(configuration: Configuration, theme: Theme);
298
  
299
  /**
300
   * Process Jasmine started message
301
   * @param info - Jasmine suite information
302
   * @param log - Original log message
303
   * @returns Processed log message
304
   */
305
  displayJasmineStarted(info: jasmine.SuiteInfo, log: string): string;
306
  
307
  /**
308
   * Process suite message
309
   * @param suite - Suite result information
310
   * @param log - Original log message
311
   * @returns Processed log message
312
   */
313
  displaySuite(suite: CustomReporterResult, log: string): string;
314
  
315
  /**
316
   * Process spec started message
317
   * @param spec - Spec result information
318
   * @param log - Original log message
319
   * @returns Processed log message
320
   */
321
  displaySpecStarted(spec: CustomReporterResult, log: string): string;
322
  
323
  /**
324
   * Process successful spec message
325
   * @param spec - Spec result information
326
   * @param log - Original log message
327
   * @returns Processed log message
328
   */
329
  displaySuccessfulSpec(spec: CustomReporterResult, log: string): string;
330
  
331
  /**
332
   * Process failed spec message
333
   * @param spec - Spec result information
334
   * @param log - Original log message
335
   * @returns Processed log message
336
   */
337
  displayFailedSpec(spec: CustomReporterResult, log: string): string;
338
  
339
  /**
340
   * Process spec error messages
341
   * @param spec - Spec result information
342
   * @param log - Original log message
343
   * @returns Processed log message
344
   */
345
  displaySpecErrorMessages(spec: CustomReporterResult, log: string): string;
346
  
347
  /**
348
   * Process summary error messages
349
   * @param spec - Spec result information
350
   * @param log - Original log message
351
   * @returns Processed log message
352
   */
353
  displaySummaryErrorMessages(spec: CustomReporterResult, log: string): string;
354
  
355
  /**
356
   * Process pending spec message
357
   * @param spec - Spec result information
358
   * @param log - Original log message
359
   * @returns Processed log message
360
   */
361
  displayPendingSpec(spec: CustomReporterResult, log: string): string;
362
}
363
```
364

365
**Custom Processor Example:**
366

367
```typescript
368
import { DisplayProcessor, StacktraceOption } from "jasmine-spec-reporter";
369

370
class CustomProcessor extends DisplayProcessor {
371
  public displayJasmineStarted(info: jasmine.SuiteInfo, log: string): string {
372
    return `Custom Test Suite: ${log}`;
373
  }
374
  
375
  public displaySuccessfulSpec(spec: CustomReporterResult, log: string): string {
376
    return `✅ ${log} (${spec._jsr?.formattedDuration || 'N/A'})`;
377
  }
378
  
379
  public displayFailedSpec(spec: CustomReporterResult, log: string): string {
380
    return `❌ ${this.theme.failed(log)}`;
381
  }
382
}
383

384
// Use the custom processor
385
const reporter = new SpecReporter({
386
  spec: {
387
    displayStacktrace: StacktraceOption.NONE
388
  },
389
  customProcessors: [CustomProcessor]
390
});
391
```
392

393
## Types
394

395
### Reporter Result Types
396

397
```typescript { .api }
398
interface CustomReporterResult extends jasmine.CustomReporterResult {
399
  _jsr?: {
400
    formattedDuration?: string;
401
  };
402
}
403

404
interface ExecutedSpecs {
405
  failed: CustomReporterResult[];
406
  pending: CustomReporterResult[];
407
  successful: CustomReporterResult[];
408
}
409
```
410

411
### Theme System
412

413
```typescript { .api }
414
class Theme {
415
  /**
416
   * Creates a new theme instance and configures colors
417
   * @param configuration - Configuration object containing color settings
418
   */
419
  constructor(configuration: Configuration);
420
  
421
  /**
422
   * Apply successful spec color formatting
423
   * @param str - String to format
424
   * @returns Formatted string with successful color
425
   */
426
  successful(str: string): string;
427
  
428
  /**
429
   * Apply failed spec color formatting
430
   * @param str - String to format
431
   * @returns Formatted string with failed color
432
   */
433
  failed(str: string): string;
434
  
435
  /**
436
   * Apply pending spec color formatting
437
   * @param str - String to format
438
   * @returns Formatted string with pending color
439
   */
440
  pending(str: string): string;
441
  
442
  /**
443
   * Apply stacktrace filename color formatting
444
   * @param str - Filename string to format
445
   * @returns Formatted filename with specified color
446
   */
447
  prettyStacktraceFilename(str: string): string;
448
  
449
  /**
450
   * Apply stacktrace line number color formatting
451
   * @param str - Line number string to format
452
   * @returns Formatted line number with specified color
453
   */
454
  prettyStacktraceLineNumber(str: string): string;
455
  
456
  /**
457
   * Apply stacktrace column number color formatting
458
   * @param str - Column number string to format
459
   * @returns Formatted column number with specified color
460
   */
461
  prettyStacktraceColumnNumber(str: string): string;
462
  
463
  /**
464
   * Apply stacktrace error color formatting
465
   * @param str - Error string to format
466
   * @returns Formatted error with specified color
467
   */
468
  prettyStacktraceError(str: string): string;
469
}
470
```
471

472
### Execution Metrics
473

474
```typescript { .api }
475
class ExecutionMetrics {
476
  successfulSpecs: number;
477
  failedSpecs: number;
478
  pendingSpecs: number;
479
  skippedSpecs: number;
480
  totalSpecsDefined: number;
481
  executedSpecs: number;
482
  globalErrors: CustomReporterResult[];
483
  duration: string;
484
  random: boolean;
485
  seed: string;
486
  
487
  /**
488
   * Start execution metrics tracking
489
   * @param suiteInfo - Jasmine suite information containing total specs defined
490
   */
491
  start(suiteInfo: jasmine.SuiteInfo): void;
492
  
493
  /**
494
   * Stop execution metrics tracking and calculate final metrics
495
   * @param runDetails - Jasmine run details containing execution order information
496
   */
497
  stop(runDetails: jasmine.RunDetails): void;
498
  
499
  /**
500
   * Start timing for an individual spec
501
   */
502
  startSpec(): void;
503
  
504
  /**
505
   * Stop timing for an individual spec and store formatted duration
506
   * @param result - Spec result to attach duration information to
507
   */
508
  stopSpec(result: CustomReporterResult): void;
509
}
510
```
511

512
## Advanced Usage
513

514
### Multiple Custom Processors
515

516
```typescript
517
import { SpecReporter, DisplayProcessor } from "jasmine-spec-reporter";
518

519
class TimestampProcessor extends DisplayProcessor {
520
  public displayJasmineStarted(info: jasmine.SuiteInfo, log: string): string {
521
    const timestamp = new Date().toISOString();
522
    return `[${timestamp}] ${log}`;
523
  }
524
}
525

526
class PrefixProcessor extends DisplayProcessor {
527
  public displaySuccessfulSpec(spec: CustomReporterResult, log: string): string {
528
    return `PASS: ${log}`;
529
  }
530
  
531
  public displayFailedSpec(spec: CustomReporterResult, log: string): string {
532
    return `FAIL: ${log}`;
533
  }
534
}
535

536
jasmine.getEnv().addReporter(new SpecReporter({
537
  customProcessors: [TimestampProcessor, PrefixProcessor]
538
}));
539
```
540

541
### Protractor Integration
542

543
```typescript
544
// In protractor.conf.js
545
const { SpecReporter } = require("jasmine-spec-reporter");
546

547
exports.config = {
548
  onPrepare: function() {
549
    jasmine.getEnv().addReporter(new SpecReporter({
550
      spec: {
551
        displayStacktrace: "raw"
552
      },
553
      summary: {
554
        displayDuration: false
555
      }
556
    }));
557
  }
558
};
559
```
560

561
### Custom Print Function
562

563
```typescript
564
import * as fs from "fs";
565

566
const logFile = fs.createWriteStream("test-results.log", { flags: "a" });
567

568
const reporter = new SpecReporter({
569
  print: (log: string) => {
570
    // Write to both console and file
571
    process.stdout.write(log + "\n");
572
    logFile.write(log + "\n");
573
  }
574
});
575
```