1/*
2 * Copyright (c) 2007 Mockito contributors
3 * This program is made available under the terms of the MIT License.
4 */
5
6package org.mockito.verification;
7
8import org.mockito.Mockito;
9
10/**
11 * VerificationWithTimeout is a {@link VerificationMode} that allows combining existing verification modes with 'timeout'. E.g:
12 *
13 * <pre class="code"><code class="java">
14 * verify(mock, timeout(100).times(5)).foo();
15 *
16 * verify(mock, timeout(100).never()).bar();
17 *
18 * verify(mock, timeout(200).atLeastOnce()).baz();
19 * </code></pre>
20 *
21 * <p>
22 * See examples in javadoc for {@link Mockito#verify(Object, VerificationMode)}
23 */
24public interface VerificationWithTimeout extends VerificationMode {
25
26    /**
27     * Allows verifying exact number of invocations within given timeout
28     * <pre class="code"><code class="java">
29     *   verify(mock, timeout(100).times(2)).someMethod("some arg");
30     * </code></pre>
31     *
32     * See examples in javadoc for {@link Mockito} class
33     *
34     * @param wantedNumberOfInvocations wanted number of invocations
35     *
36     * @return verification mode
37     */
38    public VerificationMode times(int wantedNumberOfInvocations);
39
40    /**
41     * Alias to times(0), see {@link #times(int)}
42     * <p>
43     * Verifies that interaction did not happen within given timeout. E.g:
44     * <pre class="code"><code class="java">
45     *   verify(mock, timeout(100).never()).someMethod();
46     * </code></pre>
47     *
48     * <p>
49     * If you want to verify there were NO interactions with the mock
50     * check out {@link Mockito#verifyNoMoreInteractions(Object...)}
51     * <p>
52     * See examples in javadoc for {@link Mockito} class
53     *
54     * @return verification mode
55     */
56    public VerificationMode never();
57
58    /**
59     * Allows at-least-once verification withing given timeout. E.g:
60     * <pre class="code"><code class="java">
61     *   verify(mock, timeout(100).atLeastOnce()).someMethod("some arg");
62     * </code></pre>
63     * Alias to atLeast(1)
64     * <p>
65     * See examples in javadoc for {@link Mockito} class
66     *
67     * @return verification mode
68     */
69    public VerificationMode atLeastOnce();
70
71    /**
72     * Allows at-least-x verification withing given timeout. E.g:
73     * <pre class="code"><code class="java">
74     *   verify(mock, timeout(100).atLeast(3)).someMethod("some arg");
75     * </code></pre>
76     *
77     * See examples in javadoc for {@link Mockito} class
78     *
79     * @param minNumberOfInvocations minimum number of invocations
80     *
81     * @return verification mode
82     */
83    public VerificationMode atLeast(int minNumberOfInvocations);
84
85    /**
86     * @deprecated
87     *
88     * <b>Deprecated</b>
89     * validation with timeout combined with atMost simply does not make sense...
90     * The test would have passed immediately in the concurrent environment
91     * <p>
92     * To avoid compilation erros upon upgrade the method is deprecated and it throws a "friendly reminder" exception.
93     * <p>
94     * In future release we will remove timeout(x).atMost(y) from the API.
95     * <p>
96     * Do you want to find out more? See <a href="http://code.google.com/p/mockito/issues/detail?id=235">issue 235</a>
97     *
98     * @return verification mode
99     */
100    @Deprecated
101    public VerificationMode atMost(int maxNumberOfInvocations);
102
103    /**
104     * Allows checking if given method was the only one invoked. E.g:
105     * <pre class="code"><code class="java">
106     *   verify(mock, only()).someMethod();
107     *   //above is a shorthand for following 2 lines of code:
108     *   verify(mock).someMethod();
109     *   verifyNoMoreInvocations(mock);
110     * </code></pre>
111     *
112     * <p>
113     * See also {@link Mockito#verifyNoMoreInteractions(Object...)}
114     * <p>
115     * See examples in javadoc for {@link Mockito} class
116     *
117     * @return verification mode
118     */
119    public VerificationMode only();
120}