0
# karma-qunit
1

2
karma-qunit is a Karma plugin that provides an adapter for the QUnit testing framework. It enables seamless integration between Karma test runner and QUnit test suites by automatically configuring QUnit files, providing configuration options, and establishing the bridge between QUnit test execution and Karma's reporting system.
3

4
## Package Information
5

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

11
## Core Imports
12

13
karma-qunit is not imported directly in your code. Instead, it's configured as a Karma plugin:
14

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

25
If requiring the plugin programmatically:
26

27
```javascript
28
const karmaQunit = require('karma-qunit');
29
```
30

31
## Basic Usage
32

33
```javascript
34
// karma.conf.js
35
module.exports = function (config) {
36
  config.set({
37
    frameworks: ['qunit'],
38
    plugins: ['karma-qunit'],
39
    files: [
40
      'src/**/*.js',
41
      'test/**/*.js'
42
    ],
43
    browsers: ['Chrome']
44
  });
45
};
46
```
47

48
With QUnit configuration options:
49

50
```javascript
51
// karma.conf.js  
52
module.exports = function (config) {
53
  config.set({
54
    frameworks: ['qunit'],
55
    plugins: ['karma-qunit'],
56
    files: ['test/**/*.js'],
57
    client: {
58
      clearContext: false,
59
      qunit: {
60
        showUI: true,
61
        testTimeout: 5000,
62
        autostart: true
63
      }
64
    }
65
  });
66
};
67
```
68

69
## Capabilities
70

71
### Karma Framework Registration
72

73
karma-qunit registers itself as a Karma framework plugin that can be activated by including 'qunit' in the frameworks array.
74

75
```javascript { .api }
76
/**
77
 * Main module export providing Karma framework factory
78
 */
79
module.exports = {
80
  'framework:qunit': ['factory', initQUnit]
81
};
82
```
83

84
### QUnit Framework Initialization
85

86
Initializes the QUnit framework by adding necessary files to Karma's file list.
87

88
```javascript { .api }
89
/**
90
 * Initializes QUnit framework for Karma
91
 * Automatically adds QUnit CSS, JavaScript library, and adapter files
92
 * @param {Array} files - Karma files array to modify
93
 */
94
function initQUnit(files);
95

96
/**
97
 * Dependency injection annotation for Karma framework
98
 * Specifies that initQUnit function requires config.files parameter
99
 */
100
initQUnit.$inject = ['config.files'];
101
```
102

103
### File Pattern Creation
104

105
Internal utility for creating Karma file pattern objects.
106

107
```javascript { .api }
108
/**
109
 * Creates a Karma file pattern object with default settings
110
 * @param {string} pattern - File path pattern
111
 * @returns {FilePattern} File pattern object with properties: pattern, included, served, watched
112
 */
113
function createPattern(pattern);
114

115
/** File pattern object returned by createPattern */
116
interface FilePattern {
117
  pattern: string;
118
  included: boolean;
119
  served: boolean;
120
  watched: boolean;
121
}
122
```
123

124
## Configuration Options
125

126
### QUnit Configuration (`client.qunit`)
127

128
All QUnit configuration options can be passed through Karma's client configuration:
129

130
```javascript { .api }
131
interface QUnitClientConfig {
132
  /** Display QUnit UI in browser (requires clearContext: false) */
133
  showUI?: boolean;
134
  /** Control automatic test execution start */
135
  autostart?: boolean;
136
  /** Test timeout in milliseconds */
137
  testTimeout?: number;
138
  /** Any other QUnit.config option */
139
  [key: string]: any;
140
}
141
```
142

143
**Common Configuration Options:**
144

