Home | History | Annotate | Download | only in junit 
      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
     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
    101     VerificationCollector assertLazily();
    102 }
    103