doc: properly document AssertionError

The AssertionError was always exposed but never properly documented.
This explains how it is used and what options it accepts.

PR-URL: https://github.com/nodejs/node/pull/19724
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 64 insertions, 0 deletions

diff --git a/doc/api/assert.md b/doc/api/assert.md
index 63e6950f6a..4e9ff82774 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -13,6 +13,70 @@ A `strict` and a `legacy` mode exist, while it is recommended to only use
 For more information about the used equality comparisons see
 [MDN's guide on equality comparisons and sameness][mdn-equality-guide].
 
+## Class: assert.AssertionError
+
+A subclass of `Error` that 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 going to be set to this
+    value.
+  * `actual` {any} The `actual` property on the error instance is going to
+    contain this value. Internally used for the `actual` error input in case
+    e.g., [`assert.strictEqual()`] is used.
+  * `expected` {any} The `expected` property on the error instance is going to
+    contain this value. Internally used for the `expected` error input in case
+    e.g., [`assert.strictEqual()`] is used.
+  * `operator` {string} The `operator` property on the error instance is going
+    to contain this value. Internally used to indicate what operation was used
+    for comparison (or what assertion function triggered the error).
+  * `stackStartFn` {Function} If provided, the generated stack trace is going to
+    remove all frames up to the provided 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 value in case e.g.,
+  [`assert.strictEqual()`] is used.
+* `expected` {any} Set to the expected value in case e.g.,
+  [`assert.strictEqual()`] is used.
+* `generatedMessage` {boolean} Indicates if the message was auto-generated
+  (`true`) or not.
+* `code` {string} This is always set to the string `ERR_ASSERTION` to indicate
+  that the error is actually 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 [ERR_ASSERTION]');
+  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);
+}
+```
+
 ## Strict mode
 <!-- YAML
 added: v9.9.0