Package org.hamcrest

Class CoreMatchers


  • public class CoreMatchers
    extends java.lang.Object
    • Constructor Summary

      Constructors 
      Constructor Description
      CoreMatchers()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> Matcher<T> allOf​(java.lang.Iterable<Matcher<? super T>> matchers)
      Creates a matcher that matches if the examined object matches ALL of the specified matchers.
      static <T> Matcher<T> allOf​(Matcher<? super T>... matchers)
      Creates a matcher that matches if the examined object matches ALL of the specified matchers.
      static <T> Matcher<T> any​(java.lang.Class<T> type)
      Creates a matcher that matches when the examined object is an instance of the specified type, as determined by calling the Class.isInstance(Object) method on that type, passing the the examined object.
      static <T> AnyOf<T> anyOf​(java.lang.Iterable<Matcher<? super T>> matchers)
      Creates a matcher that matches if the examined object matches ANY of the specified matchers.
      static <T> AnyOf<T> anyOf​(Matcher<? super T>... matchers)
      Creates a matcher that matches if the examined object matches ANY of the specified matchers.
      static Matcher<java.lang.Object> anything()
      Creates a matcher that always matches, regardless of the examined object.
      static Matcher<java.lang.Object> anything​(java.lang.String description)
      Creates a matcher that always matches, regardless of the examined object, but describes itself with the specified String.
      static <LHS> CombinableMatcher.CombinableBothMatcher<LHS> both​(Matcher<? super LHS> matcher)
      Creates a matcher that matches when both of the specified matchers match the examined object.
      static Matcher<java.lang.String> containsString​(java.lang.String substring)
      Creates a matcher that matches if the examined String contains the specified String anywhere.
      static Matcher<java.lang.String> containsStringIgnoringCase​(java.lang.String substring)
      Creates a matcher that matches if the examined String contains the specified String anywhere, ignoring case.
      static <T> Matcher<T> describedAs​(java.lang.String description, Matcher<T> matcher, java.lang.Object... values)
      Wraps an existing matcher, overriding its description with that specified.
      static <LHS> CombinableMatcher.CombinableEitherMatcher<LHS> either​(Matcher<? super LHS> matcher)
      Creates a matcher that matches when either of the specified matchers match the examined object.
      static Matcher<java.lang.String> endsWith​(java.lang.String suffix)
      Creates a matcher that matches if the examined String ends with the specified String.
      static Matcher<java.lang.String> endsWithIgnoringCase​(java.lang.String suffix)
      Creates a matcher that matches if the examined String ends with the specified String, ignoring case.
      static <T> Matcher<T> equalTo​(T operand)
      Creates a matcher that matches when the examined object is logically equal to the specified operand, as determined by calling the Object.equals(java.lang.Object) method on the examined object.
      static Matcher<java.lang.Object> equalToObject​(java.lang.Object operand)
      Creates an IsEqual matcher that does not enforce the values being compared to be of the same static type.
      static <U> Matcher<java.lang.Iterable<? extends U>> everyItem​(Matcher<U> itemMatcher)
      Creates a matcher for Iterables that only matches when a single pass over the examined Iterable yields items that are all matched by the specified itemMatcher.
      static <T> Matcher<java.lang.Iterable<? super T>> hasItem​(Matcher<? super T> itemMatcher)
      Creates a matcher for Iterables that only matches when a single pass over the examined Iterable yields at least one item that is matched by the specified itemMatcher.
      static <T> Matcher<java.lang.Iterable<? super T>> hasItem​(T item)
      Creates a matcher for Iterables that only matches when a single pass over the examined Iterable yields at least one item that is equal to the specified item.
      static <T> Matcher<java.lang.Iterable<T>> hasItems​(Matcher<? super T>... itemMatchers)
      Creates a matcher for Iterables that matches when consecutive passes over the examined Iterable yield at least one item that is matched by the corresponding matcher from the specified itemMatchers.
      static <T> Matcher<java.lang.Iterable<T>> hasItems​(T... items)
      Creates a matcher for Iterables that matches when consecutive passes over the examined Iterable yield at least one item that is equal to the corresponding item from the specified items.
      static <T> Matcher<T> instanceOf​(java.lang.Class<?> type)
      Creates a matcher that matches when the examined object is an instance of the specified type, as determined by calling the Class.isInstance(Object) method on that type, passing the the examined object.
      static <T> Matcher<T> is​(Matcher<T> matcher)
      Decorates another Matcher, retaining its behaviour, but allowing tests to be slightly more expressive.
      static <T> Matcher<T> is​(T value)
      A shortcut to the frequently used is(equalTo(x)).
      static <T> Matcher<T> isA​(java.lang.Class<T> type)
      A shortcut to the frequently used is(instanceOf(SomeClass.class)).
      static <T> Matcher<T> not​(Matcher<T> matcher)
      Creates a matcher that wraps an existing matcher, but inverts the logic by which it will match.
      static <T> Matcher<T> not​(T value)
      A shortcut to the frequently used not(equalTo(x)).
      static Matcher<java.lang.Object> notNullValue()
      A shortcut to the frequently used not(nullValue()).
      static <T> Matcher<T> notNullValue​(java.lang.Class<T> type)
      A shortcut to the frequently used not(nullValue(X.class)).
      static Matcher<java.lang.Object> nullValue()
      Creates a matcher that matches if examined object is null.
      static <T> Matcher<T> nullValue​(java.lang.Class<T> type)
      Creates a matcher that matches if examined object is null.
      static <T> Matcher<T> sameInstance​(T target)
      Creates a matcher that matches only when the examined object is the same instance as the specified target object.
      static Matcher<java.lang.String> startsWith​(java.lang.String prefix)
      Creates a matcher that matches if the examined String starts with the specified String.
      static Matcher<java.lang.String> startsWithIgnoringCase​(java.lang.String prefix)
      Creates a matcher that matches if the examined String starts with the specified String, ignoring case
      static <T> Matcher<T> theInstance​(T target)
      Creates a matcher that matches only when the examined object is the same instance as the specified target object.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • CoreMatchers

        public CoreMatchers()
    • Method Detail

      • allOf

        public static <T> Matcher<T> allOf​(java.lang.Iterable<Matcher<? super T>> matchers)
        Creates a matcher that matches if the examined object matches ALL of the specified matchers. For example:
        assertThat("myValue", allOf(startsWith("my"), containsString("Val")))
        Type Parameters:
        T - the matcher type.
        Parameters:
        matchers - all the matchers must pass.
        Returns:
        The matcher.
      • allOf

        @SafeVarargs
        public static <T> Matcher<T> allOf​(Matcher<? super T>... matchers)
        Creates a matcher that matches if the examined object matches ALL of the specified matchers. For example:
        assertThat("myValue", allOf(startsWith("my"), containsString("Val")))
        Type Parameters:
        T - the matcher type.
        Parameters:
        matchers - all the matchers must pass.
        Returns:
        The matcher.
      • anyOf

        public static <T> AnyOf<T> anyOf​(java.lang.Iterable<Matcher<? super T>> matchers)
        Creates a matcher that matches if the examined object matches ANY of the specified matchers. For example:
        assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))
        Type Parameters:
        T - the matcher type.
        Parameters:
        matchers - any the matchers must pass.
        Returns:
        The matcher.
      • anyOf

        @SafeVarargs
        public static <T> AnyOf<T> anyOf​(Matcher<? super T>... matchers)
        Creates a matcher that matches if the examined object matches ANY of the specified matchers. For example:
        assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))
        Type Parameters:
        T - the matcher type.
        Parameters:
        matchers - any the matchers must pass.
        Returns:
        The matcher.
      • both

        public static <LHS> CombinableMatcher.CombinableBothMatcher<LHS> both​(Matcher<? super LHS> matcher)
        Creates a matcher that matches when both of the specified matchers match the examined object. For example:
        assertThat("fab", both(containsString("a")).and(containsString("b")))
        Type Parameters:
        LHS - the matcher type.
        Parameters:
        matcher - the matcher to combine, and both musth pass.
        Returns:
        The matcher.
      • either

        public static <LHS> CombinableMatcher.CombinableEitherMatcher<LHS> either​(Matcher<? super LHS> matcher)
        Creates a matcher that matches when either of the specified matchers match the examined object. For example:
        assertThat("fan", either(containsString("a")).or(containsString("b")))
        Type Parameters:
        LHS - the matcher type.
        Parameters:
        matcher - the matcher to combine, and either must pass.
        Returns:
        The matcher.
      • describedAs

        public static <T> Matcher<T> describedAs​(java.lang.String description,
                                                 Matcher<T> matcher,
                                                 java.lang.Object... values)
        Wraps an existing matcher, overriding its description with that specified. All other functions are delegated to the decorated matcher, including its mismatch description. For example:
        describedAs("a big decimal equal to %0", equalTo(myBigDecimal), myBigDecimal.toPlainString())
        Type Parameters:
        T - the matcher type.
        Parameters:
        description - the new description for the wrapped matcher
        matcher - the matcher to wrap
        values - optional values to insert into the tokenised description
        Returns:
        The matcher.
      • everyItem

        public static <U> Matcher<java.lang.Iterable<? extends U>> everyItem​(Matcher<U> itemMatcher)
        Creates a matcher for Iterables that only matches when a single pass over the examined Iterable yields items that are all matched by the specified itemMatcher. For example:
        assertThat(Arrays.asList("bar", "baz"), everyItem(startsWith("ba")))
        Type Parameters:
        U - the matcher type.
        Parameters:
        itemMatcher - the matcher to apply to every item provided by the examined Iterable
        Returns:
        The matcher.
      • is

        public static <T> Matcher<T> is​(Matcher<T> matcher)
        Decorates another Matcher, retaining its behaviour, but allowing tests to be slightly more expressive. For example:
        assertThat(cheese, is(equalTo(smelly)))
        instead of:
        assertThat(cheese, equalTo(smelly))
        Type Parameters:
        T - the matcher type.
        Parameters:
        matcher - the matcher Is.is(org.hamcrest.Matcher<T>).
        Returns:
        The matcher.
      • is

        public static <T> Matcher<T> is​(T value)
        A shortcut to the frequently used is(equalTo(x)). For example:
        assertThat(cheese, is(smelly))
        instead of:
        assertThat(cheese, is(equalTo(smelly)))
        Type Parameters:
        T - the matcher type.
        Parameters:
        value - the value for matcher Is.is(org.hamcrest.Matcher<T>).
        Returns:
        The matcher.
      • isA

        public static <T> Matcher<T> isA​(java.lang.Class<T> type)
        A shortcut to the frequently used is(instanceOf(SomeClass.class)). For example:
        assertThat(cheese, isA(Cheddar.class))
        instead of:
        assertThat(cheese, is(instanceOf(Cheddar.class)))
        Type Parameters:
        T - the matcher type.
        Parameters:
        type - the type for matcher Is.isA(java.lang.Class<?>).
        Returns:
        The matcher.
      • anything

        public static Matcher<java.lang.Object> anything()
        Creates a matcher that always matches, regardless of the examined object.
        Returns:
        The matcher.
      • anything

        public static Matcher<java.lang.Object> anything​(java.lang.String description)
        Creates a matcher that always matches, regardless of the examined object, but describes itself with the specified String.
        Parameters:
        description - a meaningful String used when describing itself
        Returns:
        The matcher.
      • hasItem

        public static <T> Matcher<java.lang.Iterable<? super T>> hasItem​(Matcher<? super T> itemMatcher)
        Creates a matcher for Iterables that only matches when a single pass over the examined Iterable yields at least one item that is matched by the specified itemMatcher. Whilst matching, the traversal of the examined Iterable will stop as soon as a matching item is found. For example:
        assertThat(Arrays.asList("foo", "bar"), hasItem(startsWith("ba")))
        Type Parameters:
        T - the matcher type.
        Parameters:
        itemMatcher - the matcher to apply to items provided by the examined Iterable
        Returns:
        The matcher.
      • hasItem

        public static <T> Matcher<java.lang.Iterable<? super T>> hasItem​(T item)
        Creates a matcher for Iterables that only matches when a single pass over the examined Iterable yields at least one item that is equal to the specified item. Whilst matching, the traversal of the examined Iterable will stop as soon as a matching item is found. For example:
        assertThat(Arrays.asList("foo", "bar"), hasItem("bar"))
        Type Parameters:
        T - the matcher type.
        Parameters:
        item - the item to compare against the items provided by the examined Iterable
        Returns:
        The matcher.
      • hasItems

        @SafeVarargs
        public static <T> Matcher<java.lang.Iterable<T>> hasItems​(Matcher<? super T>... itemMatchers)
        Creates a matcher for Iterables that matches when consecutive passes over the examined Iterable yield at least one item that is matched by the corresponding matcher from the specified itemMatchers. Whilst matching, each traversal of the examined Iterable will stop as soon as a matching item is found. For example:
        assertThat(Arrays.asList("foo", "bar", "baz"), hasItems(endsWith("z"), endsWith("o")))
        Type Parameters:
        T - the matcher type.
        Parameters:
        itemMatchers - the matchers to apply to items provided by the examined Iterable
        Returns:
        The matcher.
      • hasItems

        @SafeVarargs
        public static <T> Matcher<java.lang.Iterable<T>> hasItems​(T... items)
        Creates a matcher for Iterables that matches when consecutive passes over the examined Iterable yield at least one item that is equal to the corresponding item from the specified items. Whilst matching, each traversal of the examined Iterable will stop as soon as a matching item is found. For example:
        assertThat(Arrays.asList("foo", "bar", "baz"), hasItems("baz", "foo"))
        Type Parameters:
        T - the matcher type.
        Parameters:
        items - the items to compare against the items provided by the examined Iterable
        Returns:
        The matcher.
      • equalTo

        public static <T> Matcher<T> equalTo​(T operand)
        Creates a matcher that matches when the examined object is logically equal to the specified operand, as determined by calling the Object.equals(java.lang.Object) method on the examined object.

        If the specified operand is null then the created matcher will only match if the examined object's equals method returns true when passed a null (which would be a violation of the equals contract), unless the examined object itself is null, in which case the matcher will return a positive match.

        The created matcher provides a special behaviour when examining Arrays, whereby it will match if both the operand and the examined object are arrays of the same length and contain items that are equal to each other (according to the above rules) in the same indexes.

        For example:
         assertThat("foo", equalTo("foo"));
         assertThat(new String[] {"foo", "bar"}, equalTo(new String[] {"foo", "bar"}));
         
        Type Parameters:
        T - the matcher type.
        Parameters:
        operand - for matcher IsEqual.equalTo(T).
        Returns:
        The matcher.
      • equalToObject

        public static Matcher<java.lang.Object> equalToObject​(java.lang.Object operand)
        Creates an IsEqual matcher that does not enforce the values being compared to be of the same static type.
        Parameters:
        operand - the object for matcher IsEqual.equalToObject(java.lang.Object).
        Returns:
        The matcher.
      • any

        public static <T> Matcher<T> any​(java.lang.Class<T> type)
        Creates a matcher that matches when the examined object is an instance of the specified type, as determined by calling the Class.isInstance(Object) method on that type, passing the the examined object.

        The created matcher forces a relationship between specified type and the examined object, and should be used when it is necessary to make generics conform, for example in the JMock clause with(any(Thing.class))

        For example:
        assertThat(new Canoe(), any(Canoe.class));
        Type Parameters:
        T - the matcher type.
        Parameters:
        type - the type for matcher IsInstanceOf.any(java.lang.Class<T>).
        Returns:
        The matcher.
      • instanceOf

        public static <T> Matcher<T> instanceOf​(java.lang.Class<?> type)
        Creates a matcher that matches when the examined object is an instance of the specified type, as determined by calling the Class.isInstance(Object) method on that type, passing the the examined object.

        The created matcher assumes no relationship between specified type and the examined object.

        For example:
        assertThat(new Canoe(), instanceOf(Paddlable.class));
        Type Parameters:
        T - the matcher type.
        Parameters:
        type - the type for matcher IsInstanceOf.instanceOf(java.lang.Class<?>).
        Returns:
        The matcher.
      • not

        public static <T> Matcher<T> not​(Matcher<T> matcher)
        Creates a matcher that wraps an existing matcher, but inverts the logic by which it will match. For example:
        assertThat(cheese, is(not(equalTo(smelly))))
        Type Parameters:
        T - the matcher type.
        Parameters:
        matcher - the matcher whose sense should be inverted
        Returns:
        The matcher.
      • not

        public static <T> Matcher<T> not​(T value)
        A shortcut to the frequently used not(equalTo(x)). For example:
        assertThat(cheese, is(not(smelly)))
        instead of:
        assertThat(cheese, is(not(equalTo(smelly))))
        Type Parameters:
        T - the matcher type.
        Parameters:
        value - the value that any examined object should not equal
        Returns:
        The matcher.
      • notNullValue

        public static Matcher<java.lang.Object> notNullValue()
        A shortcut to the frequently used not(nullValue()). For example:
        assertThat(cheese, is(notNullValue()))
        instead of:
        assertThat(cheese, is(not(nullValue())))
        Returns:
        The matcher.
      • notNullValue

        public static <T> Matcher<T> notNullValue​(java.lang.Class<T> type)
        A shortcut to the frequently used not(nullValue(X.class)). Accepts a single dummy argument to facilitate type inference.. For example:
        assertThat(cheese, is(notNullValue(X.class)))
        instead of:
        assertThat(cheese, is(not(nullValue(X.class))))
        Type Parameters:
        T - the matcher type.
        Parameters:
        type - dummy parameter used to infer the generic type of the returned matcher
        Returns:
        The matcher.
      • nullValue

        public static Matcher<java.lang.Object> nullValue()
        Creates a matcher that matches if examined object is null. For example:
        assertThat(cheese, is(nullValue())
        Returns:
        The matcher.
      • nullValue

        public static <T> Matcher<T> nullValue​(java.lang.Class<T> type)
        Creates a matcher that matches if examined object is null. Accepts a single dummy argument to facilitate type inference. For example:
        assertThat(cheese, is(nullValue(Cheese.class))
        Type Parameters:
        T - the matcher type.
        Parameters:
        type - dummy parameter used to infer the generic type of the returned matcher
        Returns:
        The matcher.
      • sameInstance

        public static <T> Matcher<T> sameInstance​(T target)
        Creates a matcher that matches only when the examined object is the same instance as the specified target object.
        Type Parameters:
        T - the matcher type.
        Parameters:
        target - the target instance against which others should be assessed
        Returns:
        The matcher.
      • theInstance

        public static <T> Matcher<T> theInstance​(T target)
        Creates a matcher that matches only when the examined object is the same instance as the specified target object.
        Type Parameters:
        T - the matcher type.
        Parameters:
        target - the target instance against which others should be assessed
        Returns:
        The matcher.
      • containsString

        public static Matcher<java.lang.String> containsString​(java.lang.String substring)
        Creates a matcher that matches if the examined String contains the specified String anywhere. For example:
        assertThat("myStringOfNote", containsString("ring"))
        Parameters:
        substring - the substring that the returned matcher will expect to find within any examined string
        Returns:
        The matcher.
      • containsStringIgnoringCase

        public static Matcher<java.lang.String> containsStringIgnoringCase​(java.lang.String substring)
        Creates a matcher that matches if the examined String contains the specified String anywhere, ignoring case. For example:
        assertThat("myStringOfNote", containsString("ring"))
        Parameters:
        substring - the substring that the returned matcher will expect to find within any examined string
        Returns:
        The matcher.
      • startsWith

        public static Matcher<java.lang.String> startsWith​(java.lang.String prefix)

        Creates a matcher that matches if the examined String starts with the specified String.

        For example:
        assertThat("myStringOfNote", startsWith("my"))
        Parameters:
        prefix - the substring that the returned matcher will expect at the start of any examined string
        Returns:
        The matcher.
      • startsWithIgnoringCase

        public static Matcher<java.lang.String> startsWithIgnoringCase​(java.lang.String prefix)

        Creates a matcher that matches if the examined String starts with the specified String, ignoring case

        For example:
        assertThat("myStringOfNote", startsWith("my"))
        Parameters:
        prefix - the substring that the returned matcher will expect at the start of any examined string
        Returns:
        The matcher.
      • endsWith

        public static Matcher<java.lang.String> endsWith​(java.lang.String suffix)
        Creates a matcher that matches if the examined String ends with the specified String. For example:
        assertThat("myStringOfNote", endsWith("Note"))
        Parameters:
        suffix - the substring that the returned matcher will expect at the end of any examined string
        Returns:
        The matcher.
      • endsWithIgnoringCase

        public static Matcher<java.lang.String> endsWithIgnoringCase​(java.lang.String suffix)
        Creates a matcher that matches if the examined String ends with the specified String, ignoring case. For example:
        assertThat("myStringOfNote", endsWith("Note"))
        Parameters:
        suffix - the substring that the returned matcher will expect at the end of any examined string
        Returns:
        The matcher.