Skip to content

assert: combine user and generated message #22695

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

assert: combine user and generated message #22695

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 94 additions & 61 deletions doc/api/assert.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,23 @@ thrown by the `assert` module will be instances of the `AssertionError` class.
### new assert.AssertionError(options)
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` is now going to be appended to the error message.
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: Added the `userMessage` property.
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `generatedMessage` property is now deprecated.
-->
* `options` {Object}
* `message` {string} If provided, the error message is going to be set to this
value.
* `message` {any} If provided and not `undefined`, it is going to be
appended to auto-generated message and the `userMessage` will be set to this
value. If the `message` is not of type string, `util.inspect()` is called
upon that value before being appended. If no message is auto-generated, the
error message will be set to this value.
* `actual` {any} The `actual` property on the error instance is going to
contain this value. Internally used for the `actual` error input in case
e.g., [`assert.strictEqual()`] is used.
Expand All @@ -46,11 +59,17 @@ and:
[`assert.strictEqual()`] is used.
* `expected` {any} Set to the expected value in case e.g.,
[`assert.strictEqual()`] is used.
* `generatedMessage` {boolean} Indicates if the message was auto-generated
(`true`) or not.
* `code` {string} This is always set to the string `ERR_ASSERTION` to indicate
that the error is actually an assertion error.
* `generatedMessage` {boolean} Deprecated. Indicates if the message was
auto-generated (`true`) or not.
* `operator` {string} Set to the passed in operator value.
* `userMessage` {any} Contains the actual passed through message by the user.
It will not be set in case the user does not provide an error message.

All error messages thrown by the `assert` module are auto-generated. If the user
provides an individual error message, it will be added to the auto-generated one
to provide extra feedback to the user.

```js
const assert = require('assert');
Expand All @@ -74,6 +93,7 @@ try {
assert.strictEqual(err.code, 'ERR_ASSERTION');
assert.strictEqual(err.operator, 'strictEqual');
assert.strictEqual(err.generatedMessage, true);
assert.strictEqual('userMessage' in err, false);
}
```

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

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

## assert.deepEqual(actual, expected[, message])
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
- version: v9.0.0
pr-url: https://github.com/nodejs/node/pull/15001
description: The `Error` names and messages are now properly compared
Expand All @@ -181,7 +204,7 @@ changes:
-->
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {any}

**Strict mode**

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

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

## assert.deepStrictEqual(actual, expected[, message])
<!-- YAML
added: v1.2.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
- version: v9.0.0
pr-url: https://github.com/nodejs/node/pull/15169
description: Enumerable symbol properties are now compared.
Expand All @@ -285,7 +309,7 @@ changes:
-->
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {any}

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

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

## assert.doesNotReject(asyncFn[, error][, message])
<!-- YAML
Expand Down Expand Up @@ -533,10 +555,14 @@ assert.doesNotThrow(
## assert.equal(actual, expected[, message])
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
-->
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {any}

**Strict mode**

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

If the values are not equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
If the values are not equal and the `message` parameter is set to an instance of
an [`Error`][] then that error will be thrown. In all other cases an
`AssertionError` is thrown, passing through the `message` parameter.

## assert.fail([message])
<!-- YAML
Expand Down Expand Up @@ -707,6 +731,9 @@ let err;
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
- version: v9.0.0
pr-url: https://github.com/nodejs/node/pull/15001
description: The `Error` names and messages are now properly compared
Expand All @@ -725,7 +752,7 @@ changes:
-->
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {any}

**Strict mode**

Expand Down Expand Up @@ -770,16 +797,17 @@ assert.notDeepEqual(obj1, obj4);
// OK
```

If the values are deeply equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
If the values are deeply equal and the `message` parameter is set to an instance
of an [`Error`][] then that error will be thrown. In all other cases an
`AssertionError` is thrown, passing through the `message` parameter.

## assert.notDeepStrictEqual(actual, expected[, message])
<!-- YAML
added: v1.2.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
- version: v9.0.0
pr-url: https://github.com/nodejs/node/pull/15398
description: The `-0` and `+0` are not considered equal anymore.
Expand All @@ -806,7 +834,7 @@ changes:
-->
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {any}

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

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

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

## assert.notEqual(actual, expected[, message])
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
-->
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {any}

**Strict mode**

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

If the values are equal, an `AssertionError` is thrown with a `message` property
set equal to the value of the `message` parameter. If the `message` parameter is
undefined, a default error message is assigned. If the `message` parameter is an
instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
If the values are equal and the `message` parameter is set to an instance of an
[`Error`][] then that error will be thrown. In all other cases an
`AssertionError` is thrown, passing through the `message` parameter.

## assert.notStrictEqual(actual, expected[, message])
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/17003
description: Used comparison changed from Strict Equality to `Object.is()`
-->
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {any}

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

If the values are strictly equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
If the values are strictly equal and the `message` parameter is set to an
instance of an [`Error`][] then that error will be thrown. In all other cases an
`AssertionError` is thrown, passing through the `message` parameter.

## assert.ok(value[, message])
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/18319
description: The `assert.ok()` (no arguments) will now use a predefined
error message.
-->
* `value` {any}
* `message` {string|Error}
* `message` {any}

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

If `value` is not truthy, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is `undefined`, a default error message is assigned. If the `message`
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
If `value` is not truthy and the `message` parameter is set to an instance of an
[`Error`][] then that error will be thrown. In all other cases an
`AssertionError` is thrown, passing through the `message` parameter.

If no arguments are passed in at all `message` will be set to the string:
``'No value argument passed to `assert.ok()`'``.

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

If specified, `message` will be the message provided by the `AssertionError` if
the `asyncFn` fails to reject.
If specified, `message` will be appended to the message provided by the
`AssertionError`, if the `asyncFn` fails to reject or in case the error
validation fails.

```js
(async () => {
Expand Down Expand Up @@ -1026,13 +1058,16 @@ argument gets considered.
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/REPLACEME
description: The `message` may now be any value.
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/17003
description: Used comparison changed from Strict Equality to `Object.is()`
-->
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {any}

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

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

## assert.throws(fn[, error][, message])
<!-- YAML
Expand Down
10 changes: 10 additions & 0 deletions doc/api/deprecations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2214,6 +2214,16 @@ the `_handle` property of the `Cipher`, `Decipher`, `DiffieHellman`,
Using the `_handle` property to access the native object is deprecated because
improper use of the native object can lead to crashing the application.

<a id="DEP0XXX"></a>
### DEP0XXX: AssertionError#generatedMessage

Type: Runtime

Instead of accessing the `generatedMessage` property of `AssertionErrors`,
please check for the `AssertionError#userMessage` existence. It contains the
actual user message without any modification and allows to detect if the user
passed through a message or not.

[`--pending-deprecation`]: cli.html#cli_pending_deprecation
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
Expand Down
Loading