Skip to content

Commit

Permalink
doc: add information about Assert behavior and maintenance
Browse files Browse the repository at this point in the history 
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: #3124
Ref: #3122

PR-URL: #3330
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Fedor Indutny <[email protected]>
Reviewed-By: Rod Vagg <[email protected]>
  • Loading branch information
@Trott @rvagg
Trott authored and rvagg committed Oct 21, 2015
1 parent 086103b commit b607366
Showing 1 changed file with 15 additions and 5 deletions.
20 changes: 15 additions & 5 deletions doc/api/assert.markdown
View file
Original file line number Diff line number Diff line change
@@ -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)

Expand All @@ -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])

Expand Down

4 comments on commit b607366

@jkillian
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However, it is recommended that a userland assertion library be used instead.

Could this be elaborated on? It seems to imply that there's something broken about the assert module included with Node.

@Trott
Copy link
Member Author

@Trott Trott commented on b607366 Nov 8, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are many surprises lurking in the Assertion library. For example, assert.deepEqual(Error('foo'), Error('bar')) does not throw an AssertionError. There are many other oddities.

@Trott
Copy link
Member Author

@Trott Trott commented on b607366 Nov 8, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To get a little more specific with a few examples:

  • deepEqual() only compares enumerable properties (which explains the surprising result with Error objects mentioned previously)
  • I'm pretty sure deepEqual() also ignores attached Symbols
  • assert.fail() has a strange method signature that behaves oddly. The first two parameters and the third parameter are mutually exclusive. So, if you want to use the third parameter, which happens to be the typical use case, you have to pass two other parameters for no reason: assert.fail(null, null, 'actual parameter you care about');

There are other things, but none of them are going to be fixed unless they cause problems for Node itself. For more explanation, you can read the discussion in the three issues cited in the commit message:

@jkillian
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see. Thank you for the details and references @Trott

Please sign in to comment.