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 authored and jasnell committed Oct 26, 2015
1 parent 87f8ccf commit 4023c7d
Showing 1 changed file with 15 additions and 5 deletions.
20 changes: 15 additions & 5 deletions doc/api/assert.markdown
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

0 comments on commit 4023c7d

Please sign in to comment.