map allows you to transform the expression to another value, and then run that new value against another matcher.
I find map to be most useful when combined with satisfyAllOf, as a kind of "fuzzy equals" matcher. Or, when you only care about some parts of a value matching but not other.
In fact, without composing map with satisfyAllOf, I don't really see the point of map at all. After all expect(foo.property).to(equal(1)) is much more readable and succinct than expect(foo).to(map(\.property, equal(1)))).
I also added some guidance for when to use map. In my view, map sits in a weird case where you want to check multiple multiple properties of a value at the same time (perhaps as part of a toEventually-style matcher), but don't want the value to conform to Equatable, nor do you check that value enough to write a custom matcher for it.
Some trivia: Originally, this matcher was named lens, from the functional programming concept. However, I changed it to map which is both closer to how it's actually used/written, and much more idiomatic to swift.
Checklist - While not every PR needs it, new features should consider this list:
[x] Does this have tests?
[x] Does this have documentation?
[ ] Does this break the public API (Requires major version bump)?
[x] Is this a new feature (Requires minor version bump)?
mapallows you to transform the expression to another value, and then run that new value against another matcher.I find
mapto be most useful when combined withsatisfyAllOf, as a kind of "fuzzy equals" matcher. Or, when you only care about some parts of a value matching but not other.In fact, without composing
mapwithsatisfyAllOf, I don't really see the point ofmapat all. After allexpect(foo.property).to(equal(1))is much more readable and succinct thanexpect(foo).to(map(\.property, equal(1)))).I also added some guidance for when to use
map. In my view,mapsits in a weird case where you want to check multiple multiple properties of a value at the same time (perhaps as part of atoEventually-style matcher), but don't want the value to conform to Equatable, nor do you check that value enough to write a custom matcher for it.Some trivia: Originally, this matcher was named
lens, from the functional programming concept. However, I changed it tomapwhich is both closer to how it's actually used/written, and much more idiomatic to swift.Checklist - While not every PR needs it, new features should consider this list: