Permalink
Browse files

refactor(Assertion): small edit and improve docs

- Rename third parameter of Assertion constructor from `stack` to
  `ssfi` for consistency's sake.
- Add documentation to Assertion constructor explaining what the `object`,
  `message`, and `ssfi` flags are for.
  • Loading branch information...
1 parent 82ca613 commit 0c0983618e025576b7c86e607cd104ebba3bc882 @meeber meeber committed Dec 18, 2016
Showing with 25 additions and 2 deletions.
  1. +25 −2 lib/chai/assertion.js
View
@@ -26,11 +26,34 @@ module.exports = function (_chai, util) {
*
* 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`.
+ *
+ * @param {Mixed} obj target of the assertion
+ * @param {String} msg (optional) custom error message
+ * @param {Function} stack (optional) starting point for removing stack frames
* @api private
*/
- function Assertion (obj, msg, stack) {
- flag(this, 'ssfi', stack || Assertion);
+ function Assertion (obj, msg, ssfi) {
+ flag(this, 'ssfi', ssfi || Assertion);
flag(this, 'object', obj);
flag(this, 'message', msg);

0 comments on commit 0c09836

Please sign in to comment.