/*
* Copyright 2010 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package spock.util.matcher;
import org.hamcrest.Matcher;
import org.spockframework.runtime.InvalidSpecException;
public class HamcrestSupport {
/**
* Used to match a value against a (Hamcrest) matcher.
* Only allowed in places where a condition is expected
* (expect-block, then-block, after an 'assert' keyword).
*
* <p>Basic example:
*
* <pre>
* import static spock.util.matcher.HamcrestSupport.that
* import static org.hamcrest.CoreMatchers.equalTo // ships with JUnit
*
* def foo = 42
*
* expect:
* that(foo, equalTo(42))
* </pre>
*
* Note that Spock supports an even simpler syntax for applying matchers:
*
* <pre>
* expect:
* foo equalTo(42)
* </pre>
*
* However, the simpler syntax cannot be used in explicit conditions
* (i.e. after the 'assert' keyword), and may not be as IDE-friendly.
* That's why this method is provided as an alternative.
*
* <h3>When would I use matchers?</h3>
*
* <p>Due to Spock's good diagnostic messages and Groovy's expressivity,
* matchers are less often needed than when, say, writing JUnit tests
* in Java. However, they come in handy when more complex conditions
* are required (and possibly repeated throughout a project).
* In such cases, Spock's Hamcrest integration provides the best of two worlds:
* the diagnostic messages known from Spock's conditions, and the
* custom failure messages of Hamcrest matchers.
*
* <h3>Third-party matchers</h3>
*
* <p>The matchers that ship with JUnit aren't very useful per se.
* Instead, you will want to use matchers from Hamcrest
* (http://code.google.com/p/hamcrest/) or other libraries. Both Hamcrest
* 1.1 and 1.2 are supported. You can also write your own matchers,
* building up a matcher library that's specific to the needs of your project.
*
* @param value the actual value
* @param matcher a matcher describing the expected value
* @param <T> the actual value's type
*/
@SuppressWarnings("UnusedDeclaration")
public static <T> void that(T value, Matcher<? super T> matcher) {
throw new InvalidSpecException("that() can only be used where a condition is expected");
}
/**
* Alias for {@link #that(Object, org.hamcrest.Matcher)} intended for use in then-blocks.
*
* @param value the actual value
* @param matcher a matcher describing the expected value
* @param <T> the actual value's type
*/
@SuppressWarnings("UnusedDeclaration")
public static <T> void expect(T value, Matcher<? super T> matcher) {
that(value, matcher);
}
}