Migration Guide

Automated Migration

Robolectric provides an automated migration tool 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 / Android Studio 3.2 or greater.

Update settings in your build.gradle:

android {
    compileSdkVersion 28
    testOptions.unitTests.includeAndroidResources = true
}

Put this in your gradle.properties:

android.enableUnitTestBinaryResources=true

If you have dependencies on com.android.support.test, switch them to androidx.test; see Migrating to AndroidX.

Deprecations

3.8	4.0
`ShadowApplication.getInstance()`	`RuntimeEnvironment.application`
`ShadowApplication.getLatestAlertDialog()`	`ShadowAlertDialog.getLatestAlertDialog()`
`ShadowApplication.getLatestDialog()`	`ShadowDialog.getLatestDialog()`
`ShadowApplication.getLatestPopupMenu()`	`ShadowPopupMenu.getLatestPopupMenu()`
`ShadowLooper.getShadowMainLooper()`	`shadowOf(Looper.getMainLooper())`

The automatic migration tool includes a migration to help with this.

@Config(manifest=...) is no longer supported when using binary resources mode. Instead, 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.
@Config(resourceDir=...), @Config(assetDir=...), and @Config(packageName...) are no longer supported in binary resources mode.

Improper Use of Shadows

Prior to 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()`
`ShadowSystemClock.currentTimeMillis();`	`SystemClock.currentTimeMillis();`

The automatic migration tool will fix most of these for you.

androidx.test

Robolectric 4.0 includes initial support for androidx.test APIs. We strongly recommend adding androidx.test:core:1.0.0 as a test dependency and using those APIs whenever possible rather than using Robolectric-specific APIs.

3.8	4.0
`RuntimeEnvironment.application`	`ApplicationProvider.getApplicationContext()`
`ShadowMotionEvent`	`MotionEventBuilder`

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 quirks of the old code, you may need to fix your tests.

Some likely issues include:

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 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 the manifest.

Migrating to 3.6

Previously Robolectric's Display and DisplayMetrics dimensions defaulted to 480px x 800px, regardless of screen size and density. Now they match the requested configuration, which defaults to 320dp x 470dp mdpi. Tests which rely on the old dimensions for layouts, pixel math, etc. can be modified for new dimensions, or by pinning them to the old size: @Config(qualifiers = "w480dp-h800dp").

3.5	3.6
`Shadow.newInstanceOf(Display.class)`	`ShadowDisplay.getDefaultDisplay()`

Migrating to 3.4

Dependencies

Robolectric tests should now be compiled with Java 8 and Android API 26.

PackageManager

We've change PackageManager simulation to follow the standard Shadow pattern as with other framework classes. You can use ShadowPackageManager where you previously used RobolectricPackageManager.

3.3 (was `@Deprecated`)	3.4
`org.robolectric.res.builder.RobolectricPackageManager`	`org.robolectric.shadows.ShadowPackageManager`
`RuntimeEnvironment.getRobolectricPackageManager()`	`shadowOf(RuntimeEnvironment.application.getPackageManager())`

If you were using RuntimeEnvironment.setRobolectricPackageManager() to install a custom PackageManager, you should move your custom behavior to a subclass of ShadowApplicationPackageManager and install it as a shadow (using @Config() and possibly @Implements(inheritImplementationMethods=true)) instead.

ActivityController.attach()

The deprecated and redundant attach() method has been removed from ActivityController, FragmentController, and ServiceController. To migrate, simply remove calls to this method.

Other Stuff

Because SharedPreferences now uses real Android framework code, Mockito mocks and spies can lead to tests hanging. Rather than spying on SharedPreferences, just assert against its state.

Migrating to 3.3

Moved classes

To simplify classloader logic and clean up packages, some classes have moved. The old class locations are @Deprecated and will be removed in 3.4.

3.2 (now `@Deprecated`)	3.3
`org.robolectric.internal.Shadow`	`org.robolectric.shadow.api.Shadow`
`org.robolectric.internal.ShadowExtractor.extract()`	`org.robolectric.shadow.api.Shadow.extract()`
`org.robolectric.util.ActivityController`	`org.robolectric.android.controller.ActivityController`
`org.robolectric.util.ContentProviderController`	`org.robolectric.android.controller.ContentProviderController`
`org.robolectric.util.FragmentController`	`org.robolectric.android.controller.FragmentController`
`org.robolectric.util.IntentServiceController`	`org.robolectric.android.controller.IntentServiceController`
`org.robolectric.util.ServiceController`	`org.robolectric.android.controller.ServiceController`
`org.robolectric.util.AccessibilityUtil`	`org.robolectric.android.AccessibilityUtil`
`org.robolectric.util.ApplicationTestUtil`	`org.robolectric.android.ApplicationTestUtil`
`org.robolectric.res.builder.StubPackageManager`	`org.robolectric.android.StubPackageManager` (but don't use unless you must)
`org.robolectric.res.builder.XmlResourceParserImpl`	`org.robolectric.android.XmlResourceParserImpl` (but don't use unless you must)
`org.robolectric.internal.fakes.RoboCharsets`	`org.robolectric.android.fakes.RoboCharsets` (but don't use unless you must)
`org.robolectric.internal.fakes.RoboExtendedResponseCache`	`org.robolectric.android.fakes.RoboExtendedResponseCache` (but don't use unless you must)
`org.robolectric.util.concurrent.RoboExecutorService`	`org.robolectric.android.util.concurrent.RoboExecutorService` (but don't use unless you must)

PackageManager

We have begun the process of switching from using a subclass of PackageManager towards PackageManager being implemented by a standard shadow, as we do for the rest of the framework. This is for a number of reasons:

It is more consistent with the way other framework code is handled.
A shadow will allow users' tests to build against any version of Android.
Switching to a shadow will allow us to defer parsing the manifest until the test or code under test makes calls to the PackageManager.

This should all be backwards compatible for the 3.3 release but now you can start migrating your code.

Before, the Robolectric class DefaultPackageManager implemented all PackageManager functionality. If you wanted to change any of its behavior, you'd extend DefaultPackageManager (or StubPackageManager) and override whichever methods you liked. Test-related setup was accomplished by calling RuntimeEnvironment.getRobolectricPackageManager(), which had extra methods for modifying its behavior.

As of 3.3, Robolectric uses the normal Android ApplicationPackageManager, and shadows all of its methods, causing it to delegate to an instance of DefaultPackageManager, which works as before. You can still replace it with your own subclass of PackageManager if you like, but that's deprecated. Instead of doing that, put your custom behavior in a subclass of ShadowApplicationPackageManager. For test-related setup, you can still access it through RuntimeEnvironment.getRobolectricPackageManager(), but you should start using shadowOf(packageManager) instead. Note that we've implemented quite a bit more of PackageManager, so you might not need any custom code any longer.

Starting with 3.4, DefaultPackageManager will be removed and its functionality will be moved into ShadowApplicationPackageManager.

3.2 (now `@Deprecated`)	3.3
`RobolectricPackageManager rpm` `= RuntimeEnvironment.getRobolectricPackageManager();`	`ShadowPackageManager shadowPackageManager` `= shadowOf(context.getPackageManager());`
`PackageManager packageManager` `= RuntimeEnvironment.getPackageManager();`	`// Prefer Android Framework APIs where possible.` `PackageManager packageManager = context.getPackageManager();`
`RuntimeEnvironment.setRobolectricPackageManager(myCustomPackageManager);`	Use a custom shadow instead! See below.

