doc: improve assert.markdown copy
General improvements to assert.markdown copy including new and improved examples PR-URL: https://github.com/nodejs/node/pull/4360 Reviewed-By: Trevor Norris <trev.norris@gmail.com>
This commit is contained in:
parent
d09c447ef9
commit
3e648eb2ca
@ -2,42 +2,131 @@
|
||||
|
||||
Stability: 3 - Locked
|
||||
|
||||
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.
|
||||
The `assert` module provides a simple set of assertion tests that can be used
|
||||
to test invariants and implement unit tests. While the `assert` module is
|
||||
generally intended for internal use by Node.js itself, it can be used by user
|
||||
code calling `require('assert')`.
|
||||
|
||||
The API for the `assert` module is [Locked][]. This means that there will be no
|
||||
additions or changes to any of the methods implemented and exposed by
|
||||
the module.
|
||||
|
||||
## assert(value[, message]), assert.ok(value[, message])
|
||||
|
||||
Tests if value is truthy. It is equivalent to
|
||||
Tests if `value` is truthy. It is equivalent to
|
||||
`assert.equal(!!value, true, message)`.
|
||||
|
||||
If `value` is not truthy, an `AssertionError` is thrown with a `message`
|
||||
property set equal to the value of the `message` parameter. If the `message`
|
||||
parameter is `undefined`, a default error message is assigned.
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert(true); // OK
|
||||
assert(1); // OK
|
||||
assert(false);
|
||||
// throws "AssertionError: false == true"
|
||||
assert(0);
|
||||
// throws "AssertionError: 0 == true"
|
||||
assert(false, 'it\'s false');
|
||||
// throws "AssertionError: it's false"
|
||||
|
||||
assert.ok(true); // OK
|
||||
assert.ok(1); // OK
|
||||
assert.ok(false);
|
||||
// throws "AssertionError: false == true"
|
||||
assert.ok(0);
|
||||
// throws "AssertionError: 0 == true"
|
||||
assert.ok(false, 'it\'s false');
|
||||
// throws "AssertionError: it's false"
|
||||
|
||||
## assert.deepEqual(actual, expected[, message])
|
||||
|
||||
Tests for deep equality. Primitive values are compared with the equal
|
||||
comparison operator ( `==` ).
|
||||
Tests for deep equality between the `actual` and `expected` parameters.
|
||||
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:
|
||||
Only enumerable "own" properties are considered. The `deepEqual()`
|
||||
implementation does not test object prototypes, attached symbols, or
|
||||
non-enumerable properties. This can lead to some potentially surprising
|
||||
results. For example, the following example 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'));
|
||||
|
||||
"Deep" equality means that the enumerable "own" properties of child objects
|
||||
are evaluated also:
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
const obj1 = {
|
||||
a : {
|
||||
b : 1
|
||||
}
|
||||
};
|
||||
const obj2 = {
|
||||
a : {
|
||||
b : 2
|
||||
}
|
||||
};
|
||||
const obj3 = {
|
||||
a : {
|
||||
b : 1
|
||||
}
|
||||
}
|
||||
const obj4 = Object.create(obj1);
|
||||
|
||||
assert.deepEqual(obj1, obj1);
|
||||
// OK, object is equal to itself
|
||||
|
||||
assert.deepEqual(obj1, obj2);
|
||||
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
|
||||
// values of b are different
|
||||
|
||||
assert.deepEqual(obj1, obj3);
|
||||
// OK, objects are equal
|
||||
|
||||
assert.deepEqual(obj1, obj4);
|
||||
// AssertionError: { a: { b: 1 } } deepEqual {}
|
||||
// Prototypes are ignored
|
||||
|
||||
If the values are not equal, an `AssertionError` is thrown with a `message`
|
||||
property set equal to the value of the `message` parameter. If the `message`
|
||||
parameter is undefined, a default error message is assigned.
|
||||
|
||||
## assert.deepStrictEqual(actual, expected[, message])
|
||||
|
||||
Tests for deep equality. Primitive values are compared with the strict equality
|
||||
operator ( `===` ).
|
||||
Generally identical to `assert.deepEqual` with the exception that primitive
|
||||
values are compared using the strict equality operator ( `===` ).
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert.deepEqual({a:1}, {a:'1'});
|
||||
// OK, because 1 == '1'
|
||||
|
||||
assert.deepStrictEqual({a:1}, {a:'1'});
|
||||
// AssertionError: { a: 1 } deepStrictEqual { a: '1' }
|
||||
// because 1 !== '1' using strict equality
|
||||
|
||||
If the values are not equal, an `AssertionError` is thrown with a `message`
|
||||
property set equal to the value of the `message` parameter. If the `message`
|
||||
parameter is undefined, a default error message is assigned.
|
||||
|
||||
## assert.doesNotThrow(block[, error][, message])
|
||||
|
||||
Expects `block` not to throw an error. See [`assert.throws()`][] for more details.
|
||||
Asserts that the function `block` does not throw an error. See
|
||||
[`assert.throws()`][] for more details.
|
||||
|
||||
If `block` throws an error and if it is of a different type from `error`, the
|
||||
thrown error will get propagated back to the caller. The following call will
|
||||
throw the [`TypeError`][], since we're not matching the error types in the
|
||||
assertion.
|
||||
When `assert.doesNotThrow()` is called, it will immediately call the `block`
|
||||
function.
|
||||
|
||||
If an error is thrown and it is the same type as that specified by the `error`
|
||||
parameter, then an `AssertionError` is thrown. If the error is of a different
|
||||
type, or if the `error` parameter is undefined, the error is propagated back
|
||||
to the caller.
|
||||
|
||||
The following, for instance, will throw the [`TypeError`][] because there is no
|
||||
matching error type in the assertion:
|
||||
|
||||
assert.doesNotThrow(
|
||||
function() {
|
||||
@ -46,8 +135,8 @@ assertion.
|
||||
SyntaxError
|
||||
);
|
||||
|
||||
In case `error` matches with the error thrown by `block`, an `AssertionError`
|
||||
is thrown instead.
|
||||
However, the following will result in an `AssertionError` with the message
|
||||
'Got unwanted exception (TypeError)..':
|
||||
|
||||
assert.doesNotThrow(
|
||||
function() {
|
||||
@ -56,47 +145,184 @@ is thrown instead.
|
||||
TypeError
|
||||
);
|
||||
|
||||
If an `AssertionError` is thrown and a value is provided for the `message`
|
||||
parameter, the value of `message` will be appended to the `AssertionError`
|
||||
message:
|
||||
|
||||
assert.doesNotThrow(
|
||||
function() {
|
||||
throw new TypeError('Wrong value');
|
||||
},
|
||||
TypeError,
|
||||
'Whoops'
|
||||
);
|
||||
// Throws: AssertionError: Got unwanted exception (TypeError). Whoops
|
||||
|
||||
## assert.equal(actual, expected[, message])
|
||||
|
||||
Tests shallow, coercive equality with the equal comparison operator ( `==` ).
|
||||
Tests shallow, coercive equality between the `actual` and `expected` parameters
|
||||
using the equal comparison operator ( `==` ).
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert.equal(1, 1);
|
||||
// OK, 1 == 1
|
||||
assert.equal(1, '1');
|
||||
// OK, 1 == '1'
|
||||
|
||||
assert.equal(1, 2);
|
||||
// AssertionError: 1 == 2
|
||||
assert.equal({a: {b: 1}}, {a: {b: 1}});
|
||||
//AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
|
||||
|
||||
If the values are not equal, an `AssertionError` is thrown with a `message`
|
||||
property set equal to the value of the `message` parameter. If the `message`
|
||||
parameter is undefined, a default error message is assigned.
|
||||
|
||||
## assert.fail(actual, expected, message, operator)
|
||||
|
||||
Throws an `AssertionError`. If `message` is falsy, it displays the values for
|
||||
`actual` and `expected` separated by the provided `operator`. Otherwise, it
|
||||
displays `message` (and does not use `actual`, `expected`, and `operator`).
|
||||
Throws an `AssertionError`. If `message` is falsy, the error message is set as
|
||||
the values of `actual` and `expected` separated by the provided `operator`.
|
||||
Otherwise, the error message is the value of `message`.
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert.fail(1, 2, undefined, '>');
|
||||
// AssertionError: 1 > 2
|
||||
|
||||
assert.fail(1, 2, 'whoops', '>');
|
||||
// AssertionError: whoops
|
||||
|
||||
## assert.ifError(value)
|
||||
|
||||
Throws `value` if `value` is truthy. This is useful when testing the `error`
|
||||
argument in callbacks.
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert.ifError(0); // OK
|
||||
assert.ifError(1); // Throws 1
|
||||
assert.ifError('error') // Throws 'error'
|
||||
assert.ifError(new Error()); // Throws Error
|
||||
|
||||
## assert.notDeepEqual(actual, expected[, message])
|
||||
|
||||
Tests for any deep inequality. Opposite of [`assert.deepEqual`][].
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
const obj1 = {
|
||||
a : {
|
||||
b : 1
|
||||
}
|
||||
};
|
||||
const obj2 = {
|
||||
a : {
|
||||
b : 2
|
||||
}
|
||||
};
|
||||
const obj3 = {
|
||||
a : {
|
||||
b : 1
|
||||
}
|
||||
}
|
||||
const obj4 = Object.create(obj1);
|
||||
|
||||
assert.deepEqual(obj1, obj1);
|
||||
AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
|
||||
|
||||
assert.deepEqual(obj1, obj2);
|
||||
// OK, obj1 and obj2 are not deeply equal
|
||||
|
||||
assert.deepEqual(obj1, obj3);
|
||||
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
|
||||
|
||||
assert.deepEqual(obj1, obj4);
|
||||
// OK, obj1 and obj2 are not deeply equal
|
||||
|
||||
If the values are deeply equal, an `AssertionError` is thrown with a `message`
|
||||
property set equal to the value of the `message` parameter. If the `message`
|
||||
parameter is undefined, a default error message is assigned.
|
||||
|
||||
## assert.notDeepStrictEqual(actual, expected[, message])
|
||||
|
||||
Tests for deep inequality. Opposite of [`assert.deepStrictEqual`][].
|
||||
Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual`][].
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert.notDeepEqual({a:1}, {a:'1'});
|
||||
// AssertionError: { a: 1 } notDeepEqual { a: '1' }
|
||||
|
||||
assert.notDeepStrictEqual({a:1}, {a:'1'});
|
||||
// OK
|
||||
|
||||
If the values are deeply and strictly equal, an `AssertionError` is thrown
|
||||
with a `message` property set equal to the value of the `message` parameter. If
|
||||
the `message` parameter is undefined, a default error message is assigned.
|
||||
|
||||
## assert.notEqual(actual, expected[, message])
|
||||
|
||||
Tests shallow, coercive inequality with the not equal comparison operator
|
||||
( `!=` ).
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert.notEqual(1, 2);
|
||||
// OK
|
||||
|
||||
assert.notEqual(1, 1);
|
||||
// AssertionError: 1 != 1
|
||||
|
||||
assert.notEqual(1, '1');
|
||||
// AssertionError: 1 != '1'
|
||||
|
||||
If the values are equal, an `AssertionError` is thrown with a `message`
|
||||
property set equal to the value of the `message` parameter. If the `message`
|
||||
parameter is undefined, a default error message is assigned.
|
||||
|
||||
## assert.notStrictEqual(actual, expected[, message])
|
||||
|
||||
Tests strict inequality as determined by the strict not equal operator
|
||||
( `!==` ).
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert.notStrictEqual(1, 2);
|
||||
// OK
|
||||
|
||||
assert.notStrictEqual(1, 1);
|
||||
// AssertionError: 1 != 1
|
||||
|
||||
assert.notStrictEqual(1, '1');
|
||||
// OK
|
||||
|
||||
If the values are strictly equal, an `AssertionError` is thrown with a
|
||||
`message` property set equal to the value of the `message` parameter. If the
|
||||
`message` parameter is undefined, a default error message is assigned.
|
||||
|
||||
## assert.strictEqual(actual, expected[, message])
|
||||
|
||||
Tests strict equality as determined by the strict equality operator ( `===` ).
|
||||
|
||||
const assert = require('assert');
|
||||
|
||||
assert.strictEqual(1, 2);
|
||||
// AssertionError: 1 === 2
|
||||
|
||||
assert.strictEqual(1, 1);
|
||||
// OK
|
||||
|
||||
assert.strictEqual(1, '1');
|
||||
// AssertionError: 1 === '1'
|
||||
|
||||
If the values are not strictly equal, an `AssertionError` is thrown with a
|
||||
`message` property set equal to the value of the `message` parameter. If the
|
||||
`message` parameter is undefined, a default error message is assigned.
|
||||
|
||||
## assert.throws(block[, error][, message])
|
||||
|
||||
Expects `block` to throw an error. `error` can be a constructor, [`RegExp`][], or
|
||||
validation function.
|
||||
Expects the function `block` to throw an error. If specified, `error` can be a
|
||||
constructor, [`RegExp`][], or validation function.
|
||||
|
||||
Validate instanceof using constructor:
|
||||
|
||||
@ -130,6 +356,7 @@ Custom error validation:
|
||||
'unexpected error'
|
||||
);
|
||||
|
||||
[Locked]: documentation.html#documentation_stability_index
|
||||
[`assert.deepEqual`]: #assert_assert_deepequal_actual_expected_message
|
||||
[`assert.deepStrictEqual`]: #assert_assert_deepstrictequal_actual_expected_message
|
||||
[`assert.throws()`]: #assert_assert_throws_block_error_message
|
||||
|
Loading…
x
Reference in New Issue
Block a user