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