New strict mocking API - MockitoSession

[mockitoguy]

Background

• Mockito strictness (improved debuggability, cleaner tests) is described in a blog post and in issue Strictness in Mockito #769
• Strict stubbing is already supported with JUnit rules - New opt-in stubbing strictness implemented in JUnit rules #807
• Open PR for supporting strict stubbing with JUnit Runners - Mockito JUnit Runner supports strict stubbing #854
• This ticket intends to discuss the goals and implementation of strict stubbing without JUnit Rules / Runner

Initial design

public class SampleTest {   
    @Mock IMethods mock;
    
    //Initialize mocks similar to MockitoAnnotations.initMocks(this), also configures strictness
    MockitoSession mockito = Mockito.mockitoSession().initMocks(this).strictness(Strictness.STRICT_STUBS).startMocking();

    @After public void after() {
        //After the test has completed, we detect unused stubs and validate mockito usage
        mockito.finishMocking();
    }

    //start and finish mocking invocations can be hidden in a common test base class
    //or abstracted out in unit test framework specific way (custom rule, etc.)

    @Test public void some_test() {
        //...
    }
}    

Alternative new public API methods

(no longer considered since the feature is merged)

//1
MockitoMocking mockito = Mockito.startMocking(this, Strictness.STRICT_STUBS);
mockito.finishMocking();
//2
MockitoSession mockito = Mockito.mockitoSession().initMocks(this).strictness(Strictness.STRICT_STUBS).startMocking();
mockito.finishMocking();
//3
MockitoSession mockito = MockitoSessionBuilder.mockitoSession().testClassInstance(this).strictness(Strictness.STRICT_STUBS).start();
mockito.stop();

Discussion

• other ideas to meet the goal (better debuggability / cleaner tests without JUnit)
• good naming / API for the feature
• consistency with existing support for strictness with Runner and the Rule

We would love to hear your feedback!

[bric3]

Here's my opinion :

• Regarding alternative 1/2/3, I prefer the API with an actual variable. Using static methods requires a hidden thread local state, while it's ok for stubbing, I think this could be bad design choice for the mockiting session. Also without MockitoSession variable it's hard to interact with, and always requires some static method.
• Not in favor of option 1, as it kinda dismiss the builder style API. And it's probably harder to evolve such API in a non breaking way.
• Not in favor of option 3, regarding the testClassInstance as it does not explain what it does with the test class instance. While initMocks suggests the behavior behind this.
• I don't mind having the static factory method on either MockitoSession or Mockito, both are good. A Mockito start point would probably be more discoverable though and will get along other lifecycle Mockito methods, like reset, validateUsage, etc... While MockitoSession could be an opportunity to have a more focused API.

[mockitoguy]

@bric3, great feedback!!!

I summarized my POV in (#865 (comment)).

Regarding alternative 1/2/3, I prefer the API with an actual variable.

All options are using variable, I removed it for clarity (but it became less clear :) I will update the ticket.

I don't mind having the static factory method on either MockitoSession or Mockito, both are good. A Mockito start point would probably be more discoverable though and will get along other lifecycle Mockito methods, like reset, validateUsage, etc... While MockitoSession could be an opportunity to have a more focused API.

Yes. Both approaches have pros and cons. Let's go ahead with Mockito.mockitoSession() at this time.

[bric3]

All options are using variable, I removed it for clarity (but it became less clear :) I will update the ticket.

ok

Yes. Both approaches have pros and cons. Let's go ahead with Mockito.mockitoSession() at this time.

That's fine by me :)

[mockitoguy]

Closed via #865