Replace subclasses of DefaultPackageManager a custom shadow (and be a good citizen and contribute your enhancements upstream :-)

@Implements(value = ApplicationPackageManager.class, inheritImplementationMethods = true)
class MyCustomPackageManager extends ShadowApplicationPackageManager {
}

If you are using a custom subclass of DefaultPackageManager to implement functionality missing in Robolectric, check again as part of this work we've added support for a bunch more widely-used PackageManager features and it might be now possible to completely remove your custom subclass.

Deprecated Classes & Methods

3.2 (now `@Deprecated`)	3.3
`org.robolectric.res.builder.RobolectricPackageManager`	`org.robolectric.shadows.ShadowPackageManager`
`RuntimeEnvironment.getRobolectricPackageManager()`	`shadowOf(RuntimeEnvironment.application.getPackageManager())`
`shadowOf(imageView).getImageResourceId()`	`shadowOf(imageView.getDrawable).getCreatedFromResId()`
`shadowOf(notification).getProgressBar().isIndeterminate()`	`shadowOf(notification).isIndeterminate()`

The following methods and classes are deprecated will be removed in 3.4:

RuntimeEnvironment.getPackageManager()
RuntimeEnvironment.getRobolectricPackageManager()
RuntimeEnvironment.setRobolectricPackageManager()
DefaultPackageManager
StubPackageManager
RobolectricPackageManager

New Gradle integration

Starting with Robolectric 3.3 + Android Studio 3.0 alpha 5 we've included better integration with the tool chain. Resources, assets and AndroidManifest.xml are treated as first class citizens and processed by the build system for correctness, performance and stability between releases. Read more here.

Migrating to 3.2

Programmatic Configuration

If you were providing custom configuration by subclassing and overriding methods on RobolectricTestRunner, you'll need to make some changes.

RobolectricTestRunner.getConfigProperties() has moved to ConfigMerger.getConfigProperties(String). But what you probably actually want to do is override RobolectricTestRunner.buildGlobalConfig().

Old code:

class MyTestRunner extends RobolectricTestRunner {
  @Override protected Properties getConfigProperties() {
    Properties props = new Properties();
    props.setProperty("sdk", "23");
    return props;
  }
}

New code:

class MyTestRunner extends RobolectricTestRunner {
  @Override protected Config buildGlobalConfig() {
    return new Config.Builder().setSdk(23).build();
  }
}

Package-Level Configuration

If you are using robolectric.properties file to configure all tests, the expected location of the file has been changed.

3.1: src/test/resources/robolectric.properties
3.2: src/test/resources/your/package/path/robolectric.properties

Migrating to 3.1

Changes

To construct Android components such as Activity, Service and ContentProvider classes you must now use the Robolectric APIs such as Robolectric.buildService(), Robolectric.buildActivity() or Robolectric.buildContentProvider() or the setup*() variants; you should not create new instances of these classes yourself. Calling these methods will create an instance of the component and attach its base context. This is now necessary as we've removed code shadowing Context and ContextWrapper in favor of using real framework code to improve fidelity.

Robolectric.buildService(MyService.class).create().get();
Robolectric.setupContentProvider(MyContentProvider.class);

We've removed shadow methods where they duplicate the functionality of the Android APIs. In general, prefer calling Android framework APIs over Robolectric shadows where possible.

3.0	3.1
`ShadowApplication.getInstance().getContentResolver()`	`RuntimeEnvironment.application.getContentResolver()`
`ShadowApplication.getInstance().getPackageManager()`	`RuntimeEnvironment.application.getPackageManager()`
`ShadowApplication.getInstance().getResources()`	`RuntimeEnvironment.application.getResources()`
`ShadowApplication.getInstance().getString()`	`RuntimeEnvironment.application.getString()`
`ShadowApplication.getInstance().resetResources()`	`RuntimeEnvironment.application.resetResources()`
`ShadowApplication.getInstance().getAssets()`	`RuntimeEnvironment.application.getAssets()`
`ShadowPreferenceManager.getDefaultSharedPreferences()`	`PreferenceManager.getDefaultSharedPreferences()`
`shadowOf(shadowOf(notification).getStyle()).getSummaryText()`	`shadowOf(notification).getContentText()`

RoboMenu now requires a context passed into its constructor. Previously it was internally using RuntimeEnvironment.application which you can use as a sensible default.
.equals() and .hashCode() methods have been removed from shadows to stop them incorrectly providing an alternative equality of the shadowed object. For example, Intent.equals() now behaves as the framework method. Instead of relying on an generically shadowed equals() method with a vague equality rule, prefer to make assertions on specific fields of interest to the test. We recommend using https://github.com/square/assertj-android to make assertions clear.
Custom shadows now require the public access modifier on methods in the shadow class.

3.1.1 Changes

RoboAttributeSet is deprecated and uses should be replaced with Robolectric.buildAttributeSet().
RobolectricGradleTestRunner is deprecated and uses should be replaced with RobolectricTestRunner.

Migrating to 3.0

New Features

Support for API 19 (KitKat)
Support for API 21 (Lollipop)
Custom test runner for Gradle / Android Studio:

@RunWith(RobolectricGradleTestRunner.class)
@Config(constants = BuildConfig.class)

Major Changes

2.4	3.0
`Robolectric.application`	`RuntimeEnvironment.application`
`Robolectric.shadowOf`	`Shadows.shadowOf`
`Robolectric.Reflection.setFinalStaticField`	`ReflectionHelpers.setStaticField`
`org.robolectric.Robolectric.<xxx>Looper`	`org.robolectric.shadows.ShadowLooper.<xxx>Looper`
`org.robolectric.Robolectric.getBackgroundScheduler`	`org.robolectric.Robolectric.getBackgroundThreadScheduler`
`org.robolectric.Robolectric.runBackgroundTasks`	`org.robolectric.Robolectric.getBackgroundThreadScheduler().advanceBy(0)` (also `org.robolectric.Robolectric.flushBackgroundThreadScheduler` will run delayed background tasks too)
`org.robolectric.Robolectric.getUiThreadScheduler`	`org.robolectric.Robolectric.getForegroundThreadScheduler`
`org.robolectric.Robolectric.runUiThreadTasks`	`org.robolectric.shadows.ShadowLooper.runUiThreadTasks`
`org.robolectric.Robolectric.runUiThreadTasksIncludingDelayedTasks`	`org.robolectric.shadows.ShadowLooper.runUiThreadTasksIncludingDelayedTasks` or `org.robolectric.Robolectric.flushForegroundThreadScheduler`
`org.robolectric.Robolectric.getShadowApplication`	`org.robolectric.shadows.ShadowApplication.getInstance`
`FragmentTestUtil.startFragment`(v4/v11)	`SupportFragmentTestUtil.startFragment` (v4) `FragmentTestUtil.startFragment` (v11)
`org.robolectric.tester.android.view.TestMenuItem`	`org.robolectric.fakes.RoboMenuItem`
`ActivityController.of`	`Robolectric.buildActivity`
`org.robolectric.Config.properties`	`robolectric.properties`
`@Config(emulateSdk=...)` / `@Config(reportSdk=...)`	`@Config(sdk=...)`
`org.robolectric.shadows.ShadowHandler`	`org.robolectric.shadows.ShadowLooper`
`org.robolectric.shadows.ShadowSettings.SettingsImpl`	`org.robolectric.shadows.ShadowSettings.ShadowSystem`
`Robolectric.packageManager = instance`	`RuntimeEnvironment.setRobolectricPackageManager(instance)`
`org.robolectric.res.builder.RobolectricPackageManager` changed from `class` to `interface`	`org.robolectric.res.builder.DefaultPackageManager`
`org.robolectric.shadows.ShadowMenuInflater`	?
`org.robolectric.Robolectric.clickOn`	`org.robolectric.shadows.ShadowView.clickOn`

Robolectric.shadowOf_ has been removed. Similar functionality exists in ShadowExtractor.extract.

Modules

Note: Shadows for non-core Android classes has moved out of the main Robolectric module. If you want to use those shadows, you'll need to include the requisite module.

org.robolectric:robolectric:3.0

Main "core" module for Robolectric 3.0.

testCompile 'org.robolectric:robolectric:3.0'

Some of the shadows in Robolectric have been split out into separate modules to reduce the number of transitive dependencies imposed on projects using Robolectric. If you want to use any of these shadows, simply add the the artifact below to your build.

org.robolectric:shadows-support-v4:3.0

Shadows for classes in the android support-v4 library.

testCompile 'org.robolectric:shadows-support-v4:3.0'

org.robolectric:shadows-httpclient:3.0

Shadows for classes in Apache HTTP client. This includes methods like Robolectric.getLatestSentHttpRequest. These methods have moved to FakeHttp.getLatestSentHttpRequest.

testCompile 'org.robolectric:shadows-httpclient:3.0'

org.robolectric:shadows-maps:3.0

Shadows for classes in Google maps.

testCompile 'org.robolectric:shadows-maps:3.0'