• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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>&#064;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>&#064;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>&#064;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>&#064;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>&#064;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, exlucdeFields)</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