public Class CoreMatchers

Creates a matcher that matches if the examined object matches ALL of the specified matchers. For example:

assertThat("myValue", allOf(startsWith("my"), containsString("Val")))

Creates a matcher that matches if the examined object matches ALL of the specified matchers. For example:

assertThat("myValue", allOf(startsWith("my"), containsString("Val")))

Annotations

@SafeVarargs

Creates a matcher that matches when the examined object is an instance of the specified type, as determined by calling the java.lang.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))

assertThat(new Canoe(), instanceOf(Canoe.class));

Creates a matcher that matches if the examined object matches ANY of the specified matchers. For example:

assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))

Creates a matcher that matches if the examined object matches ANY of the specified matchers. For example:

assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))

Annotations

@SafeVarargs

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

Creates a matcher that always matches, regardless of the examined object, but describes itself with the specified String.

Parameters

description:String

a meaningful String used when describing itself

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

Creates a matcher that matches if the examined String contains the specified String anywhere. For example:

assertThat("myStringOfNote", containsString("ring"))

Parameters

substring:String

the substring that the returned matcher will expect to find within any examined string

Creates a matcher that matches if the examined String contains the specified String anywhere, ignoring case. For example:

assertThat("myStringOfNote", containsString("ring"))

Parameters

substring:String

the substring that the returned matcher will expect to find within any examined string

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:String

the new description for the wrapped matcher

matcher:Matcher<T>

the matcher to wrap

values:Object[]

optional values to insert into the tokenised description

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

Creates a matcher that matches if the examined String ends with the specified String. For example:

assertThat("myStringOfNote", endsWith("Note"))

Parameters

suffix:String

the substring that the returned matcher will expect at the end of any examined string

Creates a matcher that matches if the examined String ends with the specified String, ignoring case. For example:

assertThat("myStringOfNote", endsWith("Note"))

Parameters

suffix:String

the substring that the returned matcher will expect at the end of any examined string

Creates a matcher that matches when the examined object is logically equal to the specified operand, as determined by calling the java.lang.Object#equals 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.

assertThat("foo", equalTo("foo"));
assertThat(new String[] {"foo", "bar"}, equalTo(new String[] {"foo", "bar"}));

Creates an org.hamcrest.core.IsEqual matcher that does not enforce the values being compared to be of the same static type.

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

Parameters

itemMatcher:Matcher<U>

the matcher to apply to every item provided by the examined Iterable

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

Parameters

itemMatcher:Matcher<? super T>

the matcher to apply to items provided by the examined Iterable

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

Parameters

item:T

the item to compare against the items provided by the examined Iterable

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

Parameters

itemMatchers:Matcher<? super T>[]

the matchers to apply to items provided by the examined Iterable

Annotations

@SafeVarargs

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

Parameters

items:T[]

the items to compare against the items provided by the examined Iterable

Annotations

@SafeVarargs

Creates a matcher that matches when the examined object is an instance of the specified type, as determined by calling the java.lang.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.

assertThat(new Canoe(), instanceOf(Paddlable.class));

Decorates another Matcher, retaining its behaviour, but allowing tests to be slightly more expressive. For example:

assertThat(cheese, is(equalTo(smelly)))

assertThat(cheese, equalTo(smelly))

A shortcut to the frequently used is(equalTo(x)). For example:

assertThat(cheese, is(smelly))

assertThat(cheese, is(equalTo(smelly)))

A shortcut to the frequently used is(instanceOf(SomeClass.class)). For example:

assertThat(cheese, isA(Cheddar.class))

assertThat(cheese, is(instanceOf(Cheddar.class)))

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:Matcher<T>

the matcher whose sense should be inverted

A shortcut to the frequently used not(equalTo(x)). For example:

assertThat(cheese, is(not(smelly)))

assertThat(cheese, is(not(equalTo(smelly))))

Parameters

value:T

the value that any examined object should not equal

A shortcut to the frequently used not(nullValue()). For example:

assertThat(cheese, is(notNullValue()))

assertThat(cheese, is(not(nullValue())))

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

assertThat(cheese, is(not(nullValue(X.class))))

Parameters

type:Class<T>

dummy parameter used to infer the generic type of the returned matcher

Creates a matcher that matches if examined object is null. For example:

assertThat(cheese, is(nullValue())

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:Class<T>

dummy parameter used to infer the generic type of the returned matcher

Creates a matcher that matches only when the examined object is the same instance as the specified target object.

Parameters

target:T

the target instance against which others should be assessed

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

assertThat("myStringOfNote", startsWith("my"))

Parameters

prefix:String

the substring that the returned matcher will expect at the start of any examined string

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

assertThat("myStringOfNote", startsWith("my"))

Parameters

prefix:String

the substring that the returned matcher will expect at the start of any examined string

Creates a matcher that matches only when the examined object is the same instance as the specified target object.

Parameters

target:T

the target instance against which others should be assessed