1 package org.hamcrest; 2 3 @SuppressWarnings("UnusedDeclaration") 4 public class CoreMatchers { 5 6 /** 7 * Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers. 8 * For example: 9 * <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre> 10 */ allOf(java.lang.Iterable<org.hamcrest.Matcher<? super T>> matchers)11 public static <T> org.hamcrest.Matcher<T> allOf(java.lang.Iterable<org.hamcrest.Matcher<? super T>> matchers) { 12 return org.hamcrest.core.AllOf.<T>allOf(matchers); 13 } 14 15 /** 16 * Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers. 17 * For example: 18 * <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre> 19 */ 20 @SafeVarargs allOf(org.hamcrest.Matcher<? super T>.... matchers)21 public static <T> org.hamcrest.Matcher<T> allOf(org.hamcrest.Matcher<? super T>... matchers) { 22 return org.hamcrest.core.AllOf.<T>allOf(matchers); 23 } 24 25 26 /** 27 * Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers. 28 * For example: 29 * <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre> 30 */ anyOf(java.lang.Iterable<org.hamcrest.Matcher<? super T>> matchers)31 public static <T> org.hamcrest.core.AnyOf<T> anyOf(java.lang.Iterable<org.hamcrest.Matcher<? super T>> matchers) { 32 return org.hamcrest.core.AnyOf.<T>anyOf(matchers); 33 } 34 35 /** 36 * Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers. 37 * For example: 38 * <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre> 39 */ 40 @SafeVarargs anyOf(org.hamcrest.Matcher<? super T>.... matchers)41 public static <T> org.hamcrest.core.AnyOf<T> anyOf(org.hamcrest.Matcher<? super T>... matchers) { 42 return org.hamcrest.core.AnyOf.<T>anyOf(matchers); 43 } 44 45 /** 46 * Creates a matcher that matches when both of the specified matchers match the examined object. 47 * For example: 48 * <pre>assertThat("fab", both(containsString("a")).and(containsString("b")))</pre> 49 */ both(org.hamcrest.Matcher<? super LHS> matcher)50 public static <LHS> org.hamcrest.core.CombinableMatcher.CombinableBothMatcher<LHS> both(org.hamcrest.Matcher<? super LHS> matcher) { 51 return org.hamcrest.core.CombinableMatcher.both(matcher); 52 } 53 54 /** 55 * Creates a matcher that matches when either of the specified matchers match the examined object. 56 * For example: 57 * <pre>assertThat("fan", either(containsString("a")).or(containsString("b")))</pre> 58 */ either(org.hamcrest.Matcher<? super LHS> matcher)59 public static <LHS> org.hamcrest.core.CombinableMatcher.CombinableEitherMatcher<LHS> either(org.hamcrest.Matcher<? super LHS> matcher) { 60 return org.hamcrest.core.CombinableMatcher.either(matcher); 61 } 62 63 /** 64 * Wraps an existing matcher, overriding its description with that specified. All other functions are 65 * delegated to the decorated matcher, including its mismatch description. 66 * For example: 67 * <pre>describedAs("a big decimal equal to %0", equalTo(myBigDecimal), myBigDecimal.toPlainString())</pre> 68 * 69 * @param description 70 * the new description for the wrapped matcher 71 * @param matcher 72 * the matcher to wrap 73 * @param values 74 * optional values to insert into the tokenised description 75 */ describedAs(java.lang.String description, org.hamcrest.Matcher<T> matcher, java.lang.Object... values)76 public static <T> org.hamcrest.Matcher<T> describedAs(java.lang.String description, org.hamcrest.Matcher<T> matcher, java.lang.Object... values) { 77 return org.hamcrest.core.DescribedAs.describedAs(description, matcher, values); 78 } 79 80 /** 81 * Creates a matcher for {@link Iterable}s that only matches when a single pass over the 82 * examined {@link Iterable} yields items that are all matched by the specified 83 * <code>itemMatcher</code>. 84 * For example: 85 * <pre>assertThat(Arrays.asList("bar", "baz"), everyItem(startsWith("ba")))</pre> 86 * 87 * @param itemMatcher 88 * the matcher to apply to every item provided by the examined {@link Iterable} 89 */ everyItem(org.hamcrest.Matcher<U> itemMatcher)90 public static <U> org.hamcrest.Matcher<java.lang.Iterable<? extends U>> everyItem(org.hamcrest.Matcher<U> itemMatcher) { 91 return org.hamcrest.core.Every.everyItem(itemMatcher); 92 } 93 94 /** 95 * Decorates another Matcher, retaining its behaviour, but allowing tests 96 * to be slightly more expressive. 97 * For example: 98 * <pre>assertThat(cheese, is(equalTo(smelly)))</pre> 99 * instead of: 100 * <pre>assertThat(cheese, equalTo(smelly))</pre> 101 */ is(org.hamcrest.Matcher<T> matcher)102 public static <T> org.hamcrest.Matcher<T> is(org.hamcrest.Matcher<T> matcher) { 103 return org.hamcrest.core.Is.is(matcher); 104 } 105 106 /** 107 * A shortcut to the frequently used <code>is(equalTo(x))</code>. 108 * For example: 109 * <pre>assertThat(cheese, is(smelly))</pre> 110 * instead of: 111 * <pre>assertThat(cheese, is(equalTo(smelly)))</pre> 112 */ is(T value)113 public static <T> org.hamcrest.Matcher<T> is(T value) { 114 return org.hamcrest.core.Is.is(value); 115 } 116 117 /** 118 * Provided to cause compile time error when used in preference to a possible runtime error if 119 * this was not here. 120 * 121 * <p>This method was removed upstream between Hamcrest 1.1 and 1.3 in favour of the 122 * instanceOf(Class) method. Unfortunately, existing usages of it could still compile against the 123 * {@link #is(Object)} method instead. Although not every existing usage would compile 124 * successfully it is possible that some could and that would result in a change in the runtime 125 * behavior that could be difficult to detect and fix. This change aims to turn any significant 126 * usage of this method into a compile time error. 127 * 128 * @deprecated Use instanceOf(SomeClass.class) instead. 129 */ is(java.lang.Class<?> type)130 public static void is(java.lang.Class<?> type) { 131 } 132 133 /** 134 * A shortcut to the frequently used <code>is(instanceOf(SomeClass.class))</code>. 135 * For example: 136 * <pre>assertThat(cheese, isA(Cheddar.class))</pre> 137 * instead of: 138 * <pre>assertThat(cheese, is(instanceOf(Cheddar.class)))</pre> 139 */ isA(java.lang.Class<T> type)140 public static <T> org.hamcrest.Matcher<T> isA(java.lang.Class<T> type) { 141 return org.hamcrest.core.Is.isA(type); 142 } 143 144 /** 145 * Creates a matcher that always matches, regardless of the examined object. 146 */ anything()147 public static org.hamcrest.Matcher<java.lang.Object> anything() { 148 return org.hamcrest.core.IsAnything.anything(); 149 } 150 151 /** 152 * Creates a matcher that always matches, regardless of the examined object, but describes 153 * itself with the specified {@link String}. 154 * 155 * @param description 156 * a meaningful {@link String} used when describing itself 157 */ anything(java.lang.String description)158 public static org.hamcrest.Matcher<java.lang.Object> anything(java.lang.String description) { 159 return org.hamcrest.core.IsAnything.anything(description); 160 } 161 162 /** 163 * Creates a matcher for {@link Iterable}s that only matches when a single pass over the 164 * examined {@link Iterable} yields at least one item that is matched by the specified 165 * <code>itemMatcher</code>. Whilst matching, the traversal of the examined {@link Iterable} 166 * will stop as soon as a matching item is found. 167 * For example: 168 * <pre>assertThat(Arrays.asList("foo", "bar"), hasItem(startsWith("ba")))</pre> 169 * 170 * @param itemMatcher 171 * the matcher to apply to items provided by the examined {@link Iterable} 172 */ hasItem(org.hamcrest.Matcher<? super T> itemMatcher)173 public static <T> org.hamcrest.Matcher<java.lang.Iterable<? super T>> hasItem(org.hamcrest.Matcher<? super T> itemMatcher) { 174 return org.hamcrest.core.IsCollectionContaining.<T>hasItem(itemMatcher); 175 } 176 177 /** 178 * Creates a matcher for {@link Iterable}s that only matches when a single pass over the 179 * examined {@link Iterable} yields at least one item that is equal to the specified 180 * <code>item</code>. Whilst matching, the traversal of the examined {@link Iterable} 181 * will stop as soon as a matching item is found. 182 * For example: 183 * <pre>assertThat(Arrays.asList("foo", "bar"), hasItem("bar"))</pre> 184 * 185 * @param item 186 * the item to compare against the items provided by the examined {@link Iterable} 187 */ hasItem(T item)188 public static <T> org.hamcrest.Matcher<java.lang.Iterable<? super T>> hasItem(T item) { 189 return org.hamcrest.core.IsCollectionContaining.<T>hasItem(item); 190 } 191 192 /** 193 * Creates a matcher for {@link Iterable}s that matches when consecutive passes over the 194 * examined {@link Iterable} yield at least one item that is matched by the corresponding 195 * matcher from the specified <code>itemMatchers</code>. Whilst matching, each traversal of 196 * the examined {@link Iterable} will stop as soon as a matching item is found. 197 * For example: 198 * <pre>assertThat(Arrays.asList("foo", "bar", "baz"), hasItems(endsWith("z"), endsWith("o")))</pre> 199 * 200 * @param itemMatchers 201 * the matchers to apply to items provided by the examined {@link Iterable} 202 */ 203 @SafeVarargs hasItems(org.hamcrest.Matcher<? super T>.... itemMatchers)204 public static <T> org.hamcrest.Matcher<java.lang.Iterable<T>> hasItems(org.hamcrest.Matcher<? super T>... itemMatchers) { 205 return org.hamcrest.core.IsCollectionContaining.<T>hasItems(itemMatchers); 206 } 207 208 /** 209 * Creates a matcher for {@link Iterable}s that matches when consecutive passes over the 210 * examined {@link Iterable} yield at least one item that is equal to the corresponding 211 * item from the specified <code>items</code>. Whilst matching, each traversal of the 212 * examined {@link Iterable} will stop as soon as a matching item is found. 213 * For example: 214 * <pre>assertThat(Arrays.asList("foo", "bar", "baz"), hasItems("baz", "foo"))</pre> 215 * 216 * @param items 217 * the items to compare against the items provided by the examined {@link Iterable} 218 */ 219 @SafeVarargs hasItems(T... items)220 public static <T> org.hamcrest.Matcher<java.lang.Iterable<T>> hasItems(T... items) { 221 return org.hamcrest.core.IsCollectionContaining.<T>hasItems(items); 222 } 223 224 /** 225 * Creates a matcher that matches when the examined object is logically equal to the specified 226 * <code>operand</code>, as determined by calling the {@link java.lang.Object#equals} method on 227 * the <b>examined</b> object. 228 * 229 * <p>If the specified operand is <code>null</code> then the created matcher will only match if 230 * the examined object's <code>equals</code> method returns <code>true</code> when passed a 231 * <code>null</code> (which would be a violation of the <code>equals</code> contract), unless the 232 * examined object itself is <code>null</code>, in which case the matcher will return a positive 233 * match.</p> 234 * 235 * <p>The created matcher provides a special behaviour when examining <code>Array</code>s, whereby 236 * it will match if both the operand and the examined object are arrays of the same length and 237 * contain items that are equal to each other (according to the above rules) <b>in the same 238 * indexes</b>.</p> 239 * For example: 240 * <pre> 241 * assertThat("foo", equalTo("foo")); 242 * assertThat(new String[] {"foo", "bar"}, equalTo(new String[] {"foo", "bar"})); 243 * </pre> 244 */ equalTo(T operand)245 public static <T> org.hamcrest.Matcher<T> equalTo(T operand) { 246 return org.hamcrest.core.IsEqual.equalTo(operand); 247 } 248 249 /** 250 * Creates an {@link org.hamcrest.core.IsEqual} matcher that does not enforce the values being 251 * compared to be of the same static type. 252 */ equalToObject(java.lang.Object operand)253 public static org.hamcrest.Matcher<java.lang.Object> equalToObject(java.lang.Object operand) { 254 return org.hamcrest.core.IsEqual.equalToObject(operand); 255 } 256 257 /** 258 * Creates a matcher that matches when the examined object is an instance of the specified <code>type</code>, 259 * as determined by calling the {@link java.lang.Class#isInstance(Object)} method on that type, passing the 260 * the examined object. 261 * 262 * <p>The created matcher forces a relationship between specified type and the examined object, and should be 263 * used when it is necessary to make generics conform, for example in the JMock clause 264 * <code>with(any(Thing.class))</code></p> 265 * For example: 266 * <pre>assertThat(new Canoe(), instanceOf(Canoe.class));</pre> 267 */ any(java.lang.Class<T> type)268 public static <T> org.hamcrest.Matcher<T> any(java.lang.Class<T> type) { 269 return org.hamcrest.core.IsInstanceOf.any(type); 270 } 271 272 /** 273 * Creates a matcher that matches when the examined object is an instance of the specified <code>type</code>, 274 * as determined by calling the {@link java.lang.Class#isInstance(Object)} method on that type, passing the 275 * the examined object. 276 * 277 * <p>The created matcher assumes no relationship between specified type and the examined object.</p> 278 * For example: 279 * <pre>assertThat(new Canoe(), instanceOf(Paddlable.class));</pre> 280 */ instanceOf(java.lang.Class<?> type)281 public static <T> org.hamcrest.Matcher<T> instanceOf(java.lang.Class<?> type) { 282 return org.hamcrest.core.IsInstanceOf.instanceOf(type); 283 } 284 285 /** 286 * Creates a matcher that wraps an existing matcher, but inverts the logic by which 287 * it will match. 288 * For example: 289 * <pre>assertThat(cheese, is(not(equalTo(smelly))))</pre> 290 * 291 * @param matcher 292 * the matcher whose sense should be inverted 293 */ not(org.hamcrest.Matcher<T> matcher)294 public static <T> org.hamcrest.Matcher<T> not(org.hamcrest.Matcher<T> matcher) { 295 return org.hamcrest.core.IsNot.not(matcher); 296 } 297 298 /** 299 * A shortcut to the frequently used <code>not(equalTo(x))</code>. 300 * For example: 301 * <pre>assertThat(cheese, is(not(smelly)))</pre> 302 * instead of: 303 * <pre>assertThat(cheese, is(not(equalTo(smelly))))</pre> 304 * 305 * @param value 306 * the value that any examined object should <b>not</b> equal 307 */ not(T value)308 public static <T> org.hamcrest.Matcher<T> not(T value) { 309 return org.hamcrest.core.IsNot.not(value); 310 } 311 312 /** 313 * A shortcut to the frequently used <code>not(nullValue())</code>. 314 * For example: 315 * <pre>assertThat(cheese, is(notNullValue()))</pre> 316 * instead of: 317 * <pre>assertThat(cheese, is(not(nullValue())))</pre> 318 */ notNullValue()319 public static org.hamcrest.Matcher<java.lang.Object> notNullValue() { 320 return org.hamcrest.core.IsNull.notNullValue(); 321 } 322 323 /** 324 * A shortcut to the frequently used <code>not(nullValue(X.class)). Accepts a 325 * single dummy argument to facilitate type inference.</code>. 326 * For example: 327 * <pre>assertThat(cheese, is(notNullValue(X.class)))</pre> 328 * instead of: 329 * <pre>assertThat(cheese, is(not(nullValue(X.class))))</pre> 330 * 331 * @param type 332 * dummy parameter used to infer the generic type of the returned matcher 333 */ notNullValue(java.lang.Class<T> type)334 public static <T> org.hamcrest.Matcher<T> notNullValue(java.lang.Class<T> type) { 335 return org.hamcrest.core.IsNull.notNullValue(type); 336 } 337 338 /** 339 * Creates a matcher that matches if examined object is <code>null</code>. 340 * For example: 341 * <pre>assertThat(cheese, is(nullValue())</pre> 342 */ nullValue()343 public static org.hamcrest.Matcher<java.lang.Object> nullValue() { 344 return org.hamcrest.core.IsNull.nullValue(); 345 } 346 347 /** 348 * Creates a matcher that matches if examined object is <code>null</code>. Accepts a 349 * single dummy argument to facilitate type inference. 350 * For example: 351 * <pre>assertThat(cheese, is(nullValue(Cheese.class))</pre> 352 * 353 * @param type 354 * dummy parameter used to infer the generic type of the returned matcher 355 */ nullValue(java.lang.Class<T> type)356 public static <T> org.hamcrest.Matcher<T> nullValue(java.lang.Class<T> type) { 357 return org.hamcrest.core.IsNull.nullValue(type); 358 } 359 360 /** 361 * Creates a matcher that matches only when the examined object is the same instance as 362 * the specified target object. 363 * 364 * @param target 365 * the target instance against which others should be assessed 366 */ sameInstance(T target)367 public static <T> org.hamcrest.Matcher<T> sameInstance(T target) { 368 return org.hamcrest.core.IsSame.sameInstance(target); 369 } 370 371 /** 372 * Creates a matcher that matches only when the examined object is the same instance as 373 * the specified target object. 374 * 375 * @param target 376 * the target instance against which others should be assessed 377 */ theInstance(T target)378 public static <T> org.hamcrest.Matcher<T> theInstance(T target) { 379 return org.hamcrest.core.IsSame.theInstance(target); 380 } 381 382 /** 383 * Creates a matcher that matches if the examined {@link String} contains the specified 384 * {@link String} anywhere. 385 * For example: 386 * <pre>assertThat("myStringOfNote", containsString("ring"))</pre> 387 * 388 * @param substring 389 * the substring that the returned matcher will expect to find within any examined string 390 */ containsString(java.lang.String substring)391 public static org.hamcrest.Matcher<java.lang.String> containsString(java.lang.String substring) { 392 return org.hamcrest.core.StringContains.containsString(substring); 393 } 394 395 /** 396 * Creates a matcher that matches if the examined {@link String} contains the specified 397 * {@link String} anywhere, ignoring case. 398 * For example: 399 * <pre>assertThat("myStringOfNote", containsString("ring"))</pre> 400 * 401 * @param substring 402 * the substring that the returned matcher will expect to find within any examined string 403 */ containsStringIgnoringCase(java.lang.String substring)404 public static org.hamcrest.Matcher<java.lang.String> containsStringIgnoringCase(java.lang.String substring) { 405 return org.hamcrest.core.StringContains.containsStringIgnoringCase(substring); 406 } 407 408 /** 409 * <p> 410 * Creates a matcher that matches if the examined {@link String} starts with the specified 411 * {@link String}. 412 * </p> 413 * For example: 414 * <pre>assertThat("myStringOfNote", startsWith("my"))</pre> 415 * 416 * @param prefix 417 * the substring that the returned matcher will expect at the start of any examined string 418 */ startsWith(java.lang.String prefix)419 public static org.hamcrest.Matcher<java.lang.String> startsWith(java.lang.String prefix) { 420 return org.hamcrest.core.StringStartsWith.startsWith(prefix); 421 } 422 423 /** 424 * <p> 425 * Creates a matcher that matches if the examined {@link String} starts with the specified 426 * {@link String}, ignoring case 427 * </p> 428 * For example: 429 * <pre>assertThat("myStringOfNote", startsWith("my"))</pre> 430 * 431 * @param prefix 432 * the substring that the returned matcher will expect at the start of any examined string 433 */ startsWithIgnoringCase(java.lang.String prefix)434 public static org.hamcrest.Matcher<java.lang.String> startsWithIgnoringCase(java.lang.String prefix) { 435 return org.hamcrest.core.StringStartsWith.startsWithIgnoringCase(prefix); 436 } 437 438 /** 439 * Creates a matcher that matches if the examined {@link String} ends with the specified 440 * {@link String}. 441 * For example: 442 * <pre>assertThat("myStringOfNote", endsWith("Note"))</pre> 443 * 444 * @param suffix 445 * the substring that the returned matcher will expect at the end of any examined string 446 */ endsWith(java.lang.String suffix)447 public static org.hamcrest.Matcher<java.lang.String> endsWith(java.lang.String suffix) { 448 return org.hamcrest.core.StringEndsWith.endsWith(suffix); 449 } 450 451 /** 452 * Creates a matcher that matches if the examined {@link String} ends with the specified 453 * {@link String}, ignoring case. 454 * For example: 455 * <pre>assertThat("myStringOfNote", endsWith("Note"))</pre> 456 * 457 * @param suffix 458 * the substring that the returned matcher will expect at the end of any examined string 459 */ endsWithIgnoringCase(java.lang.String suffix)460 public static org.hamcrest.Matcher<java.lang.String> endsWithIgnoringCase(java.lang.String suffix) { 461 return org.hamcrest.core.StringEndsWith.endsWithIgnoringCase(suffix); 462 } 463 464 } 465