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 java.util.ArrayList; 8 import java.util.Collection; 9 import java.util.HashMap; 10 import java.util.HashSet; 11 import java.util.List; 12 import java.util.Map; 13 import java.util.Set; 14 import java.util.regex.Pattern; 15 import org.mockito.internal.matchers.Any; 16 import org.mockito.internal.matchers.Contains; 17 import org.mockito.internal.matchers.EndsWith; 18 import org.mockito.internal.matchers.Equals; 19 import org.mockito.internal.matchers.InstanceOf; 20 import org.mockito.internal.matchers.Matches; 21 import org.mockito.internal.matchers.NotNull; 22 import org.mockito.internal.matchers.Null; 23 import org.mockito.internal.matchers.Same; 24 import org.mockito.internal.matchers.StartsWith; 25 import org.mockito.internal.matchers.apachecommons.ReflectionEquals; 26 import org.mockito.internal.util.Primitives; 27 28 import static org.mockito.internal.progress.ThreadSafeMockingProgress.mockingProgress; 29 import static org.mockito.internal.util.Primitives.defaultValue; 30 31 /** 32 * Allow flexible verification or stubbing. See also {@link AdditionalMatchers}. 33 * 34 * <p> 35 * {@link Mockito} extends ArgumentMatchers so to get access to all matchers just import Mockito class statically. 36 * 37 * <pre class="code"><code class="java"> 38 * //stubbing using anyInt() argument matcher 39 * when(mockedList.get(anyInt())).thenReturn("element"); 40 * 41 * //following prints "element" 42 * System.out.println(mockedList.get(999)); 43 * 44 * //you can also verify using argument matcher 45 * verify(mockedList).get(anyInt()); 46 * </code></pre> 47 * 48 * <p> 49 * Since Mockito <code>any(Class)</code> and <code>anyInt</code> family matchers perform a type check, thus they won't 50 * match <code>null</code> arguments. Instead use the <code>isNull</code> matcher. 51 * 52 * <pre class="code"><code class="java"> 53 * // stubbing using anyBoolean() argument matcher 54 * when(mock.dryRun(anyBoolean())).thenReturn("state"); 55 * 56 * // below the stub won't match, and won't return "state" 57 * mock.dryRun(null); 58 * 59 * // either change the stub 60 * when(mock.dryRun(isNull())).thenReturn("state"); 61 * mock.dryRun(null); // ok 62 * 63 * // or fix the code ;) 64 * when(mock.dryRun(anyBoolean())).thenReturn("state"); 65 * mock.dryRun(true); // ok 66 * 67 * </code></pre> 68 * 69 * The same apply for verification. 70 * </p> 71 * 72 * 73 * Scroll down to see all methods - full list of matchers. 74 * 75 * <p> 76 * <b>Warning:</b><br/> 77 * 78 * If you are using argument matchers, <b>all arguments</b> have to be provided by matchers. 79 * 80 * E.g: (example shows verification but the same applies to stubbing): 81 * </p> 82 * 83 * <pre class="code"><code class="java"> 84 * verify(mock).someMethod(anyInt(), anyString(), <b>eq("third argument")</b>); 85 * //above is correct - eq() is also an argument matcher 86 * 87 * verify(mock).someMethod(anyInt(), anyString(), <b>"third argument"</b>); 88 * //above is incorrect - exception will be thrown because third argument is given without argument matcher. 89 * </code></pre> 90 * 91 * <p> 92 * Matcher methods like <code>anyObject()</code>, <code>eq()</code> <b>do not</b> return matchers. 93 * Internally, they record a matcher on a stack and return a dummy value (usually null). 94 * This implementation is due to static type safety imposed by java compiler. 95 * The consequence is that you cannot use <code>anyObject()</code>, <code>eq()</code> methods outside of verified/stubbed method. 96 * </p> 97 * 98 * <h1>Additional matchers</h1> 99 * <p> 100 * The class {@link AdditionalMatchers} offers rarely used matchers, although they can be useful, when 101 * it is useful to combine multiple matchers or when it is useful to negate a matcher necessary. 102 * </p> 103 * 104 * <h1>Custom Argument ArgumentMatchers</h1> 105 * <p> 106 * It is important to understand the use cases and available options for dealing with non-trivial arguments 107 * <b>before</b> implementing custom argument matchers. This way, you can select the best possible approach 108 * for given scenario and produce highest quality test (clean and maintainable). 109 * Please read on in the javadoc for {@link ArgumentMatcher} to learn about approaches and see the examples. 110 * </p> 111 * 112 * @see AdditionalMatchers 113 */ 114 @SuppressWarnings("unchecked") 115 public class ArgumentMatchers { 116 117 /** 118 * Matches <strong>anything</strong>, including nulls and varargs. 119 * 120 * <p> 121 * See examples in javadoc for {@link ArgumentMatchers} class 122 * 123 * This is an alias of: {@link #anyObject()} and {@link #any(java.lang.Class)} 124 * </p> 125 * 126 * <p> 127 * <strong>Notes : </strong><br/> 128 * <ul> 129 * <li>For primitive types use {@link #anyChar()} family or {@link #isA(Class)} or {@link #any(Class)}.</li> 130 * <li>Since mockito 2.1.0 {@link #any(Class)} is not anymore an alias of this method.</li> 131 * </ul> 132 * </p> 133 * 134 * @return <code>null</code>. 135 * 136 * @see #any(Class) 137 * @see #anyObject() 138 * @see #anyVararg() 139 * @see #anyChar() 140 * @see #anyInt() 141 * @see #anyBoolean() 142 * @see #anyCollectionOf(Class) 143 */ any()144 public static <T> T any() { 145 return anyObject(); 146 } 147 148 /** 149 * Matches anything, including <code>null</code>. 150 * 151 * <p> 152 * This is an alias of: {@link #any()} and {@link #any(java.lang.Class)}. 153 * See examples in javadoc for {@link ArgumentMatchers} class. 154 * </p> 155 * 156 * @return <code>null</code>. 157 * @see #any() 158 * @see #any(Class) 159 * @see #notNull() 160 * @see #notNull(Class) 161 * @deprecated This will be removed in Mockito 3.0 (which will be java 8 only) 162 */ 163 @Deprecated anyObject()164 public static <T> T anyObject() { 165 reportMatcher(Any.ANY); 166 return null; 167 } 168 169 /** 170 * Matches any object of given type, excluding nulls. 171 * 172 * <p> 173 * This matcher will perform a type check with the given type, thus excluding values. 174 * See examples in javadoc for {@link ArgumentMatchers} class. 175 * 176 * This is an alias of: {@link #isA(Class)}} 177 * </p> 178 * 179 * <p> 180 * Since Mockito 2.1.0, only allow non-null instance of <code></code>, thus <code>null</code> is not anymore a valid value. 181 * As reference are nullable, the suggested API to <strong>match</strong> <code>null</code> 182 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 183 * 1.x. 184 * </p> 185 * 186 * <p><strong>Notes : </strong><br/> 187 * <ul> 188 * <li>For primitive types use {@link #anyChar()} family.</li> 189 * <li>Since Mockito 2.1.0 this method will perform a type check thus <code>null</code> values are not authorized.</li> 190 * <li>Since mockito 2.1.0 {@link #any()} and {@link #anyObject()} are not anymore aliases of this method.</li> 191 * </ul> 192 * </p> 193 * 194 * @param <T> The accepted type 195 * @param type the class of the accepted type. 196 * @return <code>null</code>. 197 * @see #any() 198 * @see #anyObject() 199 * @see #anyVararg() 200 * @see #isA(Class) 201 * @see #notNull() 202 * @see #notNull(Class) 203 * @see #isNull() 204 * @see #isNull(Class) 205 */ any(Class<T> type)206 public static <T> T any(Class<T> type) { 207 reportMatcher(new InstanceOf.VarArgAware(type, "<any " + type.getCanonicalName() + ">")); 208 return defaultValue(type); 209 } 210 211 /** 212 * <code>Object</code> argument that implements the given class. 213 * <p> 214 * See examples in javadoc for {@link ArgumentMatchers} class 215 * 216 * @param <T> the accepted type. 217 * @param type the class of the accepted type. 218 * @return <code>null</code>. 219 * @see #any(Class) 220 */ isA(Class<T> type)221 public static <T> T isA(Class<T> type) { 222 reportMatcher(new InstanceOf(type)); 223 return defaultValue(type); 224 } 225 226 /** 227 * Any vararg, meaning any number and values of arguments. 228 * 229 * <p> 230 * Example: 231 * <pre class="code"><code class="java"> 232 * //verification: 233 * mock.foo(1, 2); 234 * mock.foo(1, 2, 3, 4); 235 * 236 * verify(mock, times(2)).foo(anyVararg()); 237 * 238 * //stubbing: 239 * when(mock.foo(anyVararg()).thenReturn(100); 240 * 241 * //prints 100 242 * System.out.println(mock.foo(1, 2)); 243 * //also prints 100 244 * System.out.println(mock.foo(1, 2, 3, 4)); 245 * </code></pre> 246 * </p> 247 * 248 * <p> 249 * See examples in javadoc for {@link ArgumentMatchers} class. 250 * </p> 251 * 252 * @return <code>null</code>. 253 * @see #any() 254 * @see #any(Class) 255 * @deprecated as of 2.1.0 use {@link #any()} 256 */ 257 @Deprecated anyVararg()258 public static <T> T anyVararg() { 259 any(); 260 return null; 261 } 262 263 /** 264 * Any <code>boolean</code> or <strong>non-null</strong> <code>Boolean</code> 265 * 266 * <p> 267 * Since Mockito 2.1.0, only allow valued <code>Boolean</code>, thus <code>null</code> is not anymore a valid value. 268 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 269 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 270 * 1.x. 271 * </p> 272 * 273 * <p> 274 * See examples in javadoc for {@link ArgumentMatchers} class. 275 * </p> 276 * 277 * @return <code>false</code>. 278 * @see #isNull() 279 * @see #isNull(Class) 280 */ anyBoolean()281 public static boolean anyBoolean() { 282 reportMatcher(new InstanceOf(Boolean.class, "<any boolean>")); 283 return false; 284 } 285 286 /** 287 * Any <code>byte</code> or <strong>non-null</strong> <code>Byte</code>. 288 * 289 * <p> 290 * Since Mockito 2.1.0, only allow valued <code>Byte</code>, thus <code>null</code> is not anymore a valid value. 291 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 292 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 293 * 1.x. 294 * </p> 295 * 296 * <p> 297 * See examples in javadoc for {@link ArgumentMatchers} class. 298 * </p> 299 * 300 * @return <code>0</code>. 301 * @see #isNull() 302 * @see #isNull(Class) 303 */ anyByte()304 public static byte anyByte() { 305 reportMatcher(new InstanceOf(Byte.class, "<any byte>")); 306 return 0; 307 } 308 309 /** 310 * Any <code>char</code> or <strong>non-null</strong> <code>Character</code>. 311 * 312 * <p> 313 * Since Mockito 2.1.0, only allow valued <code>Character</code>, thus <code>null</code> is not anymore a valid value. 314 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 315 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 316 * 1.x. 317 * </p> 318 * 319 * <p> 320 * See examples in javadoc for {@link ArgumentMatchers} class. 321 * </p> 322 * 323 * @return <code>0</code>. 324 * @see #isNull() 325 * @see #isNull(Class) 326 */ anyChar()327 public static char anyChar() { 328 reportMatcher(new InstanceOf(Character.class, "<any char>")); 329 return 0; 330 } 331 332 /** 333 * Any int or <strong>non-null</strong> <code>Integer</code>. 334 * 335 * <p> 336 * Since Mockito 2.1.0, only allow valued <code>Integer</code>, thus <code>null</code> is not anymore a valid value. 337 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 338 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 339 * 1.x. 340 * </p> 341 * 342 * <p> 343 * See examples in javadoc for {@link ArgumentMatchers} class. 344 * </p> 345 * 346 * @return <code>0</code>. 347 * @see #isNull() 348 * @see #isNull(Class) 349 */ anyInt()350 public static int anyInt() { 351 reportMatcher(new InstanceOf(Integer.class, "<any integer>")); 352 return 0; 353 } 354 355 /** 356 * Any <code>long</code> or <strong>non-null</strong> <code>Long</code>. 357 * 358 * <p> 359 * Since Mockito 2.1.0, only allow valued <code>Long</code>, thus <code>null</code> is not anymore a valid value. 360 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 361 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 362 * 1.x. 363 * </p> 364 * 365 * <p> 366 * See examples in javadoc for {@link ArgumentMatchers} class. 367 * </p> 368 * 369 * @return <code>0</code>. 370 * @see #isNull() 371 * @see #isNull(Class) 372 */ anyLong()373 public static long anyLong() { 374 reportMatcher(new InstanceOf(Long.class, "<any long>")); 375 return 0; 376 } 377 378 /** 379 * Any <code>float</code> or <strong>non-null</strong> <code>Float</code>. 380 * 381 * <p> 382 * Since Mockito 2.1.0, only allow valued <code>Float</code>, thus <code>null</code> is not anymore a valid value. 383 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 384 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 385 * 1.x. 386 * </p> 387 * 388 * <p> 389 * See examples in javadoc for {@link ArgumentMatchers} class. 390 * </p> 391 * 392 * @return <code>0</code>. 393 * @see #isNull() 394 * @see #isNull(Class) 395 */ anyFloat()396 public static float anyFloat() { 397 reportMatcher(new InstanceOf(Float.class, "<any float>")); 398 return 0; 399 } 400 401 /** 402 * Any <code>double</code> or <strong>non-null</strong> <code>Double</code>. 403 * 404 * <p> 405 * Since Mockito 2.1.0, only allow valued <code>Double</code>, thus <code>null</code> is not anymore a valid value. 406 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 407 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 408 * 1.x. 409 * </p> 410 * 411 * <p> 412 * See examples in javadoc for {@link ArgumentMatchers} class. 413 * </p> 414 * 415 * @return <code>0</code>. 416 * @see #isNull() 417 * @see #isNull(Class) 418 */ anyDouble()419 public static double anyDouble() { 420 reportMatcher(new InstanceOf(Double.class, "<any double>")); 421 return 0; 422 } 423 424 /** 425 * Any <code>short</code> or <strong>non-null</strong> <code>Short</code>. 426 * 427 * <p> 428 * Since Mockito 2.1.0, only allow valued <code>Short</code>, thus <code>null</code> is not anymore a valid value. 429 * As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper 430 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 431 * 1.x. 432 * </p> 433 * 434 * <p> 435 * See examples in javadoc for {@link ArgumentMatchers} class. 436 * </p> 437 * 438 * @return <code>0</code>. 439 * @see #isNull() 440 * @see #isNull(Class) 441 */ anyShort()442 public static short anyShort() { 443 reportMatcher(new InstanceOf(Short.class, "<any short>")); 444 return 0; 445 } 446 447 /** 448 * Any <strong>non-null</strong> <code>String</code> 449 * 450 * <p> 451 * Since Mockito 2.1.0, only allow non-null <code>String</code>. 452 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 453 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 454 * 1.x. 455 * </p> 456 * 457 * <p> 458 * See examples in javadoc for {@link ArgumentMatchers} class. 459 * </p> 460 * 461 * @return empty String ("") 462 * @see #isNull() 463 * @see #isNull(Class) 464 */ anyString()465 public static String anyString() { 466 reportMatcher(new InstanceOf(String.class, "<any string>")); 467 return ""; 468 } 469 470 /** 471 * Any <strong>non-null</strong> <code>List</code>. 472 * 473 * <p> 474 * Since Mockito 2.1.0, only allow non-null <code>List</code>. 475 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 476 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 477 * 1.x. 478 * </p> 479 * 480 * <p> 481 * See examples in javadoc for {@link ArgumentMatchers} class. 482 * </p> 483 * 484 * @return empty List. 485 * @see #anyListOf(Class) 486 * @see #isNull() 487 * @see #isNull(Class) 488 */ anyList()489 public static <T> List<T> anyList() { 490 reportMatcher(new InstanceOf(List.class, "<any List>")); 491 return new ArrayList<T>(0); 492 } 493 494 /** 495 * Any <strong>non-null</strong> <code>List</code>. 496 * 497 * Generic friendly alias to {@link ArgumentMatchers#anyList()}. It's an alternative to 498 * <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings. 499 * 500 * <p> 501 * This method doesn't do type checks of the list content with the given type parameter, it is only there 502 * to avoid casting in the code. 503 * </p> 504 * 505 * <p> 506 * Since Mockito 2.1.0, only allow non-null <code>List</code>. 507 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 508 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 509 * 1.x. 510 * </p> 511 * 512 * <p> 513 * See examples in javadoc for {@link ArgumentMatchers} class. 514 * </p> 515 * 516 * @param clazz Type owned by the list to avoid casting 517 * @return empty List. 518 * @see #anyList() 519 * @see #isNull() 520 * @see #isNull(Class) 521 * @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic 522 * friendliness to avoid casting, this is not anymore needed in Java 8. 523 */ anyListOf(Class<T> clazz)524 public static <T> List<T> anyListOf(Class<T> clazz) { 525 return anyList(); 526 } 527 528 /** 529 * Any <strong>non-null</strong> <code>Set</code>. 530 * 531 * <p> 532 * Since Mockito 2.1.0, only allow non-null <code>Set</code>. 533 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 534 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 535 * 1.x. 536 * </p> 537 * 538 * <p> 539 * See examples in javadoc for {@link ArgumentMatchers} class. 540 * </p> 541 * 542 * @return empty Set 543 * @see #anySetOf(Class) 544 * @see #isNull() 545 * @see #isNull(Class) 546 */ anySet()547 public static <T> Set<T> anySet() { 548 reportMatcher(new InstanceOf(Set.class, "<any set>")); 549 return new HashSet<T>(0); 550 } 551 552 /** 553 * Any <strong>non-null</strong> <code>Set</code>. 554 * 555 * <p> 556 * Generic friendly alias to {@link ArgumentMatchers#anySet()}. 557 * It's an alternative to <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings. 558 * </p> 559 * 560 * <p> 561 * This method doesn't do type checks of the set content with the given type parameter, it is only there 562 * to avoid casting in the code. 563 * </p> 564 * 565 * <p> 566 * Since Mockito 2.1.0, only allow non-null <code>Set</code>. 567 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 568 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 569 * 1.x. 570 * </p> 571 * 572 * <p> 573 * See examples in javadoc for {@link ArgumentMatchers} class. 574 * </p> 575 * 576 * @param clazz Type owned by the Set to avoid casting 577 * @return empty Set 578 * @see #anySet() 579 * @see #isNull() 580 * @see #isNull(Class) 581 * @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic 582 * friendliness to avoid casting, this is not anymore needed in Java 8. 583 */ anySetOf(Class<T> clazz)584 public static <T> Set<T> anySetOf(Class<T> clazz) { 585 return anySet(); 586 } 587 588 /** 589 * Any <strong>non-null</strong> <code>Map</code>. 590 * 591 * <p> 592 * Since Mockito 2.1.0, only allow non-null <code>Map</code>. 593 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 594 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 595 * 1.x. 596 * </p> 597 * 598 * <p> 599 * See examples in javadoc for {@link ArgumentMatchers} class. 600 * </p> 601 * 602 * @return empty Map. 603 * @see #anyMapOf(Class, Class) 604 * @see #isNull() 605 * @see #isNull(Class) 606 */ anyMap()607 public static <K, V> Map<K, V> anyMap() { 608 reportMatcher(new InstanceOf(Map.class, "<any map>")); 609 return new HashMap<K, V>(0); 610 } 611 612 /** 613 * Any <strong>non-null</strong> <code>Map</code>. 614 * 615 * <p> 616 * Generic friendly alias to {@link ArgumentMatchers#anyMap()}. 617 * It's an alternative to <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings. 618 * </p> 619 * 620 * <p> 621 * This method doesn't do type checks of the map content with the given type parameter, it is only there 622 * to avoid casting in the code. 623 * </p> 624 * 625 * <p> 626 * Since Mockito 2.1.0, only allow non-null <code>Map</code>. 627 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 628 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 629 * 1.x. 630 * </p> 631 * 632 * <p> 633 * See examples in javadoc for {@link ArgumentMatchers} class. 634 * </p> 635 * 636 * @param keyClazz Type of the map key to avoid casting 637 * @param valueClazz Type of the value to avoid casting 638 * @return empty Map. 639 * @see #anyMap() 640 * @see #isNull() 641 * @see #isNull(Class) 642 * @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic 643 * friendliness to avoid casting, this is not anymore needed in Java 8. 644 */ anyMapOf(Class<K> keyClazz, Class<V> valueClazz)645 public static <K, V> Map<K, V> anyMapOf(Class<K> keyClazz, Class<V> valueClazz) { 646 return anyMap(); 647 } 648 649 /** 650 * Any <strong>non-null</strong> <code>Collection</code>. 651 * 652 * <p> 653 * Since Mockito 2.1.0, only allow non-null <code>Collection</code>. 654 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> 655 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 656 * 1.x. 657 * </p> 658 * 659 * <p> 660 * See examples in javadoc for {@link ArgumentMatchers} class. 661 * </p> 662 * 663 * @return empty Collection. 664 * @see #anyCollectionOf(Class) 665 * @see #isNull() 666 * @see #isNull(Class) 667 */ anyCollection()668 public static <T> Collection<T> anyCollection() { 669 reportMatcher(new InstanceOf(Collection.class, "<any collection>")); 670 return new ArrayList<T>(0); 671 } 672 673 /** 674 * Any <strong>non-null</strong> <code>Collection</code>. 675 * 676 * <p> 677 * Generic friendly alias to {@link ArgumentMatchers#anyCollection()}. 678 * It's an alternative to <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings. 679 * </p> 680 * 681 * <p> 682 * This method doesn't do type checks of the collection content with the given type parameter, it is only there 683 * to avoid casting in the code. 684 * </p> 685 * 686 * <p> 687 * Since Mockito 2.1.0, only allow non-null <code>Collection</code>. 688 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> 689 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 690 * 1.x. 691 * </p> 692 * 693 * <p> 694 * See examples in javadoc for {@link ArgumentMatchers} class. 695 * </p> 696 * 697 * @param clazz Type owned by the collection to avoid casting 698 * @return empty Collection. 699 * @see #anyCollection() 700 * @see #isNull() 701 * @see #isNull(Class) 702 * @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic 703 * friendliness to avoid casting, this is not anymore needed in Java 8. 704 */ anyCollectionOf(Class<T> clazz)705 public static <T> Collection<T> anyCollectionOf(Class<T> clazz) { 706 return anyCollection(); 707 } 708 709 /** 710 * Any <strong>non-null</strong> <code>Iterable</code>. 711 * 712 * <p> 713 * Since Mockito 2.1.0, only allow non-null <code>Iterable</code>. 714 * As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> 715 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 716 * 1.x. 717 * </p> 718 * 719 * <p> 720 * See examples in javadoc for {@link ArgumentMatchers} class. 721 * </p> 722 * 723 * @return empty Iterable. 724 * @see #anyIterableOf(Class) 725 * @see #isNull() 726 * @see #isNull(Class) 727 * @since 2.1.0 728 */ anyIterable()729 public static <T> Iterable<T> anyIterable() { 730 reportMatcher(new InstanceOf(Iterable.class, "<any iterable>")); 731 return new ArrayList<T>(0); 732 } 733 734 /** 735 * Any <strong>non-null</strong> <code>Iterable</code>. 736 * 737 * <p> 738 * Generic friendly alias to {@link ArgumentMatchers#anyIterable()}. 739 * It's an alternative to <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings. 740 * </p> 741 * 742 * <p> 743 * This method doesn't do type checks of the iterable content with the given type parameter, it is only there 744 * to avoid casting in the code. 745 * </p> 746 * 747 * <p> 748 * Since Mockito 2.1.0, only allow non-null <code>String</code>. 749 * As strings are nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper 750 * would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito 751 * 1.x. 752 * </p> 753 * 754 * <p> 755 * See examples in javadoc for {@link ArgumentMatchers} class. 756 * </p> 757 * 758 * @param clazz Type owned by the collection to avoid casting 759 * @return empty Iterable. 760 * @see #anyIterable() 761 * @see #isNull() 762 * @see #isNull(Class) 763 * @since 2.1.0 764 * @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic 765 * friendliness to avoid casting, this is not anymore needed in Java 8. 766 */ anyIterableOf(Class<T> clazz)767 public static <T> Iterable<T> anyIterableOf(Class<T> clazz) { 768 return anyIterable(); 769 } 770 771 772 773 /** 774 * <code>boolean</code> argument that is equal to the given value. 775 * 776 * <p> 777 * See examples in javadoc for {@link ArgumentMatchers} class 778 * </p> 779 * 780 * @param value the given value. 781 * @return <code>0</code>. 782 */ eq(boolean value)783 public static boolean eq(boolean value) { 784 reportMatcher(new Equals(value)); 785 return false; 786 } 787 788 /** 789 * <code>byte</code> argument that is equal to the given value. 790 * 791 * <p> 792 * See examples in javadoc for {@link ArgumentMatchers} class 793 * </p> 794 * 795 * @param value the given value. 796 * @return <code>0</code>. 797 */ eq(byte value)798 public static byte eq(byte value) { 799 reportMatcher(new Equals(value)); 800 return 0; 801 } 802 803 /** 804 * <code>char</code> argument that is equal to the given value. 805 * 806 * <p> 807 * See examples in javadoc for {@link ArgumentMatchers} class 808 * </p> 809 * 810 * @param value the given value. 811 * @return <code>0</code>. 812 */ eq(char value)813 public static char eq(char value) { 814 reportMatcher(new Equals(value)); 815 return 0; 816 } 817 818 /** 819 * <code>double</code> argument that is equal to the given value. 820 * 821 * <p> 822 * See examples in javadoc for {@link ArgumentMatchers} class 823 * </p> 824 * 825 * @param value the given value. 826 * @return <code>0</code>. 827 */ eq(double value)828 public static double eq(double value) { 829 reportMatcher(new Equals(value)); 830 return 0; 831 } 832 833 /** 834 * <code>float</code> argument that is equal to the given value. 835 * 836 * <p> 837 * See examples in javadoc for {@link ArgumentMatchers} class 838 * </p> 839 * 840 * @param value the given value. 841 * @return <code>0</code>. 842 */ eq(float value)843 public static float eq(float value) { 844 reportMatcher(new Equals(value)); 845 return 0; 846 } 847 848 /** 849 * <code>int</code> argument that is equal to the given value. 850 * 851 * <p> 852 * See examples in javadoc for {@link ArgumentMatchers} class 853 * </p> 854 * 855 * @param value the given value. 856 * @return <code>0</code>. 857 */ eq(int value)858 public static int eq(int value) { 859 reportMatcher(new Equals(value)); 860 return 0; 861 } 862 863 /** 864 * <code>long</code> argument that is equal to the given value. 865 * 866 * <p> 867 * See examples in javadoc for {@link ArgumentMatchers} class 868 * </p> 869 * 870 * @param value the given value. 871 * @return <code>0</code>. 872 */ eq(long value)873 public static long eq(long value) { 874 reportMatcher(new Equals(value)); 875 return 0; 876 } 877 878 /** 879 * <code>short</code> argument that is equal to the given value. 880 * <p> 881 * See examples in javadoc for {@link ArgumentMatchers} class 882 * 883 * @param value the given value. 884 * @return <code>0</code>. 885 */ eq(short value)886 public static short eq(short value) { 887 reportMatcher(new Equals(value)); 888 return 0; 889 } 890 891 /** 892 * Object argument that is equal to the given value. 893 * 894 * <p> 895 * See examples in javadoc for {@link ArgumentMatchers} class 896 * </p> 897 * 898 * @param value the given value. 899 * @return <code>null</code>. 900 */ eq(T value)901 public static <T> T eq(T value) { 902 reportMatcher(new Equals(value)); 903 if (value == null) 904 return null; 905 return (T) Primitives.defaultValue(value.getClass()); 906 } 907 908 /** 909 * Object argument that is reflection-equal to the given value with support for excluding 910 * selected fields from a class. 911 * 912 * <p> 913 * This matcher can be used when equals() is not implemented on compared objects. 914 * Matcher uses java reflection API to compare fields of wanted and actual object. 915 * </p> 916 * 917 * <p> 918 * Works similarly to <code>EqualsBuilder.reflectionEquals(this, other, excludeFields)</code> from 919 * apache commons library. 920 * <p> 921 * <b>Warning</b> The equality check is shallow! 922 * </p> 923 * 924 * <p> 925 * See examples in javadoc for {@link ArgumentMatchers} class 926 * </p> 927 * 928 * @param value the given value. 929 * @param excludeFields fields to exclude, if field does not exist it is ignored. 930 * @return <code>null</code>. 931 */ refEq(T value, String... excludeFields)932 public static <T> T refEq(T value, String... excludeFields) { 933 reportMatcher(new ReflectionEquals(value, excludeFields)); 934 return null; 935 } 936 937 /** 938 * Object argument that is the same as the given value. 939 * 940 * <p> 941 * See examples in javadoc for {@link ArgumentMatchers} class 942 * </p> 943 * 944 * @param <T> the type of the object, it is passed through to prevent casts. 945 * @param value the given value. 946 * @return <code>null</code>. 947 */ same(T value)948 public static <T> T same(T value) { 949 reportMatcher(new Same(value)); 950 if (value == null) 951 return null; 952 return (T) Primitives.defaultValue(value.getClass()); 953 } 954 955 /** 956 * <code>null</code> argument. 957 * 958 * <p> 959 * See examples in javadoc for {@link ArgumentMatchers} class 960 * </p> 961 * 962 * @return <code>null</code>. 963 * @see #isNull(Class) 964 * @see #isNotNull() 965 * @see #isNotNull(Class) 966 */ isNull()967 public static <T> T isNull() { 968 reportMatcher(Null.NULL); 969 return null; 970 } 971 972 /** 973 * <code>null</code> argument. 974 * 975 * <p> 976 * The class argument is provided to avoid casting. 977 * </p> 978 * 979 * <p> 980 * See examples in javadoc for {@link ArgumentMatchers} class 981 * </p> 982 * 983 * @param clazz Type to avoid casting 984 * @return <code>null</code>. 985 * @see #isNull() 986 * @see #isNotNull() 987 * @see #isNotNull(Class) 988 * @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic 989 * friendliness to avoid casting, this is not anymore needed in Java 8. 990 */ isNull(Class<T> clazz)991 public static <T> T isNull(Class<T> clazz) { 992 return isNull(); 993 } 994 995 /** 996 * Not <code>null</code> argument. 997 * 998 * <p> 999 * Alias to {@link ArgumentMatchers#isNotNull()} 1000 * </p> 1001 * 1002 * <p> 1003 * See examples in javadoc for {@link ArgumentMatchers} class 1004 * </p> 1005 * 1006 * @return <code>null</code>. 1007 */ notNull()1008 public static <T> T notNull() { 1009 reportMatcher(NotNull.NOT_NULL); 1010 return null; 1011 } 1012 1013 /** 1014 * Not <code>null</code> argument, not necessary of the given class. 1015 * 1016 * <p> 1017 * The class argument is provided to avoid casting. 1018 * 1019 * Alias to {@link ArgumentMatchers#isNotNull(Class)} 1020 * <p> 1021 * 1022 * <p> 1023 * See examples in javadoc for {@link ArgumentMatchers} class 1024 * </p> 1025 * 1026 * @param clazz Type to avoid casting 1027 * @return <code>null</code>. 1028 * @see #isNotNull() 1029 * @see #isNull() 1030 * @see #isNull(Class) 1031 * @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic 1032 * friendliness to avoid casting, this is not anymore needed in Java 8. 1033 */ notNull(Class<T> clazz)1034 public static <T> T notNull(Class<T> clazz) { 1035 return notNull(); 1036 } 1037 1038 /** 1039 * Not <code>null</code> argument. 1040 * 1041 * <p> 1042 * Alias to {@link ArgumentMatchers#notNull()} 1043 * </p> 1044 * 1045 * <p> 1046 * See examples in javadoc for {@link ArgumentMatchers} class 1047 * </p> 1048 * 1049 * @return <code>null</code>. 1050 * @see #isNotNull(Class) 1051 * @see #isNull() 1052 * @see #isNull(Class) 1053 */ isNotNull()1054 public static <T> T isNotNull() { 1055 return notNull(); 1056 } 1057 1058 /** 1059 * Not <code>null</code> argument, not necessary of the given class. 1060 * 1061 * <p> 1062 * The class argument is provided to avoid casting. 1063 * Alias to {@link ArgumentMatchers#notNull(Class)} 1064 * </p> 1065 * 1066 * <p> 1067 * See examples in javadoc for {@link ArgumentMatchers} class 1068 * </p> 1069 * 1070 * @param clazz Type to avoid casting 1071 * @return <code>null</code>. 1072 * @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic 1073 * friendliness to avoid casting, this is not anymore needed in Java 8. 1074 */ isNotNull(Class<T> clazz)1075 public static <T> T isNotNull(Class<T> clazz) { 1076 return notNull(clazz); 1077 } 1078 1079 1080 /** 1081 * Argument that is either <code>null</code> or of the given type. 1082 * 1083 * <p> 1084 * See examples in javadoc for {@link ArgumentMatchers} class 1085 * </p> 1086 * 1087 * @param clazz Type to avoid casting 1088 * @return <code>null</code>. 1089 */ nullable(Class<T> clazz)1090 public static <T> T nullable(Class<T> clazz) { 1091 AdditionalMatchers.or(isNull(), isA(clazz)); 1092 return (T) Primitives.defaultValue(clazz); 1093 } 1094 1095 /** 1096 * <code>String</code> argument that contains the given substring. 1097 * <p> 1098 * See examples in javadoc for {@link ArgumentMatchers} class 1099 * 1100 * @param substring the substring. 1101 * @return empty String (""). 1102 */ contains(String substring)1103 public static String contains(String substring) { 1104 reportMatcher(new Contains(substring)); 1105 return ""; 1106 } 1107 1108 /** 1109 * <code>String</code> argument that matches the given regular expression. 1110 * <p> 1111 * See examples in javadoc for {@link ArgumentMatchers} class 1112 * 1113 * @param regex the regular expression. 1114 * @return empty String (""). 1115 * 1116 * @see AdditionalMatchers#not(boolean) 1117 */ matches(String regex)1118 public static String matches(String regex) { 1119 reportMatcher(new Matches(regex)); 1120 return ""; 1121 } 1122 1123 /** 1124 * <code>Pattern</code> argument that matches the given regular expression. 1125 * <p> 1126 * See examples in javadoc for {@link ArgumentMatchers} class 1127 * 1128 * @param pattern the regular expression pattern. 1129 * @return empty String (""). 1130 * 1131 * @see AdditionalMatchers#not(boolean) 1132 */ matches(Pattern pattern)1133 public static String matches(Pattern pattern) { 1134 reportMatcher(new Matches(pattern)); 1135 return ""; 1136 } 1137 1138 /** 1139 * <code>String</code> argument that ends with the given suffix. 1140 * <p> 1141 * See examples in javadoc for {@link ArgumentMatchers} class 1142 * 1143 * @param suffix the suffix. 1144 * @return empty String (""). 1145 */ endsWith(String suffix)1146 public static String endsWith(String suffix) { 1147 reportMatcher(new EndsWith(suffix)); 1148 return ""; 1149 } 1150 1151 /** 1152 * <code>String</code> argument that starts with the given prefix. 1153 * <p> 1154 * See examples in javadoc for {@link ArgumentMatchers} class 1155 * 1156 * @param prefix the prefix. 1157 * @return empty String (""). 1158 */ startsWith(String prefix)1159 public static String startsWith(String prefix) { 1160 reportMatcher(new StartsWith(prefix)); 1161 return ""; 1162 } 1163 1164 /** 1165 * Allows creating custom argument matchers. 1166 * 1167 * <p> 1168 * This API has changed in 2.1.0, please read {@link ArgumentMatcher} for rationale and migration guide. 1169 * <b>NullPointerException</b> auto-unboxing caveat is described below. 1170 * </p> 1171 * 1172 * <p> 1173 * It is important to understand the use cases and available options for dealing with non-trivial arguments 1174 * <b>before</b> implementing custom argument matchers. This way, you can select the best possible approach 1175 * for given scenario and produce highest quality test (clean and maintainable). 1176 * Please read the documentation for {@link ArgumentMatcher} to learn about approaches and see the examples. 1177 * </p> 1178 * 1179 * <p> 1180 * <b>NullPointerException</b> auto-unboxing caveat. 1181 * In rare cases when matching primitive parameter types you <b>*must*</b> use relevant intThat(), floatThat(), etc. method. 1182 * This way you will avoid <code>NullPointerException</code> during auto-unboxing. 1183 * Due to how java works we don't really have a clean way of detecting this scenario and protecting the user from this problem. 1184 * Hopefully, the javadoc describes the problem and solution well. 1185 * If you have an idea how to fix the problem, let us know via the mailing list or the issue tracker. 1186 * </p> 1187 * 1188 * <p> 1189 * See examples in javadoc for {@link ArgumentMatcher} class 1190 * </p> 1191 * 1192 * @param matcher decides whether argument matches 1193 * @return <code>null</code>. 1194 */ argThat(ArgumentMatcher<T> matcher)1195 public static <T> T argThat(ArgumentMatcher<T> matcher) { 1196 reportMatcher(matcher); 1197 return null; 1198 } 1199 1200 /** 1201 * Allows creating custom <code>char</code> argument matchers. 1202 * 1203 * Note that {@link #argThat} will not work with primitive <code>char</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 1204 * <p> 1205 * See examples in javadoc for {@link ArgumentMatchers} class 1206 * 1207 * @param matcher decides whether argument matches 1208 * @return <code>0</code>. 1209 */ charThat(ArgumentMatcher<Character> matcher)1210 public static char charThat(ArgumentMatcher<Character> matcher) { 1211 reportMatcher(matcher); 1212 return 0; 1213 } 1214 1215 /** 1216 * Allows creating custom <code>boolean</code> argument matchers. 1217 * 1218 * Note that {@link #argThat} will not work with primitive <code>boolean</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 1219 * <p> 1220 * See examples in javadoc for {@link ArgumentMatchers} class 1221 * 1222 * @param matcher decides whether argument matches 1223 * @return <code>false</code>. 1224 */ booleanThat(ArgumentMatcher<Boolean> matcher)1225 public static boolean booleanThat(ArgumentMatcher<Boolean> matcher) { 1226 reportMatcher(matcher); 1227 return false; 1228 } 1229 1230 /** 1231 * Allows creating custom <code>byte</code> argument matchers. 1232 * 1233 * Note that {@link #argThat} will not work with primitive <code>byte</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 1234 * <p> 1235 * See examples in javadoc for {@link ArgumentMatchers} class 1236 * 1237 * @param matcher decides whether argument matches 1238 * @return <code>0</code>. 1239 */ byteThat(ArgumentMatcher<Byte> matcher)1240 public static byte byteThat(ArgumentMatcher<Byte> matcher) { 1241 reportMatcher(matcher); 1242 return 0; 1243 } 1244 1245 /** 1246 * Allows creating custom <code>short</code> argument matchers. 1247 * 1248 * Note that {@link #argThat} will not work with primitive <code>short</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 1249 * <p> 1250 * See examples in javadoc for {@link ArgumentMatchers} class 1251 * 1252 * @param matcher decides whether argument matches 1253 * @return <code>0</code>. 1254 */ shortThat(ArgumentMatcher<Short> matcher)1255 public static short shortThat(ArgumentMatcher<Short> matcher) { 1256 reportMatcher(matcher); 1257 return 0; 1258 } 1259 1260 /** 1261 * Allows creating custom <code>int</code> argument matchers. 1262 * 1263 * Note that {@link #argThat} will not work with primitive <code>int</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 1264 * <p> 1265 * See examples in javadoc for {@link ArgumentMatchers} class 1266 * 1267 * @param matcher decides whether argument matches 1268 * @return <code>0</code>. 1269 */ intThat(ArgumentMatcher<Integer> matcher)1270 public static int intThat(ArgumentMatcher<Integer> matcher) { 1271 reportMatcher(matcher); 1272 return 0; 1273 } 1274 1275 /** 1276 * Allows creating custom <code>long</code> argument matchers. 1277 * 1278 * Note that {@link #argThat} will not work with primitive <code>long</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 1279 * <p> 1280 * See examples in javadoc for {@link ArgumentMatchers} class 1281 * 1282 * @param matcher decides whether argument matches 1283 * @return <code>0</code>. 1284 */ longThat(ArgumentMatcher<Long> matcher)1285 public static long longThat(ArgumentMatcher<Long> matcher) { 1286 reportMatcher(matcher); 1287 return 0; 1288 } 1289 1290 /** 1291 * Allows creating custom <code>float</code> argument matchers. 1292 * 1293 * Note that {@link #argThat} will not work with primitive <code>float</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 1294 * <p> 1295 * See examples in javadoc for {@link ArgumentMatchers} class 1296 * 1297 * @param matcher decides whether argument matches 1298 * @return <code>0</code>. 1299 */ floatThat(ArgumentMatcher<Float> matcher)1300 public static float floatThat(ArgumentMatcher<Float> matcher) { 1301 reportMatcher(matcher); 1302 return 0; 1303 } 1304 1305 /** 1306 * Allows creating custom <code>double</code> argument matchers. 1307 * 1308 * Note that {@link #argThat} will not work with primitive <code>double</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat. 1309 * <p> 1310 * See examples in javadoc for {@link ArgumentMatchers} class 1311 * 1312 * @param matcher decides whether argument matches 1313 * @return <code>0</code>. 1314 */ doubleThat(ArgumentMatcher<Double> matcher)1315 public static double doubleThat(ArgumentMatcher<Double> matcher) { 1316 reportMatcher(matcher); 1317 return 0; 1318 } 1319 reportMatcher(ArgumentMatcher<?> matcher)1320 private static void reportMatcher(ArgumentMatcher<?> matcher) { 1321 mockingProgress().getArgumentMatcherStorage().reportMatcher(matcher); 1322 } 1323 } 1324