Skip to content

Commit

Permalink
doc: consolidate introductory text
Browse files Browse the repository at this point in the history
PR-URL: #31667
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
  • Loading branch information
Trott authored and codebytere committed Mar 30, 2020
1 parent bf729d0 commit 708aff9
Showing 1 changed file with 64 additions and 65 deletions.
129 changes: 64 additions & 65 deletions doc/api/assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,68 +5,7 @@
> Stability: 2 - Stable
The `assert` module provides a set of assertion functions for verifying
invariants. The module provides a recommended [strict assertion mode][]
and a more lenient legacy assertion mode.

## Class: assert.AssertionError

* Extends: {errors.Error}

Indicates the failure of an assertion. All errors thrown by the `assert` module
will be instances of the `AssertionError` class.

### `new assert.AssertionError(options)`
<!-- YAML
added: v0.1.21
-->

* `options` {Object}
* `message` {string} If provided, the error message is set to this value.
* `actual` {any} The `actual` property on the error instance.
* `expected` {any} The `expected` property on the error instance.
* `operator` {string} The `operator` property on the error instance.
* `stackStartFn` {Function} If provided, the generated stack trace omits
frames before this function.

A subclass of `Error` that indicates the failure of an assertion.

All instances contain the built-in `Error` properties (`message` and `name`)
and:

* `actual` {any} Set to the `actual` argument for methods such as
[`assert.strictEqual()`][].
* `expected` {any} Set to the `expected` value for methods such as
[`assert.strictEqual()`][].
* `generatedMessage` {boolean} Indicates if the message was auto-generated
(`true`) or not.
* `code` {string} Value is always `ERR_ASSERTION` to show that the error is an
assertion error.
* `operator` {string} Set to the passed in operator value.

```js
const assert = require('assert');

// Generate an AssertionError to compare the error message later:
const { message } = new assert.AssertionError({
actual: 1,
expected: 2,
operator: 'strictEqual'
});

// Verify error output:
try {
assert.strictEqual(1, 2);
} catch (err) {
assert(err instanceof assert.AssertionError);
assert.strictEqual(err.message, message);
assert.strictEqual(err.name, 'AssertionError');
assert.strictEqual(err.actual, 1);
assert.strictEqual(err.expected, 2);
assert.strictEqual(err.code, 'ERR_ASSERTION');
assert.strictEqual(err.operator, 'strictEqual');
assert.strictEqual(err.generatedMessage, true);
}
```
invariants.

## Strict assertion mode
<!-- YAML
Expand All @@ -84,9 +23,9 @@ changes:
description: Added strict assertion mode to the assert module.
-->

In strict assertion mode, `assert` functions use the comparison in the
corresponding strict functions. For example, [`assert.deepEqual()`][] will
behave like [`assert.deepStrictEqual()`][].
In strict assertion mode, non-strict methods behave like their corresponding
strict methods. For example, [`assert.deepEqual()`][] will behave like
[`assert.deepStrictEqual()`][].

In strict assertion mode, error messages for objects display a diff. In legacy
assertion mode, error messages for objects display the objects, often truncated.
Expand Down Expand Up @@ -150,6 +89,66 @@ lax:
assert.deepEqual(/a/gi, new Date());
```

## Class: assert.AssertionError

* Extends: {errors.Error}

Indicates the failure of an assertion. All errors thrown by the `assert` module
will be instances of the `AssertionError` class.

### `new assert.AssertionError(options)`
<!-- YAML
added: v0.1.21
-->

* `options` {Object}
* `message` {string} If provided, the error message is set to this value.
* `actual` {any} The `actual` property on the error instance.
* `expected` {any} The `expected` property on the error instance.
* `operator` {string} The `operator` property on the error instance.
* `stackStartFn` {Function} If provided, the generated stack trace omits
frames before this function.

A subclass of `Error` that indicates the failure of an assertion.

All instances contain the built-in `Error` properties (`message` and `name`)
and:

* `actual` {any} Set to the `actual` argument for methods such as
[`assert.strictEqual()`][].
* `expected` {any} Set to the `expected` value for methods such as
[`assert.strictEqual()`][].
* `generatedMessage` {boolean} Indicates if the message was auto-generated
(`true`) or not.
* `code` {string} Value is always `ERR_ASSERTION` to show that the error is an
assertion error.
* `operator` {string} Set to the passed in operator value.

```js
const assert = require('assert');

// Generate an AssertionError to compare the error message later:
const { message } = new assert.AssertionError({
actual: 1,
expected: 2,
operator: 'strictEqual'
});

// Verify error output:
try {
assert.strictEqual(1, 2);
} catch (err) {
assert(err instanceof assert.AssertionError);
assert.strictEqual(err.message, message);
assert.strictEqual(err.name, 'AssertionError');
assert.strictEqual(err.actual, 1);
assert.strictEqual(err.expected, 2);
assert.strictEqual(err.code, 'ERR_ASSERTION');
assert.strictEqual(err.operator, 'strictEqual');
assert.strictEqual(err.generatedMessage, true);
}
```

## `assert(value[, message])`
<!-- YAML
added: v0.5.9
Expand Down

0 comments on commit 708aff9

Please sign in to comment.