doc/api/assert.markdown

   1 # Assert
   2
   3     Stability: 3 - Locked
   4
   5 The `assert` module provides a simple set of assertion tests that can be used to
   6 test invariants. The module is intended for internal use by Node.js, but can be
   7 used in application code via `require('assert')`. However, `assert` is not a
   8 testing framework, and is not intended to be used as a general purpose assertion
   9 library.
  10
  11 The API for the `assert` module is [Locked][]. This means that there will be no
  12 additions or changes to any of the methods implemented and exposed by
  13 the module.
  14
  15 ## assert(value[, message]), assert.ok(value[, message])
  16
  17 Tests if `value` is truthy. It is equivalent to
  18 `assert.equal(!!value, true, message)`.
  19
  20 If `value` is not truthy, an `AssertionError` is thrown with a `message`
  21 property set equal to the value of the `message` parameter. If the `message`
  22 parameter is `undefined`, a default error message is assigned.
  23
  24 ```js
  25 const assert = require('assert');
  26
  27 assert(true);  // OK
  28 assert(1);     // OK
  29 assert(false);
  30   // throws "AssertionError: false == true"
  31 assert(0);
  32   // throws "AssertionError: 0 == true"
  33 assert(false, 'it\'s false');
  34   // throws "AssertionError: it's false"
  35
  36 assert.ok(true);  // OK
  37 assert.ok(1);     // OK
  38 assert.ok(false);
  39   // throws "AssertionError: false == true"
  40 assert.ok(0);
  41   // throws "AssertionError: 0 == true"
  42 assert.ok(false, 'it\'s false');
  43   // throws "AssertionError: it's false"
  44 ```
  45
  46 ## assert.deepEqual(actual, expected[, message])
  47
  48 Tests for deep equality between the `actual` and `expected` parameters.
  49 Primitive values are compared with the equal comparison operator ( `==` ).
  50
  51 Only enumerable "own" properties are considered. The `deepEqual()`
  52 implementation does not test object prototypes, attached symbols, or
  53 non-enumerable properties. This can lead to some potentially surprising
  54 results. For example, the following example does not throw an `AssertionError`
  55 because the properties on the [`Error`][] object are non-enumerable:
  56
  57 ```js
  58 // WARNING: This does not throw an AssertionError!
  59 assert.deepEqual(Error('a'), Error('b'));
  60 ```
  61
  62 "Deep" equality means that the enumerable "own" properties of child objects
  63 are evaluated also:
  64
  65 ```js
  66 const assert = require('assert');
  67
  68 const obj1 = {
  69   a : {
  70     b : 1
  71   }
  72 };
  73 const obj2 = {
  74   a : {
  75     b : 2
  76   }
  77 };
  78 const obj3 = {
  79   a : {
  80     b : 1
  81   }
  82 }
  83 const obj4 = Object.create(obj1);
  84
  85 assert.deepEqual(obj1, obj1);
  86   // OK, object is equal to itself
  87
  88 assert.deepEqual(obj1, obj2);
  89   // AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
  90   // values of b are different
  91
  92 assert.deepEqual(obj1, obj3);
  93   // OK, objects are equal
  94
  95 assert.deepEqual(obj1, obj4);
  96   // AssertionError: { a: { b: 1 } } deepEqual {}
  97   // Prototypes are ignored
  98 ```
  99
 100 If the values are not equal, an `AssertionError` is thrown with a `message`
 101 property set equal to the value of the `message` parameter. If the `message`
 102 parameter is undefined, a default error message is assigned.
 103
 104 ## assert.deepStrictEqual(actual, expected[, message])
 105
 106 Generally identical to `assert.deepEqual` with the exception that primitive
 107 values are compared using the strict equality operator ( `===` ).
 108
 109 ```js
 110 const assert = require('assert');
 111
 112 assert.deepEqual({a:1}, {a:'1'});
 113   // OK, because 1 == '1'
 114
 115 assert.deepStrictEqual({a:1}, {a:'1'});
 116   // AssertionError: { a: 1 } deepStrictEqual { a: '1' }
 117   // because 1 !== '1' using strict equality
 118 ```
 119
 120 If the values are not equal, an `AssertionError` is thrown with a `message`
 121 property set equal to the value of the `message` parameter. If the `message`
 122 parameter is undefined, a default error message is assigned.
 123
 124 ## assert.doesNotThrow(block[, error][, message])
 125
 126 Asserts that the function `block` does not throw an error. See
 127 [`assert.throws()`][] for more details.
 128
 129 When `assert.doesNotThrow()` is called, it will immediately call the `block`
 130 function.
 131
 132 If an error is thrown and it is the same type as that specified by the `error`
 133 parameter, then an `AssertionError` is thrown. If the error is of a different
 134 type, or if the `error` parameter is undefined, the error is propagated back
 135 to the caller.
 136
 137 The following, for instance, will throw the [`TypeError`][] because there is no
 138 matching error type in the assertion:
 139
 140 ```js
 141 assert.doesNotThrow(
 142   function() {
 143     throw new TypeError('Wrong value');
 144   },
 145   SyntaxError
 146 );
 147 ```
 148
 149 However, the following will result in an `AssertionError` with the message
 150 'Got unwanted exception (TypeError)..':
 151
 152 ```js
 153 assert.doesNotThrow(
 154   function() {
 155     throw new TypeError('Wrong value');
 156   },
 157   TypeError
 158 );
 159 ```
 160
 161 If an `AssertionError` is thrown and a value is provided for the `message`
 162 parameter, the value of `message` will be appended to the `AssertionError`
 163 message:
 164
 165 ```js
 166 assert.doesNotThrow(
 167   function() {
 168     throw new TypeError('Wrong value');
 169   },
 170   TypeError,
 171   'Whoops'
 172 );
 173 // Throws: AssertionError: Got unwanted exception (TypeError). Whoops
 174 ```
 175
 176 ## assert.equal(actual, expected[, message])
 177
 178 Tests shallow, coercive equality between the `actual` and `expected` parameters
 179 using the equal comparison operator ( `==` ).
 180
 181 ```js
 182 const assert = require('assert');
 183
 184 assert.equal(1, 1);
 185   // OK, 1 == 1
 186 assert.equal(1, '1');
 187   // OK, 1 == '1'
 188
 189 assert.equal(1, 2);
 190   // AssertionError: 1 == 2
 191 assert.equal({a: {b: 1}}, {a: {b: 1}});
 192   //AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
 193 ```
 194
 195 If the values are not equal, an `AssertionError` is thrown with a `message`
 196 property set equal to the value of the `message` parameter. If the `message`
 197 parameter is undefined, a default error message is assigned.
 198
 199 ## assert.fail(actual, expected, message, operator)
 200
 201 Throws an `AssertionError`. If `message` is falsy, the error message is set as
 202 the values of `actual` and `expected` separated by the provided `operator`.
 203 Otherwise, the error message is the value of `message`.
 204
 205 ```js
 206 const assert = require('assert');
 207
 208 assert.fail(1, 2, undefined, '>');
 209   // AssertionError: 1 > 2
 210
 211 assert.fail(1, 2, 'whoops', '>');
 212   // AssertionError: whoops
 213 ```
 214
 215 ## assert.ifError(value)
 216
 217 Throws `value` if `value` is truthy. This is useful when testing the `error`
 218 argument in callbacks.
 219
 220 ```js
 221 const assert = require('assert');
 222
 223 assert.ifError(0); // OK
 224 assert.ifError(1); // Throws 1
 225 assert.ifError('error') // Throws 'error'
 226 assert.ifError(new Error()); // Throws Error
 227 ```
 228
 229 ## assert.notDeepEqual(actual, expected[, message])
 230
 231 Tests for any deep inequality. Opposite of [`assert.deepEqual`][].
 232
 233 ```js
 234 const assert = require('assert');
 235
 236 const obj1 = {
 237   a : {
 238     b : 1
 239   }
 240 };
 241 const obj2 = {
 242   a : {
 243     b : 2
 244   }
 245 };
 246 const obj3 = {
 247   a : {
 248     b : 1
 249   }
 250 }
 251 const obj4 = Object.create(obj1);
 252
 253 assert.deepEqual(obj1, obj1);
 254   AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
 255
 256 assert.deepEqual(obj1, obj2);
 257   // OK, obj1 and obj2 are not deeply equal
 258
 259 assert.deepEqual(obj1, obj3);
 260   // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
 261
 262 assert.deepEqual(obj1, obj4);
 263   // OK, obj1 and obj2 are not deeply equal
 264 ```
 265
 266 If the values are deeply equal, an `AssertionError` is thrown with a `message`
 267 property set equal to the value of the `message` parameter. If the `message`
 268 parameter is undefined, a default error message is assigned.
 269
 270 ## assert.notDeepStrictEqual(actual, expected[, message])
 271
 272 Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual`][].
 273
 274 ```js
 275 const assert = require('assert');
 276
 277 assert.notDeepEqual({a:1}, {a:'1'});
 278   // AssertionError: { a: 1 } notDeepEqual { a: '1' }
 279
 280 assert.notDeepStrictEqual({a:1}, {a:'1'});
 281   // OK
 282 ```
 283
 284 If the values are deeply and strictly equal, an `AssertionError` is thrown
 285 with a `message` property set equal to the value of the `message` parameter. If
 286 the `message` parameter is undefined, a default error message is assigned.
 287
 288 ## assert.notEqual(actual, expected[, message])
 289
 290 Tests shallow, coercive inequality with the not equal comparison operator
 291 ( `!=` ).
 292
 293 ```js
 294 const assert = require('assert');
 295
 296 assert.notEqual(1, 2);
 297   // OK
 298
 299 assert.notEqual(1, 1);
 300   // AssertionError: 1 != 1
 301
 302 assert.notEqual(1, '1');
 303   // AssertionError: 1 != '1'
 304 ```
 305
 306 If the values are equal, an `AssertionError` is thrown with a `message`
 307 property set equal to the value of the `message` parameter. If the `message`
 308 parameter is undefined, a default error message is assigned.
 309
 310 ## assert.notStrictEqual(actual, expected[, message])
 311
 312 Tests strict inequality as determined by the strict not equal operator
 313 ( `!==` ).
 314
 315 ```js
 316 const assert = require('assert');
 317
 318 assert.notStrictEqual(1, 2);
 319   // OK
 320
 321 assert.notStrictEqual(1, 1);
 322   // AssertionError: 1 != 1
 323
 324 assert.notStrictEqual(1, '1');
 325   // OK
 326 ```
 327
 328 If the values are strictly equal, an `AssertionError` is thrown with a
 329 `message` property set equal to the value of the `message` parameter. If the
 330 `message` parameter is undefined, a default error message is assigned.
 331
 332 ## assert.strictEqual(actual, expected[, message])
 333
 334 Tests strict equality as determined by the strict equality operator ( `===` ).
 335
 336 ```js
 337 const assert = require('assert');
 338
 339 assert.strictEqual(1, 2);
 340   // AssertionError: 1 === 2
 341
 342 assert.strictEqual(1, 1);
 343   // OK
 344
 345 assert.strictEqual(1, '1');
 346   // AssertionError: 1 === '1'
 347 ```
 348
 349 If the values are not strictly equal, an `AssertionError` is thrown with a
 350 `message` property set equal to the value of the `message` parameter. If the
 351 `message` parameter is undefined, a default error message is assigned.
 352
 353 ## assert.throws(block[, error][, message])
 354
 355 Expects the function `block` to throw an error. If specified, `error` can be a
 356 constructor, [`RegExp`][], or validation function.
 357
 358 Validate instanceof using constructor:
 359
 360 ```js
 361 assert.throws(
 362   function() {
 363     throw new Error('Wrong value');
 364   },
 365   Error
 366 );
 367 ```
 368
 369 Validate error message using [`RegExp`][]:
 370
 371 ```js
 372 assert.throws(
 373   function() {
 374     throw new Error('Wrong value');
 375   },
 376   /value/
 377 );
 378 ```
 379
 380 Custom error validation:
 381
 382 ```js
 383 assert.throws(
 384   function() {
 385     throw new Error('Wrong value');
 386   },
 387   function(err) {
 388     if ( (err instanceof Error) && /value/.test(err) ) {
 389       return true;
 390     }
 391   },
 392   'unexpected error'
 393 );
 394 ```
 395
 396 [Locked]: documentation.html#documentation_stability_index
 397 [`assert.deepEqual`]: #assert_assert_deepequal_actual_expected_message
 398 [`assert.deepStrictEqual`]: #assert_assert_deepstrictequal_actual_expected_message
 399 [`assert.throws()`]: #assert_assert_throws_block_error_message
 400 [`Error`]: errors.html#errors_class_error
 401 [`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
 402 [`TypeError`]: errors.html#errors_class_typeerror