Map entry matchers

[tomwhoiscontrary]

This is a reboot of an earlier PR, #123. I raised that one, we discussed it, you merged it onto the 2.0.0.0 branch, but it never made it into master. I've cherry-picked it onto master. If you still think it's worthwhile, this might be a more useful PR to merge. I don't know if there are differences between master and 2.0.0.0 that would influence the implementation, so please shout if you know of any.

This adds two complementary matchers for working with maps.

The main matcher is IsMapWithEntries, which is just a FeatureMatcher for Map::entrySet. This is essentially an escape hatch from the world of maps to the world of true collections; it allows a user to write matches on maps in terms of their set of entries, using the rich set of matchers available for collections (principally contains and friends).

The second matcher is IsMapEntry, which makes it easy to write matches on the map entries themselves.

I end up writing these two matchers, in some form, in most projects i work on, because this approach so useful. Specifically, i think it's much more useful to be able to view maps as collections than it is to have a range of matchers specifically for maps.

It's possible i'm simply insane, and nobody else will find these useful. But just in case they do, here they are!

[tumbarumba]

Hi @tomwhoiscontrary, I'm preparing a new release (issue #224). I think this should be in the release, but I'm concerned it's been 3 years since the last check. Are you able to update CHANGES.md on this branch to trigger a new build, and verify it still works?

[sf105]

Looking at it again, how does this differ from the current IsMapContaining.hasEntry()? Would a better answer be to improve the error reporting?

[tomwhoiscontrary]

This PR is two semi-connected matchers.

The point of IsMapWithEntries is to move you from matching a map to matching a collection. That means you can do things like hasEntries(containsInAnyOrder(...)) to say "this map contains these keys and values, and nothing else", which you can't currently do with Hamcrest. When i'm testing code around the edges of JSON interfaces, i often want to do that. And i often want to make assertions on nested maps, where i can't just call .entrySet() on the map and then match on that, because the map is nested inside another map.

IsMapEntry is a lot like IsMapContaining, but it matches a Map.Entry, so it can be used with IsMapWithEntries.

The mismatch messages in IsMapContaining, as you mention, aren't very useful. If you have an entry with the right key but the wrong value, you just get a "map was ...", without any indication of why it didn't match. Ideally, if you had an entry with the right key but a duff value, you would get the mismatch description from the value matcher. This PR doesn't address that, though.

The map matchers i write in my own projects these days don't look quite like this any more. I will try to have a look tomorrow to see if i have anything more useful.

[sf105]

Thanks. I'll wait for your further comments.

[nhojpatrick]

@tomwhoiscontrary happy to look at again, trying to kick start the project again. Can you rebase from master as hamcrest-core and hamcrest-library has been merged into hamcrest so can't currently merge in anyway.

[nhojpatrick]

Going to try and kick start hamcrest, so if you want to get it merged, please rebase from the branch v2.3-candidates. Still trying to understand how has permissions to perform a release.