add info about how to return default values from android.jar

bug: 30757670

Change-Id: I84e1624cbe7ae8d5e4e2886d4e8f61d621729464

diff --git a/docs/html/training/testing/unit-testing/local-unit-tests.jd b/docs/html/training/testing/unit-testing/local-unit-tests.jd
index 8b109ee..d19de4f 100644 (file)
--- a/docs/html/training/testing/unit-testing/local-unit-tests.jd
+++ b/docs/html/training/testing/unit-testing/local-unit-tests.jd
@@ -112,12 +112,16 @@ Hamcrest matchers</a> (such as the {@code is()} and {@code equalTo()} methods) t
 returned result against the expected result.</p>
 
 <h3 id="mocking-dependencies">Mock Android dependencies</h3>
-<p>
-By default, the <a href="{@docRoot}tools/building/plugin-for-gradle.html">
-Android Plug-in for Gradle</a> executes your local unit tests against a modified
-version of the {@code android.jar} library, which does not contain any actual code. Instead, method
-calls to Android classes from your unit test throw an exception.
-</p>
+
+<p>By default, the <a href=
+"{@docRoot}tools/building/plugin-for-gradle.html">Android Plug-in for
+Gradle</a> executes your local unit tests against a modified version of the
+{@code android.jar} library, which does not contain any actual code. Instead,
+method calls to Android classes from your unit test throw an exception. This is
+to make sure you test only your code and do not depend on any
+particular behavior of the Android platform (that you have not explicitly
+mocked).</p>
+
 <p>
 You can use a mocking framework to stub out external dependencies in your code, to easily test that
 your component interacts with a dependency in an expected way. By substituting Android dependencies
@@ -195,6 +199,26 @@ class="external-link">Mockito API reference</a> and the
 class="external-link">sample code</a>.
 </p>
 
+<p>If the exceptions thrown by Android APIs in the
+<code>android.jar</code> are problematic for your tests, you can change the behavior so that methods
+instead return either null or zero by adding the following configuration in your project's
+top-level <code>build.gradle</code> file:</p>
+
+<pre>
+android {
+  ...
+  testOptions {
+    unitTests.returnDefaultValues = true
+  }
+}
+</pre>
+
+<p class="caution"><strong>Caution:</strong>
+Setting the <code>returnDefaultValues</code> property to <code>true</code>
+should be done with care. The null/zero return values can introduce
+regressions in your tests, which are hard to debug and might allow failing tests
+to pass. Only use it as a last resort.</p>
+
 
 <h2 id="run">Run Local Unit Tests</h2>