From 51a76651d65afd2cdd98d04c6282d16729218066 Mon Sep 17 00:00:00 2001
From: Michael Comella <michael.l.comella@gmail.com>
Date: Fri, 3 Apr 2020 08:25:30 -0700
Subject: [PATCH] For #9605 - review: clarify comments in new test runner.

---
 .../FenixRobolectricTestApplication.kt        |  4 +++-
 .../helpers/FenixRobolectricTestRunner.kt     | 19 ++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/app/src/test/java/org/mozilla/fenix/helpers/FenixRobolectricTestApplication.kt b/app/src/test/java/org/mozilla/fenix/helpers/FenixRobolectricTestApplication.kt
index 30eef5650..b333bd675 100644
--- a/app/src/test/java/org/mozilla/fenix/helpers/FenixRobolectricTestApplication.kt
+++ b/app/src/test/java/org/mozilla/fenix/helpers/FenixRobolectricTestApplication.kt
@@ -8,7 +8,9 @@ import org.mozilla.fenix.FenixApplication
 import org.mozilla.fenix.components.TestComponents
 
 /**
- * An override of our application for use in Robolectric-based unit tests.
+ * An override of our application for use in Robolectric-based unit tests. We're forced to override
+ * because our standard application fails to initialize in Robolectric with exceptions like:
+ * "Crash handler service must run in a separate process".
  */
 class FenixRobolectricTestApplication : FenixApplication() {
 
diff --git a/app/src/test/java/org/mozilla/fenix/helpers/FenixRobolectricTestRunner.kt b/app/src/test/java/org/mozilla/fenix/helpers/FenixRobolectricTestRunner.kt
index cdebf16ba..76d1b8e9a 100644
--- a/app/src/test/java/org/mozilla/fenix/helpers/FenixRobolectricTestRunner.kt
+++ b/app/src/test/java/org/mozilla/fenix/helpers/FenixRobolectricTestRunner.kt
@@ -8,7 +8,9 @@ import org.robolectric.RobolectricTestRunner
 import org.robolectric.annotation.Config
 
 /**
- * A test runner that starts Robolectric with our custom configuration for use in unit tests.
+ * A test runner that starts Robolectric with our custom configuration for use in unit tests. This
+ * should ALWAYS be used instead of RobolectricTestRunner and AndroidJUnit4. You should only use
+ * Robolectric when necessary because it non-trivially increases test duration.
  *
  * usage:
  * ```
@@ -16,10 +18,17 @@ import org.robolectric.annotation.Config
  * class ExampleUnitTest {
  * ```
  *
- * IMPORTANT NOTES:
- * - This should ALWAYS be used instead of RobolectricTestRunner and AndroidJUnit4 (note: the latter
- * just delegates to the former)
- * - You should only use Robolectric when necessary because it non-trivially increases test duration.
+ * There were three common test runners before this patch:
+ * 1. The default (@RunWith not specified) = JUnit4
+ * 2. @RunWith(RobolectricTestRunner::class) = JUnit4 with support for the Android framework via Robolectric
+ * 3. @RunWith(AndroidJUnit4::class) = JUnit4 with support for the Android framework. This currently
+ * delegates to Robolectric but is presumably generically named so that it can support different
+ * implementations in the future. The name creates confusion on over the difference between this and
+ * JUnit without any Android support (1).
+ *
+ * We chose the name RobolectricTestRunner because we want folks to know they're starting Robolectric
+ * because it increases test runtime. Furthermore, the naming of 3) is unclear so we didn't want to
+ * use that name.
  */
 class FenixRobolectricTestRunner(testClass: Class<*>) : RobolectricTestRunner(testClass) {