ext.test4j.hamcrest.Matcher Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of test4j.nodep Show documentation

There is a newer version: 2.5.0

/*  Copyright (c) 2000-2006 hamcrest.org
 */
package ext.test4j.hamcrest;

/**
 * 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 {@link BaseMatcher} abstract class, which will
 * ensure that the Matcher API can grow to support new features and remain
 * compatible with all Matcher implementations.
 * 

 * For easy access to common Matcher implementations, use the static factory
 * methods in {@link CoreMatchers}.
 * 
 * @see CoreMatchers
 * @see BaseMatcher
 */
public interface Matcher extends SelfDescribing {

	/**
	 * Evaluates the matcher for argument item.
	 * 
	 * This method matches against Object, instead of the generic type T. This
	 * is because the caller of the Matcher does not know at runtime what the
	 * type is (because of type erasure with Java generics). It is down to the
	 * implementations to check the correct type.
	 * 
	 * @param item
	 *            the object against which the matcher is evaluated.
	 * @return true if item matches, otherwise
	 *         false.
	 * 
	 * @see BaseMatcher
	 */
	boolean matches(Object actual);

	/**
	 * 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.
	 * 
	 * @param item
	 *            The item that the Matcher has rejected.
	 * @param mismatchDescription
	 *            The description to be built or appended to.
	 */
	void describeMismatch(Object item, Description mismatchDescription);
}