0
# Karma Jasmine HTML Reporter
1

2
Karma Jasmine HTML Reporter is a Karma plugin that provides a dynamic HTML interface for viewing Jasmine test results. It displays test results at the debug.html page during test execution, allowing developers to run individual tests or entire test suites interactively.
3

4
## Package Information
5

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

11
## Core Imports
12

13
This package is a Karma plugin and is not imported directly into code. Instead, it's loaded via Karma configuration:
14

15
```javascript
16
// karma.conf.js - require in plugins array
17
module.exports = function(config) {
18
  config.set({
19
    plugins: [
20
      require('karma-jasmine'),
21
      require('karma-jasmine-html-reporter')
22
    ],
23
    reporters: ['kjhtml']
24
  });
25
};
26
```
27

28
## Basic Usage
29

30
```javascript
31
// karma.conf.js
32
module.exports = function(config) {
33
  config.set({
34
    frameworks: ['jasmine'],
35
    plugins: [
36
        require('karma-jasmine'),
37
        require('karma-jasmine-html-reporter')
38
    ],
39
    reporters: ['kjhtml']
40
  });
41
};
42
```
43

44
## Architecture
45

46
The plugin consists of two main components:
47

48
- **Karma Plugin Registration**: Exports a Karma plugin factory that registers the 'kjhtml' reporter
49
- **HTML Boot Script**: A Jasmine-based HTML UI initialization script that sets up the interactive test interface
50
- **File Injection System**: Dynamically injects Jasmine core CSS/JS files and boot scripts into the Karma file array
51

52
## Capabilities
53

54
### Plugin Registration
55

56
Main Karma plugin export that provides the 'kjhtml' reporter.
57

58
```javascript { .api }
59
/**
60
 * Main plugin export - Karma plugin registration
61
 * Registers the 'kjhtml' reporter with Karma
62
 */
63
module.exports = {
64
  'reporter:kjhtml': ['type', initReporter]
65
};
66
```
67

68
### Reporter Initialization
69

70
Core function that initializes the HTML reporter and configures file injection.
71

72
```javascript { .api }
73
/**
74
 * Initializes the HTML reporter and sets up file injection
75
 * @param {Object} karmaConfig - Karma configuration object
76
 * @param {Function} baseReporterDecorator - Base reporter decorator from Karma
77
 */
78
function initReporter(karmaConfig, baseReporterDecorator) {
79
  // Implementation handles:
80
  // - Base reporter decoration  
81
  // - Configuration option processing
82
  // - Jasmine core file injection
83
  // - Boot script injection
84
}
85

86
// Dependency injection specification
87
initReporter.$inject = ['config', 'baseReporterDecorator'];
88
```
89

90
### File Pattern Creation
91

92
Internal utility function used by the reporter to create Karma file pattern objects.
93

94
```javascript { .api }
95
/**
96
 * Creates a Karma file pattern object for injecting files
97
 * @param {string} path - The file path to include
98
 * @returns {Object} Karma file pattern object
99
 */
100
function createPattern(path) {
101
  return { 
102
    pattern: path, 
103
    included: true, 
104
    served: true, 
105
    watched: false 
106
  };
107
}
108
```
109

110
### Configuration Options
111

112
Optional configuration to suppress console output when using multiple reporters.
113

114
```javascript { .api }
115
/**
116
 * Optional configuration object for the HTML reporter
117
 * Set in karma.conf.js under jasmineHtmlReporter key
118
 */
119
interface JasmineHtmlReporterConfig {
120
  /** Suppress all console output (overrides other suppress settings) */
121
  suppressAll?: boolean;
122
  /** Suppress failed test console output only */
123
  suppressFailed?: boolean;
124
}
125
```
126

127
**Usage Example:**
128

129
```javascript
130
// karma.conf.js
131
module.exports = function(config) {
132
  config.set({
133
    reporters: ['kjhtml', 'mocha'], // Multiple reporters
134

135
    jasmineHtmlReporter: {
136
      suppressAll: true,      // Suppress all messages
137
      suppressFailed: true    // Suppress failed messages only
138
    }
139
  });
140
};
141
```
142

143
### Boot Script Functionality
144

145
The boot.js script provides the HTML interface initialization:
146

147
```javascript { .api }
148
/**
149
 * Jasmine HTML interface configuration from URL query parameters
150
 */
151
interface RuntimeConfig {
152
  /** Stop execution on first spec failure */
153
  stopOnSpecFailure?: boolean;
154
  /** Stop spec on first expectation failure */
155
  stopSpecOnExpectationFailure?: boolean;
156
  /** Hide disabled specs in the UI */
157
  hideDisabled?: boolean;
158
  /** Random execution seed */
159
  random?: string;
160
  /** Specific seed for random execution */
161
  seed?: string;
162
}
163

164
/**
165
 * Jasmine Environment interface (from jasmine-core)
166
 */
167
interface JasmineEnv {
168
  configure(config: any): void;
169
  addReporter(reporter: any): void;
170
}
171

172
/**
173
 * Jasmine Timer interface (from jasmine-core)
174
 */
175
interface JasmineTimer {
176
  start(): void;
177
  elapsed(): number;
178
}
179

180
/**
181
 * HTML Reporter instance configuration
182
 */
183
interface HtmlReporterOptions {
184
  /** Jasmine environment instance */
185
  env: JasmineEnv;
186
  /** Navigation function for URL parameter changes */
187
  navigateWithNewParam: (key: string, value: string) => void;
188
  /** Query string manipulation function */
189
  addToExistingQueryString: (key: string, value: string) => string;
190
  /** Container element provider */
191
  getContainer: () => HTMLElement;
192
  /** DOM element creation function */
193
  createElement: (...args: any[]) => HTMLElement;
194
  /** Text node creation function */
195
  createTextNode: (...args: any[]) => Text;
196
  /** Timer instance for test execution timing */
197
  timer: JasmineTimer;
198
  /** Whether to enable spec filtering */
199
  filterSpecs: boolean;
200
}
201
```
202

203
## Dependencies
204

205
### Peer Dependencies
206

207
These packages must be installed in the project using karma-jasmine-html-reporter:
208

209
```json
210
{
211
  "jasmine-core": "^4.0.0 || ^5.0.0",
212
  "karma": "^6.0.0", 
213
  "karma-jasmine": "^5.0.0"
214
}
215
```
216

217
### File Dependencies
218

219
The plugin automatically injects these files from jasmine-core:
220

221
- **CSS Files**: All CSS files from jasmine-core for styling the HTML interface
222
- **JavaScript Files**: Core Jasmine JavaScript files (excluding jasmine.js which is provided by karma-jasmine)
223
- **Boot Scripts**: boot0.js from jasmine-core and the custom boot.js from the plugin
224

225
## Query Parameters
226

227
The HTML interface supports URL query parameters for test execution control:
228

229
- `spec`: Filter tests by name pattern
230
- `stopOnSpecFailure`: Stop on first test failure  
231
- `stopSpecOnExpectationFailure`: Stop on first assertion failure
232
- `hideDisabled`: Hide disabled tests in the UI
233
- `random`: Enable random test execution
234
- `seed`: Set specific seed for random execution
235

236
## Error Handling
237

238
The plugin integrates with Karma's reporter system and inherits standard Karma error handling. Configuration errors are handled through Karma's configuration validation system.
239

240
## Platform Compatibility
241

242
- **Environment**: Node.js (via Karma)
243
- **Browsers**: All browsers supported by Karma and Jasmine
244
- **Jasmine Version**: Compatible with Jasmine 4.x and 5.x as specified in peer dependencies