IMO if we're going to deviate from CommonJS spec, then the docs for assert should warn about this and provide a detailed description of their actual behavior.

This is how they do it in ringo: https://github.com/ringo/ringojs/blob/f06dd6d0c235a0c22fc50ec6ca59209e560da396/modules/assert.js#L92

Can anyone review this? @chrisdickinson or @cjihrig maybe?

This is how they do it in ringo: https://github.com/ringo/ringojs/blob/f06dd6d0c235a0c22fc50ec6ca59209e560da396/modules/assert.js#L92

A comment in the source code doesn't really cut it.

@seishun it's not a about the comment. Some facts:

• CommonJS spec has a bug;
• CommonJS spec is dead;
• node.js/io.js documentation never mentions that assert has anything to do with CommonJS;
• even ringojs, which claims that it is "CommonJS-based" and implements Unit Testing 1.0 (http://ringojs.org/documentation/commonjs_implementation) doesn't follow this part of the spec*
• assert already deviates from CommonJS spec.

The code looks fine, but this goes against what I would consider "deep equal."

I think a larger conversation needs to happen around the assert module. People are constantly identifying shortcomings and bugs in the implementation, but everyone is reluctant to change it because of CommonJS.

The code looks fine, but this goes against what I would consider "deep equal."

Can you elaborate? Do you mean this particular change or overall deepEqual implementation?

node.js/io.js documentation never mentions that assert has anything to do with CommonJS;

It doesn't explain what "deep equality" means either, which makes it "obvious" that it uses the algorithm from the buggy and dead spec. Let's not follow ringojs in confusing users even more.

The code looks fine, but this goes against what I would consider "deep equal."

Can you elaborate? Do you mean this particular change or overall deepEqual implementation?

I mean that I would expect a deepEqual implementation to examine the prototype, either using === or a call to objEquiv(). Again, I personally think the current assert methods need to be revisited in general.

@cjihrig this is covered by #639. I decided would be this best course of action. This PR is a bugfix (semver patch), #639 is a new feature (semver minor). Changing deepEqual behaviour would require major bump, which I think is not justified in this case.

I'm not comfortable providing sign-off on this, I'm more of a -0 on this

@vkurchatkin do you see this as a necessary part of #639?

@rvagg no, I don't. But since they share implementation deepStrictEqual will check prototype too. It's not something that we want in a brand new function (I guess), so I should add a condition to skip it in strict mode

As discussed at TC meeting, CommonJS spec is not relevant anymore. I will land this as soon as I see a couple of LGTMs.

Left a comment. Otherwise LGTM.

removed a.AssertionError. don't really want to drop assert.doesNotThrow, because the intention is to test deepEqual, not that two random objects are equal. what do you think?

I think that assert.doesNotThrow in general is a bit point pointless. It doesn't matter for this PR though. LGTM!

Thanks! landed in e7573f9

In the last TC meeting, I think there was some discussion about holding off on this until 2.0.0.

I'm pretty sure it wasn't. There was some confusion with #621 though . That WAS a breaking change, this is merely a bugfix

OK, cool. Sorry for the confusion.

May i add that i consider assert.deepEqual and friends to be broken, and that this is because the CommonJS assert specs do not make much sense. I understand that spec is no more considered relevant here? If so, that's a good thing.

First of all, the API is horrible. Logically, either two things are equal or they're not, but assert has no less than eight methods: equal, notEqual, deepEqual, notDeepEqual, strictEqual, notStrictEqual, deepStrictEqual, notDeepStrictEqual. If we concede that the not methods are really needed, there's still four competing concepts of 'equality' here: plain equal, deep (and plain) equal, strict equal, and deep strict equal. There should be only a single equality comparison (with two API methods as its negation is needed) with 'deep' equality covering all cases of 'shallow' equality.

As i try to show in jseq, the concept of 'equality' can lead to some hairy questions when it meets the reality of a language like JavaScript with its NaN and +0 vs –0 and so on. What is easier to see is that there's object identity, value equality, and, quite apart from this, as many kinds of 'equivalence' as you have use cases for. I'd argue that only what is currently available as assert.(not)deepStrictEqual approaches a satisfyingly logical, good-enough implementation for 'equality'; the other three concepts are either bogus or mere equivalence (that is, there may be use cases where '456' can stand in for 456, but those two values should never be considered 'equal', and this kind of comparison should not be made part of a standard library—bad enough some people still use == at all).

I suggest to introduce assert.eq (?) and assert.neq (?) (anyway, two snappy names), and remove all the other equality tests. Additionally, the behavior of eq should be based on the outcome of a new util.equals method that does sound deep and shallow equality testing. As for hairy borderline cases (NaN, –0), maybe those should be made configurable.

I agree that non-strict equality is not really useful for assertions (or more like not useful at all). On the other hand, shallow equality is important. There is no way to know if objects should be treated as values or having identity.

It is unlikely that something would be added (or removed) to assert. Recent amendments were made only to fix inadequate behaviour in non-breaking manner. There are many ways to do assertions (extend prototypes, etc) and they can live nicely in npm.

I fully understand the part where one wants to avoid breaking existing code and, therefore, keeps 'strange methods with strange behaviors' around and just adds new methods with 'better behavior'. Although if this principle is the only evolutional guideline then NodeJS will become ever more PHP-ish over the years (assert is already the most PHP-ish part of NodeJS/io.js).

I don't get where the difference between shallow and deep equality is important. 4 equals 4 and does not equal '4', [ 4 ], 5 or { foo: 4 }. { foo: { bar: 4 } } equals { foo: { bar: 4 } } and does not equal { foo: { baz: 4 } } or 4 or anything. And object identity, i argue, is something completely different. I think Python got this one right, in a very clear manner (although i know about some flaws in their concepts); if you want identity, you say a is b, a is not b ; if you want equality, you say a == b, a != b in Python.

This is really a semantic problem, and i guess where we can meet is saying that assert.strictEqual should really be assert.is—that is, the API's flaw is not that there is a method too much, but that its name is infelicitous, as it is neither about 'strictness' (?) nor is it about 'equality' but, plainly, object identity (which happens to overlap with equality for primitive values). The API feels so PHP-ish because PHP is renowned for having many broken methods and lots and lots of infelicitous naming decisions.

@cjihrig "I mean that I would expect a deepEqual implementation to examine the prototype, either using === or a call to objEquiv()"—goes to show how hairy equality can become. I'd say that if some properties of all the properties x.a, x.b, x.c of some object x are visible because of a prototype X that has, say, a and b, than that value x can not be considered equal to an object y that has y.b as an own property and only y.a through its prototype Y.a. I doubt that many equality testing suites do test for that.