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