2c0b56248a38bb63ec3037b027c7d4e97e016e9239ea46406268493669558a58b720d80f59e88dcbac75da7dcac26694911de05ed204840579a2eb49f45e81 44 KB

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