hamcrest/JavaHamcrest — pull request #28 by louisth (2013-02-06 06:10:50+00:00)
Title: Improve describeMismatch output across the board.

After running into confusing output from describeMismatch and reading the discussion at hamcrest/JavaHamcrest#9, I have tackled the problem head on. I believe @ihaworth has the right idea. Instead of trying to describe the failure, we need to describe the given item from the Matcher's point of view. According to this contract for describeMismatch, the existing implementations are basically correct.

What I've done is three things.

1. I extended and revised the Javadoc to specify this new contract for describeMismatch:
```
/**
* Generates a description of the given item from the Matcher's point of view.
* The description will be part of a larger description of why a matching
* failed, so it should be concise.
* The description should be able to replace Y in the sentence "Expected X but Y," and
* should be in the past tense, for example, "Expected null but

was <"foo">

."
* The description should NOT describe the matcher, but rather should highlight features of interest on the item as they actually are.
* The description must ALWAYS be filled in, regardless of return value of {@link #matches}.
*/
```
(DescribeMismatch is now rather misnamed, but I leave it to the maintainers to decide whether they want to break backwards compatibility to fix this.)

2. I wriote DescribeMismatchTortureTest, which calls describeMismatch on EVERY matcher in Hamcrest. I used not() with every matcher. I used a variety of matcher compositions including anyOf() and allOf(), and sub-matchers with a variety of descriptions, such as equalTo(), instanceOf(), and startsWith(). I matched against a variety of target objects. I'm there are interesting cases I missed but it's a start. What's nice is the torture test allows us to see if a description is phrased right to fit in a variety of contexts. It also allows us to check for reasonable consistency across all the matchers.

3. I fixed every broken description and mismatch description until every test in the torture test produced a reasonable result. Improvements are welcome, but I think this is a good start.

For anyone disagrees with my solution and wants to try their own hand at tackling this problem, I encourage you to at least grab the torture test. I think it does a pretty good job of illustrating and exercising the complexity of the problem.