chai 4.3.10 → 5.1.2

package/eslint.config.js

@@ -0,0 +1,12 @@
+import jsdoc from "eslint-plugin-jsdoc";
+
+export default [
+  jsdoc.configs["flat/recommended"],
+  {
+    rules: {
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-returns-description": "off",
+      "jsdoc/tag-lines": ["error", "any", { startLines: 1 }],
+    },
+  },
+];

package/index.js

@@ -1 +1 @@
-module.exports = require('./lib/chai');
+export * from './lib/chai.js';

package/lib/chai/assertion.js

@@ -5,171 +5,160 @@
  * MIT Licensed
  */
 
-var config = require('./config');
-
-module.exports = function (_chai, util) {
-  /*!
-   * Module dependencies.
-   */
-
-  var AssertionError = _chai.AssertionError
-    , flag = util.flag;
-
-  /*!
-   * Module export.
-   */
-
-  _chai.Assertion = Assertion;
-
-  /*!
-   * Assertion Constructor
-   *
-   * Creates object for chaining.
-   *
-   * `Assertion` objects contain metadata in the form of flags. Three flags can
-   * be assigned during instantiation by passing arguments to this constructor:
-   *
-   * - `object`: This flag contains the target of the assertion. For example, in
-   *   the assertion `expect(numKittens).to.equal(7);`, the `object` flag will
-   *   contain `numKittens` so that the `equal` assertion can reference it when
-   *   needed.
-   *
-   * - `message`: This flag contains an optional custom error message to be
-   *   prepended to the error message that's generated by the assertion when it
-   *   fails.
-   *
-   * - `ssfi`: This flag stands for "start stack function indicator". It
-   *   contains a function reference that serves as the starting point for
-   *   removing frames from the stack trace of the error that's created by the
-   *   assertion when it fails. The goal is to provide a cleaner stack trace to
-   *   end users by removing Chai's internal functions. Note that it only works
-   *   in environments that support `Error.captureStackTrace`, and only when
-   *   `Chai.config.includeStack` hasn't been set to `false`.
-   *
-   * - `lockSsfi`: This flag controls whether or not the given `ssfi` flag
-   *   should retain its current value, even as assertions are chained off of
-   *   this object. This is usually set to `true` when creating a new assertion
-   *   from within another assertion. It's also temporarily set to `true` before
-   *   an overwritten assertion gets called by the overwriting assertion.
-   *
-   * @param {Mixed} obj target of the assertion
-   * @param {String} msg (optional) custom error message
-   * @param {Function} ssfi (optional) starting point for removing stack frames
-   * @param {Boolean} lockSsfi (optional) whether or not the ssfi flag is locked
-   * @api private
-   */
-
-  function Assertion (obj, msg, ssfi, lockSsfi) {
-    flag(this, 'ssfi', ssfi || Assertion);
-    flag(this, 'lockSsfi', lockSsfi);
-    flag(this, 'object', obj);
-    flag(this, 'message', msg);
-
-    return util.proxify(this);
+import {config} from './config.js';
+import {AssertionError} from 'assertion-error';
+import * as util from './utils/index.js';
+
+/**
+ * Assertion Constructor
+ *
+ * Creates object for chaining.
+ *
+ * `Assertion` objects contain metadata in the form of flags. Three flags can
+ * be assigned during instantiation by passing arguments to this constructor:
+ *
+ * - `object`: This flag contains the target of the assertion. For example, in
+ * the assertion `expect(numKittens).to.equal(7);`, the `object` flag will
+ * contain `numKittens` so that the `equal` assertion can reference it when
+ * needed.
+ *
+ * - `message`: This flag contains an optional custom error message to be
+ * prepended to the error message that's generated by the assertion when it
+ * fails.
+ *
+ * - `ssfi`: This flag stands for "start stack function indicator". It
+ * contains a function reference that serves as the starting point for
+ * removing frames from the stack trace of the error that's created by the
+ * assertion when it fails. The goal is to provide a cleaner stack trace to
+ * end users by removing Chai's internal functions. Note that it only works
+ * in environments that support `Error.captureStackTrace`, and only when
+ * `Chai.config.includeStack` hasn't been set to `false`.
+ *
+ * - `lockSsfi`: This flag controls whether or not the given `ssfi` flag
+ * should retain its current value, even as assertions are chained off of
+ * this object. This is usually set to `true` when creating a new assertion
+ * from within another assertion. It's also temporarily set to `true` before
+ * an overwritten assertion gets called by the overwriting assertion.
+ *
+ * - `eql`: This flag contains the deepEqual function to be used by the assertion.
+ *
+ * @param {unknown} obj target of the assertion
+ * @param {string} msg (optional) custom error message
+ * @param {Function} ssfi (optional) starting point for removing stack frames
+ * @param {boolean} lockSsfi (optional) whether or not the ssfi flag is locked
+ * @returns {unknown}
+ * @private
+ */
+export function Assertion (obj, msg, ssfi, lockSsfi) {
+  util.flag(this, 'ssfi', ssfi || Assertion);
+  util.flag(this, 'lockSsfi', lockSsfi);
+  util.flag(this, 'object', obj);
+  util.flag(this, 'message', msg);
+  util.flag(this, 'eql', config.deepEqual || util.eql);
+
+  return util.proxify(this);
+}
+
+Object.defineProperty(Assertion, 'includeStack', {
+  get: function() {
+    console.warn('Assertion.includeStack is deprecated, use chai.config.includeStack instead.');
+    return config.includeStack;
+  },
+  set: function(value) {
+    console.warn('Assertion.includeStack is deprecated, use chai.config.includeStack instead.');
+    config.includeStack = value;
+  }
+});
+
+Object.defineProperty(Assertion, 'showDiff', {
+  get: function() {
+    console.warn('Assertion.showDiff is deprecated, use chai.config.showDiff instead.');
+    return config.showDiff;
+  },
+  set: function(value) {
+    console.warn('Assertion.showDiff is deprecated, use chai.config.showDiff instead.');
+    config.showDiff = value;
   }
+});
+
+Assertion.addProperty = function (name, fn) {
+  util.addProperty(this.prototype, name, fn);
+};
+
+Assertion.addMethod = function (name, fn) {
+  util.addMethod(this.prototype, name, fn);
+};
+
+Assertion.addChainableMethod = function (name, fn, chainingBehavior) {
+  util.addChainableMethod(this.prototype, name, fn, chainingBehavior);
+};
+
+Assertion.overwriteProperty = function (name, fn) {
+  util.overwriteProperty(this.prototype, name, fn);
+};
+
+Assertion.overwriteMethod = function (name, fn) {
+  util.overwriteMethod(this.prototype, name, fn);
+};
+
+Assertion.overwriteChainableMethod = function (name, fn, chainingBehavior) {
+  util.overwriteChainableMethod(this.prototype, name, fn, chainingBehavior);
+};
 
-  Object.defineProperty(Assertion, 'includeStack', {
-    get: function() {
-      console.warn('Assertion.includeStack is deprecated, use chai.config.includeStack instead.');
-      return config.includeStack;
-    },
-    set: function(value) {
-      console.warn('Assertion.includeStack is deprecated, use chai.config.includeStack instead.');
-      config.includeStack = value;
+/**
+ * ### .assert(expression, message, negateMessage, expected, actual, showDiff)
+ *
+ * Executes an expression and check expectations. Throws AssertionError for reporting if test doesn't pass.
+ *
+ * @name assert
+ * @param {unknown} expression to be tested
+ * @param {string | Function} message or function that returns message to display if expression fails
+ * @param {string | Function} negatedMessage or function that returns negatedMessage to display if negated expression fails
+ * @param {unknown} expected value (remember to check for negation)
+ * @param {unknown} actual (optional) will default to `this.obj`
+ * @param {boolean} showDiff (optional) when set to `true`, assert will display a diff in addition to the message if expression fails
+ * @private
+ */
+
+Assertion.prototype.assert = function (expr, msg, negateMsg, expected, _actual, showDiff) {
+  var ok = util.test(this, arguments);
+  if (false !== showDiff) showDiff = true;
+  if (undefined === expected && undefined === _actual) showDiff = false;
+  if (true !== config.showDiff) showDiff = false;
+
+  if (!ok) {
+    msg = util.getMessage(this, arguments);
+    var actual = util.getActual(this, arguments);
+    var assertionErrorObjectProperties = {
+        actual: actual
+      , expected: expected
+      , showDiff: showDiff
+    };
+
+    var operator = util.getOperator(this, arguments);
+    if (operator) {
+      assertionErrorObjectProperties.operator = operator;
     }
-  });
-
-  Object.defineProperty(Assertion, 'showDiff', {
-    get: function() {
-      console.warn('Assertion.showDiff is deprecated, use chai.config.showDiff instead.');
-      return config.showDiff;
-    },
-    set: function(value) {
-      console.warn('Assertion.showDiff is deprecated, use chai.config.showDiff instead.');
-      config.showDiff = value;
+
+    throw new AssertionError(
+      msg,
+      assertionErrorObjectProperties,
+      (config.includeStack) ? this.assert : util.flag(this, 'ssfi'));
+  }
+};
+
+/**
+ * ### ._obj
+ *
+ * Quick reference to stored `actual` value for plugin developers.
+ *
+ * @private
+ */
+Object.defineProperty(Assertion.prototype, '_obj',
+  { get: function () {
+      return util.flag(this, 'object');
     }
-  });
-
-  Assertion.addProperty = function (name, fn) {
-    util.addProperty(this.prototype, name, fn);
-  };
-
-  Assertion.addMethod = function (name, fn) {
-    util.addMethod(this.prototype, name, fn);
-  };
-
-  Assertion.addChainableMethod = function (name, fn, chainingBehavior) {
-    util.addChainableMethod(this.prototype, name, fn, chainingBehavior);
-  };
-
-  Assertion.overwriteProperty = function (name, fn) {
-    util.overwriteProperty(this.prototype, name, fn);
-  };
-
-  Assertion.overwriteMethod = function (name, fn) {
-    util.overwriteMethod(this.prototype, name, fn);
-  };
-
-  Assertion.overwriteChainableMethod = function (name, fn, chainingBehavior) {
-    util.overwriteChainableMethod(this.prototype, name, fn, chainingBehavior);
-  };
-
-  /**
-   * ### .assert(expression, message, negateMessage, expected, actual, showDiff)
-   *
-   * Executes an expression and check expectations. Throws AssertionError for reporting if test doesn't pass.
-   *
-   * @name assert
-   * @param {Philosophical} expression to be tested
-   * @param {String|Function} message or function that returns message to display if expression fails
-   * @param {String|Function} negatedMessage or function that returns negatedMessage to display if negated expression fails
-   * @param {Mixed} expected value (remember to check for negation)
-   * @param {Mixed} actual (optional) will default to `this.obj`
-   * @param {Boolean} showDiff (optional) when set to `true`, assert will display a diff in addition to the message if expression fails
-   * @api private
-   */
-
-  Assertion.prototype.assert = function (expr, msg, negateMsg, expected, _actual, showDiff) {
-    var ok = util.test(this, arguments);
-    if (false !== showDiff) showDiff = true;
-    if (undefined === expected && undefined === _actual) showDiff = false;
-    if (true !== config.showDiff) showDiff = false;
-
-    if (!ok) {
-      msg = util.getMessage(this, arguments);
-      var actual = util.getActual(this, arguments);
-      var assertionErrorObjectProperties = {
-          actual: actual
-        , expected: expected
-        , showDiff: showDiff
-      };
-
-      var operator = util.getOperator(this, arguments);
-      if (operator) {
-        assertionErrorObjectProperties.operator = operator;
-      }
-
-      throw new AssertionError(
-        msg,
-        assertionErrorObjectProperties,
-        (config.includeStack) ? this.assert : flag(this, 'ssfi'));
+  , set: function (val) {
+      util.flag(this, 'object', val);
     }
-  };
-
-  /*!
-   * ### ._obj
-   *
-   * Quick reference to stored `actual` value for plugin developers.
-   *
-   * @api private
-   */
-
-  Object.defineProperty(Assertion.prototype, '_obj',
-    { get: function () {
-        return flag(this, 'object');
-      }
-    , set: function (val) {
-        flag(this, 'object', val);
-      }
-  });
-};
+});

package/lib/chai/config.js

@@ -1,4 +1,4 @@
-module.exports = {
+export const config = {
 
   /**
    * ### config.includeStack
@@ -9,10 +9,9 @@ module.exports = {
    *
    *     chai.config.includeStack = true;  // enable stack on error
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
-
   includeStack: false,
 
   /**
@@ -24,10 +23,9 @@ module.exports = {
    * will be true when the assertion has requested a diff
    * be shown.
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
-
   showDiff: true,
 
   /**
@@ -46,10 +44,9 @@ module.exports = {
    *
    *     chai.config.truncateThreshold = 0;  // disable truncating
    *
-   * @param {Number}
-   * @api public
+   * @param {number}
+   * @public
    */
-
   truncateThreshold: 40,
 
   /**
@@ -66,10 +63,9 @@ module.exports = {
    * This feature is automatically disabled regardless of this config value
    * in environments that don't support proxies.
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
-
   useProxy: true,
 
   /**
@@ -87,8 +83,32 @@ module.exports = {
    *     chai.config.proxyExcludedKeys = ['then', 'inspect'];
    *
    * @param {Array}
-   * @api public
+   * @public
+   */
+  proxyExcludedKeys: ['then', 'catch', 'inspect', 'toJSON'],
+
+  /**
+   * ### config.deepEqual
+   *
+   * User configurable property, defines which a custom function to use for deepEqual
+   * comparisons.
+   * By default, the function used is the one from the `deep-eql` package without custom comparator.
+   *
+   *     // use a custom comparator
+   *     chai.config.deepEqual = (expected, actual) => {
+   *         return chai.util.eql(expected, actual, {
+   *             comparator: (expected, actual) => {
+   *                 // for non number comparison, use the default behavior
+   *                 if(typeof expected !== 'number') return null;
+   *                 // allow a difference of 10 between compared numbers
+   *                 return typeof actual === 'number' && Math.abs(actual - expected) < 10
+   *             }
+   *         })
+   *     };
+   *
+   * @param {Function}
+   * @public
    */
+  deepEqual: null
 
-  proxyExcludedKeys: ['then', 'catch', 'inspect', 'toJSON']
 };