1/*
2 * Copyright (c) 2017 Mockito contributors
3 * This program is made available under the terms of the MIT License.
4 */
5package org.mockito.quality;
6
7import org.mockito.Incubating;
8import org.mockito.MockitoSession;
9import org.mockito.exceptions.misusing.PotentialStubbingProblem;
10import org.mockito.exceptions.misusing.UnnecessaryStubbingException;
11import org.mockito.internal.junit.JUnitRule;
12import org.mockito.junit.MockitoJUnitRunner;
13import org.mockito.junit.MockitoRule;
14
15/**
16 * Configures the "strictness" of Mockito during a mocking session.
17 * A session typically maps to a single test method invocation.
18 * {@code Strictness} drives cleaner tests and better productivity.
19 * The easiest way to leverage enhanced {@code Strictness} is using
20 * Mockito's JUnit support ({@link MockitoRule} or {@link MockitoJUnitRunner}).
21 * If you cannot use JUnit support {@link MockitoSession} is the way to go.
22 * <p>
23 * How strictness level influences the behavior of the test (mocking session)?
24 * <ol>
25 *     <li>{@link Strictness#LENIENT} - no added behavior.
26 *       The default of Mockito 1.x.
27 *       Recommended only if you cannot use {@link #STRICT_STUBS} nor {@link #WARN}.</li>
28 *     <li>{@link Strictness#WARN} - helps keeping tests clean and improves debuggability.
29 *       Reports console warnings about unused stubs
30 *       and stubbing argument mismatch (see {@link org.mockito.quality.MockitoHint}).
31 *       The default behavior of Mockito 2.x when {@link JUnitRule} or {@link MockitoJUnitRunner} are used.</li>
32 *       Recommended if you cannot use {@link #STRICT_STUBS}.
33 *     <li>{@link Strictness#STRICT_STUBS} - ensures clean tests, reduces test code duplication, improves debuggability.
34 *       Best combination of flexibility and productivity. Highly recommended.
35 *       Planned as default for Mockito v3.
36 *       See {@link #STRICT_STUBS} for the details.
37 * </ol>
38 *
39 * @since 2.3.0
40 */
41@Incubating
42public enum Strictness {
43
44    /**
45     * No extra strictness. Mockito 1.x behavior.
46     * Recommended only if you cannot use {@link #STRICT_STUBS} nor {@link #WARN}.
47     * <p>
48     * For more information see {@link Strictness}.
49     *
50     * @since 2.3.0
51     */
52    @Incubating
53    LENIENT,
54
55    /**
56     * Helps keeping tests clean and improves debuggability.
57     * Extra warnings emitted to the console, see {@link MockitoHint}.
58     * Default Mockito 2.x behavior.
59     * Recommended if you cannot use {@link #STRICT_STUBS}.
60     * <p>
61     * For more information see {@link Strictness}.
62     *
63     * @since 2.3.0
64     */
65    @Incubating
66    WARN,
67
68    /**
69     * Ensures clean tests, reduces test code duplication, improves debuggability.
70     * Offers best combination of flexibility and productivity.
71     * Highly recommended.
72     * Planned as default for Mockito v3.
73     * <p>
74     * Adds following behavior:
75     *  <ul>
76     *      <li>Improved productivity: the test fails early when code under test invokes
77     *          stubbed method with different arguments (see {@link PotentialStubbingProblem}).</li>
78     *      <li>Cleaner tests without unnecessary stubbings:
79     *          the test fails when unused stubs are present (see {@link UnnecessaryStubbingException}).</li>
80     *      <li>Cleaner, more DRY tests ("Don't Repeat Yourself"):
81     *          If you use {@link org.mockito.Mockito#verifyNoMoreInteractions(Object...)}
82     *          you no longer need to explicitly verify stubbed invocations.
83     *          They are automatically verified for you. However if you have more invocations,
84     *          the test won't fail since it won't check that there are no more interactions on that stub.</li>
85     *  </ul>
86     *
87     * For more information see {@link Strictness}.
88     *
89     * @since 2.3.0
90     */
91    @Incubating
92    STRICT_STUBS;
93}
94