From c835ba36012708a7833055074bc17ba1437599e7 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sat, 19 Dec 2015 19:08:13 -0800 Subject: [PATCH] doc: improve assert.markdown copy General improvements to assert.markdown copy including new and improved examples PR-URL: https://github.com/nodejs/node/pull/4360 Reviewed-By: Trevor Norris --- doc/api/assert.markdown | 281 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 254 insertions(+), 27 deletions(-) diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown index eb334696805298..bab280f325ff27 100644 --- a/doc/api/assert.markdown +++ b/doc/api/assert.markdown @@ -2,42 +2,131 @@ Stability: 3 - Locked -This module is used so that Node.js can test itself. It can be accessed with -`require('assert')`. However, it is recommended that a userland assertion -library be used instead. +The `assert` module provides a simple set of assertion tests that can be used +to test invariants and implement unit tests. While the `assert` module is +generally intended for internal use by Node.js itself, it can be used by user +code calling `require('assert')`. + +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. ## assert(value[, message]), assert.ok(value[, message]) -Tests if value is truthy. It is equivalent to +Tests if `value` is truthy. It 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. + + 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" + + assert.ok(true); // OK + assert.ok(1); // OK + assert.ok(false); + // throws "AssertionError: false == true" + assert.ok(0); + // throws "AssertionError: 0 == true" + assert.ok(false, 'it\'s false'); + // throws "AssertionError: it's false" + ## assert.deepEqual(actual, expected[, message]) -Tests for deep equality. Primitive values are compared with the equal -comparison operator ( `==` ). +Tests for deep equality between the `actual` and `expected` parameters. +Primitive values are compared with the equal comparison operator ( `==` ). -This only considers enumerable properties. It does not test object prototypes, -attached symbols, or non-enumerable properties. This can lead to some -potentially surprising results. For example, this does not throw an -`AssertionError` because the properties on the [`Error`][] object are -non-enumerable: +Only enumerable "own" properties are considered. The `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: // 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: + + const assert = require('assert'); + + const obj1 = { + a : { + b : 1 + } + }; + const obj2 = { + a : { + b : 2 + } + }; + const obj3 = { + a : { + b : 1 + } + } + const obj4 = Object.create(obj1); + + 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 + + assert.deepEqual(obj1, obj3); + // OK, objects are equal + + 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]) -Tests for deep equality. Primitive values are compared with the strict equality -operator ( `===` ). +Generally identical to `assert.deepEqual` with the exception that primitive +values are compared using the strict equality operator ( `===` ). + + const assert = require('assert'); + + assert.deepEqual({a:1}, {a:'1'}); + // OK, because 1 == '1' + + assert.deepStrictEqual({a:1}, {a:'1'}); + // AssertionError: { a: 1 } deepStrictEqual { a: '1' } + // because 1 !== '1' using strict equality + +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]) -Expects `block` not to throw an error. See [`assert.throws()`][] for more details. +Asserts that the function `block` does not throw an error. See +[`assert.throws()`][] for more details. + +When `assert.doesNotThrow()` is called, it will immediately call the `block` +function. + +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. -If `block` throws an error and if it is of a different type from `error`, the -thrown error will get propagated back to the caller. The following call will -throw the [`TypeError`][], since we're not matching the error types in the -assertion. +The following, for instance, will throw the [`TypeError`][] because there is no +matching error type in the assertion: assert.doesNotThrow( function() { @@ -46,8 +135,8 @@ assertion. SyntaxError ); -In case `error` matches with the error thrown by `block`, an `AssertionError` -is thrown instead. +However, the following will result in an `AssertionError` with the message +'Got unwanted exception (TypeError)..': assert.doesNotThrow( function() { @@ -56,47 +145,184 @@ is thrown instead. 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: + + assert.doesNotThrow( + function() { + throw new TypeError('Wrong value'); + }, + TypeError, + 'Whoops' + ); + // Throws: AssertionError: Got unwanted exception (TypeError). Whoops + ## assert.equal(actual, expected[, message]) -Tests shallow, coercive equality with the equal comparison operator ( `==` ). +Tests shallow, coercive equality between the `actual` and `expected` parameters +using the equal comparison operator ( `==` ). + + const assert = require('assert'); + + assert.equal(1, 1); + // OK, 1 == 1 + assert.equal(1, '1'); + // OK, 1 == '1' + + assert.equal(1, 2); + // AssertionError: 1 == 2 + 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, it displays the values for -`actual` and `expected` separated by the provided `operator`. Otherwise, it -displays `message` (and does not use `actual`, `expected`, and `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`. + + const assert = require('assert'); + + assert.fail(1, 2, undefined, '>'); + // AssertionError: 1 > 2 + + assert.fail(1, 2, 'whoops', '>'); + // AssertionError: whoops ## assert.ifError(value) Throws `value` if `value` is truthy. This is useful when testing the `error` argument in callbacks. + const assert = require('assert'); + + assert.ifError(0); // OK + assert.ifError(1); // Throws 1 + assert.ifError('error') // Throws 'error' + assert.ifError(new Error()); // Throws Error + ## assert.notDeepEqual(actual, expected[, message]) Tests for any deep inequality. Opposite of [`assert.deepEqual`][]. + const assert = require('assert'); + + const obj1 = { + a : { + b : 1 + } + }; + const obj2 = { + a : { + b : 2 + } + }; + const obj3 = { + a : { + b : 1 + } + } + const obj4 = Object.create(obj1); + + assert.deepEqual(obj1, obj1); + AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } + + assert.deepEqual(obj1, obj2); + // OK, obj1 and obj2 are not deeply equal + + assert.deepEqual(obj1, obj3); + // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } + + assert.deepEqual(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. + ## assert.notDeepStrictEqual(actual, expected[, message]) -Tests for deep inequality. Opposite of [`assert.deepStrictEqual`][]. +Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual`][]. + + const assert = require('assert'); + + assert.notDeepEqual({a:1}, {a:'1'}); + // AssertionError: { a: 1 } notDeepEqual { a: '1' } + + assert.notDeepStrictEqual({a:1}, {a:'1'}); + // OK + +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 ( `!=` ). + const assert = require('assert'); + + assert.notEqual(1, 2); + // OK + + assert.notEqual(1, 1); + // 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 ( `!==` ). + const assert = require('assert'); + + assert.notStrictEqual(1, 2); + // OK + + assert.notStrictEqual(1, 1); + // AssertionError: 1 != 1 + + 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. + ## assert.strictEqual(actual, expected[, message]) Tests strict equality as determined by the strict equality operator ( `===` ). + const assert = require('assert'); + + assert.strictEqual(1, 2); + // AssertionError: 1 === 2 + + assert.strictEqual(1, 1); + // OK + + 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 `block` to throw an error. `error` can be a constructor, [`RegExp`][], or -validation function. +Expects the function `block` to throw an error. If specified, `error` can be a +constructor, [`RegExp`][], or validation function. Validate instanceof using constructor: @@ -130,6 +356,7 @@ Custom error validation: 'unexpected error' ); +[Locked]: documentation.html#documentation_stability_index [`assert.deepEqual`]: #assert_assert_deepequal_actual_expected_message [`assert.deepStrictEqual`]: #assert_assert_deepstrictequal_actual_expected_message [`assert.throws()`]: #assert_assert_throws_block_error_message