0
# Assertions
1

2
Comprehensive assertion library providing methods for validating test conditions, comparing values, testing exceptions, and controlling test flow.
3

4
## Capabilities
5

6
### Basic Truth Assertions
7

8
Fundamental assertions for testing boolean conditions.
9

10
```javascript { .api }
11
/**
12
 * Assert that a value is truthy
13
 * @param {any} result - Value to test
14
 * @param {string} [message] - Optional assertion message
15
 */
16
assert.ok(result, message)
17

18
/**
19
 * Assert that a value is falsy
20
 * @param {any} result - Value to test
21
 * @param {string} [message] - Optional assertion message
22
 */
23
assert.notOk(result, message)
24

25
/**
26
 * Assert that a value is strictly true
27
 * @param {any} result - Value to test
28
 * @param {string} [message] - Optional assertion message
29
 */
30
assert.true(result, message)
31

32
/**
33
 * Assert that a value is strictly false
34
 * @param {any} result - Value to test
35
 * @param {string} [message] - Optional assertion message
36
 */
37
assert.false(result, message)
38
```
39

40
**Usage Examples:**
41

42
```javascript
43
QUnit.test("truth assertions", function(assert) {
44
  assert.ok(1, "1 is truthy");
45
  assert.ok("hello", "non-empty string is truthy");
46
  assert.notOk(0, "0 is falsy");
47
  assert.notOk("", "empty string is falsy");
48
  
49
  assert.true(true, "boolean true");
50
  assert.false(false, "boolean false");
51
});
52
```
53

54
### Equality Assertions
55

56
Compare values using different equality semantics.
57

58
```javascript { .api }
59
/**
60
 * Loose equality comparison using ==
61
 * @param {any} actual - Actual value
62
 * @param {any} expected - Expected value
63
 * @param {string} [message] - Optional assertion message
64
 */
65
assert.equal(actual, expected, message)
66

67
/**
68
 * Loose inequality comparison using !=
69
 * @param {any} actual - Actual value
70
 * @param {any} expected - Expected value
71
 * @param {string} [message] - Optional assertion message
72
 */
73
assert.notEqual(actual, expected, message)
74

75
/**
76
 * Strict equality comparison using ===
77
 * @param {any} actual - Actual value
78
 * @param {any} expected - Expected value
79
 * @param {string} [message] - Optional assertion message
80
 */
81
assert.strictEqual(actual, expected, message)
82

83
/**
84
 * Strict inequality comparison using !==
85
 * @param {any} actual - Actual value
86
 * @param {any} expected - Expected value
87
 * @param {string} [message] - Optional assertion message
88
 */
89
assert.notStrictEqual(actual, expected, message)
90

91
/**
92
 * Deep equality comparison (recursive)
93
 * @param {any} actual - Actual value
94
 * @param {any} expected - Expected value
95
 * @param {string} [message] - Optional assertion message
96
 */
97
assert.deepEqual(actual, expected, message)
98

99
/**
100
 * Deep inequality comparison (recursive)
101
 * @param {any} actual - Actual value
102
 * @param {any} expected - Expected value
103
 * @param {string} [message] - Optional assertion message
104
 */
105
assert.notDeepEqual(actual, expected, message)
106
```
107

108
**Usage Examples:**
109

110
```javascript
111
QUnit.test("equality assertions", function(assert) {
112
  assert.equal("1", 1, "loose equality allows type coercion");
113
  assert.notEqual("1", 2, "loose inequality");
114
  
115
  assert.strictEqual("hello", "hello", "strings are strictly equal");
116
  assert.notStrictEqual("1", 1, "different types are not strictly equal");
117
  
118
  assert.deepEqual([1, 2, 3], [1, 2, 3], "arrays with same content");
119
  assert.deepEqual({a: 1, b: 2}, {a: 1, b: 2}, "objects with same properties");
120
  assert.notDeepEqual([1, 2], [1, 2, 3], "arrays with different content");
121
});
122
```
123

124
### Property Assertions
125

126
Compare object properties and property subsets.
127

128
```javascript { .api }
129
/**
130
 * Compare enumerable properties of objects
131
 * @param {any} actual - Actual object
132
 * @param {any} expected - Expected object
133
 * @param {string} [message] - Optional assertion message
134
 */
135
assert.propEqual(actual, expected, message)
136

137
/**
138
 * Assert enumerable properties are not equal
139
 * @param {any} actual - Actual object
140
 * @param {any} expected - Expected object
141
 * @param {string} [message] - Optional assertion message
142
 */
143
assert.notPropEqual(actual, expected, message)
144

145
/**
146
 * Assert that object contains expected properties (subset)
147
 * @param {any} actual - Actual object
148
 * @param {any} expected - Expected subset of properties
149
 * @param {string} [message] - Optional assertion message
150
 */
151
assert.propContains(actual, expected, message)
152

153
/**
154
 * Assert that object does not contain expected properties (subset)
155
 * @param {any} actual - Actual object
156
 * @param {any} expected - Properties that should not be present
157
 * @param {string} [message] - Optional assertion message
158
 */
159
assert.notPropContains(actual, expected, message)
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
QUnit.test("property assertions", function(assert) {
166
  const user = { name: "Alice", age: 30, email: "alice@example.com" };
167
  
168
  assert.propEqual(user, { name: "Alice", age: 30, email: "alice@example.com" });
169
  assert.propContains(user, { name: "Alice", age: 30 });
170
  assert.notPropContains(user, { role: "admin" });
171
});
172
```
173

174
### Exception Assertions
175

176
Test for expected exceptions and promise rejections.
177

178
```javascript { .api }
179
/**
180
 * Assert that a function throws an exception
181
 * @param {Function} block - Function that should throw
182
 * @param {any} [expected] - Expected exception (optional)
183
 * @param {string} [message] - Optional assertion message
184
 */
185
assert.throws(block, expected, message)
186

187
/**
188
 * Alias for throws()
189
 * @param {Function} block - Function that should throw
190
 * @param {any} [expected] - Expected exception (optional)
191
 * @param {string} [message] - Optional assertion message
192
 */
193
assert.raises(block, expected, message)
194

195
/**
196
 * Assert that a promise rejects
197
 * @param {Promise} promise - Promise that should reject
198
 * @param {any} [expected] - Expected rejection value (optional)
199
 * @param {string} [message] - Optional assertion message
200
 * @returns {Promise<void>}
201
 */
202
assert.rejects(promise, expected, message)
203
```
204

205
**Usage Examples:**
206

207
```javascript
208
QUnit.test("exception assertions", function(assert) {
209
  assert.throws(() => {
210
    throw new Error("Something went wrong");
211
  }, Error, "function throws Error");
212
  
213
  assert.throws(() => {
214
    JSON.parse("invalid json");
215
  }, "JSON.parse throws on invalid input");
216
  
217
  // Testing promise rejection
218
  assert.rejects(
219
    fetch("/nonexistent-endpoint"),
220
    "fetch should reject for 404"
221
  );
222
});
223
```
224

225
### Numeric Assertions
226

227
Assertions for numeric comparisons with tolerance.
228

229
```javascript { .api }
230
/**
231
 * Assert that values are within specified delta
232
 * @param {number} actual - Actual numeric value
233
 * @param {number} expected - Expected numeric value
234
 * @param {number} delta - Maximum allowed difference
235
 * @param {string} [message] - Optional assertion message
236
 */
237
assert.closeTo(actual, expected, delta, message)
238
```
239

240
**Usage Examples:**
241

242
```javascript
243
QUnit.test("numeric assertions", function(assert) {
244
  assert.closeTo(0.1 + 0.2, 0.3, 0.0001, "floating point addition");
245
  assert.closeTo(Math.PI, 3.14159, 0.00001, "PI approximation");
246
});
247
```
248

249
### Test Flow Control
250

251
Control test execution flow and assertion counting.
252

253
```javascript { .api }
254
/**
255
 * Set expected number of assertions for this test
256
 * @param {number} [count] - Expected assertion count (returns current if omitted)
257
 * @returns {number|void} Current expected count when called without arguments
258
 */
259
assert.expect(count)
260

261
/**
262
 * Create async control for pausing test execution
263
 * @param {number} [count=1] - Number of async calls expected
264
 * @returns {Function} Function to call when async operation completes
265
 */
266
assert.async(count)
267

268
/**
269
 * Set timeout for current test
270
 * @param {number} duration - Timeout in milliseconds
271
 */
272
assert.timeout(duration)
273
```
274

275
**Usage Examples:**
276

277
```javascript
278
QUnit.test("async test", function(assert) {
279
  assert.expect(2);
280
  const done = assert.async();
281
  
282
  setTimeout(() => {
283
    assert.ok(true, "first assertion");
284
    assert.ok(true, "second assertion");
285
    done();
286
  }, 100);
287
});
288

289
QUnit.test("long running test", function(assert) {
290
  assert.timeout(5000); // 5 second timeout
291
  
292
  const done = assert.async();
293
  longRunningOperation(() => {
294
    assert.ok(true, "operation completed");
295
    done();
296
  });
297
});
298
```
299

300
### Step Assertions
301

302
Record and verify step-by-step execution.
303

304
```javascript { .api }
305
/**
306
 * Record a step in test execution
307
 * @param {string} message - Step description
308
 */
309
assert.step(message)
310

311
/**
312
 * Verify that recorded steps match expected sequence
313
 * @param {string[]} steps - Array of expected step messages
314
 * @param {string} [message] - Optional assertion message
315
 */
316
assert.verifySteps(steps, message)
317
```
318

319
**Usage Examples:**
320

321
```javascript
322
QUnit.test("step verification", function(assert) {
323
  function processOrder(order) {
324
    assert.step("validate order");
325
    if (order.valid) {
326
      assert.step("calculate total");
327
      assert.step("charge payment");
328
      assert.step("send confirmation");
329
    }
330
  }
331
  
332
  processOrder({ valid: true, items: [...] });
333
  
334
  assert.verifySteps([
335
    "validate order",
336
    "calculate total", 
337
    "charge payment",
338
    "send confirmation"
339
  ], "order processing steps executed in correct order");
340
});
341
```
342

343
### Low-Level Assertion Control
344

345
Direct control over assertion results.
346

347
```javascript { .api }
348
/**
349
 * Manually push assertion result
350
 * @param {Object} resultInfo - Assertion result object
351
 * @param {boolean} resultInfo.result - Whether assertion passed
352
 * @param {any} [resultInfo.actual] - Actual value
353
 * @param {any} [resultInfo.expected] - Expected value
354
 * @param {string} [resultInfo.message] - Assertion message
355
 * @param {boolean} [resultInfo.negative] - Whether this is a negative assertion
356
 * @param {string} [resultInfo.source] - Error source information
357
 */
358
assert.pushResult(resultInfo)
359

360
/**
361
 * Alias for pushResult (legacy)
362
 * @param {boolean} result - Test result
363
 * @param {any} actual - Actual value
364
 * @param {any} expected - Expected value
365
 * @param {string} message - Assertion message
366
 * @param {boolean} [negative] - Whether this is a negative assertion
367
 */
368
assert.push(result, actual, expected, message, negative)
369
```
370

371
**Usage Examples:**
372

373
```javascript
374
QUnit.test("custom assertion", function(assert) {
375
  function customAssertion(value, message) {
376
    const result = value > 0 && value < 100;
377
    assert.pushResult({
378
      result: result,
379
      actual: value,
380
      expected: "number between 0 and 100",
381
      message: message || "value is in valid range"
382
    });
383
  }
384
  
385
  customAssertion(50, "50 is in range");
386
  customAssertion(150, "150 is out of range"); // This will fail
387
});
388
```
389

390
## Types
391

392
The assertion result object used with `pushResult()` has the following structure:
393

394
```javascript { .api }
395
/**
396
 * @typedef {Object} AssertionResult
397
 * @property {boolean} result - Whether assertion passed
398
 * @property {any} [actual] - Actual value
399
 * @property {any} [expected] - Expected value
400
 * @property {string} [message] - Assertion message
401
 * @property {string} [source] - Error details if assertion failed
402
 * @property {boolean} [negative] - Whether this is a negative assertion
403
 */
404

405
/**
406
 * The assert object contains all assertion methods and is passed
407
 * as the first parameter to test callbacks.
408
 * @typedef {Object} Assert
409
 * @property {Object} test - Current test context
410
 */
411
```