OSSForks/node
1
0
Fork 0
mirror of https://github.com/zebrajr/node.git synced 2026-01-15 12:15:26 +00:00
Code Issues Actions 8 Packages Projects Releases Wiki Activity

doc: improve assert documentation

Browse Source 
This adds a example to `assert.throws` to document checking against
error instances. It also makes it clearer what some arguments can
receive as input.

PR-URL: https://github.com/nodejs/node/pull/19885
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
This commit is contained in:
Ruben Bridgewater
2018-04-09 01:31:59 +02:00
parent f7496896c4
commit 1d6cdfce80
1 changed files with 32 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
doc/api/assert.md
View File

@@ -395,6 +395,9 @@ is little benefit by catching a rejection and then rejecting it again. Instead,
consider adding a comment next to the specific code path that should not reject
and keep error messages as expressive as possible.
If specified, `error` can be a [`Class`][], [`RegExp`][] or a validation
function. See [`assert.throws()`][] for more details.
Besides the async nature to await the completion behaves identically to
[`assert.doesNotThrow()`][].
@@ -431,8 +434,7 @@ changes:
* `error` {RegExp|Function}
* `message` {any}
Asserts that the function `block` does not throw an error. See
[`assert.throws()`][] for more details.
Asserts that the function `block` does not throw an error.
Please note: Using `assert.doesNotThrow()` is actually not useful because there
is no benefit by catching an error and then rethrowing it. Instead, consider
@@ -447,6 +449,9 @@ parameter, then an `AssertionError` is thrown. If the error is of a different
type, or if the `error` parameter is undefined, the error is propagated back
to the caller.
If specified, `error` can be a [`Class`][], [`RegExp`][] or a validation
function. See [`assert.throws()`][] for more details.
The following, for instance, will throw the [`TypeError`][] because there is no
matching error type in the assertion:
@@ -483,7 +488,7 @@ assert.doesNotThrow(
() => {
throw new TypeError('Wrong value');
},
TypeError,
/Wrong value/,
'Whoops'
);
// Throws: AssertionError: Got unwanted exception (TypeError). Whoops
@@ -916,7 +921,7 @@ assert(0);
added: REPLACEME
-->
* `block` {Function|Promise}
* `error` {RegExp|Function|Object}
* `error` {RegExp|Function|Object|Error}
* `message` {any}
Awaits the `block` promise or, if `block` is a function, immediately calls the
@@ -930,8 +935,10 @@ checking the error handler.
Besides the async nature to await the completion behaves identically to
[`assert.throws()`][].
If specified, `error` can be a constructor, [`RegExp`][], a validation
function, or an object where each property will be tested for.
If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function,
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.
@@ -1011,13 +1018,15 @@ changes:
description: The `error` parameter can now be an arrow function.
-->
* `block` {Function}
* `error` {RegExp|Function|Object}
* `error` {RegExp|Function|Object|Error}
* `message` {any}
Expects the function `block` to throw an error.
If specified, `error` can be a constructor, [`RegExp`][], a validation
function, or an object where each property will be tested for.
If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function,
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 throw.
@@ -1066,10 +1075,11 @@ assert.throws(
Custom error object / error instance:
```js
const err = new TypeError('Wrong value');
err.code = 404;
assert.throws(
() => {
const err = new TypeError('Wrong value');
err.code = 404;
throw err;
},
{
@@ -1078,6 +1088,16 @@ assert.throws(
// Note that only properties on the error object will be tested!
}
);
// Fails due to the different `message` and `name` properties:
assert.throws(
() => {
const otherErr = new Error('Not found');
otherErr.code = 404;
throw otherErr;
},
err // This tests for `message`, `name` and `code`.
);
```
Note that `error` cannot be a string. If a string is provided as the second
@@ -1118,6 +1138,7 @@ assert.throws(throwingFirst, /Second$/);
Due to the confusing notation, it is recommended not to use a string as the
second argument. This might lead to difficult-to-spot errors.
[`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
[`Error.captureStackTrace`]: errors.html#errors_error_capturestacktrace_targetobject_constructoropt
[`Error`]: errors.html#errors_class_error
[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map