Skip to content

Commit 591a6e3

Browse files
BridgeARBridgeAR
committed
assert: allow printf-style messages as assertion error
Also add functions as allowed message input. This allows to have leavy message computation to become cheaper.
1 parent 0c1fb98 commit 591a6e3

File tree

3 files changed

+315
-49
lines changed

3 files changed

+315
-49
lines changed

‎doc/api/assert.md‎

Lines changed: 74 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -305,10 +305,14 @@ destructuring and call methods directly on the instance.
305305

306306
<!-- YAML
307307
added: v0.5.9
308+
changes:
309+
- version: REPLACEME
310+
pr-url: https://github.com/nodejs/node/pull/58849
311+
description: Message may now be a `printf`-like format string or function.
308312
-->
309313

310314
* `value` {any} The input that is checked for being truthy.
311-
* `message` {string|Error}
315+
* `message` {string|Error|Function}
312316

313317
An alias of [`assert.ok()`][].
314318

@@ -324,6 +328,9 @@ changes:
324328
- version: REPLACEME
325329
pr-url: https://github.com/nodejs/node/pull/57627
326330
description: Invalid dates are now considered equal.
331+
- version: REPLACEME
332+
pr-url: https://github.com/nodejs/node/pull/58849
333+
description: Message may now be a `printf`-like format string or function.
327334
- version: v24.0.0
328335
pr-url: https://github.com/nodejs/node/pull/57622
329336
description: Recursion now stops when either side encounters a circular
@@ -375,7 +382,7 @@ changes:
375382

376383
* `actual` {any}
377384
* `expected` {any}
378-
* `message` {string|Error}
385+
* `message` {string|Error|Function}
379386

380387
**Strict assertion mode**
381388

@@ -524,6 +531,9 @@ changes:
524531
- version: REPLACEME
525532
pr-url: https://github.com/nodejs/node/pull/57627
526533
description: Invalid dates are now considered equal.
534+
- version: REPLACEME
535+
pr-url: https://github.com/nodejs/node/pull/58849
536+
description: Message may now be a `printf`-like format string or function.
527537
- version: v24.0.0
528538
pr-url: https://github.com/nodejs/node/pull/57622
529539
description: Recursion now stops when either side encounters a circular
@@ -567,7 +577,7 @@ changes:
567577

568578
* `actual` {any}
569579
* `expected` {any}
570-
* `message` {string|Error}
580+
* `message` {string|Error|Function}
571581

572582
Tests for deep equality between the `actual` and `expected` parameters.
573583
"Deep" equality means that the enumerable "own" properties of child objects
@@ -829,14 +839,17 @@ added:
829839
- v13.6.0
830840
- v12.16.0
831841
changes:
842+
- version: REPLACEME
843+
pr-url: https://github.com/nodejs/node/pull/58849
844+
description: Message may now be a `printf`-like format string or function.
832845
- version: v16.0.0
833846
pr-url: https://github.com/nodejs/node/pull/38111
834847
description: This API is no longer experimental.
835848
-->
836849

837850
* `string` {string}
838851
* `regexp` {RegExp}
839-
* `message` {string|Error}
852+
* `message` {string|Error|Function}
840853

841854
Expects the `string` input not to match the regular expression.
842855

@@ -1069,6 +1082,9 @@ assert.doesNotThrow(
10691082
<!-- YAML
10701083
added: v0.1.21
10711084
changes:
1085+
- version: REPLACEME
1086+
pr-url: https://github.com/nodejs/node/pull/58849
1087+
description: Message may now be a `printf`-like format string or function.
10721088
- version:
10731089
- v16.0.0
10741090
- v14.18.0
@@ -1083,7 +1099,7 @@ changes:
10831099

10841100
* `actual` {any}
10851101
* `expected` {any}
1086-
* `message` {string|Error}
1102+
* `message` {string|Error|Function}
10871103

10881104
**Strict assertion mode**
10891105

@@ -1254,14 +1270,17 @@ added:
12541270
- v13.6.0
12551271
- v12.16.0
12561272
changes:
1273+
- version: REPLACEME
1274+
pr-url: https://github.com/nodejs/node/pull/58849
1275+
description: Message may now be a `printf`-like format string or function.
12571276
- version: v16.0.0
12581277
pr-url: https://github.com/nodejs/node/pull/38111
12591278
description: This API is no longer experimental.
12601279
-->
12611280

12621281
* `string` {string}
12631282
* `regexp` {RegExp}
1264-
* `message` {string|Error}
1283+
* `message` {string|Error|Function}
12651284

12661285
Expects the `string` input to match the regular expression.
12671286

@@ -1303,6 +1322,9 @@ instance of {Error} then it will be thrown instead of the
13031322
<!-- YAML
13041323
added: v0.1.21
13051324
changes:
1325+
- version: REPLACEME
1326+
pr-url: https://github.com/nodejs/node/pull/58849
1327+
description: Message may now be a `printf`-like format string or function.
13061328
- version:
13071329
- v16.0.0
13081330
- v14.18.0
@@ -1338,7 +1360,7 @@ changes:
13381360

13391361
* `actual` {any}
13401362
* `expected` {any}
1341-
* `message` {string|Error}
1363+
* `message` {string|Error|Function}
13421364

13431365
**Strict assertion mode**
13441366

@@ -1427,6 +1449,9 @@ instead of the `AssertionError`.
14271449
<!-- YAML
14281450
added: v1.2.0
14291451
changes:
1452+
- version: REPLACEME
1453+
pr-url: https://github.com/nodejs/node/pull/58849
1454+
description: Message may now be a `printf`-like format string or function.
14301455
- version: v9.0.0
14311456
pr-url: https://github.com/nodejs/node/pull/15398
14321457
description: The `-0` and `+0` are not considered equal anymore.
@@ -1458,7 +1483,7 @@ changes:
14581483

14591484
* `actual` {any}
14601485
* `expected` {any}
1461-
* `message` {string|Error}
1486+
* `message` {string|Error|Function}
14621487

14631488
Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
14641489

@@ -1487,6 +1512,9 @@ instead of the [`AssertionError`][].
14871512
<!-- YAML
14881513
added: v0.1.21
14891514
changes:
1515+
- version: REPLACEME
1516+
pr-url: https://github.com/nodejs/node/pull/58849
1517+
description: Message may now be a `printf`-like format string or function.
14901518
- version:
14911519
- v16.0.0
14921520
- v14.18.0
@@ -1501,7 +1529,7 @@ changes:
15011529

15021530
* `actual` {any}
15031531
* `expected` {any}
1504-
* `message` {string|Error}
1532+
* `message` {string|Error|Function}
15051533

15061534
**Strict assertion mode**
15071535

@@ -1551,14 +1579,17 @@ parameter is an instance of {Error} then it will be thrown instead of the
15511579
<!-- YAML
15521580
added: v0.1.21
15531581
changes:
1582+
- version: REPLACEME
1583+
pr-url: https://github.com/nodejs/node/pull/58849
1584+
description: Message may now be a `printf`-like format string or function.
15541585
- version: v10.0.0
15551586
pr-url: https://github.com/nodejs/node/pull/17003
15561587
description: Used comparison changed from Strict Equality to `Object.is()`.
15571588
-->
15581589

15591590
* `actual` {any}
15601591
* `expected` {any}
1561-
* `message` {string|Error}
1592+
* `message` {string|Error|Function}
15621593

15631594
Tests strict inequality between the `actual` and `expected` parameters as
15641595
determined by [`Object.is()`][].
@@ -1604,14 +1635,17 @@ instead of the `AssertionError`.
16041635
<!-- YAML
16051636
added: v0.1.21
16061637
changes:
1638+
- version: REPLACEME
1639+
pr-url: https://github.com/nodejs/node/pull/58849
1640+
description: Message may now be a `printf`-like format string or function.
16071641
- version: v10.0.0
16081642
pr-url: https://github.com/nodejs/node/pull/18319
16091643
description: The `assert.ok()` (no arguments) will now use a predefined
16101644
error message.
16111645
-->
16121646

16131647
* `value` {any}
1614-
* `message` {string|Error}
1648+
* `message` {string|Error|Function}
16151649

16161650
Tests if `value` is truthy. It is equivalent to
16171651
`assert.equal(!!value, true, message)`.
@@ -1844,14 +1878,24 @@ argument gets considered.
18441878
<!-- YAML
18451879
added: v0.1.21
18461880
changes:
1881+
- version: REPLACEME
1882+
pr-url: https://github.com/nodejs/node/pull/58849
1883+
description: Message may now be a `printf`-like format string or function.
18471884
- version: v10.0.0
18481885
pr-url: https://github.com/nodejs/node/pull/17003
18491886
description: Used comparison changed from Strict Equality to `Object.is()`.
18501887
-->
18511888

18521889
* `actual` {any}
18531890
* `expected` {any}
1854-
* `message` {string|Error}
1891+
* `message` {string|Error|Function} Postfix `printf`-like arguments in case
1892+
it's used as format string.
1893+
If message is a function, it is called in case of a comparison failure. The
1894+
function receives the `actual` and `expected` arguments and has to return a
1895+
string that is going to be used as error message.
1896+
`printf`-like format strings and functions are beneficial for performance
1897+
reasons in case arguments are passed through. In addition, it allows nice
1898+
formatting with ease.
18551899

18561900
Tests strict equality between the `actual` and `expected` parameters as
18571901
determined by [`Object.is()`][].
@@ -1880,8 +1924,17 @@ const oranges = 2;
18801924
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
18811925
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
18821926

1927+
assert.strictEqual(apples, oranges, 'apples %s !== oranges %s', apples, oranges);
1928+
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
1929+
18831930
assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
18841931
// TypeError: Inputs are not identical
1932+
1933+
assert.strictEqual(apples, oranges, (actual, expected) => {
1934+
// Do 'heavy' computations
1935+
return `I expected ${expected} but I got ${actual}`;
1936+
});
1937+
// AssertionError [ERR_ASSERTION]: I expected oranges but I got apples
18851938
```
18861939

18871940
```cjs
@@ -1908,8 +1961,17 @@ const oranges = 2;
19081961
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
19091962
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
19101963

1964+
assert.strictEqual(apples, oranges, 'apples %s !== oranges %s', apples, oranges);
1965+
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
1966+
19111967
assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
19121968
// TypeError: Inputs are not identical
1969+
1970+
assert.strictEqual(apples, oranges, (actual, expected) => {
1971+
// Do 'heavy' computations
1972+
return `I expected ${expected} but I got ${actual}`;
1973+
});
1974+
// AssertionError [ERR_ASSERTION]: I expected oranges but I got apples
19131975
```
19141976

19151977
If the values are not strictly equal, an [`AssertionError`][] is thrown with a

0 commit comments

Comments
 (0)