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.junit;
6 
7 import org.junit.rules.TestRule;
8 import org.mockito.Incubating;
9 import org.mockito.exceptions.base.MockitoAssertionError;
10 import org.mockito.verification.VerificationMode;
11 
12 /**
13  * Use this rule in order to collect multiple verification failures and report at once.
14  * This new API in incubating - let us know if you find this feature useful.
15  * Should it be turned on by default with Mockito JUnit Rule?
16  * <p>
17  * Although {@code VerificationCollector} is a JUnit Rule, it does not necessarily have to be used as a Test Rule
18  * - see {@link #collectAndReport()}.
19  * <p>
20  * In the example below, the verification failure thrown by {@code byteReturningMethod()} does not block
21  * verifying against the {@code simpleMethod()}. After the test is run, a report is generated stating all
22  * collect verification failures.
23  *
24  * <pre class="code"><code class="java">
25  *   &#064;Rule
26  *   public VerificationCollector collector = MockitoJUnit.collector();
27  *
28  *   &#064;Test
29  *   public void should_fail() {
30  *       IMethods methods = mock(IMethods.class);
31  *
32  *       verify(methods).byteReturningMethod();
33  *       verify(methods).simpleMethod();
34  *   }
35  * </code></pre>
36  *
37  * @see org.mockito.Mockito#verify(Object)
38  * @see org.mockito.Mockito#verify(Object, VerificationMode)
39  * @since 2.1.0
40  */
41 @Incubating
42 public interface VerificationCollector extends TestRule {
43 
44     /**
45      * Collect all lazily verified behaviour. If there were failed verifications, it will
46      * throw a MockitoAssertionError containing all messages indicating the failed verifications.
47      * <p>
48      * Normally, users don't need to call this method because it is automatically invoked when test finishes
49      * (part of the JUnit Rule behavior).
50      * However, in some circumstances and edge cases, it might be useful to collect and report verification
51      * errors in the middle of the test (for example: some scenario tests or during debugging).
52      *
53      * <pre class="code"><code class="java">
54      *   &#064;Rule
55      *   public VerificationCollector collector = MockitoJUnit.collector();
56      *
57      *   &#064;Test
58      *   public void should_fail() {
59      *       IMethods methods = mock(IMethods.class);
60      *
61      *       verify(methods).byteReturningMethod();
62      *       verify(methods).simpleMethod();
63      *
64      *       //report all verification errors now:
65      *       collector.collectAndReport();
66      *
67      *       //some other test code
68      *   }
69      * </code></pre>
70      *
71      * @throws MockitoAssertionError If there were failed verifications
72      * @since 2.1.0
73      */
74     @Incubating
collectAndReport()75     void collectAndReport() throws MockitoAssertionError;
76 
77     /**
78      * Enforce all verifications are performed lazily. This method is automatically called when
79      * used as JUnitRule and normally users don't need to use it.
80      * <p>
81      * You should only use this method if you are using a VerificationCollector
82      * inside a method where only this method should be verified lazily. The other methods can
83      * still be verified directly.
84      *
85      * <pre class="code"><code class="java">
86      *   &#064;Test
87      *   public void should_verify_lazily() {
88      *       VerificationCollector collector = MockitoJUnit.collector().assertLazily();
89      *
90      *       verify(methods).byteReturningMethod();
91      *       verify(methods).simpleMethod();
92      *
93      *       collector.collectAndReport();
94      *   }
95      * </code></pre>
96      *
97      * @return this
98      * @since 2.1.0
99      */
100     @Incubating
assertLazily()101     VerificationCollector assertLazily();
102 }
103