Skip to content

Commit 89a9f00

Browse files
BridgeARBridgeAR
committed
assert: combine auto generated message with user message
So far it was difficult to tell what the actual error was about if there was only the user error. To overcome this, the user message and the auto-generated message will now be visible at the same time.
1 parent e8121d5 commit 89a9f00

8 files changed

Lines changed: 349 additions & 206 deletions

File tree

‎doc/api/assert.md‎

Lines changed: 94 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,23 @@ thrown by the `assert` module will be instances of the `AssertionError` class.
2121
### new assert.AssertionError(options)
2222
<!-- YAML
2323
added: v0.1.21
24+
changes:
25+
- version: REPLACEME
26+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
27+
description: The `message` is now going to be appended to the error message.
28+
- version: REPLACEME
29+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
30+
description: Added the `userMessage` property.
31+
- version: REPLACEME
32+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
33+
description: The `generatedMessage` property is now deprecated.
2434
-->
2535
* `options` {Object}
26-
* `message` {string} If provided, the error message is going to be set to this
27-
value.
36+
* `message` {any} If provided and not `undefined`, it is going to be
37+
appended to auto-generated message and the `userMessage` will be set to this
38+
value. If the `message` is not of type string, `util.inspect()` is called
39+
upon that value before being appended. If no message is auto-generated, the
40+
error message will be set to this value.
2841
* `actual` {any} The `actual` property on the error instance is going to
2942
contain this value. Internally used for the `actual` error input in case
3043
e.g., [`assert.strictEqual()`] is used.
@@ -46,11 +59,17 @@ and:
4659
[`assert.strictEqual()`] is used.
4760
* `expected` {any} Set to the expected value in case e.g.,
4861
[`assert.strictEqual()`] is used.
49-
* `generatedMessage` {boolean} Indicates if the message was auto-generated
50-
(`true`) or not.
5162
* `code` {string} This is always set to the string `ERR_ASSERTION` to indicate
5263
that the error is actually an assertion error.
64+
* `generatedMessage` {boolean} Deprecated. Indicates if the message was
65+
auto-generated (`true`) or not.
5366
* `operator` {string} Set to the passed in operator value.
67+
* `userMessage` {any} Contains the actual passed through message by the user.
68+
It will not be set in case the user does not provide an error message.
69+
70+
All error messages thrown by the `assert` module are auto-generated. If the user
71+
provides an individual error message, it will be added to the auto-generated one
72+
to provide extra feedback to the user.
5473

5574
```js
5675
const assert = require('assert');
@@ -74,6 +93,7 @@ try {
7493
assert.strictEqual(err.code, 'ERR_ASSERTION');
7594
assert.strictEqual(err.operator, 'strictEqual');
7695
assert.strictEqual(err.generatedMessage, true);
96+
assert.strictEqual('userMessage' in err, false);
7797
}
7898
```
7999

@@ -155,14 +175,17 @@ assert.deepEqual(/a/gi, new Date());
155175
added: v0.5.9
156176
-->
157177
* `value` {any} The input that is checked for being truthy.
158-
* `message` {string|Error}
178+
* `message` {any}
159179

160180
An alias of [`assert.ok()`][].
161181

162182
## assert.deepEqual(actual, expected[, message])
163183
<!-- YAML
164184
added: v0.1.21
165185
changes:
186+
- version: REPLACEME
187+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
188+
description: The `message` may now be any value.
166189
- version: v9.0.0
167190
pr-url: https://github.com/nodejs/node/pull/15001
168191
description: The `Error` names and messages are now properly compared
@@ -181,7 +204,7 @@ changes:
181204
-->
182205
* `actual` {any}
183206
* `expected` {any}
184-
* `message` {string|Error}
207+
* `message` {any}
185208

186209
**Strict mode**
187210

