diff --git a/docs/automated-migration.md b/docs/automated-migration.md index 7e52b8b2d..7a4e29c1e 100644 --- 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 index 802df9b61..d3ed0c1ca 100644 --- 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!  [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 b/docs/upgrade_to_version_3.md similarity index 82% rename from docs/migrating.md rename to docs/upgrade_to_version_3.md index e78ba4018..09aee3504 100644 --- a/docs/migrating.md +++ b/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`. - ---- - ## Migrating to 3.6 @@ -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,9 +469,7 @@ 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) @@ -600,12 +477,9 @@ testCompile("org.robolectric:shadows-maps:3.0") [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 new file mode 100644 index 000000000..c66aeb553 --- /dev/null +++ b/docs/upgrade_to_version_4.md @@ -0,0 +1,119 @@ +## 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`. + +[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 index 0654df144..d4471b972 100644 --- 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