1 /* 2 * Copyright (c) 2016 Mockito contributors 3 * This program is made available under the terms of the MIT License. 4 */ 5 package org.mockito; 6 7 import static org.mockito.internal.progress.ThreadSafeMockingProgress.mockingProgress; 8 import static org.mockito.internal.util.Primitives.defaultValue; 9 10 import java.util.ArrayList; 11 import java.util.Collection; 12 import java.util.HashMap; 13 import java.util.HashSet; 14 import java.util.List; 15 import java.util.Map; 16 import java.util.Set; 17 import java.util.regex.Pattern; 18 19 import org.mockito.internal.matchers.Any; 20 import org.mockito.internal.matchers.Contains; 21 import org.mockito.internal.matchers.EndsWith; 22 import org.mockito.internal.matchers.Equals; 23 import org.mockito.internal.matchers.InstanceOf; 24 import org.mockito.internal.matchers.Matches; 25 import org.mockito.internal.matchers.NotNull; 26 import org.mockito.internal.matchers.Null; 27 import org.mockito.internal.matchers.Same; 28 import org.mockito.internal.matchers.StartsWith; 29 import org.mockito.internal.matchers.apachecommons.ReflectionEquals; 30 import org.mockito.internal.util.Primitives; 31 32 /** 33 * Allow flexible verification or stubbing. See also {@link AdditionalMatchers}. 34 * 35 * <pre class="code"><code class="java"> 36 * //stubbing using anyInt() argument matcher 37 * when(mockedList.get(anyInt())).thenReturn("element"); 38 * 39 * //following prints "element" 40 * System.out.println(mockedList.get(999)); 41 * 42 * //you can also verify using argument matcher 43 * verify(mockedList).get(anyInt()); 44 * </code></pre> 45 * 46 * <p> 47 * Since Mockito <code>any(Class)</code> and <code>anyInt</code> family matchers perform a type check, thus they won't 48 * match <code>null</code> arguments. Instead use the <code>isNull</code> matcher. 49 * 50 * <pre class="code"><code class="java"> 51 * // stubbing using anyBoolean() argument matcher 52 * when(mock.dryRun(anyBoolean())).thenReturn("state"); 53 * 54 * // below the stub won't match, and won't return "state" 55 * mock.dryRun(null); 56 * 57 * // either change the stub 58 * when(mock.dryRun(isNull())).thenReturn("state"); 59 * mock.dryRun(null); // ok 60 * 61 * // or fix the code ;) 62 * when(mock.dryRun(anyBoolean())).thenReturn("state"); 63 * mock.dryRun(true); // ok 64 * 65 * </code></pre> 66 * 67 * The same apply for verification. 68 * </p> 69 * 70 * 71 * Scroll down to see all methods - full list of matchers. 72 * 73 * <p> 74 * <b>Warning:</b><br/> 75 * 76 * If you are using argument matchers, <b>all arguments</b> have to be provided by matchers. 77 * 78 * E.g: (example shows verification but the same applies to stubbing): 79 * </p> 80 * 81 * <pre class="code"><code class="java"> 82 * verify(mock).someMethod(anyInt(), anyString(), <b>eq("third argument")</b>); 83 * //above is correct - eq() is also an argument matcher 84 * 85 * verify(mock).someMethod(anyInt(), anyString(), <b>"third argument"</b>); 86 * //above is incorrect - exception will be thrown because third argument is given without argument matcher. 87 * </code></pre> 88 * 89 * <p> 90 * Matcher methods like <code>any()</code>, <code>eq()</code> <b>do not</b> return matchers. 91 * Internally, they record a matcher on a stack and return a dummy value (usually null). 92 * This implementation is due to static type safety imposed by java compiler. 93 * The consequence is that you cannot use <code>any()</code>, <code>eq()</code> methods outside of verified/stubbed method. 94 * </p> 95 * 96 * <h1>Additional matchers</h1> 97 * <p> 98 * The class {@link AdditionalMatchers} offers rarely used matchers, although they can be useful, when 99 * it is useful to combine multiple matchers or when it is useful to negate a matcher necessary. 100 * </p> 101 * 102 * <h1>Custom Argument ArgumentMatchers</h1> 103 * <p> 104 * It is important to understand the use cases and available options for dealing with non-trivial arguments 105 * <b>before</b> implementing custom argument matchers. This way, you can select the best possible approach 106 * for given scenario and produce highest quality test (clean and maintainable). 107 * Please read on in the javadoc for {@link ArgumentMatcher} to learn about approaches and see the examples. 108 * </p> 109 * 110 * @see AdditionalMatchers 111 */ 112 @CheckReturnValue 113 @SuppressWarnings("unchecked") 114 public class ArgumentMatchers { 115 116 /** 117 * Matches <strong>anything</strong>, including nulls and varargs. 118 * 119 * <p> 120 * See examples in javadoc for {@link ArgumentMatchers} class 121 * </p> 122 * 123 * <p> 124 * <strong>Notes : </strong><br/> 125 * <ul> 126 * <li>For primitive types use {@link #anyChar()} family or {@link #isA(Class)} or {@link #any(Class)}.</li> 127 * <li>Since mockito 2.1.0 {@link #any(Class)} is not anymore an alias of this method.</li> 128 * </ul> 129 * </p> 130 * 131 * @return <code>null</code>. 132 * 133 * @see #any(Class) 134 * @see #anyChar() 135 * @see #anyInt() 136 * @see #anyBoolean() 137 */ any()138 public static <T> T any() { 139 reportMatcher(Any.ANY); 140 return null; 141 } 142 143 /** 144 * Matches any object of given type, excluding nulls. 145 * 146 * <p> 147 * This matcher will perform a type check with the given type, thus excluding values. 148 * See examples in javadoc for {@link ArgumentMatchers} class. 149 * 150 * This is an alias of: {@link #isA(Class)}} 151 * </p> 152 * 153 * <p> 154 * Since Mockito 2.1.0, only allow non-null instance of <code></code>, thus <code>null</code> is not anymore a valid value. 155 * As reference are nullable, the suggested API to <strong>match</strong> <code>null</code> 156 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 157 * 1.x. 158 * </p> 159 * 160 * <p><strong>Notes : </strong><br/> 161 * <ul> 162 * <li>For primitive types use {@link #anyChar()} family.</li> 163 * <li>Since Mockito 2.1.0 this method will perform a type check thus <code>null</code> values are not authorized.</li> 164 * <li>Since mockito 2.1.0 {@link #any()} is no longer an alias of this method.</li> 165 * </ul> 166 * </p> 167 * 168 * @param <T> The accepted type 169 * @param type the class of the accepted type. 170 * @return <code>null</code>. 171 * @see #any() 172 * @see #isA(Class) 173 * @see #notNull() 174 * @see #isNull() 175 */ any(Class<T> type)176 public static <T> T any(Class<T> type) { 177 reportMatcher(new InstanceOf.VarArgAware(type, "<any " + type.getCanonicalName() + ">")); 178 return defaultValue(type); 179 } 180 181 /** 182 * <code>Object</code> argument that implements the given class. 183 * <p> 184 * See examples in javadoc for {@link ArgumentMatchers} class 185 * 186 * @param <T> the accepted type. 187 * @param type the class of the accepted type. 188 * @return <code>null</code>. 189 * @see #any(Class) 190 */ isA(Class<T> type)191 public static <T> T isA(Class<T> type) { 192 reportMatcher(new InstanceOf(type)); 193 return defaultValue(type); 194 } 195 196 /** 197 * Any <code>boolean</code> or <strong>non-null</strong> <code>Boolean</code> 198 * 199 * <p> 200 * Since Mockito 2.1.0, only allow valued <code>Boolean</code>, thus <code>null</code> is not anymore a valid value. 201 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 202 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 203 * 1.x. 204 * </p> 205 * 206 * <p> 207 * See examples in javadoc for {@link ArgumentMatchers} class. 208 * </p> 209 * 210 * @return <code>false</code>. 211 * @see #isNull() 212 */ anyBoolean()213 public static boolean anyBoolean() { 214 reportMatcher(new InstanceOf(Boolean.class, "<any boolean>")); 215 return false; 216 } 217 218 /** 219 * Any <code>byte</code> or <strong>non-null</strong> <code>Byte</code>. 220 * 221 * <p> 222 * Since Mockito 2.1.0, only allow valued <code>Byte</code>, thus <code>null</code> is not anymore a valid value. 223 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 224 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 225 * 1.x. 226 * </p> 227 * 228 * <p> 229 * See examples in javadoc for {@link ArgumentMatchers} class. 230 * </p> 231 * 232 * @return <code>0</code>. 233 * @see #isNull() 234 */ anyByte()235 public static byte anyByte() { 236 reportMatcher(new InstanceOf(Byte.class, "<any byte>")); 237 return 0; 238 } 239 240 /** 241 * Any <code>char</code> or <strong>non-null</strong> <code>Character</code>. 242 * 243 * <p> 244 * Since Mockito 2.1.0, only allow valued <code>Character</code>, thus <code>null</code> is not anymore a valid value. 245 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 246 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 247 * 1.x. 248 * </p> 249 * 250 * <p> 251 * See examples in javadoc for {@link ArgumentMatchers} class. 252 * </p> 253 * 254 * @return <code>0</code>. 255 * @see #isNull() 256 */ anyChar()257 public static char anyChar() { 258 reportMatcher(new InstanceOf(Character.class, "<any char>")); 259 return 0; 260 } 261 262 /** 263 * Any int or <strong>non-null</strong> <code>Integer</code>. 264 * 265 * <p> 266 * Since Mockito 2.1.0, only allow valued <code>Integer</code>, thus <code>null</code> is not anymore a valid value. 267 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 268 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 269 * 1.x. 270 * </p> 271 * 272 * <p> 273 * See examples in javadoc for {@link ArgumentMatchers} class. 274 * </p> 275 * 276 * @return <code>0</code>. 277 * @see #isNull() 278 */ anyInt()279 public static int anyInt() { 280 reportMatcher(new InstanceOf(Integer.class, "<any integer>")); 281 return 0; 282 } 283 284 /** 285 * Any <code>long</code> or <strong>non-null</strong> <code>Long</code>. 286 * 287 * <p> 288 * Since Mockito 2.1.0, only allow valued <code>Long</code>, thus <code>null</code> is not anymore a valid value. 289 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 290 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 291 * 1.x. 292 * </p> 293 * 294 * <p> 295 * See examples in javadoc for {@link ArgumentMatchers} class. 296 * </p> 297 * 298 * @return <code>0</code>. 299 * @see #isNull() 300 */ anyLong()301 public static long anyLong() { 302 reportMatcher(new InstanceOf(Long.class, "<any long>")); 303 return 0; 304 } 305 306 /** 307 * Any <code>float</code> or <strong>non-null</strong> <code>Float</code>. 308 * 309 * <p> 310 * Since Mockito 2.1.0, only allow valued <code>Float</code>, thus <code>null</code> is not anymore a valid value. 311 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 312 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 313 * 1.x. 314 * </p> 315 * 316 * <p> 317 * See examples in javadoc for {@link ArgumentMatchers} class. 318 * </p> 319 * 320 * @return <code>0</code>. 321 * @see #isNull() 322 */ anyFloat()323 public static float anyFloat() { 324 reportMatcher(new InstanceOf(Float.class, "<any float>")); 325 return 0; 326 } 327 328 /** 329 * Any <code>double</code> or <strong>non-null</strong> <code>Double</code>. 330 * 331 * <p> 332 * Since Mockito 2.1.0, only allow valued <code>Double</code>, thus <code>null</code> is not anymore a valid value. 333 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 334 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 335 * 1.x. 336 * </p> 337 * 338 * <p> 339 * See examples in javadoc for {@link ArgumentMatchers} class. 340 * </p> 341 * 342 * @return <code>0</code>. 343 * @see #isNull() 344 */ anyDouble()345 public static double anyDouble() { 346 reportMatcher(new InstanceOf(Double.class, "<any double>")); 347 return 0; 348 } 349 350 /** 351 * Any <code>short</code> or <strong>non-null</strong> <code>Short</code>. 352 * 353 * <p> 354 * Since Mockito 2.1.0, only allow valued <code>Short</code>, thus <code>null</code> is not anymore a valid value. 355 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 356 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 357 * 1.x. 358 * </p> 359 * 360 * <p> 361 * See examples in javadoc for {@link ArgumentMatchers} class. 362 * </p> 363 * 364 * @return <code>0</code>. 365 * @see #isNull() 366 */ anyShort()367 public static short anyShort() { 368 reportMatcher(new InstanceOf(Short.class, "<any short>")); 369 return 0; 370 } 371 372 /** 373 * Any <strong>non-null</strong> <code>String</code> 374 * 375 * <p> 376 * Since Mockito 2.1.0, only allow non-null <code>String</code>. 377 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 378 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 379 * 1.x. 380 * </p> 381 * 382 * <p> 383 * See examples in javadoc for {@link ArgumentMatchers} class. 384 * </p> 385 * 386 * @return empty String ("") 387 * @see #isNull() 388 */ anyString()389 public static String anyString() { 390 reportMatcher(new InstanceOf(String.class, "<any string>")); 391 return ""; 392 } 393 394 /** 395 * Any <strong>non-null</strong> <code>List</code>. 396 * 397 * <p> 398 * Since Mockito 2.1.0, only allow non-null <code>List</code>. 399 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 400 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 401 * 1.x. 402 * </p> 403 * 404 * <p> 405 * See examples in javadoc for {@link ArgumentMatchers} class. 406 * </p> 407 * 408 * @return empty List. 409 * @see #isNull() 410 */ anyList()411 public static <T> List<T> anyList() { 412 reportMatcher(new InstanceOf(List.class, "<any List>")); 413 return new ArrayList<T>(0); 414 } 415 416 /** 417 * Any <strong>non-null</strong> <code>Set</code>. 418 * 419 * <p> 420 * Since Mockito 2.1.0, only allow non-null <code>Set</code>. 421 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 422 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 423 * 1.x. 424 * </p> 425 * 426 * <p> 427 * See examples in javadoc for {@link ArgumentMatchers} class. 428 * </p> 429 * 430 * @return empty Set 431 * @see #isNull() 432 */ anySet()433 public static <T> Set<T> anySet() { 434 reportMatcher(new InstanceOf(Set.class, "<any set>")); 435 return new HashSet<T>(0); 436 } 437 438 /** 439 * Any <strong>non-null</strong> <code>Map</code>. 440 * 441 * <p> 442 * Since Mockito 2.1.0, only allow non-null <code>Map</code>. 443 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 444 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 445 * 1.x. 446 * </p> 447 * 448 * <p> 449 * See examples in javadoc for {@link ArgumentMatchers} class. 450 * </p> 451 * 452 * @return empty Map. 453 * @see #isNull() 454 */ anyMap()455 public static <K, V> Map<K, V> anyMap() { 456 reportMatcher(new InstanceOf(Map.class, "<any map>")); 457 return new HashMap<K, V>(0); 458 } 459 460 /** 461 * Any <strong>non-null</strong> <code>Collection</code>. 462 * 463 * <p> 464 * Since Mockito 2.1.0, only allow non-null <code>Collection</code>. 465 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> 466 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 467 * 1.x. 468 * </p> 469 * 470 * <p> 471 * See examples in javadoc for {@link ArgumentMatchers} class. 472 * </p> 473 * 474 * @return empty Collection. 475 * @see #isNull() 476 */ anyCollection()477 public static <T> Collection<T> anyCollection() { 478 reportMatcher(new InstanceOf(Collection.class, "<any collection>")); 479 return new ArrayList<T>(0); 480 } 481 482 /** 483 * Any <strong>non-null</strong> <code>Iterable</code>. 484 * 485 * <p> 486 * Since Mockito 2.1.0, only allow non-null <code>Iterable</code>. 487 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> 488 * would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito 489 * 1.x. 490 * </p> 491 * 492 * <p> 493 * See examples in javadoc for {@link ArgumentMatchers} class. 494 * </p> 495 * 496 * @return empty Iterable. 497 * @see #isNull() 498 * @since 2.1.0 499 */ anyIterable()500 public static <T> Iterable<T> anyIterable() { 501 reportMatcher(new InstanceOf(Iterable.class, "<any iterable>")); 502 return new ArrayList<T>(0); 503 } 504 505 /** 506 * <code>boolean</code> argument that is equal to the given value. 507 * 508 * <p> 509 * See examples in javadoc for {@link ArgumentMatchers} class 510 * </p> 511 * 512 * @param value the given value. 513 * @return <code>0</code>. 514 */ eq(boolean value)515 public static boolean eq(boolean value) { 516 reportMatcher(new Equals(value)); 517 return false; 518 } 519 520 /** 521 * <code>byte</code> argument that is equal to the given value. 522 * 523 * <p> 524 * See examples in javadoc for {@link ArgumentMatchers} class 525 * </p> 526 * 527 * @param value the given value. 528 * @return <code>0</code>. 529 */ eq(byte value)530 public static byte eq(byte value) { 531 reportMatcher(new Equals(value)); 532 return 0; 533 } 534 535 /** 536 * <code>char</code> argument that is equal to the given value. 537 * 538 * <p> 539 * See examples in javadoc for {@link ArgumentMatchers} class 540 * </p> 541 * 542 * @param value the given value. 543 * @return <code>0</code>. 544 */ eq(char value)545 public static char eq(char value) { 546 reportMatcher(new Equals(value)); 547 return 0; 548 } 549 550 /** 551 * <code>double</code> argument that is equal to the given value. 552 * 553 * <p> 554 * See examples in javadoc for {@link ArgumentMatchers} class 555 * </p> 556 * 557 * @param value the given value. 558 * @return <code>0</code>. 559 */ eq(double value)560 public static double eq(double value) { 561 reportMatcher(new Equals(value)); 562 return 0; 563 } 564 565 /** 566 * <code>float</code> argument that is equal to the given value. 567 * 568 * <p> 569 * See examples in javadoc for {@link ArgumentMatchers} class 570 * </p> 571 * 572 * @param value the given value. 573 * @return <code>0</code>. 574 */ eq(float value)575 public static float eq(float value) { 576 reportMatcher(new Equals(value)); 577 return 0; 578 } 579 580 /** 581 * <code>int</code> argument that is equal to the given value. 582 * 583 * <p> 584 * See examples in javadoc for {@link ArgumentMatchers} class 585 * </p> 586 * 587 * @param value the given value. 588 * @return <code>0</code>. 589 */ eq(int value)590 public static int eq(int value) { 591 reportMatcher(new Equals(value)); 592 return 0; 593 } 594 595 /** 596 * <code>long</code> argument that is equal to the given value. 597 * 598 * <p> 599 * See examples in javadoc for {@link ArgumentMatchers} class 600 * </p> 601 * 602 * @param value the given value. 603 * @return <code>0</code>. 604 */ eq(long value)605 public static long eq(long value) { 606 reportMatcher(new Equals(value)); 607 return 0; 608 } 609 610 /** 611 * <code>short</code> argument that is equal to the given value. 612 * <p> 613 * See examples in javadoc for {@link ArgumentMatchers} class 614 * 615 * @param value the given value. 616 * @return <code>0</code>. 617 */ eq(short value)618 public static short eq(short value) { 619 reportMatcher(new Equals(value)); 620 return 0; 621 } 622 623 /** 624 * Object argument that is equal to the given value. 625 * 626 * <p> 627 * See examples in javadoc for {@link ArgumentMatchers} class 628 * </p> 629 * 630 * @param value the given value. 631 * @return <code>null</code>. 632 */ eq(T value)633 public static <T> T eq(T value) { 634 reportMatcher(new Equals(value)); 635 if (value == null) return null; 636 return (T) Primitives.defaultValue(value.getClass()); 637 } 638 639 /** 640 * Object argument that is reflection-equal to the given value with support for excluding 641 * selected fields from a class. 642 * 643 * <p> 644 * This matcher can be used when equals() is not implemented on compared objects. 645 * Matcher uses java reflection API to compare fields of wanted and actual object. 646 * </p> 647 * 648 * <p> 649 * Works similarly to <code>EqualsBuilder.reflectionEquals(this, other, excludeFields)</code> from 650 * apache commons library. 651 * <p> 652 * <b>Warning</b> The equality check is shallow! 653 * </p> 654 * 655 * <p> 656 * See examples in javadoc for {@link ArgumentMatchers} class 657 * </p> 658 * 659 * @param value the given value. 660 * @param excludeFields fields to exclude, if field does not exist it is ignored. 661 * @return <code>null</code>. 662 */ refEq(T value, String... excludeFields)663 public static <T> T refEq(T value, String... excludeFields) { 664 reportMatcher(new ReflectionEquals(value, excludeFields)); 665 return null; 666 } 667 668 /** 669 * Object argument that is the same as the given value. 670 * 671 * <p> 672 * See examples in javadoc for {@link ArgumentMatchers} class 673 * </p> 674 * 675 * @param <T> the type of the object, it is passed through to prevent casts. 676 * @param value the given value. 677 * @return <code>null</code>. 678 */ same(T value)679 public static <T> T same(T value) { 680 reportMatcher(new Same(value)); 681 if (value == null) { 682 return null; 683 } 684 return (T) Primitives.defaultValue(value.getClass()); 685 } 686 687 /** 688 * <code>null</code> argument. 689 * 690 * <p> 691 * See examples in javadoc for {@link ArgumentMatchers} class 692 * </p> 693 * 694 * @return <code>null</code>. 695 * @see #isNotNull() 696 */ isNull()697 public static <T> T isNull() { 698 reportMatcher(Null.NULL); 699 return null; 700 } 701 702 /** 703 * Not <code>null</code> argument. 704 * 705 * <p> 706 * Alias to {@link ArgumentMatchers#isNotNull()} 707 * </p> 708 * 709 * <p> 710 * See examples in javadoc for {@link ArgumentMatchers} class 711 * </p> 712 * 713 * @return <code>null</code>. 714 */ notNull()715 public static <T> T notNull() { 716 reportMatcher(NotNull.NOT_NULL); 717 return null; 718 } 719 720 /** 721 * Not <code>null</code> argument. 722 * 723 * <p> 724 * Alias to {@link ArgumentMatchers#notNull()} 725 * </p> 726 * 727 * <p> 728 * See examples in javadoc for {@link ArgumentMatchers} class 729 * </p> 730 * 731 * @return <code>null</code>. 732 * @see #isNull() 733 */ isNotNull()734 public static <T> T isNotNull() { 735 return notNull(); 736 } 737 738 /** 739 * Argument that is either <code>null</code> or of the given type. 740 * 741 * <p> 742 * See examples in javadoc for {@link ArgumentMatchers} class 743 * </p> 744 * 745 * @param clazz Type to avoid casting 746 * @return <code>null</code>. 747 */ nullable(Class<T> clazz)748 public static <T> T nullable(Class<T> clazz) { 749 AdditionalMatchers.or(isNull(), isA(clazz)); 750 return Primitives.defaultValue(clazz); 751 } 752 753 /** 754 * <code>String</code> argument that contains the given substring. 755 * <p> 756 * See examples in javadoc for {@link ArgumentMatchers} class 757 * 758 * @param substring the substring. 759 * @return empty String (""). 760 */ contains(String substring)761 public static String contains(String substring) { 762 reportMatcher(new Contains(substring)); 763 return ""; 764 } 765 766 /** 767 * <code>String</code> argument that matches the given regular expression. 768 * <p> 769 * See examples in javadoc for {@link ArgumentMatchers} class 770 * 771 * @param regex the regular expression. 772 * @return empty String (""). 773 * 774 * @see AdditionalMatchers#not(boolean) 775 */ matches(String regex)776 public static String matches(String regex) { 777 reportMatcher(new Matches(regex)); 778 return ""; 779 } 780 781 /** 782 * <code>Pattern</code> argument that matches the given regular expression. 783 * <p> 784 * See examples in javadoc for {@link ArgumentMatchers} class 785 * 786 * @param pattern the regular expression pattern. 787 * @return empty String (""). 788 * 789 * @see AdditionalMatchers#not(boolean) 790 */ matches(Pattern pattern)791 public static String matches(Pattern pattern) { 792 reportMatcher(new Matches(pattern)); 793 return ""; 794 } 795 796 /** 797 * <code>String</code> argument that ends with the given suffix. 798 * <p> 799 * See examples in javadoc for {@link ArgumentMatchers} class 800 * 801 * @param suffix the suffix. 802 * @return empty String (""). 803 */ endsWith(String suffix)804 public static String endsWith(String suffix) { 805 reportMatcher(new EndsWith(suffix)); 806 return ""; 807 } 808 809 /** 810 * <code>String</code> argument that starts with the given prefix. 811 * <p> 812 * See examples in javadoc for {@link ArgumentMatchers} class 813 * 814 * @param prefix the prefix. 815 * @return empty String (""). 816 */ startsWith(String prefix)817 public static String startsWith(String prefix) { 818 reportMatcher(new StartsWith(prefix)); 819 return ""; 820 } 821 822 /** 823 * Allows creating custom argument matchers. 824 * 825 * <p> 826 * This API has changed in 2.1.0, please read {@link ArgumentMatcher} for rationale and migration guide. 827 * <b>NullPointerException</b> auto-unboxing caveat is described below. 828 * </p> 829 * 830 * <p> 831 * It is important to understand the use cases and available options for dealing with non-trivial arguments 832 * <b>before</b> implementing custom argument matchers. This way, you can select the best possible approach 833 * for given scenario and produce highest quality test (clean and maintainable). 834 * Please read the documentation for {@link ArgumentMatcher} to learn about approaches and see the examples. 835 * </p> 836 * 837 * <p> 838 * <b>NullPointerException</b> auto-unboxing caveat. 839 * In rare cases when matching primitive parameter types you <b>*must*</b> use relevant intThat(), floatThat(), etc. method. 840 * This way you will avoid <code>NullPointerException</code> during auto-unboxing. 841 * Due to how java works we don't really have a clean way of detecting this scenario and protecting the user from this problem. 842 * Hopefully, the javadoc describes the problem and solution well. 843 * If you have an idea how to fix the problem, let us know via the mailing list or the issue tracker. 844 * </p> 845 * 846 * <p> 847 * See examples in javadoc for {@link ArgumentMatcher} class 848 * </p> 849 * 850 * @param matcher decides whether argument matches 851 * @return <code>null</code>. 852 */ argThat(ArgumentMatcher<T> matcher)853 public static <T> T argThat(ArgumentMatcher<T> matcher) { 854 reportMatcher(matcher); 855 return null; 856 } 857 858 /** 859 * Allows creating custom <code>char</code> argument matchers. 860 * 861 * Note that {@link #argThat} will not work with primitive <code>char</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 862 * <p> 863 * See examples in javadoc for {@link ArgumentMatchers} class 864 * 865 * @param matcher decides whether argument matches 866 * @return <code>0</code>. 867 */ charThat(ArgumentMatcher<Character> matcher)868 public static char charThat(ArgumentMatcher<Character> matcher) { 869 reportMatcher(matcher); 870 return 0; 871 } 872 873 /** 874 * Allows creating custom <code>boolean</code> argument matchers. 875 * 876 * Note that {@link #argThat} will not work with primitive <code>boolean</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 877 * <p> 878 * See examples in javadoc for {@link ArgumentMatchers} class 879 * 880 * @param matcher decides whether argument matches 881 * @return <code>false</code>. 882 */ booleanThat(ArgumentMatcher<Boolean> matcher)883 public static boolean booleanThat(ArgumentMatcher<Boolean> matcher) { 884 reportMatcher(matcher); 885 return false; 886 } 887 888 /** 889 * Allows creating custom <code>byte</code> argument matchers. 890 * 891 * Note that {@link #argThat} will not work with primitive <code>byte</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 892 * <p> 893 * See examples in javadoc for {@link ArgumentMatchers} class 894 * 895 * @param matcher decides whether argument matches 896 * @return <code>0</code>. 897 */ byteThat(ArgumentMatcher<Byte> matcher)898 public static byte byteThat(ArgumentMatcher<Byte> matcher) { 899 reportMatcher(matcher); 900 return 0; 901 } 902 903 /** 904 * Allows creating custom <code>short</code> argument matchers. 905 * 906 * Note that {@link #argThat} will not work with primitive <code>short</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 907 * <p> 908 * See examples in javadoc for {@link ArgumentMatchers} class 909 * 910 * @param matcher decides whether argument matches 911 * @return <code>0</code>. 912 */ shortThat(ArgumentMatcher<Short> matcher)913 public static short shortThat(ArgumentMatcher<Short> matcher) { 914 reportMatcher(matcher); 915 return 0; 916 } 917 918 /** 919 * Allows creating custom <code>int</code> argument matchers. 920 * 921 * Note that {@link #argThat} will not work with primitive <code>int</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 922 * <p> 923 * See examples in javadoc for {@link ArgumentMatchers} class 924 * 925 * @param matcher decides whether argument matches 926 * @return <code>0</code>. 927 */ intThat(ArgumentMatcher<Integer> matcher)928 public static int intThat(ArgumentMatcher<Integer> matcher) { 929 reportMatcher(matcher); 930 return 0; 931 } 932 933 /** 934 * Allows creating custom <code>long</code> argument matchers. 935 * 936 * Note that {@link #argThat} will not work with primitive <code>long</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 937 * <p> 938 * See examples in javadoc for {@link ArgumentMatchers} class 939 * 940 * @param matcher decides whether argument matches 941 * @return <code>0</code>. 942 */ longThat(ArgumentMatcher<Long> matcher)943 public static long longThat(ArgumentMatcher<Long> matcher) { 944 reportMatcher(matcher); 945 return 0; 946 } 947 948 /** 949 * Allows creating custom <code>float</code> argument matchers. 950 * 951 * Note that {@link #argThat} will not work with primitive <code>float</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 952 * <p> 953 * See examples in javadoc for {@link ArgumentMatchers} class 954 * 955 * @param matcher decides whether argument matches 956 * @return <code>0</code>. 957 */ floatThat(ArgumentMatcher<Float> matcher)958 public static float floatThat(ArgumentMatcher<Float> matcher) { 959 reportMatcher(matcher); 960 return 0; 961 } 962 963 /** 964 * Allows creating custom <code>double</code> argument matchers. 965 * 966 * Note that {@link #argThat} will not work with primitive <code>double</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 967 * <p> 968 * See examples in javadoc for {@link ArgumentMatchers} class 969 * 970 * @param matcher decides whether argument matches 971 * @return <code>0</code>. 972 */ doubleThat(ArgumentMatcher<Double> matcher)973 public static double doubleThat(ArgumentMatcher<Double> matcher) { 974 reportMatcher(matcher); 975 return 0; 976 } 977 reportMatcher(ArgumentMatcher<?> matcher)978 private static void reportMatcher(ArgumentMatcher<?> matcher) { 979 mockingProgress().getArgumentMatcherStorage().reportMatcher(matcher); 980 } 981 } 982