CoreMatchers (Hamcrest 2.1 API)
Date: 2018-12-21

org.hamcrest

## Class CoreMatchers

- java.lang.Object
- - org.hamcrest.CoreMatchers

-     public class CoreMatchers
      extends java.lang.Object

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CoreMatchers()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and 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 `Iterable`s 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 `Iterable`s 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 `Iterable`s 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 `Iterable`s 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 `Iterable`s 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")))

    - #### 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")))

    - #### 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")))

    - #### 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")))

    - #### 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")))

    - #### 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")))

    - #### 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())

      Parameters:
        `description` - the new description for the wrapped matcher
        `matcher` - the matcher to wrap
        `values` - optional values to insert into the tokenised description

    - #### everyItem

          public static <U> Matcher<java.lang.Iterable<? extends U>> everyItem(Matcher<U> itemMatcher)

      Creates a matcher for `Iterable`s 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")))

      Parameters:
        `itemMatcher` - the matcher to apply to every item provided by the examined `Iterable`

    - #### 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))

    - #### 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)))

    - #### 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)))

    - #### anything

          public static Matcher<java.lang.Object> anything()

      Creates a matcher that always matches, regardless of the examined object.

    - #### 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

    - #### hasItem

          public static <T> Matcher<java.lang.Iterable<? super T>> hasItem(Matcher<? super T> itemMatcher)

      Creates a matcher for `Iterable`s 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")))

      Parameters:
        `itemMatcher` - the matcher to apply to items provided by the examined `Iterable`

    - #### hasItem

          public static <T> Matcher<java.lang.Iterable<? super T>> hasItem(T item)

      Creates a matcher for `Iterable`s 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"))

      Parameters:
        `item` - the item to compare against the items provided by the examined `Iterable`

    - #### hasItems

          @SafeVarargs
          public static <T> Matcher<java.lang.Iterable<T>> hasItems(Matcher<? super T>... itemMatchers)

      Creates a matcher for `Iterable`s 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")))

      Parameters:
        `itemMatchers` - the matchers to apply to items provided by the examined `Iterable`

    - #### hasItems

          @SafeVarargs
          public static <T> Matcher<java.lang.Iterable<T>> hasItems(T... items)

      Creates a matcher for `Iterable`s 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"))

      Parameters:
        `items` - the items to compare against the items provided by the examined `Iterable`

    - #### 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 `Array`s, 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"}));

    - #### 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.

    - #### 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(), instanceOf(Canoe.class));

    - #### 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));

    - #### 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))))

      Parameters:
        `matcher` - the matcher whose sense should be inverted

    - #### 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))))

      Parameters:
        `value` - the value that any examined object should not equal

    - #### 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())))

    - #### 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))))

      Parameters:
        `type` - dummy parameter used to infer the generic type of the returned 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())

    - #### 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))

      Parameters:
        `type` - dummy parameter used to infer the generic type of the returned 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.
      Parameters:
        `target` - the target instance against which others should be assessed

    - #### 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.
      Parameters:
        `target` - the target instance against which others should be assessed

    - #### 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

    - #### 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

    - #### 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

    - #### 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

    - #### 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

    - #### 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