Stubber.java revision e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7 
1/*
2 * Copyright (c) 2007 Mockito contributors
3 * This program is made available under the terms of the MIT License.
4 */
5package org.mockito.stubbing;
6
7import org.mockito.Mockito;
8
9/**
10 * Allows to choose a method when stubbing in doThrow()|doAnswer()|doNothing()|doReturn() style
11 * <p>
12 * Example:
13 * <pre class="code"><code class="java">
14 *   doThrow(new RuntimeException()).when(mockedList).clear();
15 *
16 *   //following throws RuntimeException:
17 *   mockedList.clear();
18 * </code></pre>
19 *
20 * Also useful when stubbing consecutive calls:
21 *
22 * <pre class="code"><code class="java">
23 *   doThrow(new RuntimeException("one")).
24 *   doThrow(new RuntimeException("two"))
25 *   .when(mock).someVoidMethod();
26 * </code></pre>
27 *
28 * Read more about those methods:
29 * <p>
30 * {@link Mockito#doThrow(Throwable)}
31 * <p>
32 * {@link Mockito#doAnswer(Answer)}
33 * <p>
34 * {@link Mockito#doNothing()}
35 * <p>
36 * {@link Mockito#doReturn(Object)}
37 * <p>
38 *
39 * See examples in javadoc for {@link Mockito}
40 */
41@SuppressWarnings("unchecked")
42public interface Stubber {
43
44    /**
45     * Allows to choose a method when stubbing in doThrow()|doAnswer()|doNothing()|doReturn() style
46     * <p>
47     * Example:
48     * <pre class="code"><code class="java">
49     *   doThrow(new RuntimeException())
50     *   .when(mockedList).clear();
51     *
52     *   //following throws RuntimeException:
53     *   mockedList.clear();
54     * </code></pre>
55     *
56     * Read more about those methods:
57     * <p>
58     * {@link Mockito#doThrow(Throwable)}
59     * <p>
60     * {@link Mockito#doAnswer(Answer)}
61     * <p>
62     * {@link Mockito#doNothing()}
63     * <p>
64     * {@link Mockito#doReturn(Object)}
65     * <p>
66     *
67     *  See examples in javadoc for {@link Mockito}
68     *
69     * @param mock The mock
70     * @return select method for stubbing
71     */
72    <T> T when(T mock);
73
74    /**
75     * Use it for stubbing consecutive calls in {@link Mockito#doThrow(Throwable)} style:
76     * <pre class="code"><code class="java">
77     *   doThrow(new RuntimeException("one")).
78     *   doThrow(new RuntimeException("two"))
79     *   .when(mock).someVoidMethod();
80     * </code></pre>
81     * See javadoc for {@link Mockito#doThrow(Throwable)}
82     *
83     * @param toBeThrown to be thrown when the stubbed method is called
84     * @return stubber - to select a method for stubbing
85     */
86    Stubber doThrow(Throwable toBeThrown);
87
88    /**
89     * Use it for stubbing consecutive calls in {@link Mockito#doThrow(Class)} style:
90     * <pre class="code"><code class="java">
91     *   doThrow(RuntimeException.class).
92     *   doThrow(IllegalArgumentException.class)
93     *   .when(mock).someVoidMethod();
94     * </code></pre>
95     * See javadoc for {@link Mockito#doThrow(Class)}
96     *
97     * @param toBeThrown exception class to be thrown when the stubbed method is called
98     * @return stubber - to select a method for stubbing
99     */
100    Stubber doThrow(Class<? extends Throwable> toBeThrown);
101
102    /**
103     * Use it for stubbing consecutive calls in {@link Mockito#doAnswer(Answer)} style:
104     * <pre class="code"><code class="java">
105     *   doAnswer(answerOne).
106     *   doAnswer(answerTwo)
107     *   .when(mock).someVoidMethod();
108     * </code></pre>
109     * See javadoc for {@link Mockito#doAnswer(Answer)}
110     *
111     * @param answer to answer when the stubbed method is called
112     * @return stubber - to select a method for stubbing
113     */
114    Stubber doAnswer(Answer answer);
115
116    /**
117     * Use it for stubbing consecutive calls in {@link Mockito#doNothing()} style:
118     * <pre class="code"><code class="java">
119     *   doNothing().
120     *   doThrow(new RuntimeException("two"))
121     *   .when(mock).someVoidMethod();
122     * </code></pre>
123     * See javadoc for {@link Mockito#doNothing()}
124     *
125     * @return stubber - to select a method for stubbing
126     */
127    Stubber doNothing();
128
129    /**
130     * Use it for stubbing consecutive calls in {@link Mockito#doReturn(Object)} style.
131     * <p>
132     * See javadoc for {@link Mockito#doReturn(Object)}
133     *
134     * @param toBeReturned to be returned when the stubbed method is called
135     * @return stubber - to select a method for stubbing
136     */
137    Stubber doReturn(Object toBeReturned);
138
139    /**
140     * Use it for stubbing consecutive calls in {@link Mockito#doCallRealMethod()} style.
141     * <p>
142     * See javadoc for {@link Mockito#doCallRealMethod()}
143     *
144     * @return stubber - to select a method for stubbing
145     */
146    Stubber doCallRealMethod();
147}
148