UNPKG

55.4 kBTypeScriptView Raw
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.4.2/lib/assert.js)
5 */
6declare 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 // tslint:disable-next-line:ban-types
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 *
62 * ```js
63 * const assert = require('assert');
64 *
65 * // Creates call tracker.
66 * const tracker = new assert.CallTracker();
67 *
68 * function func() {}
69 *
70 * // Returns a function that wraps func() that must be called exact times
71 * // before tracker.verify().
72 * const callsfunc = tracker.calls(func);
73 * ```
74 * @since v14.2.0, v12.19.0
75 * @param [fn='A no-op function']
76 * @param [exact=1]
77 * @return that wraps `fn`.
78 */
79 calls(exact?: number): () => void;
80 calls<Func extends (...args: any[]) => any>(fn?: Func, exact?: number): Func;
81 /**
82 * The arrays contains information about the expected and actual number of calls of
83 * the functions that have not been called the expected number of times.
84 *
85 * ```js
86 * import assert from 'assert';
87 *
88 * // Creates call tracker.
89 * const tracker = new assert.CallTracker();
90 *
91 * function func() {}
92 *
93 * function foo() {}
94 *
95 * // Returns a function that wraps func() that must be called exact times
96 * // before tracker.verify().
97 * const callsfunc = tracker.calls(func, 2);
98 *
99 * // Returns an array containing information on callsfunc()
100 * tracker.report();
101 * // [
102 * // {
103 * // message: 'Expected the func function to be executed 2 time(s) but was
104 * // executed 0 time(s).',
105 * // actual: 0,
106 * // expected: 2,
107 * // operator: 'func',
108 * // stack: stack trace
109 * // }
110 * // ]
111 * ```
112 *
113 * ```js
114 * const assert = require('assert');
115 *
116 * // Creates call tracker.
117 * const tracker = new assert.CallTracker();
118 *
119 * function func() {}
120 *
121 * function foo() {}
122 *
123 * // Returns a function that wraps func() that must be called exact times
124 * // before tracker.verify().
125 * const callsfunc = tracker.calls(func, 2);
126 *
127 * // Returns an array containing information on callsfunc()
128 * tracker.report();
129 * // [
130 * // {
131 * // message: 'Expected the func function to be executed 2 time(s) but was
132 * // executed 0 time(s).',
133 * // actual: 0,
134 * // expected: 2,
135 * // operator: 'func',
136 * // stack: stack trace
137 * // }
138 * // ]
139 * ```
140 * @since v14.2.0, v12.19.0
141 * @return of objects containing information about the wrapper functions returned by `calls`.
142 */
143 report(): CallTrackerReportInformation[];
144 /**
145 * Iterates through the list of functions passed to `tracker.calls()` and will throw an error for functions that
146 * have not been called the expected number of times.
147 *
148 * ```js
149 * import assert from 'assert';
150 *
151 * // Creates call tracker.
152 * const tracker = new assert.CallTracker();
153 *
154 * function func() {}
155 *
156 * // Returns a function that wraps func() that must be called exact times
157 * // before tracker.verify().
158 * const callsfunc = tracker.calls(func, 2);
159 *
160 * callsfunc();
161 *
162 * // Will throw an error since callsfunc() was only called once.
163 * tracker.verify();
164 * ```
165 *
166 * ```js
167 * const assert = require('assert');
168 *
169 * // Creates call tracker.
170 * const tracker = new assert.CallTracker();
171 *
172 * function func() {}
173 *
174 * // Returns a function that wraps func() that must be called exact times
175 * // before tracker.verify().
176 * const callsfunc = tracker.calls(func, 2);
177 *
178 * callsfunc();
179 *
180 * // Will throw an error since callsfunc() was only called once.
181 * tracker.verify();
182 * ```
183 * @since v14.2.0, v12.19.0
184 */
185 verify(): void;
186 }
187 interface CallTrackerReportInformation {
188 message: string;
189 /** The actual number of times the function was called. */
190 actual: number;
191 /** The number of times the function was expected to be called. */
192 expected: number;
193 /** The name of the function that is wrapped. */
194 operator: string;
195 /** A stack trace of the function. */
196 stack: object;
197 }
198 type AssertPredicate = RegExp | (new () => object) | ((thrown: unknown) => boolean) | object | Error;
199 /**
200 * Throws an `AssertionError` with the provided error message or a default
201 * error message. If the `message` parameter is an instance of an `Error` then
202 * it will be thrown instead of the `AssertionError`.
203 *
204 * ```js
205 * import assert from 'assert/strict';
206 *
207 * assert.fail();
208 * // AssertionError [ERR_ASSERTION]: Failed
209 *
210 * assert.fail('boom');
211 * // AssertionError [ERR_ASSERTION]: boom
212 *
213 * assert.fail(new TypeError('need array'));
214 * // TypeError: need array
215 * ```
216 *
217 * ```js
218 * const assert = require('assert/strict');
219 *
220 * assert.fail();
221 * // AssertionError [ERR_ASSERTION]: Failed
222 *
223 * assert.fail('boom');
224 * // AssertionError [ERR_ASSERTION]: boom
225 *
226 * assert.fail(new TypeError('need array'));
227 * // TypeError: need array
228 * ```
229 *
230 * Using `assert.fail()` with more than two arguments is possible but deprecated.
231 * See below for further details.
232 * @since v0.1.21
233 * @param [message='Failed']
234 */
235 function fail(message?: string | Error): never;
236 /** @deprecated since v10.0.0 - use fail([message]) or other assert functions instead. */
237 function fail(
238 actual: unknown,
239 expected: unknown,
240 message?: string | Error,
241 operator?: string,
242 // tslint:disable-next-line:ban-types
243 stackStartFn?: Function
244 ): never;
245 /**
246 * Tests if `value` is truthy. It is equivalent to`assert.equal(!!value, true, message)`.
247 *
248 * 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
249 * error message is assigned. If the `message`parameter is an instance of an `Error` then it will be thrown instead of the`AssertionError`.
250 * If no arguments are passed in at all `message` will be set to the string:`` 'No value argument passed to `assert.ok()`' ``.
251 *
252 * Be aware that in the `repl` the error message will be different to the one
253 * thrown in a file! See below for further details.
254 *
255 * ```js
256 * import assert from 'assert/strict';
257 *
258 * assert.ok(true);
259 * // OK
260 * assert.ok(1);
261 * // OK
262 *
263 * assert.ok();
264 * // AssertionError: No value argument passed to `assert.ok()`
265 *
266 * assert.ok(false, 'it\'s false');
267 * // AssertionError: it's false
268 *
269 * // In the repl:
270 * assert.ok(typeof 123 === 'string');
271 * // AssertionError: false == true
272 *
273 * // In a file (e.g. test.js):
274 * assert.ok(typeof 123 === 'string');
275 * // AssertionError: The expression evaluated to a falsy value:
276 * //
277 * // assert.ok(typeof 123 === 'string')
278 *
279 * assert.ok(false);
280 * // AssertionError: The expression evaluated to a falsy value:
281 * //
282 * // assert.ok(false)
283 *
284 * assert.ok(0);
285 * // AssertionError: The expression evaluated to a falsy value:
286 * //
287 * // assert.ok(0)
288 * ```
289 *
290 * ```js
291 * const assert = require('assert/strict');
292 *
293 * assert.ok(true);
294 * // OK
295 * assert.ok(1);
296 * // OK
297 *
298 * assert.ok();
299 * // AssertionError: No value argument passed to `assert.ok()`
300 *
301 * assert.ok(false, 'it\'s false');
302 * // AssertionError: it's false
303 *
304 * // In the repl:
305 * assert.ok(typeof 123 === 'string');
306 * // AssertionError: false == true
307 *
308 * // In a file (e.g. test.js):
309 * assert.ok(typeof 123 === 'string');
310 * // AssertionError: The expression evaluated to a falsy value:
311 * //
312 * // assert.ok(typeof 123 === 'string')
313 *
314 * assert.ok(false);
315 * // AssertionError: The expression evaluated to a falsy value:
316 * //
317 * // assert.ok(false)
318 *
319 * assert.ok(0);
320 * // AssertionError: The expression evaluated to a falsy value:
321 * //
322 * // assert.ok(0)
323 * ```
324 *
325 * ```js
326 * import assert from 'assert/strict';
327 *
328 * // Using `assert()` works the same:
329 * assert(0);
330 * // AssertionError: The expression evaluated to a falsy value:
331 * //
332 * // assert(0)
333 * ```
334 *
335 * ```js
336 * const assert = require('assert');
337 *
338 * // Using `assert()` works the same:
339 * assert(0);
340 * // AssertionError: The expression evaluated to a falsy value:
341 * //
342 * // assert(0)
343 * ```
344 * @since v0.1.21
345 */
346 function ok(value: unknown, message?: string | Error): asserts value;
347 /**
348 * **Strict assertion mode**
349 *
350 * An alias of {@link strictEqual}.
351 *
352 * **Legacy assertion mode**
353 *
354 * > Stability: 3 - Legacy: Use {@link strictEqual} instead.
355 *
356 * Tests shallow, coercive equality between the `actual` and `expected` parameters
357 * using the [Abstract Equality Comparison](https://tc39.github.io/ecma262/#sec-abstract-equality-comparison) ( `==` ). `NaN` is special handled
358 * and treated as being identical in case both sides are `NaN`.
359 *
360 * ```js
361 * import assert from 'assert';
362 *
363 * assert.equal(1, 1);
364 * // OK, 1 == 1
365 * assert.equal(1, '1');
366 * // OK, 1 == '1'
367 * assert.equal(NaN, NaN);
368 * // OK
369 *
370 * assert.equal(1, 2);
371 * // AssertionError: 1 == 2
372 * assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
373 * // AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
374 * ```
375 *
376 * ```js
377 * const assert = require('assert');
378 *
379 * assert.equal(1, 1);
380 * // OK, 1 == 1
381 * assert.equal(1, '1');
382 * // OK, 1 == '1'
383 * assert.equal(NaN, NaN);
384 * // OK
385 *
386 * assert.equal(1, 2);
387 * // AssertionError: 1 == 2
388 * assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
389 * // AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
390 * ```
391 *
392 * 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
393 * error message is assigned. If the `message`parameter is an instance of an `Error` then it will be thrown instead of the`AssertionError`.
394 * @since v0.1.21
395 */
396 function equal(actual: unknown, expected: unknown, message?: string | Error): void;
397 /**
398 * **Strict assertion mode**
399 *
400 * An alias of {@link notStrictEqual}.
401 *
402 * **Legacy assertion mode**
403 *
404 * > Stability: 3 - Legacy: Use {@link notStrictEqual} instead.
405 *
406 * 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
407 * being identical in case both
408 * sides are `NaN`.
409 *
410 * ```js
411 * import assert from 'assert';
412 *
413 * assert.notEqual(1, 2);
414 * // OK
415 *
416 * assert.notEqual(1, 1);
417 * // AssertionError: 1 != 1
418 *
419 * assert.notEqual(1, '1');
420 * // AssertionError: 1 != '1'
421 * ```
422 *
423 * ```js
424 * const assert = require('assert');
425 *
426 * assert.notEqual(1, 2);
427 * // OK
428 *
429 * assert.notEqual(1, 1);
430 * // AssertionError: 1 != 1
431 *
432 * assert.notEqual(1, '1');
433 * // AssertionError: 1 != '1'
434 * ```
435 *
436 * 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
437 * message is assigned. If the `message`parameter is an instance of an `Error` then it will be thrown instead of the`AssertionError`.
438 * @since v0.1.21
439 */
440 function notEqual(actual: unknown, expected: unknown, message?: string | Error): void;
441 /**
442 * **Strict assertion mode**
443 *
444 * An alias of {@link deepStrictEqual}.
445 *
446 * **Legacy assertion mode**
447 *
448 * > Stability: 3 - Legacy: Use {@link deepStrictEqual} instead.
449 *
450 * Tests for deep equality between the `actual` and `expected` parameters. Consider
451 * using {@link deepStrictEqual} instead. {@link deepEqual} can have
452 * surprising results.
453 *
454 * _Deep equality_ means that the enumerable "own" properties of child objects
455 * are also recursively evaluated by the following rules.
456 * @since v0.1.21
457 */
458 function deepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
459 /**
460 * **Strict assertion mode**
461 *
462 * An alias of {@link notDeepStrictEqual}.
463 *
464 * **Legacy assertion mode**
465 *
466 * > Stability: 3 - Legacy: Use {@link notDeepStrictEqual} instead.
467 *
468 * Tests for any deep inequality. Opposite of {@link deepEqual}.
469 *
470 * ```js
471 * import assert from 'assert';
472 *
473 * const obj1 = {
474 * a: {
475 * b: 1
476 * }
477 * };
478 * const obj2 = {
479 * a: {
480 * b: 2
481 * }
482 * };
483 * const obj3 = {
484 * a: {
485 * b: 1
486 * }
487 * };
488 * const obj4 = Object.create(obj1);
489 *
490 * assert.notDeepEqual(obj1, obj1);
491 * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
492 *
493 * assert.notDeepEqual(obj1, obj2);
494 * // OK
495 *
496 * assert.notDeepEqual(obj1, obj3);
497 * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
498 *
499 * assert.notDeepEqual(obj1, obj4);
500 * // OK
501 * ```
502 *
503 * ```js
504 * const assert = require('assert');
505 *
506 * const obj1 = {
507 * a: {
508 * b: 1
509 * }
510 * };
511 * const obj2 = {
512 * a: {
513 * b: 2
514 * }
515 * };
516 * const obj3 = {
517 * a: {
518 * b: 1
519 * }
520 * };
521 * const obj4 = Object.create(obj1);
522 *
523 * assert.notDeepEqual(obj1, obj1);
524 * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
525 *
526 * assert.notDeepEqual(obj1, obj2);
527 * // OK
528 *
529 * assert.notDeepEqual(obj1, obj3);
530 * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
531 *
532 * assert.notDeepEqual(obj1, obj4);
533 * // OK
534 * ```
535 *
536 * 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
537 * error message is assigned. If the`message` parameter is an instance of an `Error` then it will be thrown
538 * instead of the `AssertionError`.
539 * @since v0.1.21
540 */
541 function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
542 /**
543 * Tests strict equality between the `actual` and `expected` parameters as
544 * determined by the [SameValue Comparison](https://tc39.github.io/ecma262/#sec-samevalue).
545 *
546 * ```js
547 * import assert from 'assert/strict';
548 *
549 * assert.strictEqual(1, 2);
550 * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
551 * //
552 * // 1 !== 2
553 *
554 * assert.strictEqual(1, 1);
555 * // OK
556 *
557 * assert.strictEqual('Hello foobar', 'Hello World!');
558 * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
559 * // + actual - expected
560 * //
561 * // + 'Hello foobar'
562 * // - 'Hello World!'
563 * // ^
564 *
565 * const apples = 1;
566 * const oranges = 2;
567 * assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
568 * // AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
569 *
570 * assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
571 * // TypeError: Inputs are not identical
572 * ```
573 *
574 * ```js
575 * const assert = require('assert/strict');
576 *
577 * assert.strictEqual(1, 2);
578 * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
579 * //
580 * // 1 !== 2
581 *
582 * assert.strictEqual(1, 1);
583 * // OK
584 *
585 * assert.strictEqual('Hello foobar', 'Hello World!');
586 * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
587 * // + actual - expected
588 * //
589 * // + 'Hello foobar'
590 * // - 'Hello World!'
591 * // ^
592 *
593 * const apples = 1;
594 * const oranges = 2;
595 * assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
596 * // AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
597 *
598 * assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
599 * // TypeError: Inputs are not identical
600 * ```
601 *
602 * 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
603 * default error message is assigned. If the`message` parameter is an instance of an `Error` then it will be thrown
604 * instead of the `AssertionError`.
605 * @since v0.1.21
606 */
607 function strictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
608 /**
609 * Tests strict inequality between the `actual` and `expected` parameters as
610 * determined by the [SameValue Comparison](https://tc39.github.io/ecma262/#sec-samevalue).
611 *
612 * ```js
613 * import assert from 'assert/strict';
614 *
615 * assert.notStrictEqual(1, 2);
616 * // OK
617 *
618 * assert.notStrictEqual(1, 1);
619 * // AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to:
620 * //
621 * // 1
622 *
623 * assert.notStrictEqual(1, '1');
624 * // OK
625 * ```
626 *
627 * ```js
628 * const assert = require('assert/strict');
629 *
630 * assert.notStrictEqual(1, 2);
631 * // OK
632 *
633 * assert.notStrictEqual(1, 1);
634 * // AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to:
635 * //
636 * // 1
637 *
638 * assert.notStrictEqual(1, '1');
639 * // OK
640 * ```
641 *
642 * 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
643 * default error message is assigned. If the`message` parameter is an instance of an `Error` then it will be thrown
644 * instead of the `AssertionError`.
645 * @since v0.1.21
646 */
647 function notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
648 /**
649 * Tests for deep equality between the `actual` and `expected` parameters.
650 * "Deep" equality means that the enumerable "own" properties of child objects
651 * are recursively evaluated also by the following rules.
652 * @since v1.2.0
653 */
654 function deepStrictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
655 /**
656 * Tests for deep strict inequality. Opposite of {@link deepStrictEqual}.
657 *
658 * ```js
659 * import assert from 'assert/strict';
660 *
661 * assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
662 * // OK
663 * ```
664 *
665 * ```js
666 * const assert = require('assert/strict');
667 *
668 * assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
669 * // OK
670 * ```
671 *
672 * If the values are deeply and strictly equal, an `AssertionError` is thrown
673 * with a `message` property set equal to the value of the `message` parameter. If
674 * the `message` parameter is undefined, a default error message is assigned. If
675 * the `message` parameter is an instance of an `Error` then it will be thrown
676 * instead of the `AssertionError`.
677 * @since v1.2.0
678 */
679 function notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
680 /**
681 * Expects the function `fn` to throw an error.
682 *
683 * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes),
684 * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), a validation function,
685 * a validation object where each property will be tested for strict deep equality,
686 * or an instance of error where each property will be tested for strict deep
687 * equality including the non-enumerable `message` and `name` properties. When
688 * using an object, it is also possible to use a regular expression, when
689 * validating against a string property. See below for examples.
690 *
691 * 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
692 * fails.
693 *
694 * Custom validation object/error instance:
695 *
696 * ```js
697 * import assert from 'assert/strict';
698 *
699 * const err = new TypeError('Wrong value');
700 * err.code = 404;
701 * err.foo = 'bar';
702 * err.info = {
703 * nested: true,
704 * baz: 'text'
705 * };
706 * err.reg = /abc/i;
707 *
708 * assert.throws(
709 * () => {
710 * throw err;
711 * },
712 * {
713 * name: 'TypeError',
714 * message: 'Wrong value',
715 * info: {
716 * nested: true,
717 * baz: 'text'
718 * }
719 * // Only properties on the validation object will be tested for.
720 * // Using nested objects requires all properties to be present. Otherwise
721 * // the validation is going to fail.
722 * }
723 * );
724 *
725 * // Using regular expressions to validate error properties:
726 * throws(
727 * () => {
728 * throw err;
729 * },
730 * {
731 * // The `name` and `message` properties are strings and using regular
732 * // expressions on those will match against the string. If they fail, an
733 * // error is thrown.
734 * name: /^TypeError$/,
735 * message: /Wrong/,
736 * foo: 'bar',
737 * info: {
738 * nested: true,
739 * // It is not possible to use regular expressions for nested properties!
740 * baz: 'text'
741 * },
742 * // The `reg` property contains a regular expression and only if the
743 * // validation object contains an identical regular expression, it is going
744 * // to pass.
745 * reg: /abc/i
746 * }
747 * );
748 *
749 * // Fails due to the different `message` and `name` properties:
750 * throws(
751 * () => {
752 * const otherErr = new Error('Not found');
753 * // Copy all enumerable properties from `err` to `otherErr`.
754 * for (const [key, value] of Object.entries(err)) {
755 * otherErr[key] = value;
756 * }
757 * throw otherErr;
758 * },
759 * // The error's `message` and `name` properties will also be checked when using
760 * // an error as validation object.
761 * err
762 * );
763 * ```
764 *
765 * ```js
766 * const assert = require('assert/strict');
767 *
768 * const err = new TypeError('Wrong value');
769 * err.code = 404;
770 * err.foo = 'bar';
771 * err.info = {
772 * nested: true,
773 * baz: 'text'
774 * };
775 * err.reg = /abc/i;
776 *
777 * assert.throws(
778 * () => {
779 * throw err;
780 * },
781 * {
782 * name: 'TypeError',
783 * message: 'Wrong value',
784 * info: {
785 * nested: true,
786 * baz: 'text'
787 * }
788 * // Only properties on the validation object will be tested for.
789 * // Using nested objects requires all properties to be present. Otherwise
790 * // the validation is going to fail.
791 * }
792 * );
793 *
794 * // Using regular expressions to validate error properties:
795 * throws(
796 * () => {
797 * throw err;
798 * },
799 * {
800 * // The `name` and `message` properties are strings and using regular
801 * // expressions on those will match against the string. If they fail, an
802 * // error is thrown.
803 * name: /^TypeError$/,
804 * message: /Wrong/,
805 * foo: 'bar',
806 * info: {
807 * nested: true,
808 * // It is not possible to use regular expressions for nested properties!
809 * baz: 'text'
810 * },
811 * // The `reg` property contains a regular expression and only if the
812 * // validation object contains an identical regular expression, it is going
813 * // to pass.
814 * reg: /abc/i
815 * }
816 * );
817 *
818 * // Fails due to the different `message` and `name` properties:
819 * throws(
820 * () => {
821 * const otherErr = new Error('Not found');
822 * // Copy all enumerable properties from `err` to `otherErr`.
823 * for (const [key, value] of Object.entries(err)) {
824 * otherErr[key] = value;
825 * }
826 * throw otherErr;
827 * },
828 * // The error's `message` and `name` properties will also be checked when using
829 * // an error as validation object.
830 * err
831 * );
832 * ```
833 *
834 * Validate instanceof using constructor:
835 *
836 * ```js
837 * import assert from 'assert/strict';
838 *
839 * assert.throws(
840 * () => {
841 * throw new Error('Wrong value');
842 * },
843 * Error
844 * );
845 * ```
846 *
847 * ```js
848 * const assert = require('assert/strict');
849 *
850 * assert.throws(
851 * () => {
852 * throw new Error('Wrong value');
853 * },
854 * Error
855 * );
856 * ```
857 *
858 * Validate error message using [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions):
859 *
860 * Using a regular expression runs `.toString` on the error object, and will
861 * therefore also include the error name.
862 *
863 * ```js
864 * import assert from 'assert/strict';
865 *
866 * assert.throws(
867 * () => {
868 * throw new Error('Wrong value');
869 * },
870 * /^Error: Wrong value$/
871 * );
872 * ```
873 *
874 * ```js
875 * const assert = require('assert/strict');
876 *
877 * assert.throws(
878 * () => {
879 * throw new Error('Wrong value');
880 * },
881 * /^Error: Wrong value$/
882 * );
883 * ```
884 *
885 * Custom error validation:
886 *
887 * The function must return `true` to indicate all internal validations passed.
888 * It will otherwise fail with an `AssertionError`.
889 *
890 * ```js
891 * import assert from 'assert/strict';
892 *
893 * assert.throws(
894 * () => {
895 * throw new Error('Wrong value');
896 * },
897 * (err) => {
898 * assert(err instanceof Error);
899 * assert(/value/.test(err));
900 * // Avoid returning anything from validation functions besides `true`.
901 * // Otherwise, it's not clear what part of the validation failed. Instead,
902 * // throw an error about the specific validation that failed (as done in this
903 * // example) and add as much helpful debugging information to that error as
904 * // possible.
905 * return true;
906 * },
907 * 'unexpected error'
908 * );
909 * ```
910 *
911 * ```js
912 * const assert = require('assert/strict');
913 *
914 * assert.throws(
915 * () => {
916 * throw new Error('Wrong value');
917 * },
918 * (err) => {
919 * assert(err instanceof Error);
920 * assert(/value/.test(err));
921 * // Avoid returning anything from validation functions besides `true`.
922 * // Otherwise, it's not clear what part of the validation failed. Instead,
923 * // throw an error about the specific validation that failed (as done in this
924 * // example) and add as much helpful debugging information to that error as
925 * // possible.
926 * return true;
927 * },
928 * 'unexpected error'
929 * );
930 * ```
931 *
932 * `error` cannot be a string. If a string is provided as the second
933 * 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
934 * message as the thrown error message is going to result in an`ERR_AMBIGUOUS_ARGUMENT` error. Please read the example below carefully if using
935 * a string as the second argument gets considered:
936 *
937 * ```js
938 * import assert from 'assert/strict';
939 *
940 * function throwingFirst() {
941 * throw new Error('First');
942 * }
943 *
944 * function throwingSecond() {
945 * throw new Error('Second');
946 * }
947 *
948 * function notThrowing() {}
949 *
950 * // The second argument is a string and the input function threw an Error.
951 * // The first case will not throw as it does not match for the error message
952 * // thrown by the input function!
953 * assert.throws(throwingFirst, 'Second');
954 * // In the next example the message has no benefit over the message from the
955 * // error and since it is not clear if the user intended to actually match
956 * // against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.
957 * assert.throws(throwingSecond, 'Second');
958 * // TypeError [ERR_AMBIGUOUS_ARGUMENT]
959 *
960 * // The string is only used (as message) in case the function does not throw:
961 * assert.throws(notThrowing, 'Second');
962 * // AssertionError [ERR_ASSERTION]: Missing expected exception: Second
963 *
964 * // If it was intended to match for the error message do this instead:
965 * // It does not throw because the error messages match.
966 * assert.throws(throwingSecond, /Second$/);
967 *
968 * // If the error message does not match, an AssertionError is thrown.
969 * assert.throws(throwingFirst, /Second$/);
970 * // AssertionError [ERR_ASSERTION]
971 * ```
972 *
973 * ```js
974 * const assert = require('assert/strict');
975 *
976 * function throwingFirst() {
977 * throw new Error('First');
978 * }
979 *
980 * function throwingSecond() {
981 * throw new Error('Second');
982 * }
983 *
984 * function notThrowing() {}
985 *
986 * // The second argument is a string and the input function threw an Error.
987 * // The first case will not throw as it does not match for the error message
988 * // thrown by the input function!
989 * assert.throws(throwingFirst, 'Second');
990 * // In the next example the message has no benefit over the message from the
991 * // error and since it is not clear if the user intended to actually match
992 * // against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.
993 * assert.throws(throwingSecond, 'Second');
994 * // TypeError [ERR_AMBIGUOUS_ARGUMENT]
995 *
996 * // The string is only used (as message) in case the function does not throw:
997 * assert.throws(notThrowing, 'Second');
998 * // AssertionError [ERR_ASSERTION]: Missing expected exception: Second
999 *
1000 * // If it was intended to match for the error message do this instead:
1001 * // It does not throw because the error messages match.
1002 * assert.throws(throwingSecond, /Second$/);
1003 *
1004 * // If the error message does not match, an AssertionError is thrown.
1005 * assert.throws(throwingFirst, /Second$/);
1006 * // AssertionError [ERR_ASSERTION]
1007 * ```
1008 *
1009 * Due to the confusing error-prone notation, avoid a string as the second
1010 * argument.
1011 * @since v0.1.21
1012 */
1013 function throws(block: () => unknown, message?: string | Error): void;
1014 function throws(block: () => unknown, error: AssertPredicate, message?: string | Error): void;
1015 /**
1016 * Asserts that the function `fn` does not throw an error.
1017 *
1018 * Using `assert.doesNotThrow()` is actually not useful because there
1019 * is no benefit in catching an error and then rethrowing it. Instead, consider
1020 * adding a comment next to the specific code path that should not throw and keep
1021 * error messages as expressive as possible.
1022 *
1023 * When `assert.doesNotThrow()` is called, it will immediately call the `fn`function.
1024 *
1025 * 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
1026 * different type, or if the `error` parameter is undefined, the error is
1027 * propagated back to the caller.
1028 *
1029 * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes),
1030 * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation
1031 * function. See {@link throws} for more details.
1032 *
1033 * The following, for instance, will throw the `TypeError` because there is no
1034 * matching error type in the assertion:
1035 *
1036 * ```js
1037 * import assert from 'assert/strict';
1038 *
1039 * assert.doesNotThrow(
1040 * () => {
1041 * throw new TypeError('Wrong value');
1042 * },
1043 * SyntaxError
1044 * );
1045 * ```
1046 *
1047 * ```js
1048 * const assert = require('assert/strict');
1049 *
1050 * assert.doesNotThrow(
1051 * () => {
1052 * throw new TypeError('Wrong value');
1053 * },
1054 * SyntaxError
1055 * );
1056 * ```
1057 *
1058 * However, the following will result in an `AssertionError` with the message
1059 * 'Got unwanted exception...':
1060 *
1061 * ```js
1062 * import assert from 'assert/strict';
1063 *
1064 * assert.doesNotThrow(
1065 * () => {
1066 * throw new TypeError('Wrong value');
1067 * },
1068 * TypeError
1069 * );
1070 * ```
1071 *
1072 * ```js
1073 * const assert = require('assert/strict');
1074 *
1075 * assert.doesNotThrow(
1076 * () => {
1077 * throw new TypeError('Wrong value');
1078 * },
1079 * TypeError
1080 * );
1081 * ```
1082 *
1083 * 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:
1084 *
1085 * ```js
1086 * import assert from 'assert/strict';
1087 *
1088 * assert.doesNotThrow(
1089 * () => {
1090 * throw new TypeError('Wrong value');
1091 * },
1092 * /Wrong value/,
1093 * 'Whoops'
1094 * );
1095 * // Throws: AssertionError: Got unwanted exception: Whoops
1096 * ```
1097 *
1098 * ```js
1099 * const assert = require('assert/strict');
1100 *
1101 * assert.doesNotThrow(
1102 * () => {
1103 * throw new TypeError('Wrong value');
1104 * },
1105 * /Wrong value/,
1106 * 'Whoops'
1107 * );
1108 * // Throws: AssertionError: Got unwanted exception: Whoops
1109 * ```
1110 * @since v0.1.21
1111 */
1112 function doesNotThrow(block: () => unknown, message?: string | Error): void;
1113 function doesNotThrow(block: () => unknown, error: AssertPredicate, message?: string | Error): void;
1114 /**
1115 * Throws `value` if `value` is not `undefined` or `null`. This is useful when
1116 * testing the `error` argument in callbacks. The stack trace contains all frames
1117 * from the error passed to `ifError()` including the potential new frames for`ifError()` itself.
1118 *
1119 * ```js
1120 * import assert from 'assert/strict';
1121 *
1122 * assert.ifError(null);
1123 * // OK
1124 * assert.ifError(0);
1125 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0
1126 * assert.ifError('error');
1127 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'
1128 * assert.ifError(new Error());
1129 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error
1130 *
1131 * // Create some random error frames.
1132 * let err;
1133 * (function errorFrame() {
1134 * err = new Error('test error');
1135 * })();
1136 *
1137 * (function ifErrorFrame() {
1138 * assert.ifError(err);
1139 * })();
1140 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error
1141 * // at ifErrorFrame
1142 * // at errorFrame
1143 * ```
1144 *
1145 * ```js
1146 * const assert = require('assert/strict');
1147 *
1148 * assert.ifError(null);
1149 * // OK
1150 * assert.ifError(0);
1151 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0
1152 * assert.ifError('error');
1153 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'
1154 * assert.ifError(new Error());
1155 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error
1156 *
1157 * // Create some random error frames.
1158 * let err;
1159 * (function errorFrame() {
1160 * err = new Error('test error');
1161 * })();
1162 *
1163 * (function ifErrorFrame() {
1164 * assert.ifError(err);
1165 * })();
1166 * // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error
1167 * // at ifErrorFrame
1168 * // at errorFrame
1169 * ```
1170 * @since v0.1.97
1171 */
1172 function ifError(value: unknown): asserts value is null | undefined;
1173 /**
1174 * Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately
1175 * calls the function and awaits the returned promise to complete. It will then
1176 * check that the promise is rejected.
1177 *
1178 * If `asyncFn` is a function and it throws an error synchronously,`assert.rejects()` will return a rejected `Promise` with that error. If the
1179 * 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
1180 * handler is skipped.
1181 *
1182 * Besides the async nature to await the completion behaves identically to {@link throws}.
1183 *
1184 * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes),
1185 * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), a validation function,
1186 * an object where each property will be tested for, or an instance of error where
1187 * each property will be tested for including the non-enumerable `message` and`name` properties.
1188 *
1189 * If specified, `message` will be the message provided by the `AssertionError` if the `asyncFn` fails to reject.
1190 *
1191 * ```js
1192 * import assert from 'assert/strict';
1193 *
1194 * await assert.rejects(
1195 * async () => {
1196 * throw new TypeError('Wrong value');
1197 * },
1198 * {
1199 * name: 'TypeError',
1200 * message: 'Wrong value'
1201 * }
1202 * );
1203 * ```
1204 *
1205 * ```js
1206 * const assert = require('assert/strict');
1207 *
1208 * (async () => {
1209 * await assert.rejects(
1210 * async () => {
1211 * throw new TypeError('Wrong value');
1212 * },
1213 * {
1214 * name: 'TypeError',
1215 * message: 'Wrong value'
1216 * }
1217 * );
1218 * })();
1219 * ```
1220 *
1221 * ```js
1222 * import assert from 'assert/strict';
1223 *
1224 * await assert.rejects(
1225 * async () => {
1226 * throw new TypeError('Wrong value');
1227 * },
1228 * (err) => {
1229 * assert.strictEqual(err.name, 'TypeError');
1230 * assert.strictEqual(err.message, 'Wrong value');
1231 * return true;
1232 * }
1233 * );
1234 * ```
1235 *
1236 * ```js
1237 * const assert = require('assert/strict');
1238 *
1239 * (async () => {
1240 * await assert.rejects(
1241 * async () => {
1242 * throw new TypeError('Wrong value');
1243 * },
1244 * (err) => {
1245 * assert.strictEqual(err.name, 'TypeError');
1246 * assert.strictEqual(err.message, 'Wrong value');
1247 * return true;
1248 * }
1249 * );
1250 * })();
1251 * ```
1252 *
1253 * ```js
1254 * import assert from 'assert/strict';
1255 *
1256 * assert.rejects(
1257 * Promise.reject(new Error('Wrong value')),
1258 * Error
1259 * ).then(() => {
1260 * // ...
1261 * });
1262 * ```
1263 *
1264 * ```js
1265 * const assert = require('assert/strict');
1266 *
1267 * assert.rejects(
1268 * Promise.reject(new Error('Wrong value')),
1269 * Error
1270 * ).then(() => {
1271 * // ...
1272 * });
1273 * ```
1274 *
1275 * `error` cannot be a string. If a string is provided as the second
1276 * 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
1277 * example in {@link throws} carefully if using a string as the second
1278 * argument gets considered.
1279 * @since v10.0.0
1280 */
1281 function rejects(block: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>;
1282 function rejects(block: (() => Promise<unknown>) | Promise<unknown>, error: AssertPredicate, message?: string | Error): Promise<void>;
1283 /**
1284 * Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately
1285 * calls the function and awaits the returned promise to complete. It will then
1286 * check that the promise is not rejected.
1287 *
1288 * If `asyncFn` is a function and it throws an error synchronously,`assert.doesNotReject()` will return a rejected `Promise` with that error. If
1289 * the function does not return a promise, `assert.doesNotReject()` will return a
1290 * rejected `Promise` with an `ERR_INVALID_RETURN_VALUE` error. In both cases
1291 * the error handler is skipped.
1292 *
1293 * Using `assert.doesNotReject()` is actually not useful because there is little
1294 * benefit in catching a rejection and then rejecting it again. Instead, consider
1295 * adding a comment next to the specific code path that should not reject and keep
1296 * error messages as expressive as possible.
1297 *
1298 * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes),
1299 * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation
1300 * function. See {@link throws} for more details.
1301 *
1302 * Besides the async nature to await the completion behaves identically to {@link doesNotThrow}.
1303 *
1304 * ```js
1305 * import assert from 'assert/strict';
1306 *
1307 * await assert.doesNotReject(
1308 * async () => {
1309 * throw new TypeError('Wrong value');
1310 * },
1311 * SyntaxError
1312 * );
1313 * ```
1314 *
1315 * ```js
1316 * const assert = require('assert/strict');
1317 *
1318 * (async () => {
1319 * await assert.doesNotReject(
1320 * async () => {
1321 * throw new TypeError('Wrong value');
1322 * },
1323 * SyntaxError
1324 * );
1325 * })();
1326 * ```
1327 *
1328 * ```js
1329 * import assert from 'assert/strict';
1330 *
1331 * assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
1332 * .then(() => {
1333 * // ...
1334 * });
1335 * ```
1336 *
1337 * ```js
1338 * const assert = require('assert/strict');
1339 *
1340 * assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
1341 * .then(() => {
1342 * // ...
1343 * });
1344 * ```
1345 * @since v10.0.0
1346 */
1347 function doesNotReject(block: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>;
1348 function doesNotReject(block: (() => Promise<unknown>) | Promise<unknown>, error: AssertPredicate, message?: string | Error): Promise<void>;
1349 /**
1350 * Expects the `string` input to match the regular expression.
1351 *
1352 * ```js
1353 * import assert from 'assert/strict';
1354 *
1355 * assert.match('I will fail', /pass/);
1356 * // AssertionError [ERR_ASSERTION]: The input did not match the regular ...
1357 *
1358 * assert.match(123, /pass/);
1359 * // AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
1360 *
1361 * assert.match('I will pass', /pass/);
1362 * // OK
1363 * ```
1364 *
1365 * ```js
1366 * const assert = require('assert/strict');
1367 *
1368 * assert.match('I will fail', /pass/);
1369 * // AssertionError [ERR_ASSERTION]: The input did not match the regular ...
1370 *
1371 * assert.match(123, /pass/);
1372 * // AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
1373 *
1374 * assert.match('I will pass', /pass/);
1375 * // OK
1376 * ```
1377 *
1378 * 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
1379 * to the value of the `message` parameter. If the `message` parameter is
1380 * undefined, a default error message is assigned. If the `message` parameter is an
1381 * instance of an `Error` then it will be thrown instead of the `AssertionError`.
1382 * @since v13.6.0, v12.16.0
1383 */
1384 function match(value: string, regExp: RegExp, message?: string | Error): void;
1385 /**
1386 * Expects the `string` input not to match the regular expression.
1387 *
1388 * ```js
1389 * import assert from 'assert/strict';
1390 *
1391 * assert.doesNotMatch('I will fail', /fail/);
1392 * // AssertionError [ERR_ASSERTION]: The input was expected to not match the ...
1393 *
1394 * assert.doesNotMatch(123, /pass/);
1395 * // AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
1396 *
1397 * assert.doesNotMatch('I will pass', /different/);
1398 * // OK
1399 * ```
1400 *
1401 * ```js
1402 * const assert = require('assert/strict');
1403 *
1404 * assert.doesNotMatch('I will fail', /fail/);
1405 * // AssertionError [ERR_ASSERTION]: The input was expected to not match the ...
1406 *
1407 * assert.doesNotMatch(123, /pass/);
1408 * // AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
1409 *
1410 * assert.doesNotMatch('I will pass', /different/);
1411 * // OK
1412 * ```
1413 *
1414 * 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
1415 * to the value of the `message` parameter. If the `message` parameter is
1416 * undefined, a default error message is assigned. If the `message` parameter is an
1417 * instance of an `Error` then it will be thrown instead of the `AssertionError`.
1418 * @since v13.6.0, v12.16.0
1419 */
1420 function doesNotMatch(value: string, regExp: RegExp, message?: string | Error): void;
1421 const strict: Omit<typeof assert, 'equal' | 'notEqual' | 'deepEqual' | 'notDeepEqual' | 'ok' | 'strictEqual' | 'deepStrictEqual' | 'ifError' | 'strict'> & {
1422 (value: unknown, message?: string | Error): asserts value;
1423 equal: typeof strictEqual;
1424 notEqual: typeof notStrictEqual;
1425 deepEqual: typeof deepStrictEqual;
1426 notDeepEqual: typeof notDeepStrictEqual;
1427 // Mapped types and assertion functions are incompatible?
1428 // TS2775: Assertions require every name in the call target
1429 // to be declared with an explicit type annotation.
1430 ok: typeof ok;
1431 strictEqual: typeof strictEqual;
1432 deepStrictEqual: typeof deepStrictEqual;
1433 ifError: typeof ifError;
1434 strict: typeof strict;
1435 };
1436 }
1437 export = assert;
1438}
1439declare module 'node:assert' {
1440 import assert = require('assert');
1441 export = assert;
1442}
1443
\No newline at end of file