@@ -249,16 +272,17 @@ assert.deepEqual(obj1, obj4);
249272
// AssertionError: { a: { b: 1 } } deepEqual {}
250273
```
251274

252-
If the values are not equal, an `AssertionError` is thrown with a `message`
253-
property set equal to the value of the `message` parameter. If the `message`
254-
parameter is undefined, a default error message is assigned. If the `message`
255-
parameter is an instance of an [`Error`][] then it will be thrown instead of the
256-
`AssertionError`.
275+
If the values are not deep-equal and the `message` parameter is set to an
276+
instance of an [`Error`][] then that error will be thrown. In all other cases an
277+
`AssertionError` is thrown, passing through the `message` parameter.
257278

258279
## assert.deepStrictEqual(actual, expected[, message])
259280
<!-- YAML
260281
added: v1.2.0
261282
changes:
283+
- version: REPLACEME
284+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
285+
description: The `message` may now be any value.
262286
- version: v9.0.0
263287
pr-url: https://github.com/nodejs/node/pull/15169
264288
description: Enumerable symbol properties are now compared.
@@ -285,7 +309,7 @@ changes:
285309
-->
286310
* `actual` {any}
287311
* `expected` {any}
288-
* `message` {string|Error}
312+
* `message` {any}
289313

290314
Tests for deep equality between the `actual` and `expected` parameters.
291315
"Deep" equality means that the enumerable "own" properties of child objects
@@ -402,11 +426,9 @@ assert.deepStrictEqual(weakMap1, weakMap3);
402426
// }
403427
```
404428

405-
If the values are not equal, an `AssertionError` is thrown with a `message`
406-
property set equal to the value of the `message` parameter. If the `message`
407-
parameter is undefined, a default error message is assigned. If the `message`
408-
parameter is an instance of an [`Error`][] then it will be thrown instead of the
409-
`AssertionError`.
429+
If the values are not strictly deep-equal and the `message` parameter is set to
430+
an instance of an [`Error`][] then that error will be thrown. In all other cases
431+
an `AssertionError` is thrown, passing through the `message` parameter.
410432

