Skip to content

assert: accept undefined as message input #22696

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 2 commits into from
Closed

assert: accept undefined as message input #22696

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2160a77
assert: combine auto generated message with user message
BridgeAR Sep 3, 2018
3b80692
assert: accept `undefined` as message input
BridgeAR Sep 4, 2018
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, it is going to be appended to auto-generated
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

going to be -> will be

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to auto-generated -> to the

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 a error message.

All error messages thrown by the `assert` module are auto-generated. If the user
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is confusing to me. I don't think auto-generated is a clear term and should probably be avoided.

@nodejs/documentation

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.strictEuqal('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(block[, 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 block fails to reject.
If specified, `message` will be appended to the message provided by the
`AssertionError`, if the block call 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(block[, 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 @@ -1050,6 +1050,16 @@ deprecated along with the undocumented aliases `crypto.prng()` and
`crypto.rng()` in favor of [`crypto.randomBytes()`][] and will be removed in a
future release.

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

Type: Runtime

Instead of accessing the generatedMessage property of `AssertionErrors`, please
check for `AssertionError#userMessage` existence instead. 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