Added includeDeepMembers

[qbolec]

This is a proposition to add assert.includeDeepMembers.
It's a second attempt, as previous #588 was flawed due to my ignorance of git.
Hopefully now we can discus a the merit of the change, as I have some doubts:

• is it ok that includeDeepMembers and includeMembers ignore duplicates in the subset argument? I'd expect the function to ignore order, but not quantity of elements to be a useful feature for some scenarios (same question for sameDeepMembers, and sameMembers). The motivating example is when I want to make sure that one array is permutation of another one.
• I've added a testcase to explicitly document current behaviour described above. Is it ok to add such tests or is it unnecessarily constraining future modifications of implementation? I'm not sure if I describe my dilemma clearly, so let me paraphrase it: if the specification of a function is quite general, should the tests be more precise than the spec or be as general as the spec? I see benefits on both sides.

[keithamus]

Thanks @qbolec for the PR.

includeDeepMembers only checks that all members in the expected value are present in the actual value. So when it comes to duplicate values - I think this is acceptable. If you want a stricter checking - including that of length, then have.deep.members (haveDeepMembers) would be the more appropriate test. Unless you think we should add another one?

To answer your question about tests: yes - the tests are the spec for the assertion, so the more tests the better. If we decide that it is doing undesirable things then we can change the behaviour in a breaking version - we shouldn't be afraid to do that.

How do you feel about the above? Happy for me to merge this or want to discuss some more?

[qbolec]

Not sure if we understand each other.
Currently all of these assertions pass:

[1,2,3].should.have.deep.members([3,2,1,3]);
[1,2,3].should.deep.include.members([3,2,1,3]);
chai.assert.sameDeepMembers([1,2,3],[3,2,1,3]);

while I think they should all fail, or at least there should be some switch, option, or other method which would make them fail, as otherwise it is not trivial to implement a check for being a permutation.

[keithamus]

[1,2,3].should.have.deep.members([3,2,1,3]);
[1,2,3].should.deep.include.members([3,2,1,3]);
chai.assert.sameDeepMembers([1,2,3],[3,2,1,3]);

Hmm, as I understood the point, and in my opinion, include should be the only one that passes. This is something we definitely need to address - but let's get this PR merged, and raise a new issue to discuss the semantics of the above assertions, sound good?

[qbolec]

Sounds good to me :)