From 23a1140ddb3f83941b402e11db293a42389db273 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 12 Oct 2015 13:58:00 -0700 Subject: [PATCH] doc: add information about Assert behavior and maintenance Assert is now locked. Userland alternatives should be used. Assert is for testing Node.js itself. Document potentially surprising use of enumerable properties only in deep equality assertions. Ref: https://github.com/nodejs/node/pull/3124 Ref: https://github.com/nodejs/node/issues/3122 PR-URL: https://github.com/nodejs/node/pull/3330 Reviewed-By: Colin Ihrig Reviewed-By: Fedor Indutny Reviewed-By: Rod Vagg --- doc/api/assert.markdown | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown index fd1130eebe72a4..7bf6ebb40fd30a 100644 --- a/doc/api/assert.markdown +++ b/doc/api/assert.markdown @@ -1,9 +1,10 @@ # Assert - Stability: 2 - Stable + Stability: 3 - Locked -This module is used for writing assertion tests. You can access it with -`require('assert')`. +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. ## assert.fail(actual, expected, message, operator) @@ -26,8 +27,17 @@ Tests shallow, coercive inequality with the not equal comparison operator ## assert.deepEqual(actual, expected[, message]) -Tests for deep equality. Primitive values are compared with the equal comparison -operator ( `==` ). Doesn't take object prototypes into account. +Tests for deep equality. 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: + + // WARNING: This does not throw an AssertionError! + assert.deepEqual(Error('a'), Error('b')); ## assert.notDeepEqual(actual, expected[, message])