You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api/assert/pushResult.md
+59-41Lines changed: 59 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,47 +24,12 @@ Report the result of a custom assertion.
24
24
25
25
## Examples
26
26
27
-
If you need to express an expectation that is not abstracted by a built-in QUnit assertion, you can perform your own logic ad-hoc in an expression, and then pass two directly comparable values to [`assert.strictEqual()`](./strictEqual.md), or pass your own representative boolean result to [`assert.true()`](./true.md).
28
-
29
-
```js
30
-
QUnit.test('bad example of remainder', assert=> {
31
-
constresult=4;
32
-
constactual= (result %3) ===2;
33
-
assert.true(actual, 'remainder');
34
-
// In case of failure:
35
-
// > Actual: false
36
-
// > Expected: true
37
-
//
38
-
// No mention of the actual remainder.
39
-
// No mention of the expected value.
40
-
});
41
-
42
-
QUnit.test('good example of remainder', assert=> {
43
-
constresult=4;
44
-
assert.strictEqual(result %3, 2, 'remainder');
45
-
// In case of failure:
46
-
// > Actual: 1
47
-
// > Expected: 2
48
-
});
49
-
50
-
QUnit.test('bad example of between', assert=> {
51
-
constactual=3;
52
-
constisBetween= (actual >=1&& actual <=10);
53
-
assert.true(isBetween, 'result between 1 and 10');
54
-
// In case of failure:
55
-
// > Actual: false
56
-
// > Expected: true
57
-
//
58
-
// No mention of the actual remainder.
59
-
// No mention of the expected value.
60
-
// Cannot be expressed in a useful way with strictEqual()
61
-
});
62
-
```
63
-
64
-
### Custom assertion
27
+
### Create a QUnit assert plugin
65
28
66
29
With a custom assertion method, you can control how an assertion should be evaluated, separately from how its actual and expected values are described in case of a failure.
67
30
31
+
This provides more helpful and transparent diagnostic information when test failures are presented. It also lets you avoid duplication and separate concerns between your test requirements and the way specific a generic and re-usable check is implemented.
32
+
68
33
For example:
69
34
70
35
```js
@@ -79,11 +44,64 @@ QUnit.assert.between = function (actual, from, to, message) {
79
44
});
80
45
};
81
46
82
-
QUnit.test('custom assertion example', assert=> {
83
-
constresult=3;
47
+
QUnit.test('example', assert=> {
48
+
constresult=42;
84
49
assert.between(result, 1, 10, 'result');
85
-
// Example of failure if result is out of range
50
+
// Example test failure
86
51
// > actual: 42
87
52
// > expected: between 1 and 10
88
53
});
89
54
```
55
+
56
+
### When to create an assertion
57
+
58
+
If there isn't a built-in QUnit assertion for something that you need to check, you can always freely express it using inline JavaScript within your test. It is recommended to, whenever possible, end your ad-hoc logic with two values that you can pass to [`assert.strictEqual()`](./strictEqual.md), or pass a boolean result to [`assert.true()`](./true.md).
59
+
60
+
```js
61
+
QUnit.test('remainder example [bad]', assert=> {
62
+
constactual=4;
63
+
64
+
constresult= (actual %3) ===2;
65
+
assert.true(result);
66
+
67
+
// Example failure:
68
+
// > Actual: false
69
+
// > Expected: true
70
+
});
71
+
72
+
QUnit.test('remainder example [good]', assert=> {
73
+
constactual=4;
74
+
75
+
constresult= (actual %3);
76
+
assert.strictEqual(result, 2, 'remainder of mod 3');
77
+
78
+
// Example failure:
79
+
// > Message: remainder of mod 3
80
+
// > Actual: 1
81
+
// > Expected: 2
82
+
});
83
+
84
+
QUnit.test('between example', assert=> {
85
+
constactual=42;
86
+
87
+
constisBetween= actual >=1&& actual <=10;
88
+
assert.true(isBetween);
89
+
90
+
// Example failure:
91
+
// > Actual: false
92
+
// > Expected: true
93
+
});
94
+
```
95
+
96
+
Writing a custom expression like this is perfectly fine occasionally. But, if you need to do this a lot, you do take on additional risks and costs over time:
97
+
98
+
* Risk of subtle bugs or false positives due to logic duplication.
99
+
With a plugin, you can write/document/test it once, and then re-use.
100
+
* No mention of the actual number.
101
+
* No mention of the expected value(s).
102
+
* No description of the problem.
103
+
* No (useful) diff.
104
+
105
+
This is likely to increase the cost of debugging, requiring an issue to first be reproduced and stepped-through locally before the failure is understood. You can compensate for this by maintaining a copy of the most important information in the "message" field of your assertions.
106
+
107
+
When you create an assertion plugin instead, this is automated as part of the "actual" and "expected" values, which you can control separately from the boolean result.
0 commit comments