robolectric · MGaetan89 · Dec 6, 2024 · Dec 3, 2024
diff --git a/docs/automated-migration.md b/docs/automated-migration.md
@@ -1,6 +1,5 @@
 ---
 hide:
-- navigation
 - toc
 ---
 

diff --git a/docs/blog/posts/2018-10-25-robolectric-4-0.md b/docs/blog/posts/2018-10-25-robolectric-4-0.md
@@ -103,5 +103,5 @@ As always, thanks for your pull requests, bug reports, ideas and questions! &#x1
 [automated-migration-tool]: ../../automated-migration.md
 [espresso]: https://developer.android.com/training/testing/espresso
 [junit-runner]: https://developer.android.com/training/testing/junit-runner
-[migration]: ../../migrating.md#migrating-to-40
+[migration]: ../../upgrade_to_version_4.md#migrating-to-40
 [robolectric-4.0-release]: https://github.com/robolectric/robolectric/releases/tag/robolectric-4.0
diff --git a/docs/migrating.md → docs/upgrade_to_version_3.md b/docs/migrating.md → docs/upgrade_to_version_3.md
@@ -1,116 +1,3 @@
----
-title: Robolectric Migration Guide
----
-
-## Automated Migration
-
-Robolectric provides an [automated migration tool](automated-migration.md) to help keep your test
-suite up to date with Robolectric API changes.
-
-## Migrating to 4.0
-
-### Project Configuration
-
-Robolectric 4.0 requires Android Gradle Plugin 3.2 or greater.
-
-Update the configuration in your module's `build.gradle`/`build.gradle.kts` file:
-
-/// tab | Groovy
-```groovy
-android {
-  compileSdkVersion 28 // Or newer
-  testOptions.unitTests.includeAndroidResources = true
-}
-```
-///
-
-/// tab | Kotlin
-```kotlin
-android {
-  compileSdkVersion = 28 // Or newer
-  testOptions.unitTests.isIncludeAndroidResources = true
-}
-```
-///
-
-Add the following in your `gradle.properties` file:
-
-```properties
-android.enableUnitTestBinaryResources=true
-```
-
-If you have dependencies on `com.android.support.test`, switch them to `androidx.test`; see
-[Migrate to AndroidX][migrate-to-androidx].
-
-### Deprecations
-
-| 3.8                                        | 4.0                                                                                               |
-|--------------------------------------------|---------------------------------------------------------------------------------------------------|
-| `ShadowApplication.getInstance()`          | [`RuntimeEnvironment.application`][runtime-environment-application-javadoc]                       |
-| `ShadowApplication.getLatestAlertDialog()` | [`ShadowAlertDialog.getLatestAlertDialog()`][shadow-alert-dialog-get-latest-alert-dialog-javadoc] |
-| `ShadowApplication.getLatestDialog()`      | [`ShadowDialog.getLatestDialog()`][shadow-dialog-get-latest-dialog-javadoc]                       |
-| `ShadowApplication.getLatestPopupMenu()`   | [`ShadowPopupMenu.getLatestPopupMenu()`][shadow-popup-menu-get-latest-popup-menu-javadoc]         |
-| `ShadowLooper.getShadowMainLooper()`       | [`shadowOf(Looper.getMainLooper())`][shadow-of-looper-javadoc]                                    |
-
-The [automatic migration tool](automated-migration.md) includes a migration to help with this.
-
-The following attributes of the [`@Config`][config-javadoc] annotation are no longer supported when
-using binary resources mode:
-
-* [`assetDir`][config-asset-dir-javadoc] and [`resourceDir`][config-resource-dir-javadoc]: follow
-  the recommended file structure of your build system.
-* [`manifest`][config-manifest-javadoc]: Robolectric always uses the merged manifest generated by
-  the Android toolchain. If your test was using a custom manifest you'll need to adapt it to not
-  rely on that.
-* [`packageName`][config-package-name-javadoc]: to change your package name, override the
-  `applicationId` in your build system.
-
-### Improper Use of Shadows
-
-Prior to Robolectric 4.0, it was possible (but ill-advised) to get the shadow for an Android
-framework object and invoke framework methods there. This could result in unexpected behavior (e.g.,
-code in overridden methods in subclasses wouldn't be called). Shadow implementation methods are now
-marked `protected` to guard against this. Always invoke framework methods directly on the Android
-class.
-
-| 3.8                                      | 4.0                                                                      |
-|------------------------------------------|--------------------------------------------------------------------------|
-| `shadowOf(activity).finish();`           | [`activity.finish()`][activity-finish-documentation]                     |
-| `ShadowSystemClock.currentTimeMillis();` | [`System.currentTimeMillis()`][system-current-time-millis-documentation] |
-
-The [automatic migration tool](automated-migration.md) will fix most of these for you.
-
-### `androidx.test`
-
-Robolectric 4.0 includes initial support for [`androidx.test` APIs][androidx-test-apis]. We strongly
-recommend adding the latest version of `androidx.test:core` as a test dependency and using those
-APIs whenever possible rather than using Robolectric-specific APIs.
-
-| 3.8                              | 4.0                                                                                                         |
-|----------------------------------|-------------------------------------------------------------------------------------------------------------|
-| `RuntimeEnvironment.application` | [`ApplicationProvider.getApplicationContext()`][application-provider-get-application-context-documentation] |
-| `ShadowMotionEvent`              | [`MotionEventBuilder`][motion-event-builder-documentation]                                                  |
-
-### Troubleshooting
-
-Robolectric 4.0 replaces its old home-grown resource handling code with a direct adaptation of
-Android's resource handling code, using the full Android toolchain. This greatly improves fidelity
-to the behavior of a real Android device, but if your tests were relying on the quirks of the old
-code, you may need to fix your tests.
-
-Some likely issues include:
-
-!!! quote ""
-
-    > android.view.InflateException: Binary XML file line #3: Failed to resolve attribute at index
-    > 17: TypedValue{t=0x2/d=0x7f01000e a=-1}
-
-    This happens when your [`Activity`][activity-documentation] is using a theme that lacks values
-    for certain attributes used by layouts. Make sure you've specified an appropriate theme for your
-    activities in your `AndroidManifest`.
-
----
-
 <!-- markdownlint-disable-next-line MD033 -->
 ## Migrating to 3.6<a name="migrating-from-35-to-36"></a>
 
@@ -550,15 +437,9 @@ testCompile("org.robolectric:shadows-maps:3.0")
 
 [activity-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/ActivityController.html
 [activity-documentation]: https://developer.android.com/reference/android/app/Activity
-[activity-finish-documentation]: https://developer.android.com/reference/android/app/Activity#finish()
-[androidx-test-apis]: https://developer.android.com/reference/androidx/test/package-summary
-[application-provider-get-application-context-documentation]: https://developer.android.com/reference/androidx/test/core/app/ApplicationProvider#getApplicationContext()
 [config-asset-dir-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#assetDir()
 [config-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html
-[config-manifest-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#manifest()
 [config-merger-get-config-properties-javadoc]: javadoc/latest/org/robolectric/ConfigMerger.html#getConfigProperties(java.lang.String)
-[config-package-name-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#packageName()
-[config-resource-dir-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#resourceDir()
 [content-provider-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/ContentProviderController.html
 [content-provider-documentation]: https://developer.android.com/reference/android/content/ContentProvider
 [context-documentation]: https://developer.android.com/reference/android/content/Context
@@ -573,9 +454,7 @@ testCompile("org.robolectric:shadows-maps:3.0")
 [fake-http-get-latest-sent-http-request-javadoc]: javadoc/latest/org/robolectric/shadows/httpclient/FakeHttp.html#getLatestSentHttpRequest()
 [fragment-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/FragmentController.html
 [intent-service-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/IntentServiceController.html
-[migrate-to-androidx]: https://developer.android.com/jetpack/androidx/migrate
 [mockito]: https://site.mockito.org/
-[motion-event-builder-documentation]: https://developer.android.com/reference/androidx/test/core/view/MotionEventBuilder
 [package-manager-documentation]: https://developer.android.com/reference/android/content/pm/PackageManager
 [preference-manager-get-default-shared-preferences-documentation]: https://developer.android.com/reference/android/preference/PreferenceManager#getDefaultSharedPreferences(android.content.Context)
 [robo-executor-service-javadoc]: javadoc/latest/org/robolectric/android/util/concurrent/RoboExecutorService.html
@@ -590,22 +469,17 @@ testCompile("org.robolectric:shadows-maps:3.0")
 [runtime-environment-application-javadoc]: javadoc/latest/org/robolectric/RuntimeEnvironment.html#application
 [service-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/ServiceController.html
 [service-documentation]: https://developer.android.com/reference/android/app/Service
-[shadow-alert-dialog-get-latest-alert-dialog-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowAlertDialog.html#getLatestAlertDialog()
 [shadow-application-package-manager-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowApplicationPackageManager.html
-[shadow-dialog-get-latest-dialog-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowDialog.html#getLatestDialog()
 [shadow-display-get-default-display-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowDisplay.html#getDefaultDisplay()
 [shadow-drawable-get-created-from-res-id-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowDrawable.html#getCreatedFromResId()
 [shadow-extract-javadoc]: javadoc/latest/org/robolectric/shadow/api/Shadow.html#extract(java.lang.Object)
 [shadow-javadoc]: javadoc/latest/org/robolectric/shadow/api/Shadow.html
 [shadow-notification-get-content-text-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowNotification.html#getContentText()
 [shadow-notification-is-indeterminate-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowNotification.html#isIndeterminate()
 [shadow-of-drawable-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.graphics.drawable.Drawable)
-[shadow-of-looper-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.os.Looper)
 [shadow-of-notification-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.app.Notification)
 [shadow-of-package-manager-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.content.pm.PackageManager)
 [shadow-package-manager-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowPackageManager.html
-[shadow-popup-menu-get-latest-popup-menu-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowPopupMenu.html#getLatestPopupMenu()
 [shared-preferences-documentation]: https://developer.android.com/reference/android/content/SharedPreferences
 [square-assertj-android]: https://github.com/square/assertj-android
-[system-current-time-millis-documentation]: https://developer.android.com/reference/java/lang/System#currentTimeMillis()
 [xml-resource-parser-impl-javadoc]: javadoc/latest/org/robolectric/android/XmlResourceParserImpl.html
diff --git a/docs/upgrade_to_version_4.md b/docs/upgrade_to_version_4.md
@@ -0,0 +1,119 @@
+## Migrating to 4.0<a name="migrating-to-40"></a>
+
+### Project Configuration
+
+Robolectric 4.0 requires Android Gradle Plugin 3.2 or greater.
+
+Update the configuration in your module's `build.gradle`/`build.gradle.kts` file:
+
+/// tab | Groovy
+```groovy
+android {
+  compileSdkVersion 28 // Or newer
+  testOptions.unitTests.includeAndroidResources = true
+}
+```
+///
+
+/// tab | Kotlin
+```kotlin
+android {
+  compileSdkVersion = 28 // Or newer
+  testOptions.unitTests.isIncludeAndroidResources = true
+}
+```
+///
+
+Add the following in your `gradle.properties` file:
+
+```properties
+android.enableUnitTestBinaryResources=true
+```
+
+If you have dependencies on `com.android.support.test`, switch them to `androidx.test`; see
+[Migrate to AndroidX][migrate-to-androidx].
+
+### Deprecations
+
+| 3.8                                        | 4.0                                                                                               |
+|--------------------------------------------|---------------------------------------------------------------------------------------------------|
+| `ShadowApplication.getInstance()`          | [`RuntimeEnvironment.application`][runtime-environment-application-javadoc]                       |
+| `ShadowApplication.getLatestAlertDialog()` | [`ShadowAlertDialog.getLatestAlertDialog()`][shadow-alert-dialog-get-latest-alert-dialog-javadoc] |
+| `ShadowApplication.getLatestDialog()`      | [`ShadowDialog.getLatestDialog()`][shadow-dialog-get-latest-dialog-javadoc]                       |
+| `ShadowApplication.getLatestPopupMenu()`   | [`ShadowPopupMenu.getLatestPopupMenu()`][shadow-popup-menu-get-latest-popup-menu-javadoc]         |
+| `ShadowLooper.getShadowMainLooper()`       | [`shadowOf(Looper.getMainLooper())`][shadow-of-looper-javadoc]                                    |
+
+The [automatic migration tool](automated-migration.md) includes a migration to help with this.
+
+The following attributes of the [`@Config`][config-javadoc] annotation are no longer supported when
+using binary resources mode:
+
+* [`assetDir`][config-asset-dir-javadoc] and [`resourceDir`][config-resource-dir-javadoc]: follow
+  the recommended file structure of your build system.
+* [`manifest`][config-manifest-javadoc]: Robolectric always uses the merged manifest generated by
+  the Android toolchain. If your test was using a custom manifest you'll need to adapt it to not
+  rely on that.
+* [`packageName`][config-package-name-javadoc]: to change your package name, override the
+  `applicationId` in your build system.
+
+### Improper Use of Shadows
+
+Prior to Robolectric 4.0, it was possible (but ill-advised) to get the shadow for an Android
+framework object and invoke framework methods there. This could result in unexpected behavior (e.g.,
+code in overridden methods in subclasses wouldn't be called). Shadow implementation methods are now
+marked `protected` to guard against this. Always invoke framework methods directly on the Android
+class.
+
+| 3.8                                      | 4.0                                                                      |
+|------------------------------------------|--------------------------------------------------------------------------|
+| `shadowOf(activity).finish();`           | [`activity.finish()`][activity-finish-documentation]                     |
+| `ShadowSystemClock.currentTimeMillis();` | [`System.currentTimeMillis()`][system-current-time-millis-documentation] |
+
+The [automatic migration tool](automated-migration.md) will fix most of these for you.
+
+### `androidx.test`
+
+Robolectric 4.0 includes initial support for [`androidx.test` APIs][androidx-test-apis]. We strongly
+recommend adding the latest version of `androidx.test:core` as a test dependency and using those
+APIs whenever possible rather than using Robolectric-specific APIs.
+
+| 3.8                              | 4.0                                                                                                         |
+|----------------------------------|-------------------------------------------------------------------------------------------------------------|
+| `RuntimeEnvironment.application` | [`ApplicationProvider.getApplicationContext()`][application-provider-get-application-context-documentation] |
+| `ShadowMotionEvent`              | [`MotionEventBuilder`][motion-event-builder-documentation]                                                  |
+
+### Troubleshooting
+
+Robolectric 4.0 replaces its old home-grown resource handling code with a direct adaptation of
+Android's resource handling code, using the full Android toolchain. This greatly improves fidelity
+to the behavior of a real Android device, but if your tests were relying on the quirks of the old
+code, you may need to fix your tests.
+
+Some likely issues include:
+
+!!! quote ""
+
+    > android.view.InflateException: Binary XML file line #3: Failed to resolve attribute at index
+    > 17: TypedValue{t=0x2/d=0x7f01000e a=-1}
+
+    This happens when your [`Activity`][activity-documentation] is using a theme that lacks values
+    for certain attributes used by layouts. Make sure you've specified an appropriate theme for your
+    activities in your `AndroidManifest`.
+
+[activity-documentation]: https://developer.android.com/reference/android/app/Activity
+[activity-finish-documentation]: https://developer.android.com/reference/android/app/Activity#finish()
+[androidx-test-apis]: https://developer.android.com/reference/androidx/test/package-summary
+[application-provider-get-application-context-documentation]: https://developer.android.com/reference/androidx/test/core/app/ApplicationProvider#getApplicationContext()
+[config-asset-dir-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#assetDir()
+[config-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html
+[config-manifest-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#manifest()
+[config-package-name-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#packageName()
+[config-resource-dir-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#resourceDir()
+[migrate-to-androidx]: https://developer.android.com/jetpack/androidx/migrate
+[motion-event-builder-documentation]: https://developer.android.com/reference/androidx/test/core/view/MotionEventBuilder
+[runtime-environment-application-javadoc]: javadoc/latest/org/robolectric/RuntimeEnvironment.html#application
+[shadow-alert-dialog-get-latest-alert-dialog-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowAlertDialog.html#getLatestAlertDialog()
+[shadow-dialog-get-latest-dialog-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowDialog.html#getLatestDialog()
+[shadow-of-looper-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.os.Looper)
+[shadow-popup-menu-get-latest-popup-menu-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowPopupMenu.html#getLatestPopupMenu()
+[system-current-time-millis-documentation]: https://developer.android.com/reference/java/lang/System#currentTimeMillis()
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -79,6 +79,7 @@ plugins:
         "activity-lifecycle.md": "androidx_test.md"
         "custom-shadows.md": "extending.md"
         "errorprone-refactorings.md": "automated-migration.md"
+        "migrating.md": "automated-migration.md"
         "other-environments.md": "getting-started.md"
   - search:
 
@@ -121,10 +122,9 @@ nav:
     - "Contributor Guidelines": contributing.md
     - "Shadows": extending.md
   - "Resources":
-    - "Migration Guide": migrating.md
-    - "GitHub": https://github.com/robolectric/robolectric/
-    - "Release Notes": https://github.com/robolectric/robolectric/releases/
-    - "Issues": https://github.com/robolectric/robolectric/issues/
+    - "Automated Migration": automated-migration.md
+    - "Upgrade to Robolectric 4.x": upgrade_to_version_4.md
+    - "Upgrade to Robolectric 3.x": upgrade_to_version_3.md
     - "Javadoc":
       - "4.14": /javadoc/4.14/
       - "4.13": /javadoc/4.13/
@@ -141,6 +141,10 @@ nav:
       - "4.2": /javadoc/4.2/
       - "4.1": /javadoc/4.1/
       - "4.0": /javadoc/4.0/
+    - "":
+        - "GitHub": https://github.com/robolectric/robolectric/
+        - "Releases": https://github.com/robolectric/robolectric/releases/
+        - "Issues": https://github.com/robolectric/robolectric/issues/
   - "Blog":
     - blog/index.md
-Original file line number
+Diff line change
@@ -1,6 +1,5 @@
     ---
     hide:
-    - navigation
     - toc
     ---
@@ Expand Down @@