FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: improve assert documentation · nodejs/node@c1c78ca · GitHub

/ node Public

Commit c1c78ca

Browse files
BridgeAR
authored and
targos
committed
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: #22692 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: George Adams <george.adams@uk.ibm.com>
1 parent e5cdfb0 commit c1c78ca

1 file changed

Lines changed: 29 additions & 28 deletions

File tree

‎doc/api/assert.md‎

Lines changed: 29 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -400,19 +400,19 @@ parameter is undefined, a default error message is assigned. If the `message`
400400
parameter is an instance of an [`Error`][] then it will be thrown instead of the
401401
`AssertionError`.
402402

403-
## assert.doesNotReject(block[, error][, message])
403+
## assert.doesNotReject(asyncFn[, error][, message])
404404
<!-- YAML
405405
added: v10.0.0
406406
-->
407-
* `block` {Function|Promise}
407+
* `asyncFn` {Function|Promise}
408408
* `error` {RegExp|Function}
409-
* `message` {string|Error}
409+
* `message` {string}
410410

411-
Awaits the `block` promise or, if `block` is a function, immediately calls the
412-
function and awaits the returned promise to complete. It will then check that
413-
the promise is not rejected.
411+
Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately
412+
calls the function and awaits the returned promise to complete. It will then
413+
check that the promise is not rejected.
414414

415-
If `block` is a function and it throws an error synchronously,
415+
If `asyncFn` is a function and it throws an error synchronously,
416416
`assert.doesNotReject()` will return a rejected `Promise` with that error. If
417417
the function does not return a promise, `assert.doesNotReject()` will return a
418418
rejected `Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases
@@ -447,7 +447,7 @@ assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
447447
});
448448
```
449449

450-
## assert.doesNotThrow(block[, error][, message])
450+
## assert.doesNotThrow(fn[, error][, message])
451451
<!-- YAML
452452
added: v0.1.21
453453
changes:
@@ -458,18 +458,18 @@ changes:
458458
pr-url: https://github.com/nodejs/node/pull/3276
459459
description: The `error` parameter can now be an arrow function.
460460
-->
461-
* `block` {Function}
461+
* `fn` {Function}
462462
* `error` {RegExp|Function}
463-
* `message` {string|Error}
463+
* `message` {string}
464464

465-
Asserts that the function `block` does not throw an error.
465+
Asserts that the function `fn` does not throw an error.
466466

467467
Please note: Using `assert.doesNotThrow()` is actually not useful because there
468468
is no benefit by catching an error and then rethrowing it. Instead, consider
469469
adding a comment next to the specific code path that should not throw and keep
470470
error messages as expressive as possible.
471471

472-
When `assert.doesNotThrow()` is called, it will immediately call the `block`
472+
When `assert.doesNotThrow()` is called, it will immediately call the `fn`
473473
function.
474474

475475
If an error is thrown and it is the same type as that specified by the `error`
@@ -954,19 +954,19 @@ assert(0);
954954
// assert(0)
955955
```
956956

957-
## assert.rejects(block[, error][, message])
957+
## assert.rejects(asyncFn[, error][, message])
958958
<!-- YAML
959959
added: v10.0.0
960960
-->
961-
* `block` {Function|Promise}
961+
* `asyncFn` {Function|Promise}
962962
* `error` {RegExp|Function|Object|Error}
963-
* `message` {string|Error}
963+
* `message` {string}
964964

965-
Awaits the `block` promise or, if `block` is a function, immediately calls the
966-
function and awaits the returned promise to complete. It will then check that
967-
the promise is rejected.
965+
Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately
966+
calls the function and awaits the returned promise to complete. It will then
967+
check that the promise is rejected.
968968

969-
If `block` is a function and it throws an error synchronously,
969+
If `asyncFn` is a function and it throws an error synchronously,
970970
`assert.rejects()` will return a rejected `Promise` with that error. If the
971971
function does not return a promise, `assert.rejects()` will return a rejected
972972
`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
981981
`name` properties.
982982

983983
If specified, `message` will be the message provided by the `AssertionError` if
984-
the block fails to reject.
984+
the `asyncFn` fails to reject.
985985

986986
```js
987987
(async () => {
@@ -1052,7 +1052,7 @@ If the values are not strictly equal, an `AssertionError` is thrown with a
10521052
`message` parameter is an instance of an [`Error`][] then it will be thrown
10531053
instead of the `AssertionError`.
10541054

1055-
## assert.throws(block[, error][, message])
1055+
## assert.throws(fn[, error][, message])
10561056
<!-- YAML
10571057
added: v0.1.21
10581058
changes:
@@ -1067,11 +1067,11 @@ changes:
10671067
pr-url: https://github.com/nodejs/node/pull/3276
10681068
description: The `error` parameter can now be an arrow function.
10691069
-->
1070-
* `block` {Function}
1070+
* `fn` {Function}
10711071
* `error` {RegExp|Function|Object|Error}
1072-
* `message` {string|Error}
1072+
* `message` {string}
10731073

1074-
Expects the function `block` to throw an error.
1074+
Expects the function `fn` to throw an error.
10751075

10761076
If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function,
10771077
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
10801080
using an object, it is also possible to use a regular expression, when
10811081
validating against a string property. See below for examples.
10821082

1083-
If specified, `message` will be the message provided by the `AssertionError` if
1084-
the block fails to throw.
1083+
If specified, `message` will be appended to the message provided by the
1084+
`AssertionError` if the `fn` call fails to throw or in case the error validation
1085+
fails.
10851086

10861087
Custom validation object/error instance:
10871088

@@ -1246,12 +1247,12 @@ second argument. This might lead to difficult-to-spot errors.
12461247
[`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet
12471248
[`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message
12481249
[`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message
1249-
[`assert.doesNotThrow()`]: #assert_assert_doesnotthrow_block_error_message
1250+
[`assert.doesNotThrow()`]: #assert_assert_doesnotthrow_fn_error_message
12501251
[`assert.notDeepStrictEqual()`]: #assert_assert_notdeepstrictequal_actual_expected_message
12511252
[`assert.notStrictEqual()`]: #assert_assert_notstrictequal_actual_expected_message
12521253
[`assert.ok()`]: #assert_assert_ok_value_message
12531254
[`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message
1254-
[`assert.throws()`]: #assert_assert_throws_block_error_message
1255+
[`assert.throws()`]: #assert_assert_throws_fn_error_message
12551256
[`strict mode`]: #assert_strict_mode
12561257
[Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison
12571258
[Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL