Skip to content

Commit 0f4c63b

Browse files
MGaetan89MGaetan89
authored
Split "Migration Guide" into multiple pages (robolectric#368)
1 parent 382548d commit 0f4c63b

File tree

5 files changed

+128
-132
lines changed

5 files changed

+128
-132
lines changed

‎docs/automated-migration.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
hide:
3-
- navigation
43
- toc
54
---
65

‎docs/blog/posts/2018-10-25-robolectric-4-0.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,5 +103,5 @@ As always, thanks for your pull requests, bug reports, ideas and questions! &#x1
103103
[automated-migration-tool]: ../../automated-migration.md
104104
[espresso]: https://developer.android.com/training/testing/espresso
105105
[junit-runner]: https://developer.android.com/training/testing/junit-runner
106-
[migration]: ../../migrating.md#migrating-to-40
106+
[migration]: ../../upgrade_to_version_4.md#migrating-to-40
107107
[robolectric-4.0-release]: https://github.com/robolectric/robolectric/releases/tag/robolectric-4.0

‎docs/migrating.md‎ renamed to ‎docs/upgrade_to_version_3.md‎

Lines changed: 0 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,3 @@
1-
---
2-
title: Robolectric Migration Guide
3-
---
4-
5-
## Automated Migration
6-
7-
Robolectric provides an [automated migration tool](automated-migration.md) to help keep your test
8-
suite up to date with Robolectric API changes.
9-
10-
## Migrating to 4.0
11-
12-
### Project Configuration
13-
14-
Robolectric 4.0 requires Android Gradle Plugin 3.2 or greater.
15-
16-
Update the configuration in your module's `build.gradle`/`build.gradle.kts` file:
17-
18-
/// tab | Groovy
19-
```groovy
20-
android {
21-
compileSdkVersion 28 // Or newer
22-
testOptions.unitTests.includeAndroidResources = true
23-
}
24-
```
25-
///
26-
27-
/// tab | Kotlin
28-
```kotlin
29-
android {
30-
compileSdkVersion = 28 // Or newer
31-
testOptions.unitTests.isIncludeAndroidResources = true
32-
}
33-
```
34-
///
35-
36-
Add the following in your `gradle.properties` file:
37-
38-
```properties
39-
android.enableUnitTestBinaryResources=true
40-
```
41-
42-
If you have dependencies on `com.android.support.test`, switch them to `androidx.test`; see
43-
[Migrate to AndroidX][migrate-to-androidx].
44-
45-
### Deprecations
46-
47-
| 3.8 | 4.0 |
48-
|--------------------------------------------|---------------------------------------------------------------------------------------------------|
49-
| `ShadowApplication.getInstance()` | [`RuntimeEnvironment.application`][runtime-environment-application-javadoc] |
50-
| `ShadowApplication.getLatestAlertDialog()` | [`ShadowAlertDialog.getLatestAlertDialog()`][shadow-alert-dialog-get-latest-alert-dialog-javadoc] |
51-
| `ShadowApplication.getLatestDialog()` | [`ShadowDialog.getLatestDialog()`][shadow-dialog-get-latest-dialog-javadoc] |
52-
| `ShadowApplication.getLatestPopupMenu()` | [`ShadowPopupMenu.getLatestPopupMenu()`][shadow-popup-menu-get-latest-popup-menu-javadoc] |
53-
| `ShadowLooper.getShadowMainLooper()` | [`shadowOf(Looper.getMainLooper())`][shadow-of-looper-javadoc] |
54-
55-
The [automatic migration tool](automated-migration.md) includes a migration to help with this.
56-
57-
The following attributes of the [`@Config`][config-javadoc] annotation are no longer supported when
58-
using binary resources mode:
59-
60-
* [`assetDir`][config-asset-dir-javadoc] and [`resourceDir`][config-resource-dir-javadoc]: follow
61-
the recommended file structure of your build system.
62-
* [`manifest`][config-manifest-javadoc]: Robolectric always uses the merged manifest generated by
63-
the Android toolchain. If your test was using a custom manifest you'll need to adapt it to not
64-
rely on that.
65-
* [`packageName`][config-package-name-javadoc]: to change your package name, override the
66-
`applicationId` in your build system.
67-
68-
### Improper Use of Shadows
69-
70-
Prior to Robolectric 4.0, it was possible (but ill-advised) to get the shadow for an Android
71-
framework object and invoke framework methods there. This could result in unexpected behavior (e.g.,
72-
code in overridden methods in subclasses wouldn't be called). Shadow implementation methods are now
73-
marked `protected` to guard against this. Always invoke framework methods directly on the Android
74-
class.
75-
76-
| 3.8 | 4.0 |
77-
|------------------------------------------|--------------------------------------------------------------------------|
78-
| `shadowOf(activity).finish();` | [`activity.finish()`][activity-finish-documentation] |
79-
| `ShadowSystemClock.currentTimeMillis();` | [`System.currentTimeMillis()`][system-current-time-millis-documentation] |
80-
81-
The [automatic migration tool](automated-migration.md) will fix most of these for you.
82-
83-
### `androidx.test`
84-
85-
Robolectric 4.0 includes initial support for [`androidx.test` APIs][androidx-test-apis]. We strongly
86-
recommend adding the latest version of `androidx.test:core` as a test dependency and using those
87-
APIs whenever possible rather than using Robolectric-specific APIs.
88-
89-
| 3.8 | 4.0 |
90-
|----------------------------------|-------------------------------------------------------------------------------------------------------------|
91-
| `RuntimeEnvironment.application` | [`ApplicationProvider.getApplicationContext()`][application-provider-get-application-context-documentation] |
92-
| `ShadowMotionEvent` | [`MotionEventBuilder`][motion-event-builder-documentation] |
93-
94-
### Troubleshooting
95-
96-
Robolectric 4.0 replaces its old home-grown resource handling code with a direct adaptation of
97-
Android's resource handling code, using the full Android toolchain. This greatly improves fidelity
98-
to the behavior of a real Android device, but if your tests were relying on the quirks of the old
99-
code, you may need to fix your tests.
100-
101-
Some likely issues include:
102-
103-
!!! quote ""
104-
105-
> android.view.InflateException: Binary XML file line #3: Failed to resolve attribute at index
106-
> 17: TypedValue{t=0x2/d=0x7f01000e a=-1}
107-
108-
This happens when your [`Activity`][activity-documentation] is using a theme that lacks values
109-
for certain attributes used by layouts. Make sure you've specified an appropriate theme for your
110-
activities in your `AndroidManifest`.
111-
112-
---
113-
1141
<!-- markdownlint-disable-next-line MD033 -->
1152
## Migrating to 3.6<a name="migrating-from-35-to-36"></a>
1163

@@ -550,15 +437,9 @@ testCompile("org.robolectric:shadows-maps:3.0")
550437

551438
[activity-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/ActivityController.html
552439
[activity-documentation]: https://developer.android.com/reference/android/app/Activity
553-
[activity-finish-documentation]: https://developer.android.com/reference/android/app/Activity#finish()
554-
[androidx-test-apis]: https://developer.android.com/reference/androidx/test/package-summary
555-
[application-provider-get-application-context-documentation]: https://developer.android.com/reference/androidx/test/core/app/ApplicationProvider#getApplicationContext()
556440
[config-asset-dir-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#assetDir()
557441
[config-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html
558-
[config-manifest-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#manifest()
559442
[config-merger-get-config-properties-javadoc]: javadoc/latest/org/robolectric/ConfigMerger.html#getConfigProperties(java.lang.String)
560-
[config-package-name-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#packageName()
561-
[config-resource-dir-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#resourceDir()
562443
[content-provider-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/ContentProviderController.html
563444
[content-provider-documentation]: https://developer.android.com/reference/android/content/ContentProvider
564445
[context-documentation]: https://developer.android.com/reference/android/content/Context
@@ -573,9 +454,7 @@ testCompile("org.robolectric:shadows-maps:3.0")
573454
[fake-http-get-latest-sent-http-request-javadoc]: javadoc/latest/org/robolectric/shadows/httpclient/FakeHttp.html#getLatestSentHttpRequest()
574455
[fragment-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/FragmentController.html
575456
[intent-service-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/IntentServiceController.html
576-
[migrate-to-androidx]: https://developer.android.com/jetpack/androidx/migrate
577457
[mockito]: https://site.mockito.org/
578-
[motion-event-builder-documentation]: https://developer.android.com/reference/androidx/test/core/view/MotionEventBuilder
579458
[package-manager-documentation]: https://developer.android.com/reference/android/content/pm/PackageManager
580459
[preference-manager-get-default-shared-preferences-documentation]: https://developer.android.com/reference/android/preference/PreferenceManager#getDefaultSharedPreferences(android.content.Context)
581460
[robo-executor-service-javadoc]: javadoc/latest/org/robolectric/android/util/concurrent/RoboExecutorService.html
@@ -590,22 +469,17 @@ testCompile("org.robolectric:shadows-maps:3.0")
590469
[runtime-environment-application-javadoc]: javadoc/latest/org/robolectric/RuntimeEnvironment.html#application
591470
[service-controller-javadoc]: javadoc/latest/org/robolectric/android/controller/ServiceController.html
592471
[service-documentation]: https://developer.android.com/reference/android/app/Service
593-
[shadow-alert-dialog-get-latest-alert-dialog-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowAlertDialog.html#getLatestAlertDialog()
594472
[shadow-application-package-manager-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowApplicationPackageManager.html
595-
[shadow-dialog-get-latest-dialog-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowDialog.html#getLatestDialog()
596473
[shadow-display-get-default-display-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowDisplay.html#getDefaultDisplay()
597474
[shadow-drawable-get-created-from-res-id-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowDrawable.html#getCreatedFromResId()
598475
[shadow-extract-javadoc]: javadoc/latest/org/robolectric/shadow/api/Shadow.html#extract(java.lang.Object)
599476
[shadow-javadoc]: javadoc/latest/org/robolectric/shadow/api/Shadow.html
600477
[shadow-notification-get-content-text-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowNotification.html#getContentText()
601478
[shadow-notification-is-indeterminate-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowNotification.html#isIndeterminate()
602479
[shadow-of-drawable-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.graphics.drawable.Drawable)
603-
[shadow-of-looper-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.os.Looper)
604480
[shadow-of-notification-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.app.Notification)
605481
[shadow-of-package-manager-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.content.pm.PackageManager)
606482
[shadow-package-manager-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowPackageManager.html
607-
[shadow-popup-menu-get-latest-popup-menu-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowPopupMenu.html#getLatestPopupMenu()
608483
[shared-preferences-documentation]: https://developer.android.com/reference/android/content/SharedPreferences
609484
[square-assertj-android]: https://github.com/square/assertj-android
610-
[system-current-time-millis-documentation]: https://developer.android.com/reference/java/lang/System#currentTimeMillis()
611485
[xml-resource-parser-impl-javadoc]: javadoc/latest/org/robolectric/android/XmlResourceParserImpl.html

‎docs/upgrade_to_version_4.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
## Migrating to 4.0<a name="migrating-to-40"></a>
2+
3+
### Project Configuration
4+
5+
Robolectric 4.0 requires Android Gradle Plugin 3.2 or greater.
6+
7+
Update the configuration in your module's `build.gradle`/`build.gradle.kts` file:
8+
9+
/// tab | Groovy
10+
```groovy
11+
android {
12+
compileSdkVersion 28 // Or newer
13+
testOptions.unitTests.includeAndroidResources = true
14+
}
15+
```
16+
///
17+
18+
/// tab | Kotlin
19+
```kotlin
20+
android {
21+
compileSdkVersion = 28 // Or newer
22+
testOptions.unitTests.isIncludeAndroidResources = true
23+
}
24+
```
25+
///
26+
27+
Add the following in your `gradle.properties` file:
28+
29+
```properties
30+
android.enableUnitTestBinaryResources=true
31+
```
32+
33+
If you have dependencies on `com.android.support.test`, switch them to `androidx.test`; see
34+
[Migrate to AndroidX][migrate-to-androidx].
35+
36+
### Deprecations
37+
38+
| 3.8 | 4.0 |
39+
|--------------------------------------------|---------------------------------------------------------------------------------------------------|
40+
| `ShadowApplication.getInstance()` | [`RuntimeEnvironment.application`][runtime-environment-application-javadoc] |
41+
| `ShadowApplication.getLatestAlertDialog()` | [`ShadowAlertDialog.getLatestAlertDialog()`][shadow-alert-dialog-get-latest-alert-dialog-javadoc] |
42+
| `ShadowApplication.getLatestDialog()` | [`ShadowDialog.getLatestDialog()`][shadow-dialog-get-latest-dialog-javadoc] |
43+
| `ShadowApplication.getLatestPopupMenu()` | [`ShadowPopupMenu.getLatestPopupMenu()`][shadow-popup-menu-get-latest-popup-menu-javadoc] |
44+
| `ShadowLooper.getShadowMainLooper()` | [`shadowOf(Looper.getMainLooper())`][shadow-of-looper-javadoc] |
45+
46+
The [automatic migration tool](automated-migration.md) includes a migration to help with this.
47+
48+
The following attributes of the [`@Config`][config-javadoc] annotation are no longer supported when
49+
using binary resources mode:
50+
51+
* [`assetDir`][config-asset-dir-javadoc] and [`resourceDir`][config-resource-dir-javadoc]: follow
52+
the recommended file structure of your build system.
53+
* [`manifest`][config-manifest-javadoc]: Robolectric always uses the merged manifest generated by
54+
the Android toolchain. If your test was using a custom manifest you'll need to adapt it to not
55+
rely on that.
56+
* [`packageName`][config-package-name-javadoc]: to change your package name, override the
57+
`applicationId` in your build system.
58+
59+
### Improper Use of Shadows
60+
61+
Prior to Robolectric 4.0, it was possible (but ill-advised) to get the shadow for an Android
62+
framework object and invoke framework methods there. This could result in unexpected behavior (e.g.,
63+
code in overridden methods in subclasses wouldn't be called). Shadow implementation methods are now
64+
marked `protected` to guard against this. Always invoke framework methods directly on the Android
65+
class.
66+
67+
| 3.8 | 4.0 |
68+
|------------------------------------------|--------------------------------------------------------------------------|
69+
| `shadowOf(activity).finish();` | [`activity.finish()`][activity-finish-documentation] |
70+
| `ShadowSystemClock.currentTimeMillis();` | [`System.currentTimeMillis()`][system-current-time-millis-documentation] |
71+
72+
The [automatic migration tool](automated-migration.md) will fix most of these for you.
73+
74+
### `androidx.test`
75+
76+
Robolectric 4.0 includes initial support for [`androidx.test` APIs][androidx-test-apis]. We strongly
77+
recommend adding the latest version of `androidx.test:core` as a test dependency and using those
78+
APIs whenever possible rather than using Robolectric-specific APIs.
79+
80+
| 3.8 | 4.0 |
81+
|----------------------------------|-------------------------------------------------------------------------------------------------------------|
82+
| `RuntimeEnvironment.application` | [`ApplicationProvider.getApplicationContext()`][application-provider-get-application-context-documentation] |
83+
| `ShadowMotionEvent` | [`MotionEventBuilder`][motion-event-builder-documentation] |
84+
85+
### Troubleshooting
86+
87+
Robolectric 4.0 replaces its old home-grown resource handling code with a direct adaptation of
88+
Android's resource handling code, using the full Android toolchain. This greatly improves fidelity
89+
to the behavior of a real Android device, but if your tests were relying on the quirks of the old
90+
code, you may need to fix your tests.
91+
92+
Some likely issues include:
93+
94+
!!! quote ""
95+
96+
> android.view.InflateException: Binary XML file line #3: Failed to resolve attribute at index
97+
> 17: TypedValue{t=0x2/d=0x7f01000e a=-1}
98+
99+
This happens when your [`Activity`][activity-documentation] is using a theme that lacks values
100+
for certain attributes used by layouts. Make sure you've specified an appropriate theme for your
101+
activities in your `AndroidManifest`.
102+
103+
[activity-documentation]: https://developer.android.com/reference/android/app/Activity
104+
[activity-finish-documentation]: https://developer.android.com/reference/android/app/Activity#finish()
105+
[androidx-test-apis]: https://developer.android.com/reference/androidx/test/package-summary
106+
[application-provider-get-application-context-documentation]: https://developer.android.com/reference/androidx/test/core/app/ApplicationProvider#getApplicationContext()
107+
[config-asset-dir-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#assetDir()
108+
[config-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html
109+
[config-manifest-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#manifest()
110+
[config-package-name-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#packageName()
111+
[config-resource-dir-javadoc]: javadoc/latest/org/robolectric/annotation/Config.html#resourceDir()
112+
[migrate-to-androidx]: https://developer.android.com/jetpack/androidx/migrate
113+
[motion-event-builder-documentation]: https://developer.android.com/reference/androidx/test/core/view/MotionEventBuilder
114+
[runtime-environment-application-javadoc]: javadoc/latest/org/robolectric/RuntimeEnvironment.html#application
115+
[shadow-alert-dialog-get-latest-alert-dialog-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowAlertDialog.html#getLatestAlertDialog()
116+
[shadow-dialog-get-latest-dialog-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowDialog.html#getLatestDialog()
117+
[shadow-of-looper-javadoc]: javadoc/latest/org/robolectric/Shadows.html#shadowOf(android.os.Looper)
118+
[shadow-popup-menu-get-latest-popup-menu-javadoc]: javadoc/latest/org/robolectric/shadows/ShadowPopupMenu.html#getLatestPopupMenu()
119+
[system-current-time-millis-documentation]: https://developer.android.com/reference/java/lang/System#currentTimeMillis()

‎mkdocs.yml‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ plugins:
7979
"activity-lifecycle.md": "androidx_test.md"
8080
"custom-shadows.md": "extending.md"
8181
"errorprone-refactorings.md": "automated-migration.md"
82+
"migrating.md": "automated-migration.md"
8283
"other-environments.md": "getting-started.md"
8384
- search:
8485

@@ -121,10 +122,9 @@ nav:
121122
- "Contributor Guidelines": contributing.md
122123
- "Shadows": extending.md
123124
- "Resources":
124-
- "Migration Guide": migrating.md
125-
- "GitHub": https://github.com/robolectric/robolectric/
126-
- "Release Notes": https://github.com/robolectric/robolectric/releases/
127-
- "Issues": https://github.com/robolectric/robolectric/issues/
125+
- "Automated Migration": automated-migration.md
126+
- "Upgrade to Robolectric 4.x": upgrade_to_version_4.md
127+
- "Upgrade to Robolectric 3.x": upgrade_to_version_3.md
128128
- "Javadoc":
129129
- "4.14": /javadoc/4.14/
130130
- "4.13": /javadoc/4.13/
@@ -141,6 +141,10 @@ nav:
141141
- "4.2": /javadoc/4.2/
142142
- "4.1": /javadoc/4.1/
143143
- "4.0": /javadoc/4.0/
144+
- "":
145+
- "GitHub": https://github.com/robolectric/robolectric/
146+
- "Releases": https://github.com/robolectric/robolectric/releases/
147+
- "Issues": https://github.com/robolectric/robolectric/issues/
144148
- "Blog":
145149
- blog/index.md
146150

0 commit comments

Comments
 (0)