145
- **showUI** (boolean): Shows QUnit UI in the browser. Requires `clearContext: false` in Karma config.
146
- **autostart** (boolean): Controls whether QUnit starts automatically. Default: true.
147
- **testTimeout** (number): Test timeout in milliseconds.
148
- **Any QUnit.config option**: All options from [QUnit.config](https://api.qunitjs.com/config/QUnit.config) are supported.
149

150
### Usage Example:
151

152
```javascript
153
// karma.conf.js
154
module.exports = function (config) {
155
  config.set({
156
    frameworks: ['qunit'],
157
    plugins: ['karma-qunit'],
158
    client: {
159
      clearContext: false, // Required for showUI
160
      qunit: {
161
        showUI: true,
162
        testTimeout: 10000,
163
        autostart: false, // Manual start control
164
        reorder: false,   // QUnit config option
165
        altertitle: false // QUnit config option
166
      }
167
    }
168
  });
169
};
170
```
171

172
## Architecture
173

174
karma-qunit consists of several key components:
175

176
- **Plugin Registration**: Registers as a Karma framework plugin via factory pattern
177
- **File Management**: Automatically includes QUnit CSS, JavaScript, and adapter files
178
- **Configuration Bridge**: Passes Karma client configuration to QUnit
179
- **Test Adapter**: Bridges QUnit test execution with Karma reporting system
180
- **DOM Integration**: Manages QUnit fixture elements and optional UI display
181

182
The adapter creates a wrapper around QUnit that:
183
- Intercepts QUnit test lifecycle events (begin, testStart, log, testDone, done)
184
- Translates QUnit test results to Karma's expected format
185
- Handles test timing, error collection, and coverage reporting
186
- Manages DOM fixtures and UI elements
187

188
## Browser Integration
189

190
The adapter establishes the following browser-level integrations:
191

192
### QUnit Configuration Setup
193

194
```javascript { .api }
195
/**
196
 * Creates QUnit configuration from Karma config
197
 * @param {Object} karma - Karma instance with config property
198
 * @returns {Object} QUnit configuration object with autostart: false and merged options
199
 */
200
function createQUnitConfig(karma);
201
```
202

203
### Test Execution Control
204

205
```javascript { .api }
206
/**
207
 * Creates QUnit start function for Karma integration
208
 * @param {Object} tc - Karma test context
209
 * @param {Object} runnerPassedIn - Optional QUnit runner instance (defaults to window.QUnit)
210
 * @returns {Function} Function that initializes QUnit test execution within Karma
211
 */
212
function createQUnitStartFn(tc, runnerPassedIn);
213
```
214

215
## Automatic File Inclusion
216

217
karma-qunit automatically includes these files in your Karma configuration:
218

219
1. **qunit/qunit/qunit.css** - QUnit CSS styles
220
2. **qunit** - QUnit JavaScript library (resolved via require.resolve('qunit'))  
221
3. **lib/adapter.js** - karma-qunit adapter for browser integration
222

223
## Dependencies
224

225
### Peer Dependencies
226

227
```json
228
{
229
  "karma": "^4.0.0 || ^5.0.0 || ^6.0.0",
230
  "qunit": ">=2.1.1"
231
}
232
```
233

234
### Runtime Dependencies
235

236
karma-qunit has **zero runtime dependencies**, making it lightweight and avoiding version conflicts.
237

238
## Error Handling
239

240
The adapter captures and formats QUnit test failures:
241

242
- **Test Assertions**: Failed assertions are captured with expected/actual values
243
- **Error Messages**: Detailed error messages including source location when available
244
- **Exception Handling**: JavaScript exceptions in tests are properly reported
245
- **Global Failures**: Global failures are filtered out to avoid duplicate reporting
246

247
Test results include:
248
- Test description and module/suite information
249
- Success/failure status and skip indicators  
250
- Detailed error logs with expected vs actual comparisons
251
- Execution timing information
252

253
## Coverage Integration
254

255
karma-qunit automatically collects code coverage data when available:
256

257
```javascript
258
// Coverage data is automatically included in test completion
259
tc.complete({
260
  coverage: window.__coverage__
261
});
262
```
263

264
This integrates with coverage tools like Istanbul/nyc when configured in your Karma setup.