Overhaul bdd documentation #920

meeber · 2017-01-27T02:39:43Z

Note to self: Rebase once #947 is merged and update docs for by since it now accepts a message argument.

There are two commits in this PR.

The first commit is a small change that renames the target argument to subject in a few assertions because "target" is an overloaded term which made it difficult to document.

The second commit is a huge overhaul of the bdd documentation intended to bring clarity, consistency, and guidance to every assertion. All of the examples that are intended to pass do so with the exception of two due to #919.

Closes #914
Closes #902

keithamus · 2017-01-27T10:29:29Z

lib/chai/core/assertions.js

+   * should. With great power comes great responsibility. Whenever possible,
+   * it's best to assert that the one expected output was produced, rather than
+   * asserting that one of countless unexpected outputs wasn't produced. See
+   * individual assertions for specific guidance.


+1 great work.

keithamus · 2017-01-27T10:30:20Z

lib/chai/core/assertions.js

-   * `property` assertions.
+   * Sets the `deep` flag, causing all `.equal`, `.include`, `.members`,
+   * `.keys`, and `.property` assertions that follow in the chain to perform
+   * comparisons using deep equality instead of strict (`===`) equality.


💭 It would be really nice here to link deep equality here rather than (or in addition to) the bottom of the description. Nice to have so won't block review on this.

keithamus · 2017-01-27T10:33:26Z

lib/chai/core/assertions.js

+   * The 1st and 4th forms assert exactly what's expected of the output, whereas
+   * the 2nd and 3rd forms create uncertainty. Whenever possible, it's best to
+   * identify the exact output that's expected, and then write an assertion
+   * that only accepts that exact output as valid.


keithamus · 2017-01-27T10:35:06Z

lib/chai/core/assertions.js

+   * but may or may not have some of them.
+   *
+   * 4. `.not.any.keys`: Asserts that the target doesn't have any of the given
+   * keys.


💭 I wonder if there is a better way to phrase these? For my personal reading style these become blurry, hard to decipher. Perhaps examples would be better here? I wont block review for this though, it's much better than we currently have.

keithamus · 2017-01-27T10:41:34Z

lib/chai/core/assertions.js

-   * later used by the `keys` assertion.
+   * Unsets the `any` flag, causing all `.keys` assertions that follow in the
+   * chain to revert to the default behavior of requiring that the target have
+   * all of the given keys, rather than only needing one or more of them.


🛑 Not sure I like this one. Feels like a long and winding sentence. Maybe better?

Unsets the any flag, causing any subsequent .keys assertions to revert back to normal behaviour. The normal behavior is that the target must have all keys, while any only expects some.

Also might be useful to document the interplay of any and all in the same chain. A rough draft of what I'm thinking:

Using .any.all is effectively a noop, you will rarely need to use both in one chain, but one example of this might be:
expect({ a: 1, b: 2 }).to.have.any.keys(['b', 'c']).but.not.have.all.keys([ 'd', 'e', 'f' ]);

I think we could have an example here too. This is kind of an "advanced" feature and I think many newcomers will be confused if they see this.

keithamus · 2017-01-27T11:05:04Z

lib/chai/core/assertions.js

+   *     expect(undefined).to.be.undefined; // Recommended
+   *     expect(undefined).to.not.be.ok; // Not recommended
+   *
+   * A custom error message can be supplied as the second argument to `expect`.


👍 Makes me wonder if we should just straight up deprecate ok?

keithamus · 2017-01-27T11:08:36Z

lib/chai/core/assertions.js

+   * In modern environments, this assertion is performed using the built-in ES6
+   * `Number.isNaN` method. In legacy environments, the target is compared to
+   * itself using strict (`===`) equality. The result is the same either way:
+   * the target is only considered to be `NaN` if it's exactly `NaN`.


🛑 I feel like this is not relevant to the user here. If there is a genuine edge case that users should be wary of, we should consider it a bug and fix the edge case.

keithamus · 2017-01-27T11:09:24Z

lib/chai/core/assertions.js

+   * `undefined`. However, `.exist` should rarely be used. Whenever possible,
+   * it's best to assert that the target is equal to its expected value, rather
+   * than asserting that the target doesn't exist. See the `.equal` assertion
+   * for a better alternative.


💭 Again this pretty much feels like we should deprecate it.

keithamus · 2017-01-27T11:09:48Z

lib/chai/core/assertions.js

+   * results if a bug is later introduced in your code that changes the target's
+   * type. See the `.a` assertion for details on how to test a target's type.
+   *
+   *     expect([]).to.be.an('array').that.is.empty;


keithamus · 2017-01-27T11:10:13Z

lib/chai/core/assertions.js

+   *
+   *     expect({}, 'nooo why fail??').to.be.arguments;
+   *
+   * The alias `.Arguments` can be used interchangeably with `.arguments`.


keithamus · 2017-01-27T11:12:18Z

Quite a lot to get through here. I got up to arguments, will review the rest later. I've added some comments, but because this is so big I'll do some now and some later.

Key:

💭 - Just me expression thoughts, I won't block the review for these, but it might be nice to discuss these and maybe work to improve them, if you have time
🛑 - In my opinion, this should definitely change. This is why I have requested changes, fixing this will move my vote to approved
👍 - This is awesome work! Good job!

meeber · 2017-01-28T16:50:35Z

I'll hold off on commenting or making any changes until everyone (who wants to) has had a chance to perform a complete review.

One question though: Is it possible to add titled subsections to a particular assertion's docs? If so, how? My guess would be adding four pound signs like #### <subtitle>, but I don't know if that screws up how the website generation works in terms of headers and links in the sidebar?

lucasfcosta · 2017-01-28T16:56:20Z

lib/chai/core/assertions.js

+   *       .but.not.have.ordered.members([2, 1]);
+   *
+   * If both the `contains` and `ordered` flags are set, the ordering begins
+   * with the first element in the target.


Shouldn't it be the opposite? The ordering should follow the same order as the array given to the include assertion, right? I'm not sure it was just me that got it the wrong way but maybe this could be more clear.

lucasfcosta · 2017-01-28T17:18:21Z

lib/chai/core/assertions.js

-   *     expect([ 1, 2, 3 ]).to.eql([ 1, 2, 3 ]);
+   * The `deep.equal` assertion is almost identical to `.eql` but with one
+   * difference: `deep.equal` sets the `deep` flag which could impact other
+   * assertions that follow in the chain.


Hmmm, that's interesting. Good job!

lucasfcosta · 2017-01-28T17:20:27Z

lib/chai/core/assertions.js

@@ -968,19 +1492,32 @@ module.exports = function (chai, _) {
  });

  /**
-   * ### .instanceof(constructor)
+   * ### .instanceof(constructor[, msg])


Maybe we could add some text detailing that this fails whenever not passed a valid constructor instance and which criteria are used to determine whether something is valid or not.

During my update, I didn't really see the need to get into the details of this failing due to an invalid constructor instance. I think it's sufficiently understood by the assertion itself that it only passes when the target is an instance of the constructor, without drawing any distinction between a valid-but-different-constructor and an invalid constructor in the case of failure.

lucasfcosta · 2017-01-28T17:21:46Z

lib/chai/core/assertions.js

+   * Due to a compatibility issue, the alias `.length` can't be chained directly
+   * off of an uninvoked method such as `.a`. Therefore, `.length` can't be used
+   * interchangeably with `.lengthOf` in every situation. It's recommended to
+   * always use `.lengthOf` instead of `.length`.


lucasfcosta · 2017-01-28T17:24:25Z

Awesome job! I just left a few new minor comments.

I think this will be awesome for our contributors to read since it gives them so much information about how to use Chai effectively instead of just telling them how things work.

Great job! Also, @keithamus comments were great too, I agree with them all.

meeber · 2017-02-14T00:39:55Z

Note to self: Update .change, .increase, and .decrease docs to reflect change from chainable method to normal method.

keithamus · 2017-04-04T21:28:48Z

lib/chai/core/assertions.js

+   * `.eql` can be negated by adding `.not` earlier in the assertion chain, but
+   * it should rarely be done. Whenever possible, it's best to assert that the
+   * target is deeply equal to its expected value, rather than not deeply equal
+   * to one of countless unexpected values.


keithamus · 2017-04-04T21:33:51Z

lib/chai/core/assertions.js

+   * number greater than the given number `n`. However, `.above` should rarely
+   * be used. Whenever possible, it's best to assert that the target is equal to
+   * its expected value, rather than asserting that it's greater than some
+   * value. See the `.equal` assertion for a better alternative.


🛑 "doLength flag" is an internal thing. We shouldn't expose this to users.

💭 I think saying "should rarely be used" is a little heavy handed. Perhaps we could reword it? Something like:

.above should only be used when you cannot guarantee an exact amount. Wherever possible, one should use .equal instead.

keithamus · 2017-04-04T21:34:58Z

lib/chai/core/assertions.js

   *
-   *     expect(10).to.be.above(5);
+   * When the `doLength` flag is set, `.above` asserts that the value of the


🛑 Again, doLength is internals, let's write the assertion proper; with.length.above...

keithamus · 2017-04-04T21:36:16Z

lib/chai/core/assertions.js

+   *     expect([1, 2, 3]).to.have.lengthOf.above(2); // Not recommended
+   *
+   * `.above` can be negated by adding `.not` earlier in the assertion chain,
+   * but again, `.above` should rarely be used.


💭 Repeating ourselves here feels a little redundant. Mentioning best practices once per function doc feels sufficient.

keithamus · 2017-04-04T21:36:50Z

lib/chai/core/assertions.js

-   * ### .least(value)
+   * ### .least(n[, msg])
+   *
+   * When the `doLength` flag isn't set, `.least` asserts that the target is a


🛑 Another case of doLength mentioned.

keithamus · 2017-04-04T21:50:49Z

lib/chai/core/assertions.js

+   *     expect([1, 2, 3], 'nooo why fail??').to.have.lengthOf(2);
+   *
+   * Instead of invoking `.lengthOf` as a method, it can be used as a language
+   * chain to set the `doLength` flag, causing all `.above`, `.below`, `.least`,


🛑 doLength is internals. User's need not worry, just demonstrate the chain:

lengthOf can be chained with other assertions - for example above, below, least...

keithamus · 2017-04-04T22:35:51Z

lib/chai/core/assertions.js

+   *
+   * Asserts that the target is a number that's within a given +/- `delta` range
+   * of the given number `expected`. However, `.closeTo` should rarely be used.
+   * Whenever possible, it's best to assert that the target is equal to its


💭 another "rarely used" which is potentially hyperbolic.

keithamus · 2017-04-04T22:36:12Z

lib/chai/core/assertions.js

+   *     expect(1.5).to.be.closeTo(1, 1);
+   *
+   * `.closeTo` can be negated by adding `.not` earlier in the assertion chain,
+   * but again, `.closeTo` should rarely be used.


💭 more redundant "rarely used"

keithamus · 2017-04-04T22:40:56Z

lib/chai/core/assertions.js

+   * given function `subject` returns a different value when it's invoked before
+   * the target function compared to when it's invoked afterward. Strict (`===`)
+   * equality is used to compare `subject`'s before and after return values.
+   * `.change` should typically only be used when it has been negated by adding


🛑 should be something like ".change - when used with one argument - should typically only be used with .not."

keithamus · 2017-04-04T22:41:41Z

lib/chai/core/assertions.js

+   *
+   *     expect(noop).to.not.change(myObj, 'dots');
+   *
+   * `.change` should rarely be used without negation. Whenever possible, it's


🛑 Should be something like ".change with two arguments should rarely..."

keithamus · 2017-04-04T22:52:44Z

Okay @meeber I've reviewed all of this. Pretty much all great, I've got a few notes on some areas for concern though.

Largely I'm also sensing a theme - which is that these docs seem to suggest a lot of the assertions we provide have very limited use cases. Is this something we should be worried about? Taking a long look at the horizon, should we be slowly pushing these assertions into plugins?

meeber · 2017-04-05T00:22:20Z

Thanks for the review @keithamus. I know this was a tedious one to get through. I'll rebase once #947 is merged, go through all the feedback here, make changes, and update the PR.

Most assertions use the term "target" to refer to the object under test, but a few assertions also had a `target` argument, resulting in an overloaded term that was difficult to document. This commit renames every `target` argument to `subject`.

meeber · 2017-04-09T01:49:11Z

@keithamus @lucasfcosta @vieiralucas @shvaikalesh I just updated this PR. I made several passes through the whole thing to address concerns, improve readability, soften and de-formalize some language, move reference links closer to concepts, etc. If there are any major issues, let's fix them. But if all that's left is minor issues, then I vote we merge and proceed with the next canary release.

shvaikalesh · 2017-04-09T01:53:36Z

lib/chai/core/assertions.js

+   *     expect([{a: 1}]).to.deep.include({a: 1});
+   *     expect([{a: 1}]).to.not.include({a: 1});
+   *
+   *     // Target object deeply (but not strictly) includes `x: {a: 1}`


Missing curly braces: {x: {a: 1}}

That's actually intentional. In the previous example, braces are included because .include is looking for an object {a: 1} inside the target array. But in that example, braces aren't included because .include is looking for a property x with a value of {a: 1} in the target object. I think it would take too much verbiage to clarify this distinction within the docs, without enough gain, so I vote just leave as-is.

shvaikalesh · 2017-04-09T01:55:11Z

lib/chai/core/assertions.js

@@ -92,18 +117,19 @@ module.exports = function (chai, _) {
  /**
   * ### .nested
   *
-   * Sets the `nested` flag, later used by the `property` assertion.
+   * Enables dot- and bracket-notation in all `.property` and `.include`


Maybe we can link pathval here?

Not sure there's enough value with linking pathval. The value in linking deep-eql and type-detect is that they both have separate documentation that list rules and behaviors that are relevant to someone writing an assertion using those flags, but the documentation for pathval just provides documentation on a bunch of functions that are used when using the module independently of Chai. Since we're moving in the direction of having a bunch of micro libraries, I think we should only link those that provide direct relevant information to the Chai user.

shvaikalesh · 2017-04-09T01:57:06Z

lib/chai/core/assertions.js

-   * `.nested.property` special characters can be escaped by adding two slashes
-   * before the `.` or `[]`.
+   * If `.` or `[]` are part of an actual property name, they can be escaped by
+   * adding two backslashes before them.


Nit: second backslash is necessary only to escape the first one, unless one does

String.raw`\.link`

If we are targeting beginner-level devs, wording is OK 👍

Good point! I vote to keep as-is for now to be beginner friendly, but it might be interesting in the future to add another example using the single-slash alternative.

shvaikalesh · 2017-04-09T02:10:25Z

LGTM. Incredible job, @meeber! Love the consistency (wording, param names). Agreed on moving forward with merging.

lucasfcosta

I only thought about two possible changes, but nothing that could block this from being merged.
Awesome work.

lucasfcosta · 2017-04-09T15:20:05Z

lib/chai/core/assertions.js

+   *     expect(1).to.equal(1);
+   *     expect('foo').to.equal('foo');
+   * 
+   * Add `.deep` earlier in the chain to use deep equality instead. See the


Many users get confused about the behavior of deep when it comes to object's prototypes, maybe it would be cool for us to explain more about it here and avoid issues later.

I think deep equality is mentioned too many times throughout the documentation to go into detail about the algorithm. I prefer linking to the deep-eql project page instead where those kinds of details can go.

lucasfcosta · 2017-04-09T15:23:27Z

lib/chai/core/assertions.js

+   * ### .least(n[, msg])
+   *
+   * Asserts that the target is a number greater than or equal to the given
+   * number `n`. However, it's often best to assert that the target is equal to


IMO it makes thinks strange to have a feature and then discourage users to use it unless we show them a good reason to do it.
Maybe we could add a simple explanation telling them that when they assert something is not <other_thing> this means that something can be Inifinity - 1 things, which is too loose.

What do you think? I'm not sure this would be too much or not.

There's about a dozen assertions that fall into this category. I intend on making the argument post-4.x that a lot of them should be removed from core. For now I kinda took the strategy of gently steering users away from misusing these assertions by using language like "it's often best to do this other thing" and showing an example. For any such assertions that we end up keeping, I'd be in favor of adding a bit more explanation on when it is an appropriate time to use it.

@meeber I'm convinced.

LGTM.

keithamus · 2017-04-11T20:10:19Z

2 approvals makes a merge 😄

Good work, as always @meeber

keithamus requested changes Jan 27, 2017

View reviewed changes

lucasfcosta reviewed Jan 28, 2017

View reviewed changes

This was referenced Jan 30, 2017

fix: wrong assertion types #925

Merged

test: add .own.include and .nested.include #926

Merged

This was referenced Feb 7, 2017

respondTo throws TypeError on arrow functions #929

Closed

Chai needds a better way to assert the existence of an error #930

Closed

keithamus mentioned this pull request Feb 20, 2017

docs: update instanceof, throws docs to mention transpiler issues. #938

Closed

meeber force-pushed the update-docs branch from ed4fd84 to 1fc4a54 Compare February 21, 2017 02:15

keithamus mentioned this pull request Apr 4, 2017

Chai Roadmap #457

Closed

10 tasks

keithamus requested changes Apr 4, 2017

View reviewed changes

meeber added 2 commits April 8, 2017 09:23

style: rename target argument to subject

dce6415

Most assertions use the term "target" to refer to the object under test, but a few assertions also had a `target` argument, resulting in an overloaded term that was difficult to document. This commit renames every `target` argument to `subject`.

docs: overhaul bdd documentation

f80d699

meeber force-pushed the update-docs branch from 1fc4a54 to f80d699 Compare April 9, 2017 01:44

shvaikalesh reviewed Apr 9, 2017

View reviewed changes

lucasfcosta approved these changes Apr 9, 2017

View reviewed changes

keithamus approved these changes Apr 11, 2017

View reviewed changes

keithamus merged commit 526f885 into chaijs:master Apr 11, 2017

meeber deleted the update-docs branch August 6, 2017 13:49

HoldYourWaffle mentioned this pull request Apr 7, 2020

Throw custom error (ES6) #596

Closed

Overhaul bdd documentation #920

Overhaul bdd documentation #920

Conversation

meeber commented Jan 27, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keithamus commented Jan 27, 2017

Key:

meeber commented Jan 28, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucasfcosta commented Jan 28, 2017

meeber commented Feb 14, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keithamus commented Apr 4, 2017

meeber commented Apr 5, 2017

meeber commented Apr 9, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shvaikalesh commented Apr 9, 2017

lucasfcosta left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keithamus commented Apr 11, 2017

meeber commented Jan 27, 2017 •

edited

Loading