1 /* 2 * Copyright (c) 2007 Mockito contributors 3 * This program is made available under the terms of the MIT License. 4 */ 5 package org.mockito; 6 7 import org.hamcrest.Matcher; 8 import org.mockito.internal.matchers.*; 9 import org.mockito.internal.matchers.apachecommons.ReflectionEquals; 10 import org.mockito.internal.progress.HandyReturnValues; 11 import org.mockito.internal.progress.MockingProgress; 12 import org.mockito.internal.progress.ThreadSafeMockingProgress; 13 14 import java.util.Collection; 15 import java.util.List; 16 import java.util.Map; 17 import java.util.Set; 18 19 /** 20 * Allow flexible verification or stubbing. See also {@link AdditionalMatchers}. 21 * <p> 22 * {@link Mockito} extends Matchers so to get access to all matchers just import Mockito class statically. 23 * <pre class="code"><code class="java"> 24 * //stubbing using anyInt() argument matcher 25 * when(mockedList.get(anyInt())).thenReturn("element"); 26 * 27 * //following prints "element" 28 * System.out.println(mockedList.get(999)); 29 * 30 * //you can also verify using argument matcher 31 * verify(mockedList).get(anyInt()); 32 * </code></pre> 33 * Scroll down to see all methods - full list of matchers. 34 * <p> 35 * <b>Warning:</b> 36 * <p> 37 * If you are using argument matchers, <b>all arguments</b> have to be provided by matchers. 38 * <p> 39 * E.g: (example shows verification but the same applies to stubbing): 40 * <pre class="code"><code class="java"> 41 * verify(mock).someMethod(anyInt(), anyString(), <b>eq("third argument")</b>); 42 * //above is correct - eq() is also an argument matcher 43 * 44 * verify(mock).someMethod(anyInt(), anyString(), <b>"third argument"</b>); 45 * //above is incorrect - exception will be thrown because third argument is given without argument matcher. 46 * </code></pre> 47 * <p> 48 * Matcher methods like <code>anyObject()</code>, <code>eq()</code> <b>do not</b> return matchers. 49 * Internally, they record a matcher on a stack and return a dummy value (usually null). 50 * This implementation is due static type safety imposed by java compiler. 51 * The consequence is that you cannot use <code>anyObject()</code>, <code>eq()</code> methods outside of verified/stubbed method. 52 * 53 * <p> 54 * <b>Warning 2:</b> 55 * <p> 56 * The any family methods <b>*don't do any type checks*</b>, those are only here to avoid casting 57 * in your code. If you want to perform type checks use the {@link #isA(Class)} method. 58 * This <b>might</b> however change (type checks could be added) in a future major release. 59 * 60 * <h1>Custom Argument Matchers</h1> 61 * 62 * Use {@link Matchers#argThat} method and pass an instance of hamcrest {@link Matcher}. 63 * <p> 64 * Before you start implementing your own custom argument matcher, make sure you check out {@link ArgumentCaptor} api. 65 * <p> 66 * So, how to implement your own argument matcher? 67 * First, you might want to subclass {@link ArgumentMatcher} which is an hamcrest matcher with predefined describeTo() method. 68 * Default description generated by describeTo() uses <b>decamelized class name</b> - to promote meaningful class names. 69 * <p> 70 * Example: 71 * 72 * <pre class="code"><code class="java"> 73 * class IsListOfTwoElements extends ArgumentMatcher<List> { 74 * public boolean matches(Object list) { 75 * return ((List) list).size() == 2; 76 * } 77 * } 78 * 79 * List mock = mock(List.class); 80 * 81 * when(mock.addAll(argThat(new IsListOfTwoElements()))).thenReturn(true); 82 * 83 * mock.addAll(Arrays.asList("one", "two")); 84 * 85 * verify(mock).addAll(argThat(new IsListOfTwoElements())); 86 * </code></pre> 87 * 88 * To keep it readable you may want to extract method, e.g: 89 * <pre class="code"><code class="java"> 90 * verify(mock).addAll(<b>argThat(new IsListOfTwoElements())</b>); 91 * //becomes 92 * verify(mock).addAll(<b>listOfTwoElements()</b>); 93 * </code></pre> 94 * 95 * <b>Warning:</b> Be reasonable with using complicated argument matching, especially custom argument matchers, as it can make the test less readable. 96 * Sometimes it's better to implement equals() for arguments that are passed to mocks 97 * (Mockito naturally uses equals() for argument matching). 98 * This can make the test cleaner. 99 * <p> 100 * Also, <b>sometimes {@link ArgumentCaptor} may be a better fit</b> than custom matcher. 101 * For example, if custom argument matcher is not likely to be reused 102 * or you just need it to assert on argument values to complete verification of behavior. 103 */ 104 @SuppressWarnings("unchecked") 105 public class Matchers { 106 107 private static MockingProgress mockingProgress = new ThreadSafeMockingProgress(); 108 109 /** 110 * Any <code>boolean</code>, <code>Boolean</code> or <code>null</code>. 111 * <p> 112 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 113 * in your code. This might however change (type checks could be added) in a 114 * future major release. 115 * <p> 116 * See examples in javadoc for {@link Matchers} class 117 * 118 * @return <code>false</code>. 119 */ anyBoolean()120 public static boolean anyBoolean() { 121 return reportMatcher(Any.ANY).returnFalse(); 122 } 123 124 /** 125 * Any <code>byte</code>, <code>Byte</code> or <code>null</code>. 126 * <p> 127 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 128 * in your code. This might however change (type checks could be added) in a 129 * future major release. 130 * <p> 131 * See examples in javadoc for {@link Matchers} class 132 * 133 * @return <code>0</code>. 134 */ anyByte()135 public static byte anyByte() { 136 return reportMatcher(Any.ANY).returnZero(); 137 } 138 139 /** 140 * Any <code>char</code>, <code>Character</code> or <code>null</code>. 141 * <p> 142 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 143 * in your code. This might however change (type checks could be added) in a 144 * future major release. 145 * <p> 146 * See examples in javadoc for {@link Matchers} class 147 * 148 * @return <code>0</code>. 149 */ anyChar()150 public static char anyChar() { 151 return reportMatcher(Any.ANY).returnChar(); 152 } 153 154 /** 155 * Any int, Integer or <code>null</code>. 156 * <p> 157 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 158 * in your code. This might however change (type checks could be added) in a 159 * future major release. 160 * <p> 161 * See examples in javadoc for {@link Matchers} class 162 * 163 * @return <code>0</code>. 164 */ anyInt()165 public static int anyInt() { 166 return reportMatcher(Any.ANY).returnZero(); 167 } 168 169 /** 170 * Any <code>long</code>, <code>Long</code> or <code>null</code>. 171 * <p> 172 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 173 * in your code. This might however change (type checks could be added) in a 174 * future major release. 175 * <p> 176 * See examples in javadoc for {@link Matchers} class 177 * 178 * @return <code>0</code>. 179 */ anyLong()180 public static long anyLong() { 181 return reportMatcher(Any.ANY).returnZero(); 182 } 183 184 /** 185 * Any <code>float</code>, <code>Float</code> or <code>null</code>. 186 * <p> 187 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 188 * in your code. This might however change (type checks could be added) in a 189 * future major release. 190 * <p> 191 * See examples in javadoc for {@link Matchers} class 192 * 193 * @return <code>0</code>. 194 */ anyFloat()195 public static float anyFloat() { 196 return reportMatcher(Any.ANY).returnZero(); 197 } 198 199 /** 200 * Any <code>double</code>, <code>Double</code> or <code>null</code>. 201 * <p> 202 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 203 * in your code. This might however change (type checks could be added) in a 204 * future major release. 205 * <p> 206 * See examples in javadoc for {@link Matchers} class 207 * 208 * @return <code>0</code>. 209 */ anyDouble()210 public static double anyDouble() { 211 return reportMatcher(Any.ANY).returnZero(); 212 } 213 214 /** 215 * Any <code>short</code>, <code>Short</code> or <code>null</code>. 216 * <p> 217 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 218 * in your code. This might however change (type checks could be added) in a 219 * future major release. 220 * <p> 221 * See examples in javadoc for {@link Matchers} class 222 * 223 * @return <code>0</code>. 224 */ anyShort()225 public static short anyShort() { 226 return reportMatcher(Any.ANY).returnZero(); 227 } 228 229 /** 230 * Any <code>Object</code> or <code>null</code>. 231 * <p> 232 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 233 * in your code. This might however change (type checks could be added) in a 234 * future major release. 235 * <p> 236 * Has aliases: {@link #any()} and {@link #any(Class clazz)} 237 * <p> 238 * See examples in javadoc for {@link Matchers} class 239 * 240 * @return <code>null</code>. 241 */ anyObject()242 public static <T> T anyObject() { 243 return (T) reportMatcher(Any.ANY).returnNull(); 244 } 245 246 /** 247 * Any vararg, meaning any number and values of arguments. 248 * <p> 249 * Example: 250 * <pre class="code"><code class="java"> 251 * //verification: 252 * mock.foo(1, 2); 253 * mock.foo(1, 2, 3, 4); 254 * 255 * verify(mock, times(2)).foo(anyVararg()); 256 * 257 * //stubbing: 258 * when(mock.foo(anyVararg()).thenReturn(100); 259 * 260 * //prints 100 261 * System.out.println(mock.foo(1, 2)); 262 * //also prints 100 263 * System.out.println(mock.foo(1, 2, 3, 4)); 264 * </code></pre> 265 * See examples in javadoc for {@link Matchers} class 266 * 267 * @return <code>null</code>. 268 */ anyVararg()269 public static <T> T anyVararg() { 270 return (T) reportMatcher(AnyVararg.ANY_VARARG).returnNull(); 271 } 272 273 /** 274 * Any kind object, not necessary of the given class. 275 * The class argument is provided only to avoid casting. 276 * <p> 277 * Sometimes looks better than <code>anyObject()</code> - especially when explicit casting is required 278 * <p> 279 * Alias to {@link Matchers#anyObject()} 280 * <p> 281 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 282 * in your code. This might however change (type checks could be added) in a 283 * future major release. 284 * <p> 285 * See examples in javadoc for {@link Matchers} class 286 * 287 * @param clazz The type to avoid casting 288 * @return <code>null</code>. 289 */ any(Class<T> clazz)290 public static <T> T any(Class<T> clazz) { 291 return (T) reportMatcher(Any.ANY).returnFor(clazz); 292 } 293 294 /** 295 * Any object or <code>null</code>. 296 * <p> 297 * Shorter alias to {@link Matchers#anyObject()} 298 * <p> 299 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 300 * in your code. This might however change (type checks could be added) in a 301 * future major release. 302 * <p> 303 * See examples in javadoc for {@link Matchers} class 304 * 305 * @return <code>null</code>. 306 */ any()307 public static <T> T any() { 308 return (T) anyObject(); 309 } 310 311 /** 312 * Any <code>String</code> or <code>null</code>. 313 * <p> 314 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 315 * in your code. This might however change (type checks could be added) in a 316 * future major release. 317 * <p> 318 * See examples in javadoc for {@link Matchers} class 319 * 320 * @return empty String ("") 321 */ anyString()322 public static String anyString() { 323 return reportMatcher(Any.ANY).returnString(); 324 } 325 326 /** 327 * Any <code>List</code> or <code>null</code>. 328 * <p> 329 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 330 * in your code. This might however change (type checks could be added) in a 331 * future major release. 332 * <p> 333 * See examples in javadoc for {@link Matchers} class 334 * 335 * @return empty List. 336 */ anyList()337 public static List anyList() { 338 return reportMatcher(Any.ANY).returnList(); 339 } 340 341 /** 342 * Generic friendly alias to {@link Matchers#anyList()}. 343 * It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings. 344 * <p> 345 * Any <code>List</code> or <code>null</code>. 346 * <p> 347 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 348 * in your code. This might however change (type checks could be added) in a 349 * future major release. 350 * <p> 351 * See examples in javadoc for {@link Matchers} class 352 * 353 * @param clazz Type owned by the list to avoid casting 354 * @return empty List. 355 */ anyListOf(Class<T> clazz)356 public static <T> List<T> anyListOf(Class<T> clazz) { 357 return (List) reportMatcher(Any.ANY).returnList(); 358 } 359 360 /** 361 * Any <code>Set</code> or <code>null</code>. 362 * <p> 363 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 364 * in your code. This might however change (type checks could be added) in a 365 * future major release. 366 * <p> 367 * See examples in javadoc for {@link Matchers} class 368 * 369 * @return empty Set 370 */ anySet()371 public static Set anySet() { 372 return reportMatcher(Any.ANY).returnSet(); 373 } 374 375 /** 376 * Generic friendly alias to {@link Matchers#anySet()}. 377 * It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings. 378 * <p> 379 * Any <code>Set</code> or <code>null</code> 380 * <p> 381 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 382 * in your code. This might however change (type checks could be added) in a 383 * future major release. 384 * <p> 385 * See examples in javadoc for {@link Matchers} class 386 * 387 * @param clazz Type owned by the Set to avoid casting 388 * @return empty Set 389 */ anySetOf(Class<T> clazz)390 public static <T> Set<T> anySetOf(Class<T> clazz) { 391 return (Set) reportMatcher(Any.ANY).returnSet(); 392 } 393 394 /** 395 * Any <code>Map</code> or <code>null</code>. 396 * <p> 397 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 398 * in your code. This might however change (type checks could be added) in a 399 * future major release. 400 * <p> 401 * See examples in javadoc for {@link Matchers} class 402 * 403 * @return empty Map. 404 */ anyMap()405 public static Map anyMap() { 406 return reportMatcher(Any.ANY).returnMap(); 407 } 408 409 /** 410 * Generic friendly alias to {@link Matchers#anyMap()}. 411 * It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings. 412 * <p> 413 * Any <code>Map</code> or <code>null</code> 414 * <p> 415 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 416 * in your code. This might however change (type checks could be added) in a 417 * future major release. 418 * <p> 419 * See examples in javadoc for {@link Matchers} class 420 * 421 * @param keyClazz Type of the map key to avoid casting 422 * @param valueClazz Type of the value to avoid casting 423 * @return empty Map. 424 */ anyMapOf(Class<K> keyClazz, Class<V> valueClazz)425 public static <K, V> Map<K, V> anyMapOf(Class<K> keyClazz, Class<V> valueClazz) { 426 return reportMatcher(Any.ANY).returnMap(); 427 } 428 429 /** 430 * Any <code>Collection</code> or <code>null</code>. 431 * <p> 432 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 433 * in your code. This might however change (type checks could be added) in a 434 * future major release. 435 * <p> 436 * See examples in javadoc for {@link Matchers} class 437 * 438 * @return empty Collection. 439 */ anyCollection()440 public static Collection anyCollection() { 441 return reportMatcher(Any.ANY).returnList(); 442 } 443 444 /** 445 * Generic friendly alias to {@link Matchers#anyCollection()}. 446 * It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings. 447 * <p> 448 * Any <code>Collection</code> or <code>null</code>. 449 * <p> 450 * This method <b>*don't do any type checks*</b>, it is only there to avoid casting 451 * in your code. This might however change (type checks could be added) in a 452 * future major release. 453 * <p> 454 * See examples in javadoc for {@link Matchers} class 455 * 456 * @param clazz Type owned by the collection to avoid casting 457 * @return empty Collection. 458 */ anyCollectionOf(Class<T> clazz)459 public static <T> Collection<T> anyCollectionOf(Class<T> clazz) { 460 return (Collection) reportMatcher(Any.ANY).returnList(); 461 } 462 463 /** 464 * <code>Object</code> argument that implements the given class. 465 * <p> 466 * See examples in javadoc for {@link Matchers} class 467 * 468 * @param <T> 469 * the accepted type. 470 * @param clazz 471 * the class of the accepted type. 472 * @return <code>null</code>. 473 */ isA(Class<T> clazz)474 public static <T> T isA(Class<T> clazz) { 475 return reportMatcher(new InstanceOf(clazz)).<T>returnFor(clazz); 476 } 477 478 /** 479 * <code>boolean</code> argument that is equal to the given value. 480 * <p> 481 * See examples in javadoc for {@link Matchers} class 482 * 483 * @param value 484 * the given value. 485 * @return <code>0</code>. 486 */ eq(boolean value)487 public static boolean eq(boolean value) { 488 return reportMatcher(new Equals(value)).returnFalse(); 489 } 490 491 /** 492 * <code>byte</code> argument that is equal to the given value. 493 * <p> 494 * See examples in javadoc for {@link Matchers} class 495 * 496 * @param value 497 * the given value. 498 * @return <code>0</code>. 499 */ eq(byte value)500 public static byte eq(byte value) { 501 return reportMatcher(new Equals(value)).returnZero(); 502 } 503 504 /** 505 * <code>char</code> argument that is equal to the given value. 506 * <p> 507 * See examples in javadoc for {@link Matchers} class 508 * 509 * @param value 510 * the given value. 511 * @return <code>0</code>. 512 */ eq(char value)513 public static char eq(char value) { 514 return reportMatcher(new Equals(value)).returnChar(); 515 } 516 517 /** 518 * <code>double</code> argument that is equal to the given value. 519 * <p> 520 * See examples in javadoc for {@link Matchers} class 521 * 522 * @param value 523 * the given value. 524 * @return <code>0</code>. 525 */ eq(double value)526 public static double eq(double value) { 527 return reportMatcher(new Equals(value)).returnZero(); 528 } 529 530 /** 531 * <code>float</code> argument that is equal to the given value. 532 * <p> 533 * See examples in javadoc for {@link Matchers} class 534 * 535 * @param value 536 * the given value. 537 * @return <code>0</code>. 538 */ eq(float value)539 public static float eq(float value) { 540 return reportMatcher(new Equals(value)).returnZero(); 541 } 542 543 /** 544 * <code>int</code> argument that is equal to the given value. 545 * <p> 546 * See examples in javadoc for {@link Matchers} class 547 * 548 * @param value 549 * the given value. 550 * @return <code>0</code>. 551 */ eq(int value)552 public static int eq(int value) { 553 return reportMatcher(new Equals(value)).returnZero(); 554 } 555 556 /** 557 * <code>long</code> argument that is equal to the given value. 558 * <p> 559 * See examples in javadoc for {@link Matchers} class 560 * 561 * @param value 562 * the given value. 563 * @return <code>0</code>. 564 */ eq(long value)565 public static long eq(long value) { 566 return reportMatcher(new Equals(value)).returnZero(); 567 } 568 569 /** 570 * <code>short</code> argument that is equal to the given value. 571 * <p> 572 * See examples in javadoc for {@link Matchers} class 573 * 574 * @param value 575 * the given value. 576 * @return <code>0</code>. 577 */ eq(short value)578 public static short eq(short value) { 579 return reportMatcher(new Equals(value)).returnZero(); 580 } 581 582 /** 583 * Object argument that is equal to the given value. 584 * <p> 585 * See examples in javadoc for {@link Matchers} class 586 * 587 * @param value 588 * the given value. 589 * @return <code>null</code>. 590 */ eq(T value)591 public static <T> T eq(T value) { 592 return (T) reportMatcher(new Equals(value)).<T>returnFor(value); 593 } 594 595 /** 596 * Object argument that is reflection-equal to the given value with support for excluding 597 * selected fields from a class. 598 * <p> 599 * This matcher can be used when equals() is not implemented on compared objects. 600 * Matcher uses java reflection API to compare fields of wanted and actual object. 601 * <p> 602 * Works similarly to EqualsBuilder.reflectionEquals(this, other, exlucdeFields) from 603 * apache commons library. 604 * <p> 605 * <b>Warning</b> The equality check is shallow! 606 * <p> 607 * See examples in javadoc for {@link Matchers} class 608 * 609 * @param value 610 * the given value. 611 * @param excludeFields 612 * fields to exclude, if field does not exist it is ignored. 613 * @return <code>null</code>. 614 */ refEq(T value, String... excludeFields)615 public static <T> T refEq(T value, String... excludeFields) { 616 return reportMatcher(new ReflectionEquals(value, excludeFields)).<T>returnNull(); 617 } 618 619 /** 620 * Object argument that is the same as the given value. 621 * <p> 622 * See examples in javadoc for {@link Matchers} class 623 * 624 * @param <T> 625 * the type of the object, it is passed through to prevent casts. 626 * @param value 627 * the given value. 628 * @return <code>null</code>. 629 */ same(T value)630 public static <T> T same(T value) { 631 return (T) reportMatcher(new Same(value)).<T>returnFor(value); 632 } 633 634 /** 635 * <code>null</code> argument. 636 * <p> 637 * See examples in javadoc for {@link Matchers} class 638 * 639 * @return <code>null</code>. 640 */ isNull()641 public static Object isNull() { 642 return reportMatcher(Null.NULL).returnNull(); 643 } 644 645 /** 646 * <code>null</code> argument. 647 * The class argument is provided to avoid casting. 648 * <p> 649 * See examples in javadoc for {@link Matchers} class 650 * 651 * @param clazz Type to avoid casting 652 * @return <code>null</code>. 653 */ isNull(Class<T> clazz)654 public static <T> T isNull(Class<T> clazz) { 655 return (T) reportMatcher(Null.NULL).returnNull(); 656 } 657 658 /** 659 * Not <code>null</code> argument. 660 * <p> 661 * alias to {@link Matchers#isNotNull()} 662 * <p> 663 * See examples in javadoc for {@link Matchers} class 664 * 665 * @return <code>null</code>. 666 */ notNull()667 public static Object notNull() { 668 return reportMatcher(NotNull.NOT_NULL).returnNull(); 669 } 670 671 /** 672 * Not <code>null</code> argument, not necessary of the given class. 673 * The class argument is provided to avoid casting. 674 * <p> 675 * alias to {@link Matchers#isNotNull(Class)} 676 * <p> 677 * See examples in javadoc for {@link Matchers} class 678 * 679 * @param clazz Type to avoid casting 680 * @return <code>null</code>. 681 */ notNull(Class<T> clazz)682 public static <T> T notNull(Class<T> clazz) { 683 return (T) reportMatcher(NotNull.NOT_NULL).returnNull(); 684 } 685 686 /** 687 * Not <code>null</code> argument. 688 * <p> 689 * alias to {@link Matchers#notNull()} 690 * <p> 691 * See examples in javadoc for {@link Matchers} class 692 * 693 * @return <code>null</code>. 694 */ isNotNull()695 public static Object isNotNull() { 696 return notNull(); 697 } 698 699 /** 700 * Not <code>null</code> argument, not necessary of the given class. 701 * The class argument is provided to avoid casting. 702 * <p> 703 * alias to {@link Matchers#notNull(Class)} 704 * <p> 705 * See examples in javadoc for {@link Matchers} class 706 * 707 * @param clazz Type to avoid casting 708 * @return <code>null</code>. 709 */ isNotNull(Class<T> clazz)710 public static <T> T isNotNull(Class<T> clazz) { 711 return notNull(clazz); 712 } 713 714 /** 715 * <code>String</code> argument that contains the given substring. 716 * <p> 717 * See examples in javadoc for {@link Matchers} class 718 * 719 * @param substring 720 * the substring. 721 * @return empty String (""). 722 */ contains(String substring)723 public static String contains(String substring) { 724 return reportMatcher(new Contains(substring)).returnString(); 725 } 726 727 /** 728 * <code>String</code> argument that matches the given regular expression. 729 * <p> 730 * See examples in javadoc for {@link Matchers} class 731 * 732 * @param regex 733 * the regular expression. 734 * @return empty String (""). 735 */ matches(String regex)736 public static String matches(String regex) { 737 return reportMatcher(new Matches(regex)).returnString(); 738 } 739 740 /** 741 * <code>String</code> argument that ends with the given suffix. 742 * <p> 743 * See examples in javadoc for {@link Matchers} class 744 * 745 * @param suffix 746 * the suffix. 747 * @return empty String (""). 748 */ endsWith(String suffix)749 public static String endsWith(String suffix) { 750 return reportMatcher(new EndsWith(suffix)).returnString(); 751 } 752 753 /** 754 * <code>String</code> argument that starts with the given prefix. 755 * <p> 756 * See examples in javadoc for {@link Matchers} class 757 * 758 * @param prefix 759 * the prefix. 760 * @return empty String (""). 761 */ startsWith(String prefix)762 public static String startsWith(String prefix) { 763 return reportMatcher(new StartsWith(prefix)).returnString(); 764 } 765 766 /** 767 * Allows creating custom argument matchers. 768 * <p> 769 * In rare cases when the parameter is a primitive then you <b>*must*</b> use relevant intThat(), floatThat(), etc. method. 770 * This way you will avoid <code>NullPointerException</code> during auto-unboxing. 771 * <p> 772 * See examples in javadoc for {@link ArgumentMatcher} class 773 * 774 * @param matcher decides whether argument matches 775 * @return <code>null</code>. 776 */ argThat(Matcher<T> matcher)777 public static <T> T argThat(Matcher<T> matcher) { 778 return reportMatcher(matcher).<T>returnNull(); 779 } 780 781 /** 782 * Allows creating custom <code>Character</code> argument matchers. 783 * <p> 784 * See examples in javadoc for {@link Matchers} class 785 * 786 * @param matcher decides whether argument matches 787 * @return <code>0</code>. 788 */ charThat(Matcher<Character> matcher)789 public static char charThat(Matcher<Character> matcher) { 790 return reportMatcher(matcher).returnChar(); 791 } 792 793 /** 794 * Allows creating custom <code>Boolean</code> argument matchers. 795 * <p> 796 * See examples in javadoc for {@link Matchers} class 797 * 798 * @param matcher decides whether argument matches 799 * @return <code>false</code>. 800 */ booleanThat(Matcher<Boolean> matcher)801 public static boolean booleanThat(Matcher<Boolean> matcher) { 802 return reportMatcher(matcher).returnFalse(); 803 } 804 805 /** 806 * Allows creating custom <code>Byte</code> argument matchers. 807 * <p> 808 * See examples in javadoc for {@link Matchers} class 809 * 810 * @param matcher decides whether argument matches 811 * @return <code>0</code>. 812 */ byteThat(Matcher<Byte> matcher)813 public static byte byteThat(Matcher<Byte> matcher) { 814 return reportMatcher(matcher).returnZero(); 815 } 816 817 /** 818 * Allows creating custom <code>Short</code> argument matchers. 819 * <p> 820 * See examples in javadoc for {@link Matchers} class 821 * 822 * @param matcher decides whether argument matches 823 * @return <code>0</code>. 824 */ shortThat(Matcher<Short> matcher)825 public static short shortThat(Matcher<Short> matcher) { 826 return reportMatcher(matcher).returnZero(); 827 } 828 829 /** 830 * Allows creating custom <code>Integer</code> argument matchers. 831 * <p> 832 * See examples in javadoc for {@link Matchers} class 833 * 834 * @param matcher decides whether argument matches 835 * @return <code>0</code>. 836 */ intThat(Matcher<Integer> matcher)837 public static int intThat(Matcher<Integer> matcher) { 838 return reportMatcher(matcher).returnZero(); 839 } 840 841 /** 842 * Allows creating custom <code>Long</code> argument matchers. 843 * <p> 844 * See examples in javadoc for {@link Matchers} class 845 * 846 * @param matcher decides whether argument matches 847 * @return <code>0</code>. 848 */ longThat(Matcher<Long> matcher)849 public static long longThat(Matcher<Long> matcher) { 850 return reportMatcher(matcher).returnZero(); 851 } 852 853 /** 854 * Allows creating custom <code>Float</code> argument matchers. 855 * <p> 856 * See examples in javadoc for {@link Matchers} class 857 * 858 * @param matcher decides whether argument matches 859 * @return <code>0</code>. 860 */ floatThat(Matcher<Float> matcher)861 public static float floatThat(Matcher<Float> matcher) { 862 return reportMatcher(matcher).returnZero(); 863 } 864 865 /** 866 * Allows creating custom <code>Double</code> argument matchers. 867 * <p> 868 * See examples in javadoc for {@link Matchers} class 869 * 870 * @param matcher decides whether argument matches 871 * @return <code>0</code>. 872 */ doubleThat(Matcher<Double> matcher)873 public static double doubleThat(Matcher<Double> matcher) { 874 return reportMatcher(matcher).returnZero(); 875 } 876 reportMatcher(Matcher<?> matcher)877 private static HandyReturnValues reportMatcher(Matcher<?> matcher) { 878 return mockingProgress.getArgumentMatcherStorage().reportMatcher(matcher); 879 } 880 } 881