From c1c78ca4eb90f4d20c8593a0edb2bae493dab87e Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Tue, 4 Sep 2018 01:10:29 +0200 Subject: [PATCH] doc: improve assert documentation This fixes the officially accepted message types for `assert.throws()`, `assert.rejects()`, `assert.doesNotThrow()` and `assert.doesNotReject()`. It also renames the `block` argument in those functions to `fn` and `promiseFn` for further clarity. PR-URL: https://github.com/nodejs/node/pull/22692 Reviewed-By: Luigi Pinca Reviewed-By: Vse Mozhet Byt Reviewed-By: Anna Henningsen Reviewed-By: James M Snell Reviewed-By: George Adams --- doc/api/assert.md | 57 ++++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 71edf4c415e1ef..4800bed4e8239d 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -400,19 +400,19 @@ 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`. -## assert.doesNotReject(block[, error][, message]) +## assert.doesNotReject(asyncFn[, error][, message]) -* `block` {Function|Promise} +* `asyncFn` {Function|Promise} * `error` {RegExp|Function} -* `message` {string|Error} +* `message` {string} -Awaits the `block` promise or, if `block` is a function, immediately calls the -function and awaits the returned promise to complete. It will then check that -the promise is not rejected. +Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately +calls the function and awaits the returned promise to complete. It will then +check that the promise is not rejected. -If `block` is a function and it throws an error synchronously, +If `asyncFn` is a function and it throws an error synchronously, `assert.doesNotReject()` will return a rejected `Promise` with that error. If the function does not return a promise, `assert.doesNotReject()` will return a rejected `Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases @@ -447,7 +447,7 @@ assert.doesNotReject(Promise.reject(new TypeError('Wrong value'))) }); ``` -## assert.doesNotThrow(block[, error][, message]) +## assert.doesNotThrow(fn[, error][, message]) -* `block` {Function} +* `fn` {Function} * `error` {RegExp|Function} -* `message` {string|Error} +* `message` {string} -Asserts that the function `block` does not throw an error. +Asserts that the function `fn` 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 adding a comment next to the specific code path that should not throw and keep error messages as expressive as possible. -When `assert.doesNotThrow()` is called, it will immediately call the `block` +When `assert.doesNotThrow()` is called, it will immediately call the `fn` function. If an error is thrown and it is the same type as that specified by the `error` @@ -954,19 +954,19 @@ assert(0); // assert(0) ``` -## assert.rejects(block[, error][, message]) +## assert.rejects(asyncFn[, error][, message]) -* `block` {Function|Promise} +* `asyncFn` {Function|Promise} * `error` {RegExp|Function|Object|Error} -* `message` {string|Error} +* `message` {string} -Awaits the `block` promise or, if `block` is a function, immediately calls the -function and awaits the returned promise to complete. It will then check that -the promise is rejected. +Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately +calls the function and awaits the returned promise to complete. It will then +check that the promise is rejected. -If `block` is a function and it throws an error synchronously, +If `asyncFn` is a function and it throws an error synchronously, `assert.rejects()` will return a rejected `Promise` with that error. If the function does not return a promise, `assert.rejects()` will return a rejected `Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the error @@ -981,7 +981,7 @@ 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. +the `asyncFn` fails to reject. ```js (async () => { @@ -1052,7 +1052,7 @@ If the values are not strictly equal, an `AssertionError` is thrown with a `message` parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. -## assert.throws(block[, error][, message]) +## assert.throws(fn[, error][, message]) -* `block` {Function} +* `fn` {Function} * `error` {RegExp|Function|Object|Error} -* `message` {string|Error} +* `message` {string} -Expects the function `block` to throw an error. +Expects the function `fn` to throw an error. If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function, a validation object where each property will be tested for strict deep equality, @@ -1080,8 +1080,9 @@ equality including the non-enumerable `message` and `name` properties. When using an object, it is also possible to use a regular expression, when validating against a string property. See below for examples. -If specified, `message` will be the message provided by the `AssertionError` if -the block fails to throw. +If specified, `message` will be appended to the message provided by the +`AssertionError` if the `fn` call fails to throw or in case the error validation +fails. Custom validation object/error instance: @@ -1246,12 +1247,12 @@ second argument. This might lead to difficult-to-spot errors. [`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet [`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message [`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message -[`assert.doesNotThrow()`]: #assert_assert_doesnotthrow_block_error_message +[`assert.doesNotThrow()`]: #assert_assert_doesnotthrow_fn_error_message [`assert.notDeepStrictEqual()`]: #assert_assert_notdeepstrictequal_actual_expected_message [`assert.notStrictEqual()`]: #assert_assert_notstrictequal_actual_expected_message [`assert.ok()`]: #assert_assert_ok_value_message [`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message -[`assert.throws()`]: #assert_assert_throws_block_error_message +[`assert.throws()`]: #assert_assert_throws_fn_error_message [`strict mode`]: #assert_strict_mode [Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison [Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring