Robolectric is the industry-standard unit testing framework for Android. With Robolectric, your tests run in a simulated Android environment inside a JVM, without the overhead and flakiness of an emulator. Robolectric tests routinely run 10x faster than those on cold-started emulators.

Robolectric supports running unit tests for 14 different versions of Android, ranging from Nougat (API level 24) to Cinnamon Bun (API level 37).

Usage

To use Robolectric in your project, simply add the necessary dependencies to your module's build.gradle/build.gradle.kts file:

testImplementation("junit:junit:4.13.2")
testImplementation("org.robolectric:robolectric:4.17")
testImplementation("androidx.test.ext:junit:1.3.0")

Then you can write your tests using Robolectric, like the following example:

@RunWith(AndroidJUnit4.class)
public class MyActivityTest {
  @Test
  public void clickingButton_shouldChangeMessage() {
    try (ActivityController<MyActivity> controller = Robolectric.buildActivity(MyActivity.class)) {
      controller.setup(); // Moves the Activity to the RESUMED state
      MyActivity activity = controller.get();

      activity.findViewById(R.id.button).performClick();
      assertEquals(((TextView) activity.findViewById(R.id.text)).getText(), "Robolectric Rocks!");
    }
  }
}

For more information about how to install and use Robolectric in your project, extend its functionality, and join the community of contributors, you can visit robolectric.org.

Building and Contributing

Robolectric is built using Gradle. Both Android Studio and IntelliJ can import the top-level build.gradle.kts file and will automatically generate their project files from it.

To get Robolectric up and running on your machine, check out this guide.

To get a high-level overview of Robolectric's architecture, check out robolectric.org.

Development model

Robolectric is actively developed in several locations. The primary location is this GitHub repository, which is considered the source-of-truth for Robolectric code. It is where contributions from the broader Android developer community occur. There is also an active development tree of Robolectric internally at Google, where contributions from first-party Android developers occur. By having a development tree of Robolectric internally at Google, it enables first-party Android developers to more efficiently make contributions to Robolectric. This tree is synced directly to the google branch every time a change occurs using the Copybara code sync tool. Bidirectional merges of this branch and the master branch occur regularly.

Robolectric also has usage in the Android platform via the external/robolectric repo project. Contributions to this source tree are typically related to new SDK support and evolving platform APIs. Changes from this branch are upstreamed to the internal Robolectric tree at Google, which eventually propagate to the GitHub branches.

Although complex, this distributed development model enables Android developers in different environments to use and contribute to Robolectric, while allowing changes to eventually make their way to public Robolectric releases.

[!TIP] You can trigger the sync_google_master workflow to create a PR to sync the google branch into master.

Using Snapshots

If you would like to live on the bleeding edge, you can try running against a snapshot build. Keep in mind that snapshots represent the most recent changes on the master and may contain bugs.

build.gradle

repositories {
    maven { url "https://central.sonatype.com/repository/maven-snapshots/" }
}

dependencies {
    testImplementation "org.robolectric:robolectric:4.19-SNAPSHOT"
}

Coding agents

We encourage using coding agents, both to write contributions and to review them.

Robolectric has historically been a difficult project to understand, because it relies on many low-level JVM APIs, such as bytecode instrumentation and custom class loaders. Agents help contributors work through that complexity and make high-quality contributions.

The complexity of the project has also limited what we could take on with the time and people available. With agents, we can take on more ambitious projects for Robolectric.

One goal is to make Robolectric as useful as possible to coding agents, so that iterating on Android projects is quick and efficient.

Before sending a pull request, review the code yourself and make sure it is sensible and well-formed.

AGENTS.md has the instructions for coding agents working in this repository.