From 1d6cdfce807ba81f372cd3ab6d6ba81f71abeb6b Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Mon, 9 Apr 2018 01:31:59 +0200 Subject: doc: improve assert documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-By: Michaël Zasso Reviewed-By: James M Snell Reviewed-By: Trivikram Kamat --- doc/api/assert.md | 43 ++++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) (limited to 'doc/api/assert.md') diff --git a/doc/api/assert.md b/doc/api/assert.md index c868ef64e0..6d96359d00 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -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 -- cgit v1.2.3