From c87ed21fdf6e393e6f7601bd867f61e529cc058d Mon Sep 17 00:00:00 2001
From: ConorDavenport <cnrdavenport@gmail.com>
Date: Thu, 27 Feb 2020 11:41:05 +0000
Subject: [PATCH] assert: port common.mustCall() to assert

Fixes: https://github.com/nodejs/node/issues/31392

PR-URL: https://github.com/nodejs/node/pull/31982
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Zeyu Yang <himself65@outlook.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Denys Otrishko <shishugi@gmail.com>
---
 doc/api/assert.md                             | 135 ++++++++++++++++++
 doc/api/errors.md                             |   7 +
 lib/assert.js                                 |   3 +
 lib/internal/assert/assertion_error.js        |  20 ++-
 lib/internal/assert/calltracker.js            |  93 ++++++++++++
 lib/internal/errors.js                        |   2 +
 node.gyp                                      |   1 +
 .../parallel/test-assert-calltracker-calls.js |  66 +++++++++
 .../test-assert-calltracker-report.js         |  32 +++++
 .../test-assert-calltracker-verify.js         |  32 +++++
 10 files changed, 388 insertions(+), 3 deletions(-)
 create mode 100644 lib/internal/assert/calltracker.js
 create mode 100644 test/parallel/test-assert-calltracker-calls.js
 create mode 100644 test/parallel/test-assert-calltracker-report.js
 create mode 100644 test/parallel/test-assert-calltracker-verify.js

diff --git a/doc/api/assert.md b/doc/api/assert.md
index 9731ddaa13f315..f8178ed6ec1249 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -149,6 +149,137 @@ try {
 }
 ```
 
+## Class: `assert.CallTracker`
+
+### `new assert.CallTracker()`
+<!-- YAML
+added: REPLACEME
+-->
+
+Creates a new [`CallTracker`][] object which can be used to track if functions
+were called a specific number of times. The `tracker.verify()` must be called
+for the verification to take place. The usual pattern would be to call it in a
+[`process.on('exit')`][] handler.
+
+```js
+const assert = require('assert');
+
+const tracker = new assert.CallTracker();
+
+function func() {}
+
+// callsfunc() must be called exactly 1 time before tracker.verify().
+const callsfunc = tracker.calls(func, 1);
+
+callsfunc();
+
+// Calls tracker.verify() and verifies if all tracker.calls() functions have
+// been called exact times.
+process.on('exit', () => {
+  tracker.verify();
+});
+```
+
+### `tracker.calls([fn][, exact])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `fn` {Function} **Default** A no-op function.
+* `exact` {number} **Default** `1`.
+* Returns: {Function} that wraps `fn`.
+
+The wrapper function is expected to be called exactly `exact` times. If the
+function has not been called exactly `exact` times when
+[`tracker.verify()`][] is called, then [`tracker.verify()`][] will throw an
+error.
+
+```js
+const assert = require('assert');
+
+// Creates call tracker.
+const tracker = new assert.CallTracker();
+
+function func() {}
+
+// Returns a function that wraps func() that must be called exact times
+// before tracker.verify().
+const callsfunc = tracker.calls(func);
+```
+
+### `tracker.report()`
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Array} of objects containing information about the wrapper functions
+returned by [`tracker.calls()`][].
+* Object {Object}
+  * `message` {string}
+  * `actual` {number} The actual number of times the function was called.
+  * `expected` {number} The number of times the function was expected to be
+    called.
+  * `operator` {string} The name of the function that is wrapped.
+  * `stack` {Object} A stack trace of the function.
+
+The arrays contains information about the expected and actual number of calls of
+the functions that have not been called the expected number of times.
+
+```js
+const assert = require('assert');
+
+// Creates call tracker.
+const tracker = new assert.CallTracker();
+
+function func() {}
+
+function foo() {}
+
+// Returns a function that wraps func() that must be called exact times
+// before tracker.verify().
+const callsfunc = tracker.calls(func, 2);
+
+// Returns an array containing information on callsfunc()
+tracker.report();
+// [
+//  {
+//    message: 'Expected the func function to be executed 2 time(s) but was
+//    executed 0 time(s).',
+//    actual: 0,
+//    expected: 2,
+//    operator: 'func',
+//    stack: stack trace
+//  }
+// ]
+```
+
+### `tracker.verify()`
+<!-- YAML
+added: REPLACEME
+-->
+
+Iterates through the list of functions passed to
+[`tracker.calls()`][] and will throw an error for functions that
+have not been called the expected number of times.
+
+```js
+const assert = require('assert');
+
+// Creates call tracker.
+const tracker = new assert.CallTracker();
+
+function func() {}
+
+// Returns a function that wraps func() that must be called exact times
+// before tracker.verify().
+const callsfunc = tracker.calls(func, 2);
+
+callsfunc();
+
+// Will throw an error since callsfunc() was only called once.
+tracker.verify();
+```
+
 ## `assert(value[, message])`
 <!-- YAML
 added: v0.5.9
@@ -1429,6 +1560,7 @@ argument.
 [`TypeError`]: errors.html#errors_class_typeerror
 [`WeakMap`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
 [`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet
+[`CallTracker`]: #assert_class_assert_calltracker
 [`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message
 [`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message
 [`assert.doesNotThrow()`]: #assert_assert_doesnotthrow_fn_error_message
@@ -1440,6 +1572,9 @@ argument.
 [`assert.ok()`]: #assert_assert_ok_value_message
 [`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message
 [`assert.throws()`]: #assert_assert_throws_fn_error_message
+[`process.on('exit')`]: process.html#process_event_exit
+[`tracker.calls()`]: #assert_class_assert_CallTracker#tracker_calls
+[`tracker.verify()`]: #assert_class_assert_CallTracker#tracker_verify
 [strict assertion mode]: #assert_strict_assertion_mode
 [Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison
 [Object wrappers]: https://developer.mozilla.org/en-US/docs/Glossary/Primitive#Primitive_wrapper_objects_in_JavaScript
diff --git a/doc/api/errors.md b/doc/api/errors.md
index 5b1599febea9b7..172eadf7686794 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -1967,6 +1967,12 @@ A `Transform` stream finished with data still in the write buffer.
 
 The initialization of a TTY failed due to a system error.
 
+<a id="ERR_UNAVAILABLE_DURING_EXIT"></a>
+### `ERR_UNAVAILABLE_DURING_EXIT`
+
+Function was called within a [`process.on('exit')`][] handler that shouldn't be
+called within [`process.on('exit')`][] handler.
+
 <a id="ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET"></a>
 ### `ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET`
 
@@ -2545,6 +2551,7 @@ such as `process.stdout.on('data')`.
 [`net`]: net.html
 [`new URL(input)`]: url.html#url_constructor_new_url_input_base
 [`new URLSearchParams(iterable)`]: url.html#url_constructor_new_urlsearchparams_iterable
+[`process.on('exit')`]: process.html#Event:-`'exit'`
 [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback
 [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`readable._read()`]: stream.html#stream_readable_read_size_1
diff --git a/lib/assert.js b/lib/assert.js
index 45c4644279de33..6ad672d698602d 100644
--- a/lib/assert.js
+++ b/lib/assert.js
@@ -51,6 +51,7 @@ const { NativeModule } = require('internal/bootstrap/loaders');
 const { isError } = require('internal/util');
 
 const errorCache = new Map();
+const CallTracker = require('internal/assert/calltracker');
 
 let isDeepEqual;
 let isDeepStrictEqual;
@@ -928,6 +929,8 @@ assert.doesNotMatch = function doesNotMatch(string, regexp, message) {
   internalMatch(string, regexp, message, doesNotMatch);
 };
 
+assert.CallTracker = CallTracker;
+
 // Expose a strict only variant of assert
 function strict(...args) {
   innerOk(strict, args.length, ...args);
diff --git a/lib/internal/assert/assertion_error.js b/lib/internal/assert/assertion_error.js
index 691f057ad281e3..3c2150c69e4e09 100644
--- a/lib/internal/assert/assertion_error.js
+++ b/lib/internal/assert/assertion_error.js
@@ -312,6 +312,7 @@ class AssertionError extends Error {
       message,
       operator,
       stackStartFn,
+      details,
       // Compatibility with older versions.
       stackStartFunction
     } = options;
@@ -426,9 +427,22 @@ class AssertionError extends Error {
       configurable: true
     });
     this.code = 'ERR_ASSERTION';
-    this.actual = actual;
-    this.expected = expected;
-    this.operator = operator;
+    if (details) {
+      this.actual = undefined;
+      this.expected = undefined;
+      this.operator = undefined;
+      for (let i = 0; i < details.length; i++) {
+        this['message ' + i] = details[i].message;
+        this['actual ' + i] = details[i].actual;
+        this['expected ' + i] = details[i].expected;
+        this['operator ' + i] = details[i].operator;
+        this['stack trace ' + i] = details[i].stack;
+      }
+    } else {
+      this.actual = actual;
+      this.expected = expected;
+      this.operator = operator;
+    }
     // eslint-disable-next-line no-restricted-syntax
     Error.captureStackTrace(this, stackStartFn || stackStartFunction);
     // Create error message including the error code in the name.
diff --git a/lib/internal/assert/calltracker.js b/lib/internal/assert/calltracker.js
new file mode 100644
index 00000000000000..74f517f3f9e99b
--- /dev/null
+++ b/lib/internal/assert/calltracker.js
@@ -0,0 +1,93 @@
+'use strict';
+
+const {
+  Error,
+  SafeSet,
+} = primordials;
+
+const {
+  codes: {
+    ERR_UNAVAILABLE_DURING_EXIT,
+  },
+} = require('internal/errors');
+const AssertionError = require('internal/assert/assertion_error');
+const {
+  validateUint32,
+} = require('internal/validators');
+
+const noop = () => {};
+
+class CallTracker {
+
+  #callChecks = new SafeSet()
+
+  calls(fn, exact = 1) {
+    if (process._exiting)
+      throw new ERR_UNAVAILABLE_DURING_EXIT();
+    if (typeof fn === 'number') {
+      exact = fn;
+      fn = noop;
+    } else if (fn === undefined) {
+      fn = noop;
+    }
+
+    validateUint32(exact, 'exact', true);
+
+    const context = {
+      exact,
+      actual: 0,
+      // eslint-disable-next-line no-restricted-syntax
+      stackTrace: new Error(),
+      name: fn.name || 'calls'
+    };
+    const callChecks = this.#callChecks;
+    callChecks.add(context);
+
+    return function() {
+      context.actual++;
+      if (context.actual === context.exact) {
+        // Once function has reached its call count remove it from
+        // callChecks set to prevent memory leaks.
+        callChecks.delete(context);
+      }
+      // If function has been called more than expected times, add back into
+      // callchecks.
+      if (context.actual === context.exact + 1) {
+        callChecks.add(context);
+      }
+      return fn.apply(this, arguments);
+    };
+  }
+
+  report() {
+    const errors = [];
+    for (const context of this.#callChecks) {
+      // If functions have not been called exact times
+      if (context.actual !== context.exact) {
+        const message = `Expected the ${context.name} function to be ` +
+                        `executed ${context.exact} time(s) but was ` +
+                        `executed ${context.actual} time(s).`;
+        errors.push({
+          message,
+          actual: context.actual,
+          expected: context.exact,
+          operator: context.name,
+          stack: context.stackTrace
+        });
+      }
+    }
+    return errors;
+  }
+
+  verify() {
+    const errors = this.report();
+    if (errors.length > 0) {
+      throw new AssertionError({
+        message: 'Function(s) were not called the expected number of times',
+        details: errors,
+      });
+    }
+  }
+}
+
+module.exports = CallTracker;
diff --git a/lib/internal/errors.js b/lib/internal/errors.js
index e9e11bf0fb195b..0682b58af61e17 100644
--- a/lib/internal/errors.js
+++ b/lib/internal/errors.js
@@ -1380,6 +1380,8 @@ E('ERR_TRANSFORM_ALREADY_TRANSFORMING',
 E('ERR_TRANSFORM_WITH_LENGTH_0',
   'Calling transform done when writableState.length != 0', Error);
 E('ERR_TTY_INIT_FAILED', 'TTY initialization failed', SystemError);
+E('ERR_UNAVAILABLE_DURING_EXIT', 'Cannot call function in process exit ' +
+  'handler', Error);
 E('ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET',
   '`process.setupUncaughtExceptionCapture()` was called while a capture ' +
     'callback was already active',
diff --git a/node.gyp b/node.gyp
index c3ffd2ff2147e2..2f0f0f152ba8b3 100644
--- a/node.gyp
+++ b/node.gyp
@@ -96,6 +96,7 @@
       'lib/zlib.js',
       'lib/internal/assert.js',
       'lib/internal/assert/assertion_error.js',
+      'lib/internal/assert/calltracker.js',
       'lib/internal/async_hooks.js',
       'lib/internal/buffer.js',
       'lib/internal/cli_table.js',
diff --git a/test/parallel/test-assert-calltracker-calls.js b/test/parallel/test-assert-calltracker-calls.js
new file mode 100644
index 00000000000000..4de23d4658468a
--- /dev/null
+++ b/test/parallel/test-assert-calltracker-calls.js
@@ -0,0 +1,66 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+
+// This test ensures that assert.CallTracker.calls() works as intended.
+
+const tracker = new assert.CallTracker();
+
+function bar() {}
+
+const err = {
+  code: 'ERR_INVALID_ARG_TYPE',
+};
+
+// Ensures calls() throws on invalid input types.
+assert.throws(() => {
+  const callsbar = tracker.calls(bar, '1');
+  callsbar();
+}, err
+);
+
+assert.throws(() => {
+  const callsbar = tracker.calls(bar, 0.1);
+  callsbar();
+}, { code: 'ERR_OUT_OF_RANGE' }
+);
+
+assert.throws(() => {
+  const callsbar = tracker.calls(bar, true);
+  callsbar();
+}, err
+);
+
+assert.throws(() => {
+  const callsbar = tracker.calls(bar, () => {});
+  callsbar();
+}, err
+);
+
+assert.throws(() => {
+  const callsbar = tracker.calls(bar, null);
+  callsbar();
+}, err
+);
+
+// Expects an error as tracker.calls() cannot be called within a process exit
+// handler.
+process.on('exit', () => {
+  assert.throws(() => tracker.calls(bar, 1), {
+    code: 'ERR_UNAVAILABLE_DURING_EXIT',
+  });
+});
+
+const msg = 'Expected to throw';
+
+function func() {
+  throw new Error(msg);
+}
+
+const callsfunc = tracker.calls(func, 1);
+
+// Expects callsfunc() to call func() which throws an error.
+assert.throws(
+  () => callsfunc(),
+  { message: msg }
+);
diff --git a/test/parallel/test-assert-calltracker-report.js b/test/parallel/test-assert-calltracker-report.js
new file mode 100644
index 00000000000000..79186c88fd058b
--- /dev/null
+++ b/test/parallel/test-assert-calltracker-report.js
@@ -0,0 +1,32 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+
+// This test ensures that the assert.CallTracker.report() works as intended.
+
+const tracker = new assert.CallTracker();
+
+function foo() {}
+
+const callsfoo = tracker.calls(foo, 1);
+
+// Ensures that foo was added to the callChecks array.
+if (tracker.report()[0].operator !== 'foo') {
+  process.exit(1);
+}
+
+callsfoo();
+
+// Ensures that foo was removed from the callChecks array after being called the
+// expected number of times.
+if (typeof tracker.report()[0] === undefined) {
+  process.exit(1);
+}
+
+callsfoo();
+
+// Ensures that foo was added back to the callChecks array after being called
+// more than the expected number of times.
+if (tracker.report()[0].operator !== 'foo') {
+  process.exit(1);
+}
diff --git a/test/parallel/test-assert-calltracker-verify.js b/test/parallel/test-assert-calltracker-verify.js
new file mode 100644
index 00000000000000..75d20bf9c49c38
--- /dev/null
+++ b/test/parallel/test-assert-calltracker-verify.js
@@ -0,0 +1,32 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+
+// This test ensures that assert.CallTracker.verify() works as intended.
+
+const tracker = new assert.CallTracker();
+
+const msg = 'Function(s) were not called the expected number of times';
+
+function foo() {}
+
+const callsfoo = tracker.calls(foo, 1);
+
+// Expects an error as callsfoo() was called less than one time.
+assert.throws(
+  () => tracker.verify(),
+  { message: msg }
+);
+
+callsfoo();
+
+// Will throw an error if callsfoo() isn't called exactly once.
+tracker.verify();
+
+callsfoo();
+
+// Expects an error as callsfoo() was called more than once.
+assert.throws(
+  () => tracker.verify(),
+  { message: msg }
+);