Merge pull request #825 from Biron-BI/checkUnnecessaryStub

Better detection of unnecessary stubbing

README.md

@@ -262,6 +262,12 @@ This will internally call `confirmVerified` on all mocks after each test, to mak
 
 Please note that this behavior may not work as expected when running tests in your IDE, as it is Gradle who takes care of handling the exception being thrown when these `confirmVerified` calls fail.
 
+#### Automatic unnecessary stubbing check
+
+You can make sure that all stubbed methods are useful - used at least once - by also annotating your test class with `@MockKExtension.CheckUnnecessaryStub`.
+
+This will internally call `checkUnnecessaryStub` on all mocks after each test, to make sure there are no unnecessary stubbings.
+
 
 ### Spy
 
@@ -718,6 +724,18 @@ verify {
 confirmVerified(car) // makes sure all calls were covered with verification
 ```
 
+### Unnecessary stubbing
+
+Because clean & maintainable test code requires zero unnecessary code, you can ensure that there is no unnecessary stubs.
+
+```
+checkUnnecessaryStub(mock1, mock2)
+```
+
+It will throw an exception if there are some declared calls on the mocks that are not used by the tested code.
+This can happen if you have declared some really unnecessary stubs or if the tested code doesn't call an expected one.  
+
+
 ### Recording exclusions
 
 To exclude unimportant calls from being recorded, you can use `excludeRecords`:
@@ -1174,37 +1192,38 @@ Here are a few tables to help you master the DSL.
 
 ### Top level functions
 
-|Function|Description|
-|--------|-----------|
-|`mockk<T>(...)`|builds a regular mock|
-|`spyk<T>()`|builds a spy using the default constructor|
-|`spyk(obj)`|builds a spy by copying from `obj`|
-|`slot`|creates a capturing slot|
-|`every`|starts a stubbing block|
-|`coEvery`|starts a stubbing block for coroutines|
-|`verify`|starts a verification block|
-|`coVerify`|starts a verification block for coroutines|
-|`verifyAll`|starts a verification block that should include all calls|
-|`coVerifyAll`|starts a verification block that should include all calls for coroutines|
-|`verifyOrder`|starts a verification block that checks the order|
-|`coVerifyOrder`|starts a verification block that checks the order for coroutines|
-|`verifySequence`|starts a verification block that checks whether all calls were made in a specified sequence|
-|`coVerifySequence`|starts a verification block that checks whether all calls were made in a specified sequence for coroutines|
-|`excludeRecords`|exclude some calls from being recorded|
-|`confirmVerified`|confirms that all recorded calls were verified|
-|`clearMocks`|clears specified mocks|
-|`registerInstanceFactory`|allows you to redefine the way of instantiation for certain object|
-|`mockkClass`|builds a regular mock by passing the class as parameter|
-|`mockkObject`|turns an object into an object mock, or clears it if was already transformed|
-|`unmockkObject`|turns an object mock back into a regular object|
-|`mockkStatic`|makes a static mock out of a class, or clears it if it was already transformed|
-|`unmockkStatic`|turns a static mock back into a regular class|
-|`clearStaticMockk`|clears a static mock|
-|`mockkConstructor`|makes a constructor mock out of a class, or clears it if it was already transformed|
-|`unmockkConstructor`|turns a constructor mock back into a regular class|
-|`clearConstructorMockk`|clears the constructor mock|
-|`unmockkAll`|unmocks object, static and constructor mocks|
-|`clearAllMocks`|clears regular, object, static and constructor mocks|
+|Function| Description                                                                                                |
+|--------|------------------------------------------------------------------------------------------------------------|
+|`mockk<T>(...)`| builds a regular mock                                                                                      |
+|`spyk<T>()`| builds a spy using the default constructor                                                                 |
+|`spyk(obj)`| builds a spy by copying from `obj`                                                                         |
+|`slot`| creates a capturing slot                                                                                   |
+|`every`| starts a stubbing block                                                                                    |
+|`coEvery`| starts a stubbing block for coroutines                                                                     |
+|`verify`| starts a verification block                                                                                |
+|`coVerify`| starts a verification block for coroutines                                                                 |
+|`verifyAll`| starts a verification block that should include all calls                                                  |
+|`coVerifyAll`| starts a verification block that should include all calls for coroutines                                   |
+|`verifyOrder`| starts a verification block that checks the order                                                          |
+|`coVerifyOrder`| starts a verification block that checks the order for coroutines                                           |
+|`verifySequence`| starts a verification block that checks whether all calls were made in a specified sequence                |
+|`coVerifySequence`| starts a verification block that checks whether all calls were made in a specified sequence for coroutines |
+|`excludeRecords`| exclude some calls from being recorded                                                                     |
+|`confirmVerified`| confirms that all recorded calls were verified                                                             |
+|`checkUnnecessaryStub`| confirms that all recorded calls are used at least once                                                    |
+|`clearMocks`| clears specified mocks                                                                                     |
+|`registerInstanceFactory`| allows you to redefine the way of instantiation for certain object                                         |
+|`mockkClass`| builds a regular mock by passing the class as parameter                                                    |
+|`mockkObject`| turns an object into an object mock, or clears it if was already transformed                               |
+|`unmockkObject`| turns an object mock back into a regular object                                                            |
+|`mockkStatic`| makes a static mock out of a class, or clears it if it was already transformed                             |
+|`unmockkStatic`| turns a static mock back into a regular class                                                              |
+|`clearStaticMockk`| clears a static mock                                                                                       |
+|`mockkConstructor`| makes a constructor mock out of a class, or clears it if it was already transformed                        |
+|`unmockkConstructor`| turns a constructor mock back into a regular class                                                         |
+|`clearConstructorMockk`| clears the constructor mock                                                                                |
+|`unmockkAll`| unmocks object, static and constructor mocks                                                               |
+|`clearAllMocks`| clears regular, object, static and constructor mocks                                                       |
 
 
 ### Matchers

dsl/common/src/main/kotlin/io/mockk/API.kt

@@ -278,6 +278,19 @@ object MockKDsl {
         }
     }
 
+    /**
+     * Checks if all recorded calls are necessary.
+     */
+    fun internalCheckUnnecessaryStub(vararg mocks: Any) {
+        if (mocks.isEmpty()) {
+            MockKGateway.implementation().verificationAcknowledger.checkUnnecessaryStub()
+        }
+
+        for (mock in mocks) {
+            MockKGateway.implementation().verificationAcknowledger.checkUnnecessaryStub(mock)
+        }
+    }
+
     /**
      * Resets information associated with mock
      */

dsl/common/src/main/kotlin/io/mockk/GatewayAPI.kt

@@ -253,6 +253,10 @@ interface MockKGateway {
         fun acknowledgeVerified(mock: Any)
 
         fun acknowledgeVerified()
+
+        fun checkUnnecessaryStub(mock: Any)
+
+        fun checkUnnecessaryStub()
     }
 
     interface MockTypeChecker {

mockk/common/src/main/kotlin/io/mockk/MockK.kt

@@ -319,6 +319,13 @@ fun confirmVerified(vararg mocks: Any) = MockK.useImpl {
     MockKDsl.internalConfirmVerified(*mocks)
 }
 
+/**
+ * Checks if all recorded calls are necessary.
+ */
+fun checkUnnecessaryStub(vararg mocks: Any) = MockK.useImpl {
+    MockKDsl.internalCheckUnnecessaryStub(*mocks)
+}
+
 /**
  * Resets information associated with specified mocks.
  * To clear all mocks use clearAllMocks.

mockk/common/src/main/kotlin/io/mockk/impl/recording/CommonVerificationAcknowledger.kt

@@ -26,6 +26,15 @@ class CommonVerificationAcknowledger(
         acknowledgeVerificationHelper(stub)
     }
 
+    override fun checkUnnecessaryStub() {
+        stubRepo.allStubs.forEach { checkUnnecessaryStubHelper(it) }
+    }
+
+    override fun checkUnnecessaryStub(mock: Any) {
+        val stub = stubRepo.stubFor(mock)
+        checkUnnecessaryStubHelper(stub)
+    }
+
     private fun acknowledgeVerificationHelper(stub: Stub) {
         val allCalls = stub.allRecordedCalls().map { InternalPlatform.ref(it) }.toHashSet()
         val verifiedCalls = stub.verifiedCalls().map { InternalPlatform.ref(it) }.toHashSet()
@@ -57,4 +66,17 @@ class CommonVerificationAcknowledger(
                 VerificationHelpers.stackTraces(notVerified)
     }
 
-}
+    private fun checkUnnecessaryStubHelper(stub: Stub) {
+        val unnecessaryMatcher = stub.matcherUsages().filterValues { it == 0 }.keys
+
+        if (unnecessaryMatcher.isEmpty()) return
+
+        val report =
+            "Unnecessary stubbings detected.\nFollowing stubbings are not used, either because there are unnecessary or because tested code doesn't call them :\n\n" +
+                    unnecessaryMatcher
+                        .mapIndexed { idx, matcher -> "${idx + 1}) $matcher" }
+                        .joinToString("\n")
+        throw AssertionError(report)
+    }
+
+}

mockk/common/src/main/kotlin/io/mockk/impl/stub/ConstructorStub.kt

@@ -77,6 +77,8 @@ class ConstructorStub(
             it.substitute(revertRepresentation)
         }
 
+    override fun matcherUsages() = stub.matcherUsages()
+
     override fun clear(options: MockKGateway.ClearOptions) =
         stub.clear(options)
 
@@ -97,4 +99,4 @@ class ConstructorStub(
     override fun toStr() = stub.toStr()
     override fun stdObjectAnswer(invocation: Invocation) = stub.stdObjectAnswer(invocation.substitute(represent))
     override fun dispose() = stub.dispose()
-}
+}

mockk/common/src/main/kotlin/io/mockk/impl/stub/MockKStub.kt

@@ -30,15 +30,15 @@ open class MockKStub(
     var disposeRoutine: () -> Unit = {}
 
     override fun addAnswer(matcher: InvocationMatcher, answer: Answer<*>) {
-        val invocationAnswer = InvocationAnswer(matcher, answer)
+        val invocationAnswer = InvocationAnswer(matcher, answer, 0)
         answers.add(invocationAnswer)
     }
 
     override fun answer(invocation: Invocation): Any? {
         val invocationAndMatcher = InternalPlatform.synchronized(answers) {
             answers
-                .reversed()
-                .firstOrNull { it.matcher.match(invocation) }
+                .findLast { it.matcher.match(invocation) }
+                ?.also { it.usageCount++ }
         } ?: return defaultAnswer(invocation)
 
         return with(invocationAndMatcher) {
@@ -187,6 +187,11 @@ open class MockKStub(
         }
     }
 
+    override fun matcherUsages(): Map<InvocationMatcher, Int> =
+        InternalPlatform.synchronized(answers) {
+            answers.associate { it.matcher to it.usageCount }
+        }
+
     override fun toStr() = "${type.simpleName}($name)"
 
     override fun childMockK(matcher: InvocationMatcher, childType: KClass<*>): Any {
@@ -289,7 +294,7 @@ open class MockKStub(
         val childOfRegex = Regex("child(\\^(\\d+))? of (.+)")
     }
 
-    private data class InvocationAnswer(val matcher: InvocationMatcher, val answer: Answer<*>)
+    private data class InvocationAnswer(val matcher: InvocationMatcher, val answer: Answer<*>, var usageCount: Int)
 
     protected fun Invocation.allEqMatcher() =
         InvocationMatcher(

mockk/common/src/main/kotlin/io/mockk/impl/stub/Stub.kt

@@ -28,6 +28,8 @@ interface Stub : Disposable {
 
     fun verifiedCalls(): List<Invocation>
 
+    fun matcherUsages(): Map<InvocationMatcher, Int>
+
     fun clear(options: MockKGateway.ClearOptions)
 
     fun handleInvocation(

mockk/jvm/api/mockk-jvm.api

@@ -1133,6 +1133,9 @@ public final class io/mockk/junit5/MockKExtension$Companion {
 public abstract interface annotation class io/mockk/junit5/MockKExtension$ConfirmVerification : java/lang/annotation/Annotation {
 }
 
+public abstract interface annotation class io/mockk/junit5/MockKExtension$CheckUnnecessaryStub : java/lang/annotation/Annotation {
+}
+
 public abstract interface annotation class io/mockk/junit5/MockKExtension$KeepMocks : java/lang/annotation/Annotation {
 }
 

mockk/jvm/src/main/kotlin/io/mockk/junit5/MockKExtension.kt

@@ -1,13 +1,10 @@
 package io.mockk.junit5
 
-import io.mockk.MockKAnnotations
-import io.mockk.confirmVerified
+import io.mockk.*
 import io.mockk.impl.annotations.AdditionalInterface
 import io.mockk.impl.annotations.MockK
 import io.mockk.impl.annotations.RelaxedMockK
 import io.mockk.impl.annotations.SpyK
-import io.mockk.mockkClass
-import io.mockk.unmockkAll
 import org.junit.jupiter.api.extension.*
 import java.lang.annotation.Inherited
 import java.lang.reflect.AnnotatedElement
@@ -93,6 +90,10 @@ class MockKExtension : TestInstancePostProcessor, ParameterResolver, AfterAllCal
         if (context.confirmVerification) {
             confirmVerified()
         }
+
+        if (context.checkUnnecessaryStub) {
+            checkUnnecessaryStub()
+        }
     }
 
     private val ExtensionContext.keepMocks: Boolean
@@ -111,6 +112,14 @@ class MockKExtension : TestInstancePostProcessor, ParameterResolver, AfterAllCal
         get() = map { it.getAnnotation(ConfirmVerification::class.java) != null}
             .orElse(false)
 
+    private val ExtensionContext.checkUnnecessaryStub: Boolean
+        get() = testClass.checkUnnecessaryStub ||
+                getConfigurationParameter(CHECK_UNNECESSARY_STUB_PROPERTY).map { it.toBoolean() }.orElse(false)
+
+    private val Optional<out AnnotatedElement>.checkUnnecessaryStub
+        get() = map { it.getAnnotation(CheckUnnecessaryStub::class.java) != null}
+            .orElse(false)
+
     /***
      * Prevent calling [unmockkAll] after each test execution
      */
@@ -124,9 +133,15 @@ class MockKExtension : TestInstancePostProcessor, ParameterResolver, AfterAllCal
     @Target(AnnotationTarget.CLASS)
     annotation class ConfirmVerification
 
+    @Inherited
+    @Retention(AnnotationRetention.RUNTIME)
+    @Target(AnnotationTarget.CLASS)
+    annotation class CheckUnnecessaryStub
+
     companion object {
         const val KEEP_MOCKS_PROPERTY = "mockk.junit.extension.keepmocks"
         const val CONFIRM_VERIFICATION_PROPERTY = "mockk.junit.extension.confirmverification"
+        const val CHECK_UNNECESSARY_STUB_PROPERTY = "mockk.junit.extension.checkUnnecessaryStub"
     }
 
 }

mockk/jvm/src/test/kotlin/io/mockk/it/VerificationAcknowledgeTest.kt

@@ -1,6 +1,8 @@
 package io.mockk.it
 
 import io.mockk.*
+import org.hamcrest.CoreMatchers.equalTo
+import org.hamcrest.MatcherAssert.assertThat
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertFails
@@ -38,6 +40,69 @@ class VerificationAcknowledgeTest {
         assertEquals(3, mock.op(1))
     }
 
+    @Test
+    fun `checkUnnecessaryStub with single call to each stub`() {
+        doCalls1()
+        checkUnnecessaryStub(mock)
+    }
+
+    @Test
+    fun `checkUnnecessaryStub with multiple calls to some stub`() {
+        doCalls2()
+        checkUnnecessaryStub(mock)
+    }
+
+    @Test
+    fun `checkUnnecessaryStub with some used and some unused stubs`() {
+        every { mock.op(98) } returns 1
+        every { mock.op(99) } returns 2
+        doCalls1()
+        assertFailsWith<AssertionError> {
+            checkUnnecessaryStub(mock)
+        }
+            .also {
+                assertThat(
+                    it.message, equalTo(
+                        "Unnecessary stubbings detected.\n" +
+                                "Following stubbings are not used, either because there are unnecessary or because tested code doesn't call them :\n" +
+                                "\n" +
+                                "1) ${mock}.op(eq(98)))\n" +
+                                "2) ${mock}.op(eq(99)))"
+                    )
+                )
+            }
+    }
+
+    @Test
+    fun `checkUnnecessaryStubAll with single call to each stub`() {
+        clearAllMocks() // ensure that previous tests haven't created unnecessary stubs
+        doCalls1()
+        val mock2 = mockk<MockCls>()
+        every { mock2.op(98) } returns 1
+        mock2.op(98)
+        checkUnnecessaryStub()
+    }
+
+    @Test
+    fun `checkUnnecessaryStubAll with some used and some unused stubs`() {
+        clearAllMocks() // ensure that previous tests haven't created unnecessary stubs
+        doCalls1()
+        val mock2 = mockk<MockCls> { every { op(42) } returns 1 }
+        assertFailsWith<AssertionError> {
+            checkUnnecessaryStub()
+        }
+            .also {
+                assertThat(
+                    it.message, equalTo(
+                        "Unnecessary stubbings detected.\n" +
+                                "Following stubbings are not used, either because there are unnecessary or because tested code doesn't call them :\n" +
+                                "\n" +
+                                "1) ${mock2}.op(eq(42)))"
+                    )
+                )
+            }
+    }
+
     @Test
     fun checkVerify() {
         doCalls1()