Skip to content

Commit b607366

Browse files
Trottrvagg
authored andcommitted
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: #3124 Ref: #3122 PR-URL: #3330 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Fedor Indutny <fedor@indutny.com> Reviewed-By: Rod Vagg <rod@vagg.org>
1 parent 086103b commit b607366

File tree

1 file changed

+15
-5
lines changed

1 file changed

+15
-5
lines changed

doc/api/assert.markdown

+15-5
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# Assert
22

3-
Stability: 2 - Stable
3+
Stability: 3 - Locked
44

5-
This module is used for writing assertion tests. You can access it with
6-
`require('assert')`.
5+
This module is used so that Node.js can test itself. It can be accessed with
6+
`require('assert')`. However, it is recommended that a userland assertion
7+
library be used instead.
78

89
## assert.fail(actual, expected, message, operator)
910

@@ -26,8 +27,17 @@ Tests shallow, coercive inequality with the not equal comparison operator
2627

2728
## assert.deepEqual(actual, expected[, message])
2829

29-
Tests for deep equality. Primitive values are compared with the equal comparison
30-
operator ( `==` ). Doesn't take object prototypes into account.
30+
Tests for deep equality. Primitive values are compared with the equal
31+
comparison operator ( `==` ).
32+
33+
This only considers enumerable properties. It does not test object prototypes,
34+
attached symbols, or non-enumerable properties. This can lead to some
35+
potentially surprising results. For example, this does not throw an
36+
`AssertionError` because the properties on the `Error` object are
37+
non-enumerable:
38+
39+
// WARNING: This does not throw an AssertionError!
40+
assert.deepEqual(Error('a'), Error('b'));
3141

3242
## assert.notDeepEqual(actual, expected[, message])
3343

0 commit comments

Comments
 (0)