Matcher
A matcher over acceptable values. A matcher is able to describe itself to give feedback when it fails.
Matcher implementations should NOT directly implement this interface. Instead, extend the BaseMatcher abstract class, which will ensure that the Matcher API can grow to support new features and remain compatible with all Matcher implementations.
When using Hamcrest, there is no guarantee as to how often matches() or describeMismatch() will be called, so the objects passed as actual arguments should not change when referenced. If you're testing a stream, a good practice is to collect the contents of the stream before matching.
N.B. Well designed matchers should be immutable.
See also
Inheritors
Functions
This method simply acts a friendly reminder not to implement Matcher directly and instead extend BaseMatcher. It's easy to ignore JavaDoc, but a bit harder to ignore compile errors .
Generate a description of why the matcher has not accepted the item. The description will be part of a larger description of why a matching failed, so it should be concise. This method assumes that matches(item) is false, but will not check this.
Generates a description of the object. The description may be part of a a description of a larger object of which this is just a component, so it should be worded appropriately.