20991d85b2ed10fd2ad4fd6200fbae17970377b80108e7d49d100b78bfe70cd61de36461a7a05f76bb66b636d919762526cd2f5c27b805fc3fe2845fdf9da3 44 KB

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