Repository: mockito/mockito
Issue: Silent JUnit runner and quiet JUnit rule are better expose in the docs
Labels: docs

See great feedback from a user in #384


Issue comments:
https://github.com/mockito/mockito/issues/384#issuecomment-243044175

@szczepiq This is not the javadoc but I've mentioned a bit the runner in the what's new / migration guide in the wiki in the improvement section 

https://github.com/mockito/mockito/wiki/What%27s-new-in-Mockito-2

Per https://github.com/mockito/mockito/issues/720#issuecomment-257087017 the message of `UnnecessaryStubbingException` should be improved to mention `MockitoJUnitRunner.Silent`.


Pull request review comments:

Patch that resolved the issue:
diff --git a/src/main/java/org/mockito/exceptions/misusing/UnnecessaryStubbingException.java b/src/main/java/org/mockito/exceptions/misusing/UnnecessaryStubbingException.java
index 39fbae80ee..603dc349e1 100644
--- a/src/main/java/org/mockito/exceptions/misusing/UnnecessaryStubbingException.java
+++ b/src/main/java/org/mockito/exceptions/misusing/UnnecessaryStubbingException.java
@@ -5,8 +5,13 @@
 package org.mockito.exceptions.misusing;
 
 /**
- * Unnecessary stubs are stubbed method calls that were never realized during test execution
- * (see also {@link org.mockito.quality.MockitoHint}), example:
+ * This exception indicates presence of unused stubbings.
+ * It is highly recommended to remove unused stubbings to keep the codebase clean.
+ * You can opt-out from detecting unused stubbings using {@link org.mockito.runners.MockitoJUnitRunner.Silent} or
+ * {@link org.mockito.junit.MockitoRule#silent()} (when you are using Mockito JUnit rules.
+ * For more information about detecting unused stubbings, see {@link org.mockito.quality.MockitoHint}.
+ * <p>
+ * Unnecessary stubbings are stubbed method calls that were never realized during test execution. Example:
  * <pre class="code"><code class="java">
  * //code under test:
  * ...
@@ -26,7 +31,13 @@
  * In order to keep the codebase clean & maintainable it is necessary to remove unnecessary code.
  * Otherwise tests are harder to read and reason about.
  * <p>
+ * Mockito JUnit Runner triggers <code>UnnecessaryStubbingException</code> only when none of the test methods use the stubbings.
+ * This means that it is ok to put default stubbing in a 'setup' method or in test class constructor.
+ * That default stubbing needs to be used at least once by one of the test methods.
+ * <p>
  * To find out more about detecting unused stubbings see {@link org.mockito.quality.MockitoHint}.
+ * See javadoc for {@link org.mockito.runners.MockitoJUnitRunner} to find out how Mockito JUnit Runner detects unused stubs.
+ * See javadoc for {@link org.mockito.junit.MockitoRule} to understand the behavior or Mockito JUnit Rules.
  */
 public class UnnecessaryStubbingException extends RuntimeException {
     public UnnecessaryStubbingException(String message) {
diff --git a/src/main/java/org/mockito/internal/exceptions/Reporter.java b/src/main/java/org/mockito/internal/exceptions/Reporter.java
index 807bdee3a3..86e284b22c 100644
--- a/src/main/java/org/mockito/internal/exceptions/Reporter.java
+++ b/src/main/java/org/mockito/internal/exceptions/Reporter.java
@@ -839,7 +839,7 @@ public static UnnecessaryStubbingException formatUnncessaryStubbingException(Cla
                 "Unnecessary stubbings detected in test class: " + testClass.getSimpleName(),
                 "Clean & maintainable test code requires zero unnecessary code.",
                 "Following stubbings are unnecessary (click to navigate to relevant line of code):" + stubbings,
-                "Please remove unnecessary stubbings. More info: javadoc for UnnecessaryStubbingException class."
+                "Please remove unnecessary stubbings or use 'silent' option. More info: javadoc for UnnecessaryStubbingException class."
         ));
     }
 }


Test patch:
diff --git a/src/test/java/org/mockitousage/junitrunner/UnusedStubsExceptionMessageTest.java b/src/test/java/org/mockitousage/junitrunner/UnusedStubsExceptionMessageTest.java
index 3760e64467..637f7acac5 100644
--- a/src/test/java/org/mockitousage/junitrunner/UnusedStubsExceptionMessageTest.java
+++ b/src/test/java/org/mockitousage/junitrunner/UnusedStubsExceptionMessageTest.java
@@ -49,7 +49,7 @@ public void lists_all_unused_stubs_cleanly() {
                         "Following stubbings are unnecessary (click to navigate to relevant line of code):\n" +
                         "  1. -> at org.mockitousage.junitrunner.UnusedStubsExceptionMessageTest$HasUnnecessaryStubs.<init>(UnusedStubsExceptionMessageTest.java:0)\n" +
                         "  2. -> at org.mockitousage.junitrunner.UnusedStubsExceptionMessageTest$HasUnnecessaryStubs.<init>(UnusedStubsExceptionMessageTest.java:0)\n" +
-                        "Please remove unnecessary stubbings. More info: javadoc for UnnecessaryStubbingException class.",
+                        "Please remove unnecessary stubbings or use 'silent' option. More info: javadoc for UnnecessaryStubbingException class.",
                 filterLineNo(failure.getException().getMessage()));
     }
 }