Special case maps with only value keys

[natebosch]

Closes #2256

When checking deep equality on Map instances (including maps nested in
other collection types) we allow keys which are instances of other
collection (and don't have a useful operator ==) and keys which are
Condition callbacks that could potentially match multiple keys of the
actual value. This is maximally flexible, but it loses the nested path
information we are otherwise able to keep for iterables compared by
index.

Check whether expectation maps have any keys which need this special
treatment, and if not, special case to an algorithm close to the
Iterable algorithm which can enqueue nested checks and maintain the
direct known path into the collection.

Update the doc comment to describe the new behavior. This does
potentially introduce confusion since a change which adds a Condition
key has to potential to make other keys in the same expectation
behaved differently. The benefit is a more actionable failure output for
the much more common case of checking expectations with hardcoded keys.

[natebosch]

@jakemac53 - WDYT about this behavior?

[jakemac53]

Sounds pretty reasonable to me.

[gnprice]

This looks great, thank you!

This does
potentially introduce confusion since a change which adds a Condition
key has to potential to make other keys in the same expectation
behaved differently

To make sure it's visible on this thread too: I just replied to a remark about this on the issue. It's possible to give a fun demo for this, in fact (#2256 (comment)), using as actual a SplayTreeMap with both 0.0 and -0.0 as keys, so that turning a different expected key from a plain value to a Condition turns the check from passing to failing.

But I think it's the case that that sort of behavior can only come about when one of the maps involved doesn't behave consistent with how a Map is supposed to behave (like in that demo, where it has two ==-equal keys). And I think it's appropriate for a general-purpose test-assertion library like this one to rely on the invariants of Map and so on; it needs some kind of structure in order to make sense of things at all.

[natebosch]

I'm pretty happy with how this is working as I use it. I think we should land this.

[github-actions]

PR Health

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

Package publish validation ✔️

Package	Version	Status
package:checks	0.3.1-wip	WIP (no publish necessary)
package:test	1.25.9-wip	WIP (no publish necessary)
package:test_api	0.7.4-wip	WIP (no publish necessary)
package:test_core	0.6.6-wip	WIP (no publish necessary)

Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.