improve error reporting with configurable actual value description

If a test fails, we get output of the form
    Expected: <matcher.describeTo(...)>
    got: <actual.toString()>

Since the matcher necessarily knows about the object being matched
("actual") it seems to makes sense to allow the matcher to describe the
(failed) matched object as it wishes.

One suggestion is to add a method to Matcher to the effect of
describeMatched(Object/T actual), and replacing actual.toString() in the
above with matcher.describeMatched(actual) would give better reporting.
(This name can certainly be improved, maybe even just describe()? Further,
there may be better ways of implementing this to get the information into
the "got" output.)

This is useful, for example, in the case that the object being tested has a
toString() implementation that doesn't give information useful as an
expected value, but the matcher is testing some property not written into
the string.

Concrete example: an ActiveMQ queue returns something of the form
"<queue://queue_name>". If we are making an assertion about the number of
messages currently on the queue, the "got" message is entirely unhelpful,
when we read
    Expected: hasDepth(6)
    got: <queue://name>

The workaround is to add this information into the "expected" string by
caching the result of the test (in this case the queue depth) in the
matcher. This doesn't exactly feel elegant.

A default implementation in BaseMatcher could just return
actual.toString(), so however this change is implemented, it should be
fully backwards compatible.

Original issue reported on code.google.com by joe.kear...@gtempaccount.com on 22 Apr 2008 at 11:45

hardayal / hamcrest

improve error reporting with configurable actual value description #36