Skip to content

doc: improve assert documentation #22692

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
BridgeAR wants to merge 3 commits into from
Closed

doc: improve assert documentation #22692

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
278b1b6
doc: improve assert documentation
BridgeAR Sep 3, 2018
2d152ed
fixup: address comment
BridgeAR Sep 5, 2018
1ed83bf
fixup: address Anna's comment
BridgeAR Sep 5, 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
Next Next commit
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.
  • Loading branch information
@BridgeAR
BridgeAR committed Sep 4, 2018
commit 278b1b6ee32d4142e253ed19db65b4987f7ff6e7
57 changes: 29 additions & 28 deletions doc/api/assert.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -408,19 +408,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(promiseFn[, error][, message])
Copy link
Copy Markdown
Member

@addaleax addaleax Sep 5, 2018

Choose a reason for hiding this comment

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

How about asyncFn? That’s more or less the name the language settled on…

<!-- YAML
added: v10.0.0
-->
* `block` {Function|Promise}
* `promiseFn` {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 `promiseFn` promise or, if `promiseFn` 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 `promiseFn` 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
Expand Down Expand Up @@ -455,7 +455,7 @@ assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
});
```

## assert.doesNotThrow(block[, error][, message])
## assert.doesNotThrow(fn[, error][, message])
<!-- YAML
added: v0.1.21
changes:
Expand All @@ -466,18 +466,18 @@ changes:
pr-url: https://github.com/nodejs/node/pull/3276
description: The `error` parameter can now be an arrow function.
-->
* `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`
Expand Down Expand Up @@ -964,19 +964,19 @@ assert(0);
// assert(0)
```

## assert.rejects(block[, error][, message])
## assert.rejects(promiseFn[, error][, message])
<!-- YAML
added: v10.0.0
-->
* `block` {Function|Promise}
* `promiseFn` {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 `promiseFn` promise or, if `promiseFn` 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 `promiseFn` 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
Expand All @@ -991,7 +991,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 `promiseFn` fails to reject.

```js
(async () => {
Expand Down Expand Up @@ -1063,7 +1063,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])
<!-- YAML
added: v0.1.21
changes:
Expand All @@ -1078,11 +1078,11 @@ changes:
pr-url: https://github.com/nodejs/node/pull/3276
description: The `error` parameter can now be an arrow function.
-->
* `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,
Expand All @@ -1091,8 +1091,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
Copy link
Copy Markdown
Contributor

@vsemozhetbyt vsemozhetbyt Sep 5, 2018

Choose a reason for hiding this comment

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

fn -> `fn`

fails.

Custom validation object/error instance:

Expand Down Expand Up @@ -1258,12 +1259,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
Expand Down