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.