.length(value) deprecation

I noticed that the documentation says:

Deprecation notice: Using length as an assertion will be deprecated in version 2.4.0 and removed in 3.0.0. Code using the old style of asserting for length property value using length(value) should be switched to use lengthOf(value) instead.

But I also noticed that chai is on 3.5.0 and .length(value) seems to still be a thing. Am I missing something here?

[meeber]

Since discussion restarted on this in #841, now seems like a good time to make a decision regarding .length. Here’s a summary of the problem and our options:

The problem is that .length throws an error when chained directly off of an uncalled chainable method (e.g., .a.length). In the past, it threw errors in more situations, but #642 narrowed it down to only this one situation. The reason this problem exists is because .length is a builtin property of functions in JavaScript, and the reason it can’t be fixed by just deleting the builtin .length property and replacing it with Chai’s .length is because in legacy environments such as Node v0.12 and IE 11, the .length property is non-configurable.

It’s worth noting that no issues regarding this problem have been opened on Chai’s issue tracker since #642 was implemented; all discussions about it have instead been triggered by someone asking about why .length is being deprecated. I consider it a low impact problem, both because it’s rarely triggered, and because it fails loudly by throwing an error message instead of doing something more destructive, such as silently passing an invalid assertion.

Options:

1. Completely remove all forms of .length from Chai. From a purely ideological standpoint, I think this is the best option, and it would’ve been my preferred option near the beginning of the project. However, at this point in the project, I believe that this ends up being a high-impact solution for a low-impact problem. In other words, the cost of this breaking change would be far greater than the benefit of fixing the bug, even if a codemod was shipped to help users update their assertions. Therefore, I’m opposed to this option.

2. Fix the bug in ES6 environments (meaning it will still fail in legacy environments). I’m no longer in favor of this option. The same tests having different results between different environments supported by Chai is too costly to some users, even though it fixes the bug for the majority of users.

3. Use proxies to provide a more user-friendly error message in ES6 environments (meaning it will still fail in all environments). This is my favorite option. The behavior remains consistent among all environments given that an error is always thrown, but in most environments we’re able to provide a more descriptive error message to our users. And in the future when we no longer support pre-ES6 legacy environments, we can circle back to this issue and fix it for good by implementing Option 2.

4. Do nothing. Given that Option 3 doesn’t have any cost to users, I don’t see any advantage to this option over Option 3. Therefore, I’m opposed to this option.

Let’s figure out where everyone stands on this issue and move forward with an option for 4.0.

[keithamus]

Well articulated @meeber. I’ve been putting thought into this myself and came up with the same conclusion as I think you have: I think door number 3 - explicitly erroring in <function>.length scenarios for ES6 to highlight problems on both ES6 & ES5 environments.

As you mentioned above, the only real case for this should be where a method assertion is used right before a keyword - for chai core this is only a/an but we could probably detect whatever method it was, and provide an appropriate error message…

Error: you used `.have.a.length(1)` but due to an edge case in older browsers `a.length` won't work. Please use `.have.length(1)` instead.

To misquote Lt James Gordon, it’s not the fix we deserve but it is the fix we need.