0
# QUnit
1

2
QUnit is a powerful, easy-to-use JavaScript testing framework that provides comprehensive testing infrastructure for both client-side and server-side JavaScript applications. Originally developed for the jQuery project, it has evolved into a standalone testing framework that supports Node.js, SpiderMonkey, and all major web browsers with zero dependencies.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
// ES Modules
15
import QUnit from "qunit";
16
```
17

18
CommonJS:
19

20
```javascript
21
// CommonJS
22
const QUnit = require("qunit");
23
```
24

25
Browser (global):
26

27
```html
28
<script src="https://code.jquery.com/qunit/qunit-2.24.1.js"></script>
29
```
30

31
## Basic Usage
32

33
```javascript
34
import QUnit from "qunit";
35

36
// Define a test module
37
QUnit.module("Math Operations", function() {
38
  
39
  // Define a test
40
  QUnit.test("addition works correctly", function(assert) {
41
    assert.strictEqual(2 + 2, 4, "2 + 2 should equal 4");
42
    assert.ok(5 > 3, "5 is greater than 3");
43
  });
44
  
45
  // Test with setup and teardown
46
  QUnit.test("multiplication", function(assert) {
47
    assert.expect(2);
48
    assert.strictEqual(3 * 4, 12, "3 * 4 equals 12");
49
    assert.strictEqual(0 * 5, 0, "0 * 5 equals 0");
50
  });
51
});
52

53
// Start the test suite (if autostart is disabled)
54
QUnit.start();
55
```
56

57
## Architecture
58

59
QUnit is built around several key components:
60

61
- **Test Definition API**: Functions for defining individual tests and organizing them into modules
62
- **Assertion System**: Comprehensive set of assertion methods for validating test conditions
63
- **Configuration System**: Flexible configuration options for controlling test execution behavior
64
- **Event System**: Event-driven architecture for monitoring test lifecycle and results
65
- **Reporter System**: Built-in and extensible reporting system for different output formats
66
- **Hook System**: Global and module-level hooks for setup and teardown operations
67
- **CLI Interface**: Command-line tools for running tests in Node.js environments
68

69
## Capabilities
70

71
### Test Definition
72

73
Core functionality for defining and organizing tests into logical groups with support for various test types and execution modes.
74

75
```javascript { .api }
76
/**
77
 * Define a test
78
 * @param {string} testName - Name of the test
79
 * @param {Function} callback - Test callback function
80
 */
81
QUnit.test(testName, callback)
82

83
/**
84
 * Define a test module
85
 * @param {string} name - Module name
86
 * @param {Function} [scope] - Module callback function
87
 */
88
QUnit.module(name, scope)
89

90
/**
91
 * Define a test module with options
92
 * @param {string} name - Module name
93
 * @param {Object} options - Module configuration
94
 * @param {Function} [scope] - Module callback function
95
 */
96
QUnit.module(name, options, scope)
97
```
98

99
[Test Definition](./test-definition.md)
100

101
### Assertions
102

103
Comprehensive assertion library providing methods for validating test conditions, comparing values, and testing exceptions.
104

105
```javascript { .api }
106
/**
107
 * Assertion methods available in test callbacks
108
 */
109
assert.ok(result, message)
110
assert.strictEqual(actual, expected, message)
111
assert.deepEqual(actual, expected, message)
112
assert.throws(block, expected, message)
113
assert.async(count)
114
assert.step(message)
115
assert.verifySteps(steps, message)
116
assert.timeout(duration)
117
```
118

119
[Assertions](./assertions.md)
120

121
### Configuration
122

123
Flexible configuration system for controlling test execution, filtering tests, setting timeouts, and customizing behavior.
124

125
```javascript { .api }
126
/**
127
 * QUnit configuration object
128
 * @typedef {Object} QUnitConfig
129
 * @property {boolean} autostart - Whether to automatically start tests
130
 * @property {boolean} reorder - Whether to reorder tests based on previous failures
131
 * @property {boolean} requireExpects - Whether all tests must call expect()
132
 * @property {number} testTimeout - Default timeout for tests in milliseconds
133
 * @property {string} filter - Filter tests by name
134
 * @property {string} module - Filter tests by module name
135
 * @property {boolean} noglobals - Check for global variable pollution
136
 * @property {boolean} failOnZeroTests - Fail when no tests are run
137
 * @property {number} maxDepth - Maximum depth for object comparison
138
 */
139
QUnit.config
140
```
141

142
[Configuration](./configuration.md)
143

144
### Event System
145

146
Event-driven architecture enabling monitoring of test lifecycle, capturing results, and building custom reporting solutions.
147

148
```javascript { .api }
149
/**
150
 * Register event listener
151
 * @param {string} eventName - Event name
152
 * @param {Function} callback - Event callback
153
 */
154
QUnit.on(eventName, callback)
155

156
// Available events: "runStart", "suiteStart", "testStart", "assertion", 
157
// "testEnd", "suiteEnd", "runEnd", "error"
158
```
159

160
[Events](./events.md)
161

162
### CLI Interface
163

164
Command-line interface for running tests in Node.js environments with extensive configuration options and built-in reporters.
165

166
```javascript { .api }
167
// Command line usage:
168
// qunit [options] [files...]
169

170
/**
171
 * CLI Options
172
 * @typedef {Object} CLIOptions
173
 * @property {string} [filter] - Filter tests by pattern
174
 * @property {string} [module] - Run only specified module
175
 * @property {string} [reporter] - Specify reporter (console, tap)
176
 * @property {string[]} [require] - Modules to require before tests
177
 * @property {string} [seed] - Seed for test randomization
178
 * @property {boolean} [watch] - Watch files for changes
179
 */
180
```
181

182
[CLI Interface](./cli.md)
183

184
### Hook System
185

186
Global and module-level hooks for setup and teardown operations, providing flexible test lifecycle management.
187

188
```javascript { .api }
189
/**
190
 * Global hooks that apply to all tests
191
 * @param {Function} callback - Hook callback function
192
 */
193
QUnit.hooks.beforeEach(callback)
194
QUnit.hooks.afterEach(callback)
195

196
/**
197
 * Module-level hooks (available in module callback)
198
 * @param {Function} callback - Hook callback function
199
 */
200
hooks.before(callback)
201
hooks.beforeEach(callback)
202
hooks.afterEach(callback)
203
hooks.after(callback)
204
```
205

206
[Hook System](./hooks.md)
207

208
### Error Handling
209

210
Robust error and exception handling capabilities for managing uncaught errors and debugging test execution.
211

212
```javascript { .api }
213
/**
214
 * Error handling functions
215
 * @param {Function} callback - Error callback function
216
 */
217
QUnit.onError(callback)
218
QUnit.onUncaughtException(callback)
219

220
/**
221
 * Push test failure
222
 * @param {string} message - Failure message
223
 * @param {string} [source] - Source location
224
 */
225
QUnit.pushFailure(message, source)
226
```
227

228
[Error Handling](./error-handling.md)
229

230
### Utility Functions
231

232
Helper functions for object comparison, type checking, serialization, and debugging support.
233

234
```javascript { .api }
235
/**
236
 * Utility functions
237
 */
238
QUnit.equiv(a, b)        // Deep equivalence check
239
QUnit.dump.parse(obj)    // Serialize object to string
240
QUnit.is(type, obj)      // Type checking
241
QUnit.objectType(obj)    // Get object type
242
QUnit.diff(a, b)         // Generate diff between values
243
QUnit.stack(offset)      // Get stack trace
244
```
245

246
[Utility Functions](./utilities.md)
247

248
## Types
249

250
## Test Flavors
251

252
QUnit supports several test variants for different testing scenarios:
253

254
```javascript { .api }
255
/**
256
 * Test variations
257
 */
258
QUnit.test(name, callback)      // Regular test
259
QUnit.skip(name)                // Skip test
260
QUnit.only(name, callback)      // Run only this test
261
QUnit.todo(name, callback)      // Todo test (expected to fail)
262

263
/**
264
 * Module variations
265
 */
266
QUnit.module(name, scope)       // Regular module
267
QUnit.module.skip(name, scope)  // Skip entire module
268
QUnit.module.only(name, scope)  // Run only this module
269
QUnit.module.todo(name, scope)  // Todo module
270
```
271

272
[Test Flavors](./test-flavors.md)
273

274
## Types
275

276
```javascript { .api }
277
/**
278
 * @typedef {Object} ModuleOptions
279
 * @property {Function} [before] - Setup before module
280
 * @property {Function} [beforeEach] - Setup before each test
281
 * @property {Function} [afterEach] - Teardown after each test
282
 * @property {Function} [after] - Teardown after module
283
 */
284

285
/**
286
 * @typedef {Object} AssertionResult
287
 * @property {boolean} result - Whether assertion passed
288
 * @property {any} [actual] - Actual value
289
 * @property {any} [expected] - Expected value
290
 * @property {string} [message] - Assertion message
291
 */
292
```