411433
## assert.doesNotReject(asyncFn[, error][, message])
412434
<!-- YAML
@@ -533,10 +555,14 @@ assert.doesNotThrow(
533555
## assert.equal(actual, expected[, message])
534556
<!-- YAML
535557
added: v0.1.21
558+
changes:
559+
- version: REPLACEME
560+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
561+
description: The `message` may now be any value.
536562
-->
537563
* `actual` {any}
538564
* `expected` {any}
539-
* `message` {string|Error}
565+
* `message` {any}
540566

541567
**Strict mode**
542568

@@ -563,11 +589,9 @@ assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
563589
// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
564590
```
565591

566-
If the values are not equal, an `AssertionError` is thrown with a `message`
567-
property set equal to the value of the `message` parameter. If the `message`
568-
parameter is undefined, a default error message is assigned. If the `message`
569-
parameter is an instance of an [`Error`][] then it will be thrown instead of the
570-
`AssertionError`.
592+
If the values are not equal and the `message` parameter is set to an instance of
593+
an [`Error`][] then that error will be thrown. In all other cases an
594+
`AssertionError` is thrown, passing through the `message` parameter.
571595

572596
## assert.fail([message])
573597
<!-- YAML
@@ -707,6 +731,9 @@ let err;
707731
<!-- YAML
708732
added: v0.1.21
709733
changes:
734+
- version: REPLACEME
735+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
736+
description: The `message` may now be any value.
710737
- version: v9.0.0
711738
pr-url: https://github.com/nodejs/node/pull/15001
712739
description: The `Error` names and messages are now properly compared
@@ -725,7 +752,7 @@ changes:
725752
-->
726753
* `actual` {any}
727754
* `expected` {any}
728-
* `message` {string|Error}
755+
* `message` {any}
729756

730757
**Strict mode**
731758

@@ -770,16 +797,17 @@ assert.notDeepEqual(obj1, obj4);
770797
// OK
771798
```
772799

773-
If the values are deeply equal, an `AssertionError` is thrown with a `message`
774-
property set equal to the value of the `message` parameter. If the `message`
775-
parameter is undefined, a default error message is assigned. If the `message`
776-
parameter is an instance of an [`Error`][] then it will be thrown instead of the
777-
`AssertionError`.
800+
If the values are deeply equal and the `message` parameter is set to an instance
801+
of an [`Error`][] then that error will be thrown. In all other cases an
802+
`AssertionError` is thrown, passing through the `message` parameter.
778803

779804
## assert.notDeepStrictEqual(actual, expected[, message])
780805
<!-- YAML
781806
added: v1.2.0
782807
changes:
808+
- version: REPLACEME
809+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
810+
description: The `message` may now be any value.
783811
- version: v9.0.0
784812
pr-url: https://github.com/nodejs/node/pull/15398
785813
description: The `-0` and `+0` are not considered equal anymore.
@@ -806,7 +834,7 @@ changes:
806834
-->
807835
* `actual` {any}
808836
* `expected` {any}
809-
* `message` {string|Error}
837+
* `message` {any}
810838

811839
Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
812840

@@ -817,19 +845,21 @@ assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
817845
// OK
818846
```
819847

820-
If the values are deeply and strictly equal, an `AssertionError` is thrown with
821-
a `message` property set equal to the value of the `message` parameter. If the
822-
`message` parameter is undefined, a default error message is assigned. If the
823-
`message` parameter is an instance of an [`Error`][] then it will be thrown
824-
instead of the `AssertionError`.
848+
If the values are strictly deep-equal and the `message` parameter is set to an
849+
instance of an [`Error`][] then that error will be thrown. In all other cases an
850+
`AssertionError` is thrown, passing through the `message` parameter.
825851

826852
## assert.notEqual(actual, expected[, message])
827853
<!-- YAML
828854
added: v0.1.21
855+
changes:
856+
- version: REPLACEME
857+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
858+
description: The `message` may now be any value.
829859
-->
830860
* `actual` {any}
831861
* `expected` {any}
832-
* `message` {string|Error}
862+
* `message` {any}
833863

834864
**Strict mode**
835865

@@ -855,23 +885,24 @@ assert.notEqual(1, '1');
855885
// AssertionError: 1 != '1'
856886
```
857887

858-
If the values are equal, an `AssertionError` is thrown with a `message` property
859-
set equal to the value of the `message` parameter. If the `message` parameter is
860-
undefined, a default error message is assigned. If the `message` parameter is an
861-
instance of an [`Error`][] then it will be thrown instead of the
862-
`AssertionError`.
888+
If the values are equal and the `message` parameter is set to an instance of an
889+
[`Error`][] then that error will be thrown. In all other cases an
890+
`AssertionError` is thrown, passing through the `message` parameter.
863891

864892
## assert.notStrictEqual(actual, expected[, message])
865893
<!-- YAML
866894
added: v0.1.21
867895
changes:
896+
- version: REPLACEME
897+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
898+
description: The `message` may now be any value.
868899
- version: v10.0.0
869900
pr-url: https://github.com/nodejs/node/pull/17003
870901
description: Used comparison changed from Strict Equality to `Object.is()`
871902
-->
872903
* `actual` {any}
873904
* `expected` {any}
874-
* `message` {string|Error}
905+
* `message` {any}
875906

876907
Tests strict inequality between the `actual` and `expected` parameters as
877908
determined by the [SameValue Comparison][].
@@ -891,32 +922,32 @@ assert.notStrictEqual(1, '1');
891922
// OK
892923
```
893924

894-
If the values are strictly equal, an `AssertionError` is thrown with a `message`
895-
property set equal to the value of the `message` parameter. If the `message`
896-
parameter is undefined, a default error message is assigned. If the `message`
897-
parameter is an instance of an [`Error`][] then it will be thrown instead of the
898-
`AssertionError`.
925+
If the values are strictly equal and the `message` parameter is set to an
926+
instance of an [`Error`][] then that error will be thrown. In all other cases an
927+
`AssertionError` is thrown, passing through the `message` parameter.
899928

900929
## assert.ok(value[, message])
901930
<!-- YAML
902931
added: v0.1.21
903932
changes:
933+
- version: REPLACEME
934+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
935+
description: The `message` may now be any value.
904936
- version: v10.0.0
905937
pr-url: https://github.com/nodejs/node/pull/18319
906938
description: The `assert.ok()` (no arguments) will now use a predefined
907939
error message.
908940
-->
909941
* `value` {any}
910-
* `message` {string|Error}
942+
* `message` {any}
911943

912944
Tests if `value` is truthy. It is equivalent to
913945
`assert.equal(!!value, true, message)`.
914946

915-
If `value` is not truthy, an `AssertionError` is thrown with a `message`
916-
property set equal to the value of the `message` parameter. If the `message`
917-
parameter is `undefined`, a default error message is assigned. If the `message`
918-
parameter is an instance of an [`Error`][] then it will be thrown instead of the
919-
`AssertionError`.
947+
If `value` is not truthy and the `message` parameter is set to an instance of an
948+
[`Error`][] then that error will be thrown. In all other cases an
949+
`AssertionError` is thrown, passing through the `message` parameter.
950+
920951
If no arguments are passed in at all `message` will be set to the string:
921952
``'No value argument passed to `assert.ok()`'``.
922953

@@ -990,8 +1021,9 @@ an object where each property will be tested for, or an instance of error where
9901021
each property will be tested for including the non-enumerable `message` and
9911022
`name` properties.
9921023

993-
If specified, `message` will be the message provided by the `AssertionError` if
994-
the `asyncFn` fails to reject.
1024+
If specified, `message` will be appended to the message provided by the
1025+
`AssertionError`, if the `asyncFn` fails to reject or in case the error
1026+
validation fails.
9951027

9961028
```js
9971029
(async () => {
@@ -1026,13 +1058,16 @@ argument gets considered.
10261058
<!-- YAML
10271059
added: v0.1.21
10281060
changes:
1061+
- version: REPLACEME
1062+
pr-url: https://github.com/nodejs/node/pull/REPLACEME
1063+
description: The `message` may now be any value.
10291064
- version: v10.0.0
10301065
pr-url: https://github.com/nodejs/node/pull/17003
10311066
description: Used comparison changed from Strict Equality to `Object.is()`
10321067
-->
10331068
* `actual` {any}
10341069
* `expected` {any}
1035-
* `message` {string|Error}
1070+
* `message` {any}
10361071

10371072
Tests strict equality between the `actual` and `expected` parameters as
10381073
determined by the [SameValue Comparison][].
@@ -1057,11 +1092,9 @@ assert.strictEqual('Hello foobar', 'Hello World!');
10571092
// ^
10581093
```
10591094

1060-
If the values are not strictly equal, an `AssertionError` is thrown with a
1061-
`message` property set equal to the value of the `message` parameter. If the
1062-
`message` parameter is undefined, a default error message is assigned. If the
1063-
`message` parameter is an instance of an [`Error`][] then it will be thrown
1064-
instead of the `AssertionError`.
1095+
If the values are not strictly equal and the `message` parameter is set to an
1096+
instance of an [`Error`][] then that error will be thrown. In all other cases an
1097+
`AssertionError` is thrown, passing through the `message` parameter.
10651098

10661099
## assert.throws(fn[, error][, message])
10671100
<!-- YAML

‎doc/api/deprecations.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2214,6 +2214,16 @@ the `_handle` property of the `Cipher`, `Decipher`, `DiffieHellman`,
22142214
Using the `_handle` property to access the native object is deprecated because
22152215
improper use of the native object can lead to crashing the application.
22162216
2217+
<a id="DEP0XXX"></a>
2218+
### DEP0XXX: AssertionError#generatedMessage
2219+
2220+
Type: Runtime
2221+
2222+
Instead of accessing the `generatedMessage` property of `AssertionErrors`,
2223+
please check for the `AssertionError#userMessage` existence. It contains the
2224+
actual user message without any modification and allows to detect if the user
2225+
passed through a message or not.
2226+
22172227
[`--pending-deprecation`]: cli.html#cli_pending_deprecation
22182228
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
22192229
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array

0 commit comments

Comments
 (0)