diff --git a/doc/api/assert.md b/doc/api/assert.md index bc5c0b833ae5aa..877bb1de89f02f 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -8,160 +8,161 @@ used in application code via `require('assert')`. However, `assert` is not a testing framework, and is not intended to be used as a general purpose assertion library. -The API for the `assert` module is [Locked][]. This means that there will be no -additions or changes to any of the methods implemented and exposed by -the module. +The API for the `assert` module is [Locked]. This means that there will be no +additions or changes to any of the methods implemented and exposed by this module. ## assert(value[, message]) -An alias of [`assert.ok()`][] . - -```js -const assert = require('assert'); - -assert(true); // OK -assert(1); // OK -assert(false); - // throws "AssertionError: false == true" -assert(0); - // throws "AssertionError: 0 == true" -assert(false, 'it\'s false'); - // throws "AssertionError: it's false" -``` +An alias of [`assert.ok()`]. ## assert.deepEqual(actual, expected[, message]) -Tests for deep equality between the `actual` and `expected` parameters. -Primitive values are compared with the equal comparison operator ( `==` ). +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use when `actual` and `expected` + are not equal. If not supplied, then a generated message containing `actual` + and `expected` is used. +* Return: `undefined` + +Tests *deep* equality between `actual` and `expected` as determined by the `==` +operator. If `actual` and `expected` are not equal, then an `AssertionError` +exception is thrown. -Only enumerable "own" properties are considered. The `deepEqual()` +Only enumerable "own" properties are considered. The `assert.deepEqual()` implementation does not test object prototypes, attached symbols, or non-enumerable properties. This can lead to some potentially surprising -results. For example, the following example does not throw an `AssertionError` -because the properties on the [`Error`][] object are non-enumerable: +results. + +Example: The following does not throw an `AssertionError` because the properties +on the [`Error`] object are non-enumerable ```js +const assert = require('assert'); + // WARNING: This does not throw an AssertionError! assert.deepEqual(Error('a'), Error('b')); ``` "Deep" equality means that the enumerable "own" properties of child objects -are evaluated also: +are evaluated as well. + +Examples: ```js const assert = require('assert'); const obj1 = { - a : { - b : 1 + a: { + b: 1 } }; const obj2 = { - a : { - b : 2 + a: { + b: 2 } }; const obj3 = { - a : { - b : 1 + a: { + b: 1 } }; const obj4 = Object.create(obj1); +// OK assert.deepEqual(obj1, obj1); - // OK, object is equal to itself - -assert.deepEqual(obj1, obj2); - // AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } } - // values of b are different +// OK assert.deepEqual(obj1, obj3); - // OK, objects are equal +// Throws an exception: AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } } +// The reason for this is that the values of `b` are different +assert.deepEqual(obj1, obj2); + +// Throws an exception: AssertionError: { a: { b: 1 } } deepEqual {} +// The reason for this is that prototypes are ignored assert.deepEqual(obj1, obj4); - // AssertionError: { a: { b: 1 } } deepEqual {} - // Prototypes are ignored ``` -If the values are not equal, an `AssertionError` is thrown with a `message` -property set equal to the value of the `message` parameter. If the `message` -parameter is undefined, a default error message is assigned. - ## assert.deepStrictEqual(actual, expected[, message]) -Generally identical to `assert.deepEqual()` with two exceptions. First, -primitive values are compared using the strict equality operator ( `===` ). -Second, object comparisons include a strict equality check of their prototypes. +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use when `actual` and `expected` + are not equal. If not supplied, then a generated message containing `actual` + and `expected` is used. + +Tests *deep* equality between `actual` and `expected` as determined by the `===` +operator. If `actual` and `expected` are not equal, then an `AssertionError` +exception is thrown. + +Object comparisons include a strict equal check of their prototypes. + +Example: ```js const assert = require('assert'); -assert.deepEqual({a:1}, {a:'1'}); - // OK, because 1 == '1' +const obj1 = { + a: 1 +}; +const obj2 = { + a: '1' +}; -assert.deepStrictEqual({a:1}, {a:'1'}); - // AssertionError: { a: 1 } deepStrictEqual { a: '1' } - // because 1 !== '1' using strict equality +// Throws an exception: AssertionError: { a: 1 } deepStrictEqual { a: '1' } +assert.deepStrictEqual(obj1, obj2); ``` -If the values are not equal, an `AssertionError` is thrown with a `message` -property set equal to the value of the `message` parameter. If the `message` -parameter is undefined, a default error message is assigned. - ## assert.doesNotThrow(block[, error][, message]) -Asserts that the function `block` does not throw an error. See -[`assert.throws()`][] for more details. +* `block` {Function} A function that is not expected to throw an exception +* `error` {Function | RegExp} A constructor, regular expression, or validation + function to be used when matching an exception thrown by `block` +* `message` {String} A message that is appended to the exception thrown when + `block` fails to throw an exception. +* Return: `undefined` -When `assert.doesNotThrow()` is called, it will immediately call the `block` -function. +Calls the function `block`, not expecting an exception to be thrown. If `block` +throws an exception that matches `error`, an `AssertionError` exception is thrown. +If the exception does *not* match `error` (or `error` is not supplied), then the +original exception is re-thrown. -If an error is thrown and it is the same type as that specified by the `error` -parameter, then an `AssertionError` is thrown. If the error is of a different -type, or if the `error` parameter is undefined, the error is propagated back -to the caller. +This function is the opposite of [`assert.throws()`]. -The following, for instance, will throw the [`TypeError`][] because there is no -matching error type in the assertion: +Examples: ```js +const assert = require('assert'); + +// Throws an exception: TypeError: Wrong value assert.doesNotThrow( () => { throw new TypeError('Wrong value'); }, SyntaxError ); -``` - -However, the following will result in an `AssertionError` with the message -'Got unwanted exception (TypeError)..': -```js +// Throws an exception: AssertionError: Got unwanted exception (TypeError).. assert.doesNotThrow( () => { throw new TypeError('Wrong value'); }, TypeError ); -``` - -If an `AssertionError` is thrown and a value is provided for the `message` -parameter, the value of `message` will be appended to the `AssertionError` -message: -```js +// Throws an exception: AssertionError: Got unwanted exception (TypeError). Whoops assert.doesNotThrow( () => { throw new TypeError('Wrong value'); @@ -169,7 +170,6 @@ assert.doesNotThrow( TypeError, 'Whoops' ); -// Throws: AssertionError: Got unwanted exception (TypeError). Whoops ``` ## assert.equal(actual, expected[, message]) @@ -177,44 +177,61 @@ assert.doesNotThrow( added: v0.1.21 --> -Tests shallow, coercive equality between the `actual` and `expected` parameters -using the equal comparison operator ( `==` ). +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use when `actual` and `expected` + are not equal. If not supplied, then a generated message containing `actual` + and `expected` is used. +* Return: `undefined` + +Tests equality between `actual` and `expected` as determined by the (shallow +and coercive) `==` operator. If `actual` and `expected` are not equal, then an +`AssertionError` exception is thrown. + +Examples: ```js const assert = require('assert'); +// OK assert.equal(1, 1); - // OK, 1 == 1 + +// OK assert.equal(1, '1'); - // OK, 1 == '1' +// Throws an exception: AssertionError: 1 == 2 assert.equal(1, 2); - // AssertionError: 1 == 2 + +// Throws an exception: AssertionError: { a: { b: 1 } } == { a: { b: 1 } } assert.equal({a: {b: 1}}, {a: {b: 1}}); - //AssertionError: { a: { b: 1 } } == { a: { b: 1 } } ``` -If the values are not equal, an `AssertionError` is thrown with a `message` -property set equal to the value of the `message` parameter. If the `message` -parameter is undefined, a default error message is assigned. - ## assert.fail(actual, expected, message, operator) -Throws an `AssertionError`. If `message` is falsy, the error message is set as -the values of `actual` and `expected` separated by the provided `operator`. -Otherwise, the error message is the value of `message`. +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use. If not supplied, then a + generated message containing `actual` and `expected` is used. +* `operator` {String} If `message` is not specified, this is a comparison operator + that is inserted between `actual` and `expected` in the generated exception + message. +* Return: `undefined` + +Always throws an `AssertionError`. + +Examples: ```js const assert = require('assert'); +// Throws an exception: AssertionError: 1 > 2 assert.fail(1, 2, undefined, '>'); - // AssertionError: 1 > 2 +// Throws an exception: AssertionError: whoops assert.fail(1, 2, 'whoops', '>'); - // AssertionError: whoops ``` ## assert.ifError(value) @@ -222,16 +239,28 @@ assert.fail(1, 2, 'whoops', '>'); added: v0.1.97 --> -Throws `value` if `value` is truthy. This is useful when testing the `error` -argument in callbacks. +* `value` {mixed} +* Return: `undefined` + +Throws `value` if `value` evaluates to `true`. This is useful when testing the +error argument in callbacks. + +Examples: ```js const assert = require('assert'); -assert.ifError(0); // OK +// OK +assert.ifError(0); + +// Throws an exception: 1 assert.ifError(1); // Throws 1 -assert.ifError('error'); // Throws 'error' -assert.ifError(new Error()); // Throws Error + +// Throws an exception: error +assert.ifError('error'); + +// Throws an exception: Error +assert.ifError(new Error()); ``` ## assert.notDeepEqual(actual, expected[, message]) @@ -239,139 +268,187 @@ assert.ifError(new Error()); // Throws Error added: v0.1.21 --> -Tests for any deep inequality. Opposite of [`assert.deepEqual()`][]. +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use when `actual` and `expected` + are equal. If not supplied, then a generated message containing `actual` and + `expected` is used. + +Tests *deep* inequality between `actual` and `expected` as determined by the `!=` +operator. If `actual` and `expected` are equal, then an `AssertionError` +exception is thrown. + +Only enumerable "own" properties are considered. The `assert.notDeepEqual()` +implementation does not test object prototypes, attached symbols, or +non-enumerable properties. This can lead to some potentially surprising +results. + +This function is the opposite of [`assert.deepEqual()`]. + +Examples: ```js const assert = require('assert'); const obj1 = { - a : { - b : 1 + a: { + b: 1 } }; const obj2 = { - a : { - b : 2 + a: { + b: 2 } }; const obj3 = { - a : { - b : 1 + a: { + b: 1 } -} +}; const obj4 = Object.create(obj1); -assert.notDeepEqual(obj1, obj1); - // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } - +// OK assert.notDeepEqual(obj1, obj2); - // OK, obj1 and obj2 are not deeply equal - -assert.notDeepEqual(obj1, obj3); - // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } +// OK assert.notDeepEqual(obj1, obj4); - // OK, obj1 and obj2 are not deeply equal -``` -If the values are deeply equal, an `AssertionError` is thrown with a `message` -property set equal to the value of the `message` parameter. If the `message` -parameter is undefined, a default error message is assigned. +// Throws an exception: AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } +assert.notDeepEqual(obj1, obj1); + +// Throws an exception: AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } +assert.notDeepEqual(obj1, obj3); +``` ## assert.notDeepStrictEqual(actual, expected[, message]) -Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][]. +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use when `actual` and `expected` + are equal. If not supplied, then a generated message containing `actual` and + `expected` is used. + +Tests *deep* inequality between `actual` and `expected` as determined by the `!==` +operator. If `actual` and `expected` are equal, then an `AssertionError` +exception is thrown. + +Object comparisons include a not strict equal check of their prototypes. + +This function is the opposite of [`assert.deepStrictEqual()`]. + +Examples: ```js const assert = require('assert'); -assert.notDeepEqual({a:1}, {a:'1'}); - // AssertionError: { a: 1 } notDeepEqual { a: '1' } +const obj1 = { + a: 1 +}; +const obj2 = { + a: '1' +}; -assert.notDeepStrictEqual({a:1}, {a:'1'}); - // OK +// OK +assert.notDeepStrictEqual(obj1, obj2); ``` -If the values are deeply and strictly equal, an `AssertionError` is thrown -with a `message` property set equal to the value of the `message` parameter. If -the `message` parameter is undefined, a default error message is assigned. - ## assert.notEqual(actual, expected[, message]) -Tests shallow, coercive inequality with the not equal comparison operator -( `!=` ). +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use when `actual` and `expected` + are equal. If not supplied, then a generated message containing `actual` and + `expected` is used. + +Tests inequality between `actual` and `expected` as determined by the (shallow +and coercive) `!=` operator. If `actual` and `expected` are equal, then an +`AssertionError` exception is thrown. + +Examples: ```js const assert = require('assert'); +// OK assert.notEqual(1, 2); - // OK +// Throws an exception: AssertionError: 1 != 1 assert.notEqual(1, 1); - // AssertionError: 1 != 1 +// Throws an exception: AssertionError: 1 != '1' assert.notEqual(1, '1'); - // AssertionError: 1 != '1' ``` -If the values are equal, an `AssertionError` is thrown with a `message` -property set equal to the value of the `message` parameter. If the `message` -parameter is undefined, a default error message is assigned. - ## assert.notStrictEqual(actual, expected[, message]) -Tests strict inequality as determined by the strict not equal operator -( `!==` ). +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use when `actual` and `expected` + are equal. If not supplied, then a generated message containing `actual` and + `expected` is used. + +Tests inequality between `actual` and `expected` as determined by the `!==` +operator. If `actual` and `expected` are equal, then an `AssertionError` exception +is thrown. + +Examples: ```js const assert = require('assert'); +// OK assert.notStrictEqual(1, 2); - // OK - -assert.notStrictEqual(1, 1); - // AssertionError: 1 != 1 +// OK assert.notStrictEqual(1, '1'); - // OK -``` -If the values are strictly equal, an `AssertionError` is thrown with a -`message` property set equal to the value of the `message` parameter. If the -`message` parameter is undefined, a default error message is assigned. +// Throws an exception: AssertionError: 1 != 1 +assert.notStrictEqual(1, 1); +``` ## assert.ok(value[, message]) -Tests if `value` is truthy. It is equivalent to -`assert.equal(!!value, true, message)`. +* `value` {mixed} A value to check +* `message` {String} The exception message to use when `value` does not evaluate + to `true`. If not supplied, then a generated message containing `value` is used. +* Return: `undefined` + +Tests if `value` evaluates to `true`. If `value` does not evaluate to `true`, +then an `AssertionError` exception is thrown. + +This function is equivalent to `assert.equal(!!value, true, message)`. -If `value` is not truthy, an `AssertionError` is thrown with a `message` -property set equal to the value of the `message` parameter. If the `message` -parameter is `undefined`, a default error message is assigned. +Examples: ```js const assert = require('assert'); -assert.ok(true); // OK -assert.ok(1); // OK +// OK +assert.ok(true); + +// OK +assert.ok(1); + +// Throws an exception: AssertionError: false == true assert.ok(false); - // throws "AssertionError: false == true" + +// Throws an exception: AssertionError: 0 == true assert.ok(0); - // throws "AssertionError: 0 == true" -assert.ok(false, 'it\'s false'); - // throws "AssertionError: it's false" + +// Throws an exception: AssertionError: it's false +assert.ok(false, 'it is false'); ``` ## assert.strictEqual(actual, expected[, message]) @@ -379,39 +456,47 @@ assert.ok(false, 'it\'s false'); added: v0.1.21 --> -Tests strict equality as determined by the strict equality operator ( `===` ). +* `actual` {mixed} A value to check +* `expected` {mixed} The expected value of `actual` +* `message` {String} The exception message to use when `actual` and `expected` + are not equal. If not supplied, then a generated message containing `actual` + and `expected` is used. + +Tests equality between `actual` and `expected` as determined by the `===` +operator. If `actual` and `expected` are not equal, then an `AssertionError` +exception is thrown. + +Examples: ```js const assert = require('assert'); -assert.strictEqual(1, 2); - // AssertionError: 1 === 2 - +// OK assert.strictEqual(1, 1); - // OK +// Throws an exception: AssertionError: 1 === 2 +assert.strictEqual(1, 2); + +// Throws an exception: AssertionError: 1 === '1' assert.strictEqual(1, '1'); - // AssertionError: 1 === '1' ``` -If the values are not strictly equal, an `AssertionError` is thrown with a -`message` property set equal to the value of the `message` parameter. If the -`message` parameter is undefined, a default error message is assigned. - ## assert.throws(block[, error][, message]) -Expects the function `block` to throw an error. - -If specified, `error` can be a constructor, [`RegExp`][], or validation -function. +* `block` {Function} A function that is expected to throw an exception +* `error` {Function | RegExp} A constructor, regular expression, or validation + function to be used when matching an exception thrown by `block` +* `message` {String} The exception message to use when `block` fails to throw an + exception. If not supplied, then a generic, generated message is used. +* Return: `undefined` -If specified, `message` will be the message provided by the `AssertionError` if -the block fails to throw. +Calls the function `block`, expecting an exception to be thrown. If `block` +does not throw an exception, an `AssertionError` exception is thrown. -Validate instanceof using constructor: +Example: Match a thrown exception by constructor ```js assert.throws( @@ -422,7 +507,7 @@ assert.throws( ); ``` -Validate error message using [`RegExp`][]: +Example: Match a thrown exception by testing its message with a [`RegExp`] ```js assert.throws( @@ -433,15 +518,15 @@ assert.throws( ); ``` -Custom error validation: +Example: Match a thrown exception using a custom validation function ```js assert.throws( () => { throw new Error('Wrong value'); }, - function(err) { - if ( (err instanceof Error) && /value/.test(err) ) { + (err) => { + if ((err instanceof Error) && /value/.test(err)) { return true; } }, @@ -451,21 +536,24 @@ assert.throws( Note that `error` can not be a string. If a string is provided as the second argument, then `error` is assumed to be omitted and the string will be used for -`message` instead. This can lead to easy-to-miss mistakes: +`message` instead. This can lead to easy-to-miss mistakes. + +Example: ```js // THIS IS A MISTAKE! DO NOT DO THIS! assert.throws(myFunction, 'missing foo', 'did not throw with expected message'); -// Do this instead. +// Do this instead assert.throws(myFunction, /missing foo/, 'did not throw with expected message'); ``` -[Locked]: documentation.html#documentation_stability_index [`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message [`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message [`assert.ok()`]: #assert_assert_ok_value_message [`assert.throws()`]: #assert_assert_throws_block_error_message [`Error`]: errors.html#errors_class_error -[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions [`TypeError`]: errors.html#errors_class_typeerror + +[Locked]: documentation.html#documentation_stability_index +[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions