Keys for maps and sets

[lucasfcosta]

Hello everyone, this PR aims to solve #632.

Here's a summary of the changes I made:

1. I am using .some() instead of .filter() when checking for any keys. There is no need to calculate the full size of intersections (intersection > 0), if we have one it's already bigger than 0 therefore we don't need to iterate through everything.
2. I had to change the mixedArgs message because keys assertion now accepts objects as keys (as I've said on Add assertions for ES6 Maps and Sets #632).
3. When checking maps and sets' keys we need to compare objects, that's why I'm using _.eql(expectedKey, actualKey).
4. I noticed that the assert interface had no keys related methods, so I added every possible combination (any/all/contains/have - Please notice that some of these combinations have the same meaning, as explained on the keys method description, so I added only the ones with different effects)
5. I included tests for these changes on all three interface's test files.
6. Every method I've touched got it's JSDoc comments updated (examples were included too).

PS.: When creating these tests I've had to use if (Maps !== undefined) and if (Sets !== undefined) because apparently PhantomJS 1.9 uses an engine that hasn't implemented these specs yet.

Feel free to point possible mistakes and give feedback or new ideas.

Thanks everyone

[keithamus]

Would be good to have an example of passing multiple objects as keys here.

[lucasfcosta]

Yes, it would be good!
Totally forgot it, thanks for pointing this

[keithamus]

Only a couple of minor points above. Otherwise this looks awesome @lucasfcosta. Great work, as usual 😄

[lucasfcosta]

Thanks, @keithamus!
Your feedback is great as usual too 😄

Well, I'm aware _.eql uses deep equality and I've used it because when, for example, a Map has an object as Key and I compare the objects (even if they're equal) I will get false as result because === checks for referential equality, therefore this, for example, wouldn't work:

expect(new Map([[{objKey: 'value'}, 'value'], [1, 2]])).to.contain.key([{objKey: 'value'}]);

This will fail, because although the object used as key on the map is depply equal to the one passed to the .key assertion they're not the same so === will return false. If you want to check for referential equality only then I feel like we should use ===.

[keithamus]

@lucasfcosta sure, I expected you to say as much - I should have elaborated more in my original comment, but got a little side tracked with other things.

Deep equality is going to be sometimes desirable within Maps, but sometimes referential equality will be desirable. If we start with using referential equality, we can always move to deep equality later - by adding the .deep qualifier. We won't be able to (easily) do the same the other way around.

[lucasfcosta]

Ah, I understand now and I totally agree, it really seems to be the right step. I haven't thought about it before.
I can also implement the deep check when there is a deep flag if you want me to.

Thanks for the explanation, I'll make sure to update this PR with the changes we talked about ASAP 😃

[keithamus]

We can tackle the deep flag in another PR, to keep this one simple 😄

[lucasfcosta]

This one is done! 🎉
I look forward to implementing the deep flag support on another PR later, if you don't mind. I feel like it would be very useful when it comes to Maps and Sets.

And thanks again for your support!

[sukrosono]

@lucasfcosta awesome 😄

[keithamus]

Fantastic work as usual @lucasfcosta. Feel free to make a PR adding support for deep Map/Set keys 😄

[lucasfcosta]

Thanks @keithamus, I'll certainly do it 😄

[sukrosono]

close #632 ?