8000 doc: improve assert.markdown copy · nodejs/node@823269d · GitHub
[go: up one dir, main page]
Skip to content

Commit 823269d

Browse files
jasnellMyles Borins
jasnell
authored and
Myles Borins
committed
doc: improve assert.markdown copy
General improvements to assert.markdown copy including new and improved examples PR-URL: #4360 Reviewed-By: Trevor Norris <trev.norris@gmail.com>
1 parent 761af37 commit 823269d

File tree

1 file changed

+254
-27
lines changed

1 file changed

+254
-27
lines changed

‎doc/api/assert.markdown‎

Lines changed: 254 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,42 +2,131 @@
22

33
Stability: 3 - Locked
44

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.
5+
The `assert` module provides a simple set of assertion tests that can be used
6+
to test invariants and implement unit tests. While the `assert` module is
7+
generally intended for internal use by Node.js itself, it can be used by user
8+
code calling `require('assert')`.
9+
10+
The API for the `assert` module is [Locked][]. This means that there will be no
11+
additions or changes to any of the methods implemented and exposed by
12+
the module.
813

914
## assert(value[, message]), assert.ok(value[, message])
1015

11-
Tests if value is truthy. It is equivalent to
16+
Tests if `value` is truthy. It is equivalent to
1217
`assert.equal(!!value, true, message)`.
1318

19+
If `value` is not truthy, an `AssertionError` is thrown with a `message`
20+
property set equal to the value of the `message` parameter. If the `message`
21+
parameter is `undefined`, a default error message is assigned.
22+
23+
const assert = require('assert');
24+
25+
assert(true); // OK
26+
assert(1); // OK
27+
assert(false);
28+
// throws "AssertionError: false == true"
29+
assert(0);
30+
// throws "AssertionError: 0 == true"
31+
assert(false, 'it\'s false');
32+
// throws "AssertionError: it's false"
33+
34+
assert.ok(true); // OK
35+
assert.ok(1); // OK
36+
assert.ok(false);
37+
// throws "AssertionError: false == true"
38+
assert.ok(0);
39+
// throws "AssertionError: 0 == true"
40+
assert.ok(false, 'it\'s false');
41+
// throws "AssertionError: it's false"
42+
1443
## assert.deepEqual(actual, expected[, message])
1544

16-
Tests for deep equality. Primitive values are compared with the equal
17-
comparison operator ( `==` ).
45+
Tests for deep equality between the `actual` and `expected` parameters.
46+
Primitive values are compared with the equal comparison operator ( `==` ).
1847

19-
This only considers enumerable properties. It does not test object prototypes,
20-
attached symbols, or non-enumerable properties. This can lead to some
21-
potentially surprising results. For example, this does not throw an
22-
`AssertionError` because the properties on the [`Error`][] object are
23-
non-enumerable:
48+
Only enumerable "own" properties are considered. The `deepEqual()`
49+
implementation does not test object prototypes, attached symbols, or
50+
non-enumerable properties. This can lead to some potentially surprising
51+
results. For example, the following example does not throw an `AssertionError`
52+
because the properties on the [`Error`][] object are non-enumerable:
2453

2554
// WARNING: This does not throw an AssertionError!
2655
assert.deepEqual(Error('a'), Error('b'));
2756

57+
"Deep" equality means that the enumerable "own" properties of child objects
58+
are evaluated also:
59+
60+
const assert = require('assert');
61+
62+
const obj1 = {
63+
a : {
64+
b : 1
65+
}
66+
};
67+
const obj2 = {
68+
a : {
69+
b : 2
70+
}
71+
};
72+
const obj3 = {
73+
a : {
74+
b : 1
75+
}
76+
}
77+
const obj4 = Object.create(obj1);
78+
79+
assert.deepEqual( 9E88 obj1, obj1);
80+
// OK, object is equal to itself
81+
82+
assert.deepEqual(obj1, obj2);
83+
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
84+
// values of b are different
85+
86+
assert.deepEqual(obj1, obj3);
87+
// OK, objects are equal
88+
89+
assert.deepEqual(obj1, obj4);
90+
// AssertionError: { a: { b: 1 } } deepEqual {}
91+
// Prototypes are ignored
92+
93+
If the values are not equal, an `AssertionError` is thrown with a `message`
94+
property set equal to the value of the `message` parameter. If the `message`
95+
parameter is undefined, a default error message is assigned.
96+
2897
## assert.deepStrictEqual(actual, expected[, message])
2998

30-
Tests for deep equality. Primitive values are compared with the strict equality
31-
operator ( `===` ).
99+
Generally identical to `assert.deepEqual` with the exception that primitive
100+
values are compared using the strict equality operator ( `===` ).
101+
102+
const assert = require('assert');
103+
104+
assert.deepEqual({a:1}, {a:'1'});
105+
// OK, because 1 == '1'
106+
107+
assert.deepStrictEqual({a:1}, {a:'1'});
108+
// AssertionError: { a: 1 } deepStrictEqual { a: '1' }
109+
// because 1 !== '1' using strict equality
110+
111+
If the values are not equal, an `AssertionError` is thrown with a `message`
112+
property set equal to the value of the `message` parameter. If the `message`
113+
parameter is undefined, a default error message is assigned.
32114

33115
## assert.doesNotThrow(block[, error][, message])
34116

35-
Expects `block` not to throw an error. See [`assert.throws()`][] for more details.
117+
Asserts that the function `block` does not throw an error. See
118+
[`assert.throws()`][] for more details.
119+
120+
When `assert.doesNotThrow()` is called, it will immediately call the `block`
121+
function.
122+
123+
If an error is thrown and it is the same type as that specified by the `error`
124+
parameter, then an `AssertionError` is thrown. If the error is of a different
125+
type, or if the `error` parameter is undefined, the error is propagated back
126+
to the caller.
36127

37-
If `block` throws an error and if it is of a different type from `error`, the
38-
thrown error will get propagated back to the caller. The following call will
39-
throw the [`TypeError`][], since we're not matching the error types in the
40-
assertion.
128+
The following, for instance, will throw the [`TypeError`][] because there is no
129+
matching error type in the assertion:
41130

42131
assert.doesNotThrow(
43132
function() {
@@ -46,8 +135,8 @@ assertion.
46135
SyntaxError
47136
);
48137

49-
In case `error` matches with the error thrown by `block`, an `AssertionError`
50-
is thrown instead.
138+
However, the following will result in an `AssertionError` with the message
139+
'Got unwanted exception (TypeError)..':
51140

52141
assert.doesNotThrow(
53142
function() {
@@ -56,47 +145,184 @@ is thrown instead.
56145
TypeError
57146
);
58147

148+
If an `AssertionError` is thrown and a value is provided for the `message`
149+
parameter, the value of `message` will be appended to the `AssertionError`
150+
message:
151+
152+
assert.doesNotThrow(
153+
function() {
154+
throw new TypeError('Wrong value');
155+
},
156+
TypeError,
157+
'Whoops'
158+
);
159+
// Throws: AssertionError: Got unwanted exception (TypeError). Whoops
160+
59161
## assert.equal(actual, expected[, message])
60162

61-
Tests shallow, coercive equality with the equal comparison operator ( `==` ).
163+
Tests shallow, coercive equality between the `actual` and `expected` parameters
164+
using the equal comparison operator ( `==` ).
165+
166+
const assert = require('assert');
167+
168+
assert.equal(1, 1);
169+
// OK, 1 == 1
170+
assert.equal(1, '1');
171+
// OK, 1 == '1'
172+
173+
assert.equal(1, 2);
174+
// AssertionError: 1 == 2
175+
assert.equal({a: {b: 1}}, {a: {b: 1}});
176+
//AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
177+
178+
If the values are not equal, an `AssertionError` is thrown with a `message`
179+
property set equal to the value of the `message` parameter. If the `message`
180+
parameter is undefined, a default error message is assigned.
62181

63182
## assert.fail(actual, expected, message, operator)
64183

65-
Throws an `AssertionError`. If `message` is falsy, it displays the values for
66-
`actual` and `expected` separated by the provided `operator`. Otherwise, it
67-
displays `message` (and does not use `actual`, `expected`, and `operator`).
184+
Throws an `AssertionError`. If `message` is falsy, the error message is set as
185+
the values of `actual` and `expected` separated by the provided `operator`.
186+
Otherwise, the error message is the value of `message`.
187+
188+
const assert = require('assert');
189+
190+
assert.fail(1, 2, undefined, '>');
191+
// AssertionError: 1 > 2
192+
193+
assert.fail(1, 2, 'whoops', '>');
194+
// AssertionError: whoops
68195

69196
## assert.ifError(value)
70197

71198
Throws `value` if `value` is truthy. This is useful when testing the `error`
72199
argument in callbacks.
73200

201+
const assert = require('assert');
202+
203+
assert.ifError(0); // OK
204+
assert.ifError(1); // Throws 1
205+
assert.ifError('error') // Throws 'error'
206+
assert.ifError(new Error()); // Throws Error
207+
74208
## assert.notDeepEqual(actual, expected[, message])
75209

76210
Tests for any deep inequality. Opposite of [`assert.deepEqual`][].
77211

212+
const assert = require('assert');
213+
214+
const obj1 = {
215+
a : {
216+
b : 1
217+
}
218+
};
219+
const obj2 = {
220+
a : {
221+
b : 2
222+
}
223+
};
224+
const obj3 = {
225+
a : {
226+
b : 1
227+
}
228+
}
229+
const obj4 = Object.create(obj1);
230+
231+
assert.deepEqual(obj1, obj1);
232+
AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
233+
234+
assert.deepEqual(obj1, obj2);
235+
// OK, obj1 and obj2 are not deeply equal
236+
237+
assert.deepEqual(obj1, obj3);
238+
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
239+
240+
assert.deepEqual(obj1, obj4);
241+
// OK, obj1 and obj2 are not deeply equal
242+
243+
If the values are deeply equal, an `AssertionError` is thrown with a `message`
244+
property set equal to the value of the `message` parameter. If the `message`
245+
parameter is undefined, a default error message is assigned.
246+
78247
## assert.notDeepStrictEqual(actual, expected[, message])
79248

80-
Tests for deep inequality. Opposite of [`assert.deepStrictEqual`][].
249+
Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual`][].
250+
251+
const assert = require('assert');
252+
253+
assert.notDeepEqual({a:1}, {a:'1'});
254+
// AssertionError: { a: 1 } notDeepEqual { a: '1' }
255+
256+
assert.notDeepStrictEqual({a:1}, {a:'1'});
257+
// OK
258+
259+
If the values are deeply and strictly equal, an `AssertionError` is thrown
260+
with a `message` property set equal to the value of the `message` parameter. If
261+
the `message` parameter is undefined, a default error message is assigned.
81262

82263
## assert.notEqual(actual, expected[, message])
83264

84265
Tests shallow, coercive inequality with the not equal comparison operator
85266
( `!=` ).
86267

268+
const assert = require('assert');
269+
270+
assert.notEqual(1, 2);
271+
// OK
272+
273+
assert.notEqual(1, 1);
274+
// AssertionError: 1 != 1
275+
276+
assert.notEqual(1, '1');
277+
// AssertionError: 1 != '1'
278+
279+
If the values are equal, an `AssertionError` is thrown with a `message`
280+
property set equal to the value of the `message` parameter. If the `message`
281+
parameter is undefined, a default error message is assigned.
282+
87283
## assert.notStrictEqual(actual, expected[, message])
88284

89285
Tests strict inequality as determined by the strict not equal operator
90286
( `!==` ).
91287

288+
const assert = require('assert');
289+
290+
assert.notStrictEqual(1, 2);
291+
// OK
292+
293+
assert.notStrictEqual(1, 1);
294+
// AssertionError: 1 != 1
295+
296+
assert.notStrictEqual(1, '1');
297+
// OK
298+
299+
If the values are strictly equal, an `AssertionError` is thrown with a
300+
`message` property set equal to the value of the `message` parameter. If the
301+
`message` parameter is undefined, a default error message is assigned.
302+
92303
## assert.strictEqual(actual, expected[, message])
93304

94305
Tests strict equality as determined by the strict equality operator ( `===` ).
95306

307+
const assert = require('assert');
308+
309+
assert.strictEqual(1, 2);
310+
// AssertionError: 1 === 2
311+
312+
assert.strictEqual(1, 1);
313+
// OK
314+
315+
assert.strictEqual(1, '1');
316+
// AssertionError: 1 === '1'
317+
318+
If the values are not strictly equal, an `AssertionError` is thrown with a
319+
`message` property set equal to the value of the `message` parameter. If the
320+
`message` parameter is undefined, a default error message is assigned.
321+
96322
## assert.throws(block[, error][, message])
97323

98-
Expects `block` to 38BA throw an error. `error` can be a constructor, [`RegExp`][], or
99-
validation function.
324+
Expects the function `block` to throw an error. If specified, `error` can be a
325+
constructor, [`RegExp`][], or validation function.
100326

101327
Validate instanceof using constructor:
102328

@@ -130,6 +356,7 @@ Custom error validation:
130356
'unexpected error'
131357
);
132358

359+
[Locked]: documentation.html#documentation_stability_index
133360
[`assert.deepEqual`]: #assert_assert_deepequal_actual_expected_message
134361
[`assert.deepStrictEqual`]: #assert_assert_deepstrictequal_actual_expected_message
135362
[`assert.throws()`]: #assert_assert_throws_block_error_message

0 commit comments

Comments
 (0)
0