Class CoreMatchers
CodeMatchers
provides syntactic sugar for building matchers, or
chains of matchers. By using static imports on these methods, concise and
readable code calling the matchers can be maintained.
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T> Matcher
<T> Creates a matcher that matches if the examined object matches ALL of the specified matchers.static <T> Matcher
<T> Creates a matcher that matches if the examined object matches ALL of the specified matchers.static <T> Matcher
<T> Creates a matcher that matches when the examined object is an instance of the specifiedtype
, as determined by calling theClass.isInstance(Object)
method on that type, passing the examined object.static <T> AnyOf
<T> Creates a matcher that matches if the examined object matches ANY of the specified matchers.static <T> AnyOf
<T> Creates a matcher that matches if the examined object matches ANY of the specified matchers.anything()
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 specifiedString
.static <LHS> CombinableMatcher.CombinableBothMatcher
<LHS> Creates a matcher that matches when both of the specified matchers match the examined object.containsString
(String substring) containsStringIgnoringCase
(String substring) static <T> Matcher
<T> describedAs
(String description, Matcher<T> matcher, Object... values) Wraps an existing matcher, overriding its description with that specified.static <LHS> CombinableMatcher.CombinableEitherMatcher
<LHS> Creates a matcher that matches when either of the specified matchers match the examined object.endsWithIgnoringCase
(String suffix) static <T> Matcher
<T> equalTo
(T operand) Creates a matcher that matches when the examined object is logically equal to the specifiedoperand
, as determined by calling theObject.equals(java.lang.Object)
method on the examined object.equalToObject
(Object operand) Creates anIsEqual
matcher that does not enforce the values being compared to be of the same static type.hasItem
(T item) hasItems
(T... items) static <T> Matcher
<T> instanceOf
(Class<?> type) Creates a matcher that matches when the examined object is an instance of the specifiedtype
, as determined by calling theClass.isInstance(Object)
method on that type, passing the the examined object.static <T> Matcher
<T> 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 usedis(equalTo(x))
.static <T> Matcher
<T> A shortcut to the frequently usedis(instanceOf(SomeClass.class))
.static <T> Matcher
<T> 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 usednot(equalTo(x))
.A shortcut to the frequently usednot(nullValue())
.static <T> Matcher
<T> notNullValue
(Class<T> type) A shortcut to the frequently usednot(nullValue(X.class)).
Creates a matcher that matches if examined object isnull
.static <T> Matcher
<T> Creates a matcher that matches if examined object isnull
.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.startsWith
(String prefix) startsWithIgnoringCase
(String prefix) 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.
-
Method Details
-
allOf
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
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
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
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
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 must 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
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 matchermatcher
- the matcher to wrapvalues
- optional values to insert into the tokenized description- Returns:
- The matcher.
-
everyItem
Creates a matcher forIterable
s that only matches when a single pass over the examinedIterable
yields items that are all matched by the specifieditemMatcher
. 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 examinedIterable
- Returns:
- The matcher.
-
is
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 to wrap.- Returns:
- The matcher.
-
is
A shortcut to the frequently usedis(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 to check.- Returns:
- The matcher.
-
isA
A shortcut to the frequently usedis(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 to check.- Returns:
- The matcher.
-
anything
Creates a matcher that always matches, regardless of the examined object.- Returns:
- The matcher.
-
anything
Creates a matcher that always matches, regardless of the examined object, but describes itself with the specifiedString
.- Parameters:
description
- a meaningfulString
used when describing itself- Returns:
- The matcher.
-
hasItem
Creates a matcher forIterable
s that only matches when a single pass over the examinedIterable
yields at least one item that is matched by the specifieditemMatcher
. Whilst matching, the traversal of the examinedIterable
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 examinedIterable
- Returns:
- The matcher.
-
hasItem
Creates a matcher forIterable
s that only matches when a single pass over the examinedIterable
yields at least one item that is equal to the specifieditem
. Whilst matching, the traversal of the examinedIterable
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 examinedIterable
- Returns:
- The matcher.
-
hasItems
Creates a matcher forIterable
s that matches when consecutive passes over the examinedIterable
yield at least one item that is matched by the corresponding matcher from the specifieditemMatchers
. Whilst matching, each traversal of the examinedIterable
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 examinedIterable
- Returns:
- The matcher.
-
hasItems
Creates a matcher forIterable
s that matches when consecutive passes over the examinedIterable
yield at least one item that is equal to the corresponding item from the specifieditems
. Whilst matching, each traversal of the examinedIterable
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 examinedIterable
- Returns:
- The matcher.
-
equalTo
Creates a matcher that matches when the examined object is logically equal to the specifiedoperand
, as determined by calling theObject.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'sequals
method returnstrue
when passed anull
(which would be a violation of theequals
contract), unless the examined object itself isnull
, in which case the matcher will return a positive match.The created matcher provides a special behaviour when examining
For example: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.assertThat("foo", equalTo("foo")); assertThat(new String[] {"foo", "bar"}, equalTo(new String[] {"foo", "bar"}));
- Type Parameters:
T
- the matcher type.- Parameters:
operand
- the value to check.- Returns:
- The matcher.
-
equalToObject
Creates anIsEqual
matcher that does not enforce the values being compared to be of the same static type.- Parameters:
operand
- the value to check.- Returns:
- The matcher.
-
any
Creates a matcher that matches when the examined object is an instance of the specifiedtype
, as determined by calling theClass.isInstance(Object)
method on that type, passing 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
For example:with(any(Thing.class))
assertThat(new Canoe(), any(Canoe.class));
- Type Parameters:
T
- the matcher type.- Parameters:
type
- the type to check.- Returns:
- The matcher.
-
instanceOf
Creates a matcher that matches when the examined object is an instance of the specifiedtype
, as determined by calling theClass.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 to check.- Returns:
- The matcher.
-
not
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
A shortcut to the frequently usednot(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
A shortcut to the frequently usednot(nullValue())
. For example:assertThat(cheese, is(notNullValue()))
instead of:assertThat(cheese, is(not(nullValue())))
- Returns:
- The matcher.
-
notNullValue
A shortcut to the frequently usednot(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
Creates a matcher that matches if examined object isnull
. For example:assertThat(cheese, is(nullValue())
- Returns:
- The matcher.
-
nullValue
Creates a matcher that matches if examined object isnull
. 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
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
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
Creates a matcher that matches if the examinedString
contains the specifiedString
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
Creates a matcher that matches if the examinedString
contains the specifiedString
anywhere, ignoring case. For example:assertThat("myStringOfNote", containsStringIgnoringCase("Ring"))
- Parameters:
substring
- the substring that the returned matcher will expect to find within any examined string- Returns:
- The matcher.
-
startsWith
Creates a matcher that matches if the examined
For example:String
starts with the specifiedString
.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
Creates a matcher that matches if the examined
For example:String
starts with the specifiedString
, ignoring caseassertThat("myStringOfNote", startsWithIgnoringCase("My"))
- Parameters:
prefix
- the substring that the returned matcher will expect at the start of any examined string- Returns:
- The matcher.
-
endsWith
Creates a matcher that matches if the examinedString
ends with the specifiedString
. 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
Creates a matcher that matches if the examinedString
ends with the specifiedString
, ignoring case. For example:assertThat("myStringOfNote", endsWithIgnoringCase("note"))
- Parameters:
suffix
- the substring that the returned matcher will expect at the end of any examined string- Returns:
- The matcher.
-