assert.d.ts (40803B)
1 /** 2 * The `assert` module provides a set of assertion functions for verifying 3 * invariants. 4 * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/assert.js) 5 */ 6 declare module "assert" { 7 /** 8 * An alias of {@link ok}. 9 * @since v0.5.9 10 * @param value The input that is checked for being truthy. 11 */ 12 function assert(value: unknown, message?: string | Error): asserts value; 13 namespace assert { 14 /** 15 * Indicates the failure of an assertion. All errors thrown by the `assert` module 16 * will be instances of the `AssertionError` class. 17 */ 18 class AssertionError extends Error { 19 actual: unknown; 20 expected: unknown; 21 operator: string; 22 generatedMessage: boolean; 23 code: "ERR_ASSERTION"; 24 constructor(options?: { 25 /** If provided, the error message is set to this value. */ 26 message?: string | undefined; 27 /** The `actual` property on the error instance. */ 28 actual?: unknown | undefined; 29 /** The `expected` property on the error instance. */ 30 expected?: unknown | undefined; 31 /** The `operator` property on the error instance. */ 32 operator?: string | undefined; 33 /** If provided, the generated stack trace omits frames before this function. */ 34 // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type 35 stackStartFn?: Function | undefined; 36 }); 37 } 38 /** 39 * This feature is currently experimental and behavior might still change. 40 * @since v14.2.0, v12.19.0 41 * @experimental 42 */ 43 class CallTracker { 44 /** 45 * The wrapper function is expected to be called exactly `exact` times. If the 46 * function has not been called exactly `exact` times when `tracker.verify()` is called, then `tracker.verify()` will throw an 47 * error. 48 * 49 * ```js 50 * import assert from 'assert'; 51 * 52 * // Creates call tracker. 53 * const tracker = new assert.CallTracker(); 54 * 55 * function func() {} 56 * 57 * // Returns a function that wraps func() that must be called exact times 58 * // before tracker.verify(). 59 * const callsfunc = tracker.calls(func); 60 * ``` 61 * @since v14.2.0, v12.19.0 62 * @param [fn='A no-op function'] 63 * @param [exact=1] 64 * @return that wraps `fn`. 65 */ 66 calls(exact?: number): () => void; 67 calls<Func extends (...args: any[]) => any>(fn?: Func, exact?: number): Func; 68 /** 69 * Example: 70 * 71 * ```js 72 * import assert from 'node:assert'; 73 * 74 * const tracker = new assert.CallTracker(); 75 * 76 * function func() {} 77 * const callsfunc = tracker.calls(func); 78 * callsfunc(1, 2, 3); 79 * 80 * assert.deepStrictEqual(tracker.getCalls(callsfunc), 81 * [{ thisArg: this, arguments: [1, 2, 3 ] }]); 82 * ``` 83 * 84 * @since v18.8.0, v16.18.0 85 * @param fn 86 * @returns An Array with the calls to a tracked function. 87 */ 88 getCalls(fn: Function): CallTrackerCall[]; 89 /** 90 * The arrays contains information about the expected and actual number of calls of 91 * the functions that have not been called the expected number of times. 92 * 93 * ```js 94 * import assert from 'assert'; 95 * 96 * // Creates call tracker. 97 * const tracker = new assert.CallTracker(); 98 * 99 * function func() {} 100 * 101 * function foo() {} 102 * 103 * // Returns a function that wraps func() that must be called exact times 104 * // before tracker.verify(). 105 * const callsfunc = tracker.calls(func, 2); 106 * 107 * // Returns an array containing information on callsfunc() 108 * tracker.report(); 109 * // [ 110 * // { 111 * // message: 'Expected the func function to be executed 2 time(s) but was 112 * // executed 0 time(s).', 113 * // actual: 0, 114 * // expected: 2, 115 * // operator: 'func', 116 * // stack: stack trace 117 * // } 118 * // ] 119 * ``` 120 * @since v14.2.0, v12.19.0 121 * @return of objects containing information about the wrapper functions returned by `calls`. 122 */ 123 report(): CallTrackerReportInformation[]; 124 /** 125 * Reset calls of the call tracker. 126 * If a tracked function is passed as an argument, the calls will be reset for it. 127 * If no arguments are passed, all tracked functions will be reset. 128 * 129 * ```js 130 * import assert from 'node:assert'; 131 * 132 * const tracker = new assert.CallTracker(); 133 * 134 * function func() {} 135 * const callsfunc = tracker.calls(func); 136 * 137 * callsfunc(); 138 * // Tracker was called once 139 * tracker.getCalls(callsfunc).length === 1; 140 * 141 * tracker.reset(callsfunc); 142 * tracker.getCalls(callsfunc).length === 0; 143 * ``` 144 * 145 * @since v18.8.0, v16.18.0 146 * @param fn a tracked function to reset. 147 */ 148 reset(fn?: Function): void; 149 /** 150 * Iterates through the list of functions passed to `tracker.calls()` and will throw an error for functions that 151 * have not been called the expected number of times. 152 * 153 * ```js 154 * import assert from 'assert'; 155 * 156 * // Creates call tracker. 157 * const tracker = new assert.CallTracker(); 158 * 159 * function func() {} 160 * 161 * // Returns a function that wraps func() that must be called exact times 162 * // before tracker.verify(). 163 * const callsfunc = tracker.calls(func, 2); 164 * 165 * callsfunc(); 166 * 167 * // Will throw an error since callsfunc() was only called once. 168 * tracker.verify(); 169 * ``` 170 * @since v14.2.0, v12.19.0 171 */ 172 verify(): void; 173 } 174 interface CallTrackerCall { 175 thisArg: object; 176 arguments: unknown[]; 177 } 178 interface CallTrackerReportInformation { 179 message: string; 180 /** The actual number of times the function was called. */ 181 actual: number; 182 /** The number of times the function was expected to be called. */ 183 expected: number; 184 /** The name of the function that is wrapped. */ 185 operator: string; 186 /** A stack trace of the function. */ 187 stack: object; 188 } 189 type AssertPredicate = RegExp | (new() => object) | ((thrown: unknown) => boolean) | object | Error; 190 /** 191 * Throws an `AssertionError` with the provided error message or a default 192 * error message. If the `message` parameter is an instance of an `Error` then 193 * it will be thrown instead of the `AssertionError`. 194 * 195 * ```js 196 * import assert from 'assert/strict'; 197 * 198 * assert.fail(); 199 * // AssertionError [ERR_ASSERTION]: Failed 200 * 201 * assert.fail('boom'); 202 * // AssertionError [ERR_ASSERTION]: boom 203 * 204 * assert.fail(new TypeError('need array')); 205 * // TypeError: need array 206 * ``` 207 * 208 * Using `assert.fail()` with more than two arguments is possible but deprecated. 209 * See below for further details. 210 * @since v0.1.21 211 * @param [message='Failed'] 212 */ 213 function fail(message?: string | Error): never; 214 /** @deprecated since v10.0.0 - use fail([message]) or other assert functions instead. */ 215 function fail( 216 actual: unknown, 217 expected: unknown, 218 message?: string | Error, 219 operator?: string, 220 // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type 221 stackStartFn?: Function, 222 ): never; 223 /** 224 * Tests if `value` is truthy. It is equivalent to`assert.equal(!!value, true, message)`. 225 * 226 * 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 227 * error message is assigned. If the `message`parameter is an instance of an `Error` then it will be thrown instead of the`AssertionError`. 228 * If no arguments are passed in at all `message` will be set to the string:`` 'No value argument passed to `assert.ok()`' ``. 229 * 230 * Be aware that in the `repl` the error message will be different to the one 231 * thrown in a file! See below for further details. 232 * 233 * ```js 234 * import assert from 'assert/strict'; 235 * 236 * assert.ok(true); 237 * // OK 238 * assert.ok(1); 239 * // OK 240 * 241 * assert.ok(); 242 * // AssertionError: No value argument passed to `assert.ok()` 243 * 244 * assert.ok(false, 'it\'s false'); 245 * // AssertionError: it's false 246 * 247 * // In the repl: 248 * assert.ok(typeof 123 === 'string'); 249 * // AssertionError: false == true 250 * 251 * // In a file (e.g. test.js): 252 * assert.ok(typeof 123 === 'string'); 253 * // AssertionError: The expression evaluated to a falsy value: 254 * // 255 * // assert.ok(typeof 123 === 'string') 256 * 257 * assert.ok(false); 258 * // AssertionError: The expression evaluated to a falsy value: 259 * // 260 * // assert.ok(false) 261 * 262 * assert.ok(0); 263 * // AssertionError: The expression evaluated to a falsy value: 264 * // 265 * // assert.ok(0) 266 * ``` 267 * 268 * ```js 269 * import assert from 'assert/strict'; 270 * 271 * // Using `assert()` works the same: 272 * assert(0); 273 * // AssertionError: The expression evaluated to a falsy value: 274 * // 275 * // assert(0) 276 * ``` 277 * @since v0.1.21 278 */ 279 function ok(value: unknown, message?: string | Error): asserts value; 280 /** 281 * **Strict assertion mode** 282 * 283 * An alias of {@link strictEqual}. 284 * 285 * **Legacy assertion mode** 286 * 287 * > Stability: 3 - Legacy: Use {@link strictEqual} instead. 288 * 289 * Tests shallow, coercive equality between the `actual` and `expected` parameters 290 * using the [Abstract Equality Comparison](https://tc39.github.io/ecma262/#sec-abstract-equality-comparison) ( `==` ). `NaN` is special handled 291 * and treated as being identical in case both sides are `NaN`. 292 * 293 * ```js 294 * import assert from 'assert'; 295 * 296 * assert.equal(1, 1); 297 * // OK, 1 == 1 298 * assert.equal(1, '1'); 299 * // OK, 1 == '1' 300 * assert.equal(NaN, NaN); 301 * // OK 302 * 303 * assert.equal(1, 2); 304 * // AssertionError: 1 == 2 305 * assert.equal({ a: { b: 1 } }, { a: { b: 1 } }); 306 * // AssertionError: { a: { b: 1 } } == { a: { b: 1 } } 307 * ``` 308 * 309 * 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 310 * error message is assigned. If the `message`parameter is an instance of an `Error` then it will be thrown instead of the`AssertionError`. 311 * @since v0.1.21 312 */ 313 function equal(actual: unknown, expected: unknown, message?: string | Error): void; 314 /** 315 * **Strict assertion mode** 316 * 317 * An alias of {@link notStrictEqual}. 318 * 319 * **Legacy assertion mode** 320 * 321 * > Stability: 3 - Legacy: Use {@link notStrictEqual} instead. 322 * 323 * Tests shallow, coercive inequality with the [Abstract Equality Comparison](https://tc39.github.io/ecma262/#sec-abstract-equality-comparison)(`!=` ). `NaN` is special handled and treated as 324 * being identical in case both 325 * sides are `NaN`. 326 * 327 * ```js 328 * import assert from 'assert'; 329 * 330 * assert.notEqual(1, 2); 331 * // OK 332 * 333 * assert.notEqual(1, 1); 334 * // AssertionError: 1 != 1 335 * 336 * assert.notEqual(1, '1'); 337 * // AssertionError: 1 != '1' 338 * ``` 339 * 340 * 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 341 * message is assigned. If the `message`parameter is an instance of an `Error` then it will be thrown instead of the`AssertionError`. 342 * @since v0.1.21 343 */ 344 function notEqual(actual: unknown, expected: unknown, message?: string | Error): void; 345 /** 346 * **Strict assertion mode** 347 * 348 * An alias of {@link deepStrictEqual}. 349 * 350 * **Legacy assertion mode** 351 * 352 * > Stability: 3 - Legacy: Use {@link deepStrictEqual} instead. 353 * 354 * Tests for deep equality between the `actual` and `expected` parameters. Consider 355 * using {@link deepStrictEqual} instead. {@link deepEqual} can have 356 * surprising results. 357 * 358 * _Deep equality_ means that the enumerable "own" properties of child objects 359 * are also recursively evaluated by the following rules. 360 * @since v0.1.21 361 */ 362 function deepEqual(actual: unknown, expected: unknown, message?: string | Error): void; 363 /** 364 * **Strict assertion mode** 365 * 366 * An alias of {@link notDeepStrictEqual}. 367 * 368 * **Legacy assertion mode** 369 * 370 * > Stability: 3 - Legacy: Use {@link notDeepStrictEqual} instead. 371 * 372 * Tests for any deep inequality. Opposite of {@link deepEqual}. 373 * 374 * ```js 375 * import assert from 'assert'; 376 * 377 * const obj1 = { 378 * a: { 379 * b: 1 380 * } 381 * }; 382 * const obj2 = { 383 * a: { 384 * b: 2 385 * } 386 * }; 387 * const obj3 = { 388 * a: { 389 * b: 1 390 * } 391 * }; 392 * const obj4 = Object.create(obj1); 393 * 394 * assert.notDeepEqual(obj1, obj1); 395 * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } 396 * 397 * assert.notDeepEqual(obj1, obj2); 398 * // OK 399 * 400 * assert.notDeepEqual(obj1, obj3); 401 * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } 402 * 403 * assert.notDeepEqual(obj1, obj4); 404 * // OK 405 * ``` 406 * 407 * 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 408 * error message is assigned. If the`message` parameter is an instance of an `Error` then it will be thrown 409 * instead of the `AssertionError`. 410 * @since v0.1.21 411 */ 412 function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void; 413 /** 414 * Tests strict equality between the `actual` and `expected` parameters as 415 * determined by the [SameValue Comparison](https://tc39.github.io/ecma262/#sec-samevalue). 416 * 417 * ```js 418 * import assert from 'assert/strict'; 419 * 420 * assert.strictEqual(1, 2); 421 * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal: 422 * // 423 * // 1 !== 2 424 * 425 * assert.strictEqual(1, 1); 426 * // OK 427 * 428 * assert.strictEqual('Hello foobar', 'Hello World!'); 429 * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal: 430 * // + actual - expected 431 * // 432 * // + 'Hello foobar' 433 * // - 'Hello World!' 434 * // ^ 435 * 436 * const apples = 1; 437 * const oranges = 2; 438 * assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`); 439 * // AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2 440 * 441 * assert.strictEqual(1, '1', new TypeError('Inputs are not identical')); 442 * // TypeError: Inputs are not identical 443 * ``` 444 * 445 * 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 446 * default error message is assigned. If the`message` parameter is an instance of an `Error` then it will be thrown 447 * instead of the `AssertionError`. 448 * @since v0.1.21 449 */ 450 function strictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T; 451 /** 452 * Tests strict inequality between the `actual` and `expected` parameters as 453 * determined by the [SameValue Comparison](https://tc39.github.io/ecma262/#sec-samevalue). 454 * 455 * ```js 456 * import assert from 'assert/strict'; 457 * 458 * assert.notStrictEqual(1, 2); 459 * // OK 460 * 461 * assert.notStrictEqual(1, 1); 462 * // AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to: 463 * // 464 * // 1 465 * 466 * assert.notStrictEqual(1, '1'); 467 * // OK 468 * ``` 469 * 470 * 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 471 * default error message is assigned. If the`message` parameter is an instance of an `Error` then it will be thrown 472 * instead of the `AssertionError`. 473 * @since v0.1.21 474 */ 475 function notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void; 476 /** 477 * Tests for deep equality between the `actual` and `expected` parameters. 478 * "Deep" equality means that the enumerable "own" properties of child objects 479 * are recursively evaluated also by the following rules. 480 * @since v1.2.0 481 */ 482 function deepStrictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T; 483 /** 484 * Tests for deep strict inequality. Opposite of {@link deepStrictEqual}. 485 * 486 * ```js 487 * import assert from 'assert/strict'; 488 * 489 * assert.notDeepStrictEqual({ a: 1 }, { a: '1' }); 490 * // OK 491 * ``` 492 * 493 * If the values are deeply and strictly equal, an `AssertionError` is thrown 494 * with a `message` property set equal to the value of the `message` parameter. If 495 * the `message` parameter is undefined, a default error message is assigned. If 496 * the `message` parameter is an instance of an `Error` then it will be thrown 497 * instead of the `AssertionError`. 498 * @since v1.2.0 499 */ 500 function notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void; 501 /** 502 * Expects the function `fn` to throw an error. 503 * 504 * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), 505 * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), a validation function, 506 * a validation object where each property will be tested for strict deep equality, 507 * or an instance of error where each property will be tested for strict deep 508 * equality including the non-enumerable `message` and `name` properties. When 509 * using an object, it is also possible to use a regular expression, when 510 * validating against a string property. See below for examples. 511 * 512 * If specified, `message` will be appended to the message provided by the`AssertionError` if the `fn` call fails to throw or in case the error validation 513 * fails. 514 * 515 * Custom validation object/error instance: 516 * 517 * ```js 518 * import assert from 'assert/strict'; 519 * 520 * const err = new TypeError('Wrong value'); 521 * err.code = 404; 522 * err.foo = 'bar'; 523 * err.info = { 524 * nested: true, 525 * baz: 'text' 526 * }; 527 * err.reg = /abc/i; 528 * 529 * assert.throws( 530 * () => { 531 * throw err; 532 * }, 533 * { 534 * name: 'TypeError', 535 * message: 'Wrong value', 536 * info: { 537 * nested: true, 538 * baz: 'text' 539 * } 540 * // Only properties on the validation object will be tested for. 541 * // Using nested objects requires all properties to be present. Otherwise 542 * // the validation is going to fail. 543 * } 544 * ); 545 * 546 * // Using regular expressions to validate error properties: 547 * throws( 548 * () => { 549 * throw err; 550 * }, 551 * { 552 * // The `name` and `message` properties are strings and using regular 553 * // expressions on those will match against the string. If they fail, an 554 * // error is thrown. 555 * name: /^TypeError$/, 556 * message: /Wrong/, 557 * foo: 'bar', 558 * info: { 559 * nested: true, 560 * // It is not possible to use regular expressions for nested properties! 561 * baz: 'text' 562 * }, 563 * // The `reg` property contains a regular expression and only if the 564 * // validation object contains an identical regular expression, it is going 565 * // to pass. 566 * reg: /abc/i 567 * } 568 * ); 569 * 570 * // Fails due to the different `message` and `name` properties: 571 * throws( 572 * () => { 573 * const otherErr = new Error('Not found'); 574 * // Copy all enumerable properties from `err` to `otherErr`. 575 * for (const [key, value] of Object.entries(err)) { 576 * otherErr[key] = value; 577 * } 578 * throw otherErr; 579 * }, 580 * // The error's `message` and `name` properties will also be checked when using 581 * // an error as validation object. 582 * err 583 * ); 584 * ``` 585 * 586 * Validate instanceof using constructor: 587 * 588 * ```js 589 * import assert from 'assert/strict'; 590 * 591 * assert.throws( 592 * () => { 593 * throw new Error('Wrong value'); 594 * }, 595 * Error 596 * ); 597 * ``` 598 * 599 * Validate error message using [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions): 600 * 601 * Using a regular expression runs `.toString` on the error object, and will 602 * therefore also include the error name. 603 * 604 * ```js 605 * import assert from 'assert/strict'; 606 * 607 * assert.throws( 608 * () => { 609 * throw new Error('Wrong value'); 610 * }, 611 * /^Error: Wrong value$/ 612 * ); 613 * ``` 614 * 615 * Custom error validation: 616 * 617 * The function must return `true` to indicate all internal validations passed. 618 * It will otherwise fail with an `AssertionError`. 619 * 620 * ```js 621 * import assert from 'assert/strict'; 622 * 623 * assert.throws( 624 * () => { 625 * throw new Error('Wrong value'); 626 * }, 627 * (err) => { 628 * assert(err instanceof Error); 629 * assert(/value/.test(err)); 630 * // Avoid returning anything from validation functions besides `true`. 631 * // Otherwise, it's not clear what part of the validation failed. Instead, 632 * // throw an error about the specific validation that failed (as done in this 633 * // example) and add as much helpful debugging information to that error as 634 * // possible. 635 * return true; 636 * }, 637 * 'unexpected error' 638 * ); 639 * ``` 640 * 641 * `error` cannot be a string. If a string is provided as the second 642 * argument, then `error` is assumed to be omitted and the string will be used for`message` instead. This can lead to easy-to-miss mistakes. Using the same 643 * message as the thrown error message is going to result in an`ERR_AMBIGUOUS_ARGUMENT` error. Please read the example below carefully if using 644 * a string as the second argument gets considered: 645 * 646 * ```js 647 * import assert from 'assert/strict'; 648 * 649 * function throwingFirst() { 650 * throw new Error('First'); 651 * } 652 * 653 * function throwingSecond() { 654 * throw new Error('Second'); 655 * } 656 * 657 * function notThrowing() {} 658 * 659 * // The second argument is a string and the input function threw an Error. 660 * // The first case will not throw as it does not match for the error message 661 * // thrown by the input function! 662 * assert.throws(throwingFirst, 'Second'); 663 * // In the next example the message has no benefit over the message from the 664 * // error and since it is not clear if the user intended to actually match 665 * // against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error. 666 * assert.throws(throwingSecond, 'Second'); 667 * // TypeError [ERR_AMBIGUOUS_ARGUMENT] 668 * 669 * // The string is only used (as message) in case the function does not throw: 670 * assert.throws(notThrowing, 'Second'); 671 * // AssertionError [ERR_ASSERTION]: Missing expected exception: Second 672 * 673 * // If it was intended to match for the error message do this instead: 674 * // It does not throw because the error messages match. 675 * assert.throws(throwingSecond, /Second$/); 676 * 677 * // If the error message does not match, an AssertionError is thrown. 678 * assert.throws(throwingFirst, /Second$/); 679 * // AssertionError [ERR_ASSERTION] 680 * ``` 681 * 682 * Due to the confusing error-prone notation, avoid a string as the second 683 * argument. 684 * @since v0.1.21 685 */ 686 function throws(block: () => unknown, message?: string | Error): void; 687 function throws(block: () => unknown, error: AssertPredicate, message?: string | Error): void; 688 /** 689 * Asserts that the function `fn` does not throw an error. 690 * 691 * Using `assert.doesNotThrow()` is actually not useful because there 692 * is no benefit in catching an error and then rethrowing it. Instead, consider 693 * adding a comment next to the specific code path that should not throw and keep 694 * error messages as expressive as possible. 695 * 696 * When `assert.doesNotThrow()` is called, it will immediately call the `fn`function. 697 * 698 * 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 699 * different type, or if the `error` parameter is undefined, the error is 700 * propagated back to the caller. 701 * 702 * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), 703 * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation 704 * function. See {@link throws} for more details. 705 * 706 * The following, for instance, will throw the `TypeError` because there is no 707 * matching error type in the assertion: 708 * 709 * ```js 710 * import assert from 'assert/strict'; 711 * 712 * assert.doesNotThrow( 713 * () => { 714 * throw new TypeError('Wrong value'); 715 * }, 716 * SyntaxError 717 * ); 718 * ``` 719 * 720 * However, the following will result in an `AssertionError` with the message 721 * 'Got unwanted exception...': 722 * 723 * ```js 724 * import assert from 'assert/strict'; 725 * 726 * assert.doesNotThrow( 727 * () => { 728 * throw new TypeError('Wrong value'); 729 * }, 730 * TypeError 731 * ); 732 * ``` 733 * 734 * 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: 735 * 736 * ```js 737 * import assert from 'assert/strict'; 738 * 739 * assert.doesNotThrow( 740 * () => { 741 * throw new TypeError('Wrong value'); 742 * }, 743 * /Wrong value/, 744 * 'Whoops' 745 * ); 746 * // Throws: AssertionError: Got unwanted exception: Whoops 747 * ``` 748 * @since v0.1.21 749 */ 750 function doesNotThrow(block: () => unknown, message?: string | Error): void; 751 function doesNotThrow(block: () => unknown, error: AssertPredicate, message?: string | Error): void; 752 /** 753 * Throws `value` if `value` is not `undefined` or `null`. This is useful when 754 * testing the `error` argument in callbacks. The stack trace contains all frames 755 * from the error passed to `ifError()` including the potential new frames for`ifError()` itself. 756 * 757 * ```js 758 * import assert from 'assert/strict'; 759 * 760 * assert.ifError(null); 761 * // OK 762 * assert.ifError(0); 763 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0 764 * assert.ifError('error'); 765 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error' 766 * assert.ifError(new Error()); 767 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error 768 * 769 * // Create some random error frames. 770 * let err; 771 * (function errorFrame() { 772 * err = new Error('test error'); 773 * })(); 774 * 775 * (function ifErrorFrame() { 776 * assert.ifError(err); 777 * })(); 778 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error 779 * // at ifErrorFrame 780 * // at errorFrame 781 * ``` 782 * @since v0.1.97 783 */ 784 function ifError(value: unknown): asserts value is null | undefined; 785 /** 786 * Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately 787 * calls the function and awaits the returned promise to complete. It will then 788 * check that the promise is rejected. 789 * 790 * If `asyncFn` is a function and it throws an error synchronously,`assert.rejects()` will return a rejected `Promise` with that error. If the 791 * function does not return a promise, `assert.rejects()` will return a rejected`Promise` with an `ERR_INVALID_RETURN_VALUE` error. In both cases the error 792 * handler is skipped. 793 * 794 * Besides the async nature to await the completion behaves identically to {@link throws}. 795 * 796 * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), 797 * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), a validation function, 798 * an object where each property will be tested for, or an instance of error where 799 * each property will be tested for including the non-enumerable `message` and `name` properties. 800 * 801 * If specified, `message` will be the message provided by the `AssertionError` if the `asyncFn` fails to reject. 802 * 803 * ```js 804 * import assert from 'assert/strict'; 805 * 806 * await assert.rejects( 807 * async () => { 808 * throw new TypeError('Wrong value'); 809 * }, 810 * { 811 * name: 'TypeError', 812 * message: 'Wrong value' 813 * } 814 * ); 815 * ``` 816 * 817 * ```js 818 * import assert from 'assert/strict'; 819 * 820 * await assert.rejects( 821 * async () => { 822 * throw new TypeError('Wrong value'); 823 * }, 824 * (err) => { 825 * assert.strictEqual(err.name, 'TypeError'); 826 * assert.strictEqual(err.message, 'Wrong value'); 827 * return true; 828 * } 829 * ); 830 * ``` 831 * 832 * ```js 833 * import assert from 'assert/strict'; 834 * 835 * assert.rejects( 836 * Promise.reject(new Error('Wrong value')), 837 * Error 838 * ).then(() => { 839 * // ... 840 * }); 841 * ``` 842 * 843 * `error` cannot be a string. If a string is provided as the second 844 * argument, then `error` is assumed to be omitted and the string will be used for`message` instead. This can lead to easy-to-miss mistakes. Please read the 845 * example in {@link throws} carefully if using a string as the second 846 * argument gets considered. 847 * @since v10.0.0 848 */ 849 function rejects(block: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>; 850 function rejects( 851 block: (() => Promise<unknown>) | Promise<unknown>, 852 error: AssertPredicate, 853 message?: string | Error, 854 ): Promise<void>; 855 /** 856 * Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately 857 * calls the function and awaits the returned promise to complete. It will then 858 * check that the promise is not rejected. 859 * 860 * If `asyncFn` is a function and it throws an error synchronously,`assert.doesNotReject()` will return a rejected `Promise` with that error. If 861 * the function does not return a promise, `assert.doesNotReject()` will return a 862 * rejected `Promise` with an `ERR_INVALID_RETURN_VALUE` error. In both cases 863 * the error handler is skipped. 864 * 865 * Using `assert.doesNotReject()` is actually not useful because there is little 866 * benefit in catching a rejection and then rejecting it again. Instead, consider 867 * adding a comment next to the specific code path that should not reject and keep 868 * error messages as expressive as possible. 869 * 870 * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), 871 * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation 872 * function. See {@link throws} for more details. 873 * 874 * Besides the async nature to await the completion behaves identically to {@link doesNotThrow}. 875 * 876 * ```js 877 * import assert from 'assert/strict'; 878 * 879 * await assert.doesNotReject( 880 * async () => { 881 * throw new TypeError('Wrong value'); 882 * }, 883 * SyntaxError 884 * ); 885 * ``` 886 * 887 * ```js 888 * import assert from 'assert/strict'; 889 * 890 * assert.doesNotReject(Promise.reject(new TypeError('Wrong value'))) 891 * .then(() => { 892 * // ... 893 * }); 894 * ``` 895 * @since v10.0.0 896 */ 897 function doesNotReject( 898 block: (() => Promise<unknown>) | Promise<unknown>, 899 message?: string | Error, 900 ): Promise<void>; 901 function doesNotReject( 902 block: (() => Promise<unknown>) | Promise<unknown>, 903 error: AssertPredicate, 904 message?: string | Error, 905 ): Promise<void>; 906 /** 907 * Expects the `string` input to match the regular expression. 908 * 909 * ```js 910 * import assert from 'assert/strict'; 911 * 912 * assert.match('I will fail', /pass/); 913 * // AssertionError [ERR_ASSERTION]: The input did not match the regular ... 914 * 915 * assert.match(123, /pass/); 916 * // AssertionError [ERR_ASSERTION]: The "string" argument must be of type string. 917 * 918 * assert.match('I will pass', /pass/); 919 * // OK 920 * ``` 921 * 922 * If the values do not match, or if the `string` argument is of another type than`string`, an `AssertionError` is thrown with a `message` property set equal 923 * to the value of the `message` parameter. If the `message` parameter is 924 * undefined, a default error message is assigned. If the `message` parameter is an 925 * instance of an `Error` then it will be thrown instead of the `AssertionError`. 926 * @since v13.6.0, v12.16.0 927 */ 928 function match(value: string, regExp: RegExp, message?: string | Error): void; 929 /** 930 * Expects the `string` input not to match the regular expression. 931 * 932 * ```js 933 * import assert from 'assert/strict'; 934 * 935 * assert.doesNotMatch('I will fail', /fail/); 936 * // AssertionError [ERR_ASSERTION]: The input was expected to not match the ... 937 * 938 * assert.doesNotMatch(123, /pass/); 939 * // AssertionError [ERR_ASSERTION]: The "string" argument must be of type string. 940 * 941 * assert.doesNotMatch('I will pass', /different/); 942 * // OK 943 * ``` 944 * 945 * If the values do match, or if the `string` argument is of another type than`string`, an `AssertionError` is thrown with a `message` property set equal 946 * to the value of the `message` parameter. If the `message` parameter is 947 * undefined, a default error message is assigned. If the `message` parameter is an 948 * instance of an `Error` then it will be thrown instead of the `AssertionError`. 949 * @since v13.6.0, v12.16.0 950 */ 951 function doesNotMatch(value: string, regExp: RegExp, message?: string | Error): void; 952 const strict: 953 & Omit< 954 typeof assert, 955 | "equal" 956 | "notEqual" 957 | "deepEqual" 958 | "notDeepEqual" 959 | "ok" 960 | "strictEqual" 961 | "deepStrictEqual" 962 | "ifError" 963 | "strict" 964 > 965 & { 966 (value: unknown, message?: string | Error): asserts value; 967 equal: typeof strictEqual; 968 notEqual: typeof notStrictEqual; 969 deepEqual: typeof deepStrictEqual; 970 notDeepEqual: typeof notDeepStrictEqual; 971 // Mapped types and assertion functions are incompatible? 972 // TS2775: Assertions require every name in the call target 973 // to be declared with an explicit type annotation. 974 ok: typeof ok; 975 strictEqual: typeof strictEqual; 976 deepStrictEqual: typeof deepStrictEqual; 977 ifError: typeof ifError; 978 strict: typeof strict; 979 }; 980 } 981 export = assert; 982 } 983 declare module "node:assert" { 984 import assert = require("assert"); 985 export = assert; 986 }