haxorqt
Home
Console
Upload
information
Create File
Create Folder
About
:
/
opt
/
alt
/
alt-nodejs9
/
root
/
lib
/
node_modules
/
npm
/
html
/
html
/
api
/
Filename :
assert.json
back
Copy
{ "source": "doc/api/assert.md", "modules": [ { "textRaw": "Assert", "name": "assert", "introduced_in": "v0.10.0", "stability": 2, "stabilityText": "Stable", "desc": "<p>The <code>assert</code> module provides a simple set of assertion tests that can be used to\ntest invariants.</p>\n<p>A <code>strict</code> and a <code>legacy</code> mode exist, while it is recommended to only use\n<a href=\"#assert_strict_mode\"><code>strict mode</code></a>.</p>\n<p>For more information about the used equality comparisons see\n<a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness\">MDN's guide on equality comparisons and sameness</a>.</p>\n", "modules": [ { "textRaw": "Strict mode", "name": "strict_mode", "meta": { "added": [ "v9.9.0" ], "changes": [ { "version": "v9.9.0", "pr-url": "https://github.com/nodejs/node/pull/17615", "description": "Added error diffs to the strict mode" }, { "version": "v9.9.0", "pr-url": "https://github.com/nodejs/node/pull/17002", "description": "Added strict mode to the assert module." } ] }, "desc": "<p>When using the <code>strict mode</code>, any <code>assert</code> function will use the equality used\nin the strict function mode. So <a href=\"#assert_assert_deepequal_actual_expected_message\"><code>assert.deepEqual()</code></a> will, for example,\nwork the same as <a href=\"#assert_assert_deepstrictequal_actual_expected_message\"><code>assert.deepStrictEqual()</code></a>.</p>\n<p>On top of that, error messages which involve objects produce an error diff\ninstead of displaying both objects. That is not the case for the legacy mode.</p>\n<p>It can be accessed using:</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n</code></pre>\n<p>Example error diff (the <code>expected</code>, <code>actual</code>, and <code>Lines skipped</code> will be on a\nsingle row):</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]);\n</code></pre>\n<pre><code class=\"lang-diff\">AssertionError [ERR_ASSERTION]: Input A expected to deepStrictEqual input B:\n+ expected\n- actual\n... Lines skipped\n\n [\n [\n...\n 2,\n- 3\n+ '3'\n ],\n...\n 5\n ]\n</code></pre>\n<p>To deactivate the colors, use the <code>NODE_DISABLE_COLORS</code> environment variable.\nPlease note that this will also deactivate the colors in the REPL.</p>\n", "type": "module", "displayName": "Strict mode" }, { "textRaw": "Legacy mode", "name": "legacy_mode", "stability": 0, "stabilityText": "Deprecated: Use strict mode instead.", "desc": "<p>When accessing <code>assert</code> directly instead of using the <code>strict</code> property, the\n<a href=\"https://tc39.github.io/ecma262/#sec-abstract-equality-comparison\">Abstract Equality Comparison</a> will be used for any function without "strict"\nin its name, such as <a href=\"#assert_assert_deepequal_actual_expected_message\"><code>assert.deepEqual()</code></a>.</p>\n<p>It can be accessed using:</p>\n<pre><code class=\"lang-js\">const assert = require('assert');\n</code></pre>\n<p>It is recommended to use the <a href=\"#assert_strict_mode\"><code>strict mode</code></a> instead as the\n<a href=\"https://tc39.github.io/ecma262/#sec-abstract-equality-comparison\">Abstract Equality Comparison</a> can often have surprising results. This is\nespecially true for <a href=\"#assert_assert_deepequal_actual_expected_message\"><code>assert.deepEqual()</code></a>, where the comparison rules are\nlax:</p>\n<pre><code class=\"lang-js\">// WARNING: This does not throw an AssertionError!\nassert.deepEqual(/a/gi, new Date());\n</code></pre>\n", "type": "module", "displayName": "Legacy mode" }, { "textRaw": "Caveats", "name": "caveats", "desc": "<p>For the following cases, consider using ES2015 <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is\"><code>Object.is()</code></a>,\nwhich uses the <a href=\"https://tc39.github.io/ecma262/#sec-samevaluezero\">SameValueZero</a> comparison.</p>\n<pre><code class=\"lang-js\">const a = 0;\nconst b = -a;\nassert.notStrictEqual(a, b);\n// AssertionError: 0 !== -0\n// Strict Equality Comparison doesn't distinguish between -0 and +0...\nassert(!Object.is(a, b));\n// but Object.is() does!\n\nconst str1 = 'foo';\nconst str2 = 'foo';\nassert.strictEqual(str1 / 1, str2 / 1);\n// AssertionError: NaN === NaN\n// Strict Equality Comparison can't be used to check NaN...\nassert(Object.is(str1 / 1, str2 / 1));\n// but Object.is() can!\n</code></pre>\n<p>For more information, see\n<a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness\">MDN's guide on equality comparisons and sameness</a>.</p>\n", "type": "module", "displayName": "Caveats" } ], "methods": [ { "textRaw": "assert(value[, message])", "type": "method", "name": "assert", "meta": { "added": [ "v0.5.9" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`value` {any} ", "name": "value", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "value" }, { "name": "message", "optional": true } ] } ], "desc": "<p>An alias of <a href=\"#assert_assert_ok_value_message\"><code>assert.ok()</code></a>.</p>\n" }, { "textRaw": "assert.deepEqual(actual, expected[, message])", "type": "method", "name": "deepEqual", "meta": { "added": [ "v0.1.21" ], "changes": [ { "version": "v9.0.0", "pr-url": "https://github.com/nodejs/node/pull/15001", "description": "Error names and messages are now properly compared" }, { "version": "v8.0.0", "pr-url": "https://github.com/nodejs/node/pull/12142", "description": "Set and Map content is also compared" }, { "version": "v6.4.0, v4.7.1", "pr-url": "https://github.com/nodejs/node/pull/8002", "description": "Typed array slices are handled correctly now." }, { "version": "v6.1.0, v4.5.0", "pr-url": "https://github.com/nodejs/node/pull/6432", "description": "Objects with circular references can be used as inputs now." }, { "version": "v5.10.1, v4.4.3", "pr-url": "https://github.com/nodejs/node/pull/5910", "description": "Handle non-`Uint8Array` typed arrays correctly." } ] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true } ] } ], "desc": "<p><strong>Strict mode</strong></p>\n<p>An alias of <a href=\"#assert_assert_deepstrictequal_actual_expected_message\"><code>assert.deepStrictEqual()</code></a>.</p>\n<p><strong>Legacy mode</strong></p>\n<blockquote>\n<p>Stability: 0 - Deprecated: Use <a href=\"#assert_assert_deepstrictequal_actual_expected_message\"><code>assert.deepStrictEqual()</code></a> instead.</p>\n</blockquote>\n<p>Tests for deep equality between the <code>actual</code> and <code>expected</code> parameters.\nPrimitive values are compared with the <a href=\"https://tc39.github.io/ecma262/#sec-abstract-equality-comparison\">Abstract Equality Comparison</a>\n( <code>==</code> ).</p>\n<p>Only <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties\">enumerable "own" properties</a> are considered. The\n<a href=\"#assert_assert_deepequal_actual_expected_message\"><code>assert.deepEqual()</code></a> implementation does not test the\n<a href=\"https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots\"><code>[[Prototype]]</code></a> of objects or enumerable own <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol\"><code>Symbol</code></a>\nproperties. For such checks, consider using <a href=\"#assert_assert_deepstrictequal_actual_expected_message\"><code>assert.deepStrictEqual()</code></a>\ninstead. <a href=\"#assert_assert_deepequal_actual_expected_message\"><code>assert.deepEqual()</code></a> can have potentially surprising results. The\nfollowing example does not throw an <code>AssertionError</code> because the properties on\nthe <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions\"><code>RegExp</code></a> object are not enumerable:</p>\n<pre><code class=\"lang-js\">// WARNING: This does not throw an AssertionError!\nassert.deepEqual(/a/gi, new Date());\n</code></pre>\n<p>An exception is made for <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map\"><code>Map</code></a> and <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set\"><code>Set</code></a>. Maps and Sets have their\ncontained items compared too, as expected.</p>\n<p>"Deep" equality means that the enumerable "own" properties of child objects\nare evaluated also:</p>\n<pre><code class=\"lang-js\">const assert = require('assert');\n\nconst obj1 = {\n a: {\n b: 1\n }\n};\nconst obj2 = {\n a: {\n b: 2\n }\n};\nconst obj3 = {\n a: {\n b: 1\n }\n};\nconst obj4 = Object.create(obj1);\n\nassert.deepEqual(obj1, obj1);\n// OK, object is equal to itself\n\nassert.deepEqual(obj1, obj2);\n// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }\n// values of b are different\n\nassert.deepEqual(obj1, obj3);\n// OK, objects are equal\n\nassert.deepEqual(obj1, obj4);\n// AssertionError: { a: { b: 1 } } deepEqual {}\n// Prototypes are ignored\n</code></pre>\n<p>If the values are not equal, an <code>AssertionError</code> is thrown with a <code>message</code>\nproperty set equal to the value of the <code>message</code> parameter. If the <code>message</code>\nparameter is undefined, a default error message is assigned. If the <code>message</code>\nparameter is an instance of an [<code>Error</code>][] then it will be thrown instead of the\n<code>AssertionError</code>.</p>\n" }, { "textRaw": "assert.deepStrictEqual(actual, expected[, message])", "type": "method", "name": "deepStrictEqual", "meta": { "added": [ "v1.2.0" ], "changes": [ { "version": "v9.0.0", "pr-url": "https://github.com/nodejs/node/pull/15169", "description": "Enumerable symbol properties are now compared." }, { "version": "v9.0.0", "pr-url": "https://github.com/nodejs/node/pull/15036", "description": "NaN is now compared using the [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) comparison." }, { "version": "v8.5.0", "pr-url": "https://github.com/nodejs/node/pull/15001", "description": "Error names and messages are now properly compared" }, { "version": "v8.0.0", "pr-url": "https://github.com/nodejs/node/pull/12142", "description": "Set and Map content is also compared" }, { "version": "v6.4.0, v4.7.1", "pr-url": "https://github.com/nodejs/node/pull/8002", "description": "Typed array slices are handled correctly now." }, { "version": "v6.1.0", "pr-url": "https://github.com/nodejs/node/pull/6432", "description": "Objects with circular references can be used as inputs now." }, { "version": "v5.10.1, v4.4.3", "pr-url": "https://github.com/nodejs/node/pull/5910", "description": "Handle non-`Uint8Array` typed arrays correctly." } ] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true } ] } ], "desc": "<p>Tests for deep equality between the <code>actual</code> and <code>expected</code> parameters.\n"Deep" equality means that the enumerable "own" properties of child objects\nare recursively evaluated also by the following rules.</p>\n", "modules": [ { "textRaw": "Comparison details", "name": "comparison_details", "desc": "<ul>\n<li>Primitive values are compared using the <a href=\"https://tc39.github.io/ecma262/#sec-samevalue\">SameValue Comparison</a>, used by\n<a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is\"><code>Object.is()</code></a>.</li>\n<li><a href=\"https://tc39.github.io/ecma262/#sec-object.prototype.tostring\">Type tags</a> of objects should be the same.</li>\n<li><a href=\"https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots\"><code>[[Prototype]]</code></a> of objects are compared using\nthe <a href=\"https://tc39.github.io/ecma262/#sec-strict-equality-comparison\">Strict Equality Comparison</a>.</li>\n<li>Only <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties\">enumerable "own" properties</a> are considered.</li>\n<li>[<code>Error</code>][] names and messages are always compared, even if these are not\nenumerable properties.</li>\n<li>Enumerable own <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol\"><code>Symbol</code></a> properties are compared as well.</li>\n<li><a href=\"https://developer.mozilla.org/en-US/docs/Glossary/Primitive#Primitive_wrapper_objects_in_JavaScript\">Object wrappers</a> are compared both as objects and unwrapped values.</li>\n<li>Object properties are compared unordered.</li>\n<li>Map keys and Set items are compared unordered.</li>\n<li>Recursion stops when both sides differ or both sides encounter a circular\nreference.</li>\n<li><a href=\"https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/WeakMap\"><code>WeakMap</code></a> and <a href=\"https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/WeakSet\"><code>WeakSet</code></a> comparison does not rely on their values. See\nbelow for further details.</li>\n</ul>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.deepStrictEqual({ a: 1 }, { a: '1' });\n// AssertionError: { a: 1 } deepStrictEqual { a: '1' }\n// because 1 !== '1' using SameValue comparison\n\n// The following objects don't have own properties\nconst date = new Date();\nconst object = {};\nconst fakeDate = {};\nObject.setPrototypeOf(fakeDate, Date.prototype);\n\nassert.deepStrictEqual(object, fakeDate);\n// AssertionError: {} deepStrictEqual Date {}\n// Different [[Prototype]]\n\nassert.deepStrictEqual(date, fakeDate);\n// AssertionError: 2017-03-11T14:25:31.849Z deepStrictEqual Date {}\n// Different type tags\n\nassert.deepStrictEqual(NaN, NaN);\n// OK, because of the SameValue comparison\n\nassert.deepStrictEqual(new Number(1), new Number(2));\n// Fails because the wrapped number is unwrapped and compared as well.\nassert.deepStrictEqual(new String('foo'), Object('foo'));\n// OK because the object and the string are identical when unwrapped.\n\nassert.deepStrictEqual(-0, -0);\n// OK\nassert.deepStrictEqual(0, -0);\n// AssertionError: 0 deepStrictEqual -0\n\nconst symbol1 = Symbol();\nconst symbol2 = Symbol();\nassert.deepStrictEqual({ [symbol1]: 1 }, { [symbol1]: 1 });\n// OK, because it is the same symbol on both objects.\nassert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });\n// Fails because symbol1 !== symbol2!\n\nconst weakMap1 = new WeakMap();\nconst weakMap2 = new WeakMap([[{}, {}]]);\nconst weakMap3 = new WeakMap();\nweakMap3.unequal = true;\n\nassert.deepStrictEqual(weakMap1, weakMap2);\n// OK, because it is impossible to compare the entries\nassert.deepStrictEqual(weakMap1, weakMap3);\n// Fails because weakMap3 has a property that weakMap1 does not contain!\n</code></pre>\n<p>If the values are not equal, an <code>AssertionError</code> is thrown with a <code>message</code>\nproperty set equal to the value of the <code>message</code> parameter. If the <code>message</code>\nparameter is undefined, a default error message is assigned. If the <code>message</code>\nparameter is an instance of an [<code>Error</code>][] then it will be thrown instead of the\n<code>AssertionError</code>.</p>\n", "type": "module", "displayName": "Comparison details" } ] }, { "textRaw": "assert.doesNotThrow(block[, error][, message])", "type": "method", "name": "doesNotThrow", "meta": { "added": [ "v0.1.21" ], "changes": [ { "version": "v5.11.0, v4.4.5", "pr-url": "https://github.com/nodejs/node/pull/2407", "description": "The `message` parameter is respected now." }, { "version": "v4.2.0", "pr-url": "https://github.com/nodejs/node/pull/3276", "description": "The `error` parameter can now be an arrow function." } ] }, "signatures": [ { "params": [ { "textRaw": "`block` {Function} ", "name": "block", "type": "Function" }, { "textRaw": "`error` {RegExp|Function} ", "name": "error", "type": "RegExp|Function", "optional": true }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "block" }, { "name": "error", "optional": true }, { "name": "message", "optional": true } ] } ], "desc": "<p>Asserts that the function <code>block</code> does not throw an error. See\n<a href=\"#assert_assert_throws_block_error_message\"><code>assert.throws()</code></a> for more details.</p>\n<p>Please note: Using <code>assert.doesNotThrow()</code> is actually not useful because there\nis no benefit by catching an error and then rethrowing it. Instead, consider\nadding a comment next to the specific code path that should not throw and keep\nerror messages as expressive as possible.</p>\n<p>When <code>assert.doesNotThrow()</code> is called, it will immediately call the <code>block</code>\nfunction.</p>\n<p>If an error is thrown and it is the same type as that specified by the <code>error</code>\nparameter, then an <code>AssertionError</code> is thrown. If the error is of a different\ntype, or if the <code>error</code> parameter is undefined, the error is propagated back\nto the caller.</p>\n<p>The following, for instance, will throw the <a href=\"errors.html#errors_class_typeerror\"><code>TypeError</code></a> because there is no\nmatching error type in the assertion:</p>\n<!-- eslint-disable no-restricted-syntax -->\n<pre><code class=\"lang-js\">assert.doesNotThrow(\n () => {\n throw new TypeError('Wrong value');\n },\n SyntaxError\n);\n</code></pre>\n<p>However, the following will result in an <code>AssertionError</code> with the message\n'Got unwanted exception (TypeError)..':</p>\n<!-- eslint-disable no-restricted-syntax -->\n<pre><code class=\"lang-js\">assert.doesNotThrow(\n () => {\n throw new TypeError('Wrong value');\n },\n TypeError\n);\n</code></pre>\n<p>If an <code>AssertionError</code> is thrown and a value is provided for the <code>message</code>\nparameter, the value of <code>message</code> will be appended to the <code>AssertionError</code>\nmessage:</p>\n<!-- eslint-disable no-restricted-syntax -->\n<pre><code class=\"lang-js\">assert.doesNotThrow(\n () => {\n throw new TypeError('Wrong value');\n },\n TypeError,\n 'Whoops'\n);\n// Throws: AssertionError: Got unwanted exception (TypeError). Whoops\n</code></pre>\n" }, { "textRaw": "assert.equal(actual, expected[, message])", "type": "method", "name": "equal", "meta": { "added": [ "v0.1.21" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true } ] } ], "desc": "<p><strong>Strict mode</strong></p>\n<p>An alias of <a href=\"#assert_assert_strictequal_actual_expected_message\"><code>assert.strictEqual()</code></a>.</p>\n<p><strong>Legacy mode</strong></p>\n<blockquote>\n<p>Stability: 0 - Deprecated: Use <a href=\"#assert_assert_strictequal_actual_expected_message\"><code>assert.strictEqual()</code></a> instead.</p>\n</blockquote>\n<p>Tests shallow, coercive equality between the <code>actual</code> and <code>expected</code> parameters\nusing the <a href=\"https://tc39.github.io/ecma262/#sec-abstract-equality-comparison\">Abstract Equality Comparison</a> ( <code>==</code> ).</p>\n<pre><code class=\"lang-js\">const assert = require('assert');\n\nassert.equal(1, 1);\n// OK, 1 == 1\nassert.equal(1, '1');\n// OK, 1 == '1'\n\nassert.equal(1, 2);\n// AssertionError: 1 == 2\nassert.equal({ a: { b: 1 } }, { a: { b: 1 } });\n//AssertionError: { a: { b: 1 } } == { a: { b: 1 } }\n</code></pre>\n<p>If the values are not equal, an <code>AssertionError</code> is thrown with a <code>message</code>\nproperty set equal to the value of the <code>message</code> parameter. If the <code>message</code>\nparameter is undefined, a default error message is assigned. If the <code>message</code>\nparameter is an instance of an [<code>Error</code>][] then it will be thrown instead of the\n<code>AssertionError</code>.</p>\n" }, { "textRaw": "assert.fail([message])", "type": "method", "name": "fail", "meta": { "added": [ "v0.1.21" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} **Default:** `'Failed'` ", "name": "message", "type": "any", "desc": "**Default:** `'Failed'`", "optional": true }, { "textRaw": "`operator` {string} **Default:** '!=' ", "name": "operator", "type": "string", "desc": "**Default:** '!='", "optional": true }, { "textRaw": "`stackStartFunction` {Function} **Default:** `assert.fail` ", "name": "stackStartFunction", "type": "Function", "desc": "**Default:** `assert.fail`", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true }, { "name": "operator", "optional": true }, { "name": "stackStartFunction", "optional": true } ] }, { "params": [ { "name": "message", "optional": true } ] } ], "desc": "<p>Throws an <code>AssertionError</code>. If <code>message</code> is falsy, the error message is set as\nthe values of <code>actual</code> and <code>expected</code> separated by the provided <code>operator</code>. If\nthe <code>message</code> parameter is an instance of an [<code>Error</code>][] then it will be thrown\ninstead of the <code>AssertionError</code>. If just the two <code>actual</code> and <code>expected</code>\narguments are provided, <code>operator</code> will default to <code>'!='</code>. If <code>message</code> is\nprovided only it will be used as the error message, the other arguments will be\nstored as properties on the thrown object. If <code>stackStartFunction</code> is provided,\nall stack frames above that function will be removed from stacktrace (see\n<a href=\"errors.html#errors_error_capturestacktrace_targetobject_constructoropt\"><code>Error.captureStackTrace</code></a>). If no arguments are given, the default message\n<code>Failed</code> will be used.</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.fail(1, 2, undefined, '>');\n// AssertionError [ERR_ASSERTION]: 1 > 2\n\nassert.fail(1, 2, 'fail');\n// AssertionError [ERR_ASSERTION]: fail\n\nassert.fail(1, 2, 'whoops', '>');\n// AssertionError [ERR_ASSERTION]: whoops\n\nassert.fail(1, 2, new TypeError('need array'));\n// TypeError: need array\n</code></pre>\n<p><em>Note</em>: In the last two cases <code>actual</code>, <code>expected</code>, and <code>operator</code> have no\ninfluence on the error message.</p>\n<pre><code class=\"lang-js\">assert.fail();\n// AssertionError [ERR_ASSERTION]: Failed\n\nassert.fail('boom');\n// AssertionError [ERR_ASSERTION]: boom\n\nassert.fail('a', 'b');\n// AssertionError [ERR_ASSERTION]: 'a' != 'b'\n</code></pre>\n<p>Example use of <code>stackStartFunction</code> for truncating the exception's stacktrace:</p>\n<pre><code class=\"lang-js\">function suppressFrame() {\n assert.fail('a', 'b', undefined, '!==', suppressFrame);\n}\nsuppressFrame();\n// AssertionError [ERR_ASSERTION]: 'a' !== 'b'\n// at repl:1:1\n// at ContextifyScript.Script.runInThisContext (vm.js:44:33)\n// ...\n</code></pre>\n" }, { "textRaw": "assert.fail(actual, expected[, message[, operator[, stackStartFunction]]])", "type": "method", "name": "fail", "meta": { "added": [ "v0.1.21" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} **Default:** `'Failed'` ", "name": "message", "type": "any", "desc": "**Default:** `'Failed'`", "optional": true }, { "textRaw": "`operator` {string} **Default:** '!=' ", "name": "operator", "type": "string", "desc": "**Default:** '!='", "optional": true }, { "textRaw": "`stackStartFunction` {Function} **Default:** `assert.fail` ", "name": "stackStartFunction", "type": "Function", "desc": "**Default:** `assert.fail`", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true }, { "name": "operator", "optional": true }, { "name": "stackStartFunction", "optional": true } ] } ], "desc": "<p>Throws an <code>AssertionError</code>. If <code>message</code> is falsy, the error message is set as\nthe values of <code>actual</code> and <code>expected</code> separated by the provided <code>operator</code>. If\nthe <code>message</code> parameter is an instance of an [<code>Error</code>][] then it will be thrown\ninstead of the <code>AssertionError</code>. If just the two <code>actual</code> and <code>expected</code>\narguments are provided, <code>operator</code> will default to <code>'!='</code>. If <code>message</code> is\nprovided only it will be used as the error message, the other arguments will be\nstored as properties on the thrown object. If <code>stackStartFunction</code> is provided,\nall stack frames above that function will be removed from stacktrace (see\n<a href=\"errors.html#errors_error_capturestacktrace_targetobject_constructoropt\"><code>Error.captureStackTrace</code></a>). If no arguments are given, the default message\n<code>Failed</code> will be used.</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.fail(1, 2, undefined, '>');\n// AssertionError [ERR_ASSERTION]: 1 > 2\n\nassert.fail(1, 2, 'fail');\n// AssertionError [ERR_ASSERTION]: fail\n\nassert.fail(1, 2, 'whoops', '>');\n// AssertionError [ERR_ASSERTION]: whoops\n\nassert.fail(1, 2, new TypeError('need array'));\n// TypeError: need array\n</code></pre>\n<p><em>Note</em>: In the last two cases <code>actual</code>, <code>expected</code>, and <code>operator</code> have no\ninfluence on the error message.</p>\n<pre><code class=\"lang-js\">assert.fail();\n// AssertionError [ERR_ASSERTION]: Failed\n\nassert.fail('boom');\n// AssertionError [ERR_ASSERTION]: boom\n\nassert.fail('a', 'b');\n// AssertionError [ERR_ASSERTION]: 'a' != 'b'\n</code></pre>\n<p>Example use of <code>stackStartFunction</code> for truncating the exception's stacktrace:</p>\n<pre><code class=\"lang-js\">function suppressFrame() {\n assert.fail('a', 'b', undefined, '!==', suppressFrame);\n}\nsuppressFrame();\n// AssertionError [ERR_ASSERTION]: 'a' !== 'b'\n// at repl:1:1\n// at ContextifyScript.Script.runInThisContext (vm.js:44:33)\n// ...\n</code></pre>\n" }, { "textRaw": "assert.ifError(value)", "type": "method", "name": "ifError", "meta": { "added": [ "v0.1.97" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`value` {any} ", "name": "value", "type": "any" } ] }, { "params": [ { "name": "value" } ] } ], "desc": "<p>Throws <code>value</code> if <code>value</code> is truthy. This is useful when testing the <code>error</code>\nargument in callbacks.</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.ifError(null);\n// OK\nassert.ifError(0);\n// OK\nassert.ifError(1);\n// Throws 1\nassert.ifError('error');\n// Throws 'error'\nassert.ifError(new Error());\n// Throws Error\n</code></pre>\n" }, { "textRaw": "assert.notDeepEqual(actual, expected[, message])", "type": "method", "name": "notDeepEqual", "meta": { "added": [ "v0.1.21" ], "changes": [ { "version": "v9.0.0", "pr-url": "https://github.com/nodejs/node/pull/15001", "description": "Error names and messages are now properly compared" }, { "version": "v8.0.0", "pr-url": "https://github.com/nodejs/node/pull/12142", "description": "Set and Map content is also compared" }, { "version": "v6.4.0, v4.7.1", "pr-url": "https://github.com/nodejs/node/pull/8002", "description": "Typed array slices are handled correctly now." }, { "version": "v6.1.0, v4.5.0", "pr-url": "https://github.com/nodejs/node/pull/6432", "description": "Objects with circular references can be used as inputs now." }, { "version": "v5.10.1, v4.4.3", "pr-url": "https://github.com/nodejs/node/pull/5910", "description": "Handle non-`Uint8Array` typed arrays correctly." } ] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true } ] } ], "desc": "<p><strong>Strict mode</strong></p>\n<p>An alias of <a href=\"#assert_assert_notdeepstrictequal_actual_expected_message\"><code>assert.notDeepStrictEqual()</code></a>.</p>\n<p><strong>Legacy mode</strong></p>\n<blockquote>\n<p>Stability: 0 - Deprecated: Use <a href=\"#assert_assert_notdeepstrictequal_actual_expected_message\"><code>assert.notDeepStrictEqual()</code></a> instead.</p>\n</blockquote>\n<p>Tests for any deep inequality. Opposite of <a href=\"#assert_assert_deepequal_actual_expected_message\"><code>assert.deepEqual()</code></a>.</p>\n<pre><code class=\"lang-js\">const assert = require('assert');\n\nconst obj1 = {\n a: {\n b: 1\n }\n};\nconst obj2 = {\n a: {\n b: 2\n }\n};\nconst obj3 = {\n a: {\n b: 1\n }\n};\nconst obj4 = Object.create(obj1);\n\nassert.notDeepEqual(obj1, obj1);\n// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }\n\nassert.notDeepEqual(obj1, obj2);\n// OK: obj1 and obj2 are not deeply equal\n\nassert.notDeepEqual(obj1, obj3);\n// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }\n\nassert.notDeepEqual(obj1, obj4);\n// OK: obj1 and obj4 are not deeply equal\n</code></pre>\n<p>If the values are deeply equal, an <code>AssertionError</code> is thrown with a <code>message</code>\nproperty set equal to the value of the <code>message</code> parameter. If the <code>message</code>\nparameter is undefined, a default error message is assigned. If the <code>message</code>\nparameter is an instance of an [<code>Error</code>][] then it will be thrown instead of the\n<code>AssertionError</code>.</p>\n" }, { "textRaw": "assert.notDeepStrictEqual(actual, expected[, message])", "type": "method", "name": "notDeepStrictEqual", "meta": { "added": [ "v1.2.0" ], "changes": [ { "version": "v9.0.0", "pr-url": "https://github.com/nodejs/node/pull/15398", "description": "-0 and +0 are not considered equal anymore." }, { "version": "v9.0.0", "pr-url": "https://github.com/nodejs/node/pull/15036", "description": "NaN is now compared using the [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) comparison." }, { "version": "v9.0.0", "pr-url": "https://github.com/nodejs/node/pull/15001", "description": "Error names and messages are now properly compared" }, { "version": "v8.0.0", "pr-url": "https://github.com/nodejs/node/pull/12142", "description": "Set and Map content is also compared" }, { "version": "v6.4.0, v4.7.1", "pr-url": "https://github.com/nodejs/node/pull/8002", "description": "Typed array slices are handled correctly now." }, { "version": "v6.1.0", "pr-url": "https://github.com/nodejs/node/pull/6432", "description": "Objects with circular references can be used as inputs now." }, { "version": "v5.10.1, v4.4.3", "pr-url": "https://github.com/nodejs/node/pull/5910", "description": "Handle non-`Uint8Array` typed arrays correctly." } ] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true } ] } ], "desc": "<p>Tests for deep strict inequality. Opposite of <a href=\"#assert_assert_deepstrictequal_actual_expected_message\"><code>assert.deepStrictEqual()</code></a>.</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.notDeepStrictEqual({ a: 1 }, { a: '1' });\n// OK\n</code></pre>\n<p>If the values are deeply and strictly equal, an <code>AssertionError</code> is thrown with\na <code>message</code> property set equal to the value of the <code>message</code> parameter. If the\n<code>message</code> parameter is undefined, a default error message is assigned. If the\n<code>message</code> parameter is an instance of an [<code>Error</code>][] then it will be thrown\ninstead of the <code>AssertionError</code>.</p>\n" }, { "textRaw": "assert.notEqual(actual, expected[, message])", "type": "method", "name": "notEqual", "meta": { "added": [ "v0.1.21" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true } ] } ], "desc": "<p><strong>Strict mode</strong></p>\n<p>An alias of <a href=\"#assert_assert_notstrictequal_actual_expected_message\"><code>assert.notStrictEqual()</code></a>.</p>\n<p><strong>Legacy mode</strong></p>\n<blockquote>\n<p>Stability: 0 - Deprecated: Use <a href=\"#assert_assert_notstrictequal_actual_expected_message\"><code>assert.notStrictEqual()</code></a> instead.</p>\n</blockquote>\n<p>Tests shallow, coercive inequality with the <a href=\"https://tc39.github.io/ecma262/#sec-abstract-equality-comparison\">Abstract Equality Comparison</a>\n( <code>!=</code> ).</p>\n<pre><code class=\"lang-js\">const assert = require('assert');\n\nassert.notEqual(1, 2);\n// OK\n\nassert.notEqual(1, 1);\n// AssertionError: 1 != 1\n\nassert.notEqual(1, '1');\n// AssertionError: 1 != '1'\n</code></pre>\n<p>If the values are equal, an <code>AssertionError</code> is thrown with a <code>message</code> property\nset equal to the value of the <code>message</code> parameter. If the <code>message</code> parameter is\nundefined, a default error message is assigned. If the <code>message</code> parameter is an\ninstance of an [<code>Error</code>][] then it will be thrown instead of the\n<code>AssertionError</code>.</p>\n" }, { "textRaw": "assert.notStrictEqual(actual, expected[, message])", "type": "method", "name": "notStrictEqual", "meta": { "added": [ "v0.1.21" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true } ] } ], "desc": "<p>Tests strict inequality between the <code>actual</code> and <code>expected</code> parameters as\ndetermined by the <a href=\"https://tc39.github.io/ecma262/#sec-samevalue\">SameValue Comparison</a>.</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.notStrictEqual(1, 2);\n// OK\n\nassert.notStrictEqual(1, 1);\n// AssertionError: 1 !== 1\n\nassert.notStrictEqual(1, '1');\n// OK\n</code></pre>\n<p>If the values are strictly equal, an <code>AssertionError</code> is thrown with a <code>message</code>\nproperty set equal to the value of the <code>message</code> parameter. If the <code>message</code>\nparameter is undefined, a default error message is assigned. If the <code>message</code>\nparameter is an instance of an [<code>Error</code>][] then it will be thrown instead of the\n<code>AssertionError</code>.</p>\n" }, { "textRaw": "assert.ok(value[, message])", "type": "method", "name": "ok", "meta": { "added": [ "v0.1.21" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`value` {any} ", "name": "value", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "value" }, { "name": "message", "optional": true } ] } ], "desc": "<p>Tests if <code>value</code> is truthy. It is equivalent to\n<code>assert.equal(!!value, true, message)</code>.</p>\n<p>If <code>value</code> is not truthy, an <code>AssertionError</code> is thrown with a <code>message</code>\nproperty set equal to the value of the <code>message</code> parameter. If the <code>message</code>\nparameter is <code>undefined</code>, a default error message is assigned. If the <code>message</code>\nparameter is an instance of an [<code>Error</code>][] then it will be thrown instead of the\n<code>AssertionError</code>.</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.ok(true);\n// OK\nassert.ok(1);\n// OK\nassert.ok(false);\n// throws "AssertionError: false == true"\nassert.ok(0);\n// throws "AssertionError: 0 == true"\nassert.ok(false, 'it\\'s false');\n// throws "AssertionError: it's false"\n</code></pre>\n" }, { "textRaw": "assert.strictEqual(actual, expected[, message])", "type": "method", "name": "strictEqual", "meta": { "added": [ "v0.1.21" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`actual` {any} ", "name": "actual", "type": "any" }, { "textRaw": "`expected` {any} ", "name": "expected", "type": "any" }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "actual" }, { "name": "expected" }, { "name": "message", "optional": true } ] } ], "desc": "<p>Tests strict equality between the <code>actual</code> and <code>expected</code> parameters as\ndetermined by the <a href=\"https://tc39.github.io/ecma262/#sec-samevalue\">SameValue Comparison</a>.</p>\n<pre><code class=\"lang-js\">const assert = require('assert').strict;\n\nassert.strictEqual(1, 2);\n// AssertionError: 1 === 2\n\nassert.strictEqual(1, 1);\n// OK\n\nassert.strictEqual(1, '1');\n// AssertionError: 1 === '1'\n</code></pre>\n<p>If the values are not strictly equal, an <code>AssertionError</code> is thrown with a\n<code>message</code> property set equal to the value of the <code>message</code> parameter. If the\n<code>message</code> parameter is undefined, a default error message is assigned. If the\n<code>message</code> parameter is an instance of an [<code>Error</code>][] then it will be thrown\ninstead of the <code>AssertionError</code>.</p>\n" }, { "textRaw": "assert.throws(block[, error][, message])", "type": "method", "name": "throws", "meta": { "added": [ "v0.1.21" ], "changes": [ { "version": "v9.9.0", "pr-url": "https://github.com/nodejs/node/pull/17584", "description": "The `error` parameter can now be an object as well." }, { "version": "v4.2.0", "pr-url": "https://github.com/nodejs/node/pull/3276", "description": "The `error` parameter can now be an arrow function." } ] }, "signatures": [ { "params": [ { "textRaw": "`block` {Function} ", "name": "block", "type": "Function" }, { "textRaw": "`error` {RegExp|Function|object} ", "name": "error", "type": "RegExp|Function|object", "optional": true }, { "textRaw": "`message` {any} ", "name": "message", "type": "any", "optional": true } ] }, { "params": [ { "name": "block" }, { "name": "error", "optional": true }, { "name": "message", "optional": true } ] } ], "desc": "<p>Expects the function <code>block</code> to throw an error.</p>\n<p>If specified, <code>error</code> can be a constructor, <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions\"><code>RegExp</code></a>, a validation\nfunction, or an object where each property will be tested for.</p>\n<p>If specified, <code>message</code> will be the message provided by the <code>AssertionError</code> if\nthe block fails to throw.</p>\n<p>Validate instanceof using constructor:</p>\n<pre><code class=\"lang-js\">assert.throws(\n () => {\n throw new Error('Wrong value');\n },\n Error\n);\n</code></pre>\n<p>Validate error message using <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions\"><code>RegExp</code></a>:</p>\n<p>Using a regular expression runs <code>.toString</code> on the error object, and will\ntherefore also include the error name.</p>\n<pre><code class=\"lang-js\">assert.throws(\n () => {\n throw new Error('Wrong value');\n },\n /^Error: Wrong value$/\n);\n</code></pre>\n<p>Custom error validation:</p>\n<pre><code class=\"lang-js\">assert.throws(\n () => {\n throw new Error('Wrong value');\n },\n function(err) {\n if ((err instanceof Error) && /value/.test(err)) {\n return true;\n }\n },\n 'unexpected error'\n);\n</code></pre>\n<p>Custom error object / error instance:</p>\n<pre><code class=\"lang-js\">assert.throws(\n () => {\n const err = new TypeError('Wrong value');\n err.code = 404;\n throw err;\n },\n {\n name: 'TypeError',\n message: 'Wrong value'\n // Note that only properties on the error object will be tested!\n }\n);\n</code></pre>\n<p>Note that <code>error</code> can not be a string. If a string is provided as the second\nargument, then <code>error</code> is assumed to be omitted and the string will be used for\n<code>message</code> instead. This can lead to easy-to-miss mistakes. Please read the\nexample below carefully if using a string as the second argument gets\nconsidered:</p>\n<!-- eslint-disable no-restricted-syntax -->\n<pre><code class=\"lang-js\">function throwingFirst() {\n throw new Error('First');\n}\nfunction throwingSecond() {\n throw new Error('Second');\n}\nfunction notThrowing() {}\n\n// The second argument is a string and the input function threw an Error.\n// In that case both cases do not throw as neither is going to try to\n// match for the error message thrown by the input function!\nassert.throws(throwingFirst, 'Second');\nassert.throws(throwingSecond, 'Second');\n\n// The string is only used (as message) in case the function does not throw:\nassert.throws(notThrowing, 'Second');\n// AssertionError [ERR_ASSERTION]: Missing expected exception: Second\n\n// If it was intended to match for the error message do this instead:\nassert.throws(throwingSecond, /Second$/);\n// Does not throw because the error messages match.\nassert.throws(throwingFirst, /Second$/);\n// Throws a error:\n// Error: First\n// at throwingFirst (repl:2:9)\n</code></pre>\n<p>Due to the confusing notation, it is recommended not to use a string as the\nsecond argument. This might lead to difficult-to-spot errors.</p>\n" } ], "type": "module", "displayName": "Assert" } ] }