0
# Robolectric
1

2
Robolectric is the industry-standard unit testing framework for Android that enables running tests in a simulated Android environment inside a JVM without requiring an emulator or device. It provides comprehensive Android API mocking, lifecycle management, and shadow implementations for 15 different Android versions (API levels 21-35), making tests run 10x faster than emulator-based tests.
3

4
## Package Information
5

6
- **Package Name**: org.robolectric:robolectric
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your `build.gradle`:
10

11
```gradle
12
testImplementation "org.robolectric:robolectric:4.15.1"
13
```
14

15
## Core Imports
16

17
```java
18
import org.robolectric.Robolectric;
19
import org.robolectric.RuntimeEnvironment;
20
import org.robolectric.RobolectricTestRunner;
21
import org.robolectric.annotation.Config;
22
import org.robolectric.annotation.LooperMode;
23
```
24

25
For component controllers:
26

27
```java
28
import org.robolectric.android.controller.ActivityController;
29
import org.robolectric.android.controller.ServiceController;
30
```
31

32
For shadow access:
33

34
```java
35
import static org.robolectric.Shadows.shadowOf;
36
```
37

38
## Basic Usage
39

40
```java
41
import org.junit.Test;
42
import org.junit.runner.RunWith;
43
import org.robolectric.Robolectric;
44
import org.robolectric.RobolectricTestRunner;
45
import org.robolectric.annotation.Config;
46

47
@RunWith(RobolectricTestRunner.class)
48
@Config(sdk = 28)
49
public class MyActivityTest {
50

51
    @Test
52
    public void testActivityCreation() {
53
        // Create and setup activity
54
        MyActivity activity = Robolectric.setupActivity(MyActivity.class);
55
        
56
        // Test activity behavior
57
        assertThat(activity).isNotNull();
58
        assertThat(activity.isFinishing()).isFalse();
59
    }
60

61
    @Test
62
    public void testButtonClick() {
63
        // Build activity with controller for lifecycle management
64
        ActivityController<MyActivity> controller = 
65
            Robolectric.buildActivity(MyActivity.class);
66
        MyActivity activity = controller.create().start().resume().get();
67

68
        // Find views and test interactions
69
        Button button = activity.findViewById(R.id.my_button);
70
        TextView textView = activity.findViewById(R.id.my_text);
71
        
72
        button.performClick();
73
        
74
        assertThat(textView.getText().toString()).isEqualTo("Button clicked!");
75
        
76
        // Clean up
77
        controller.pause().stop().destroy();
78
    }
79
}
80
```
81

82
## Architecture
83

84
Robolectric's architecture consists of several key components:
85

86
- **Test Runner**: `RobolectricTestRunner` provides the JUnit integration and test environment setup
87
- **Component Controllers**: Manage Android component lifecycles (Activity, Service, etc.)
88
- **Shadow System**: Comprehensive mock implementations of Android framework classes
89
- **Runtime Environment**: Simulates Android runtime with configurable device properties
90
- **Configuration System**: Annotations for controlling test behavior and Android simulation
91
- **Sandboxing**: Bytecode instrumentation for Android API interception and redirection
92

93
## Capabilities
94

95
### Test Runner and Configuration
96

97
Core test execution framework with comprehensive configuration options for SDK levels, device properties, application settings, and test behavior control.
98

99
```java { .api }
100
@RunWith(RobolectricTestRunner.class)
101
public class RobolectricTestRunner extends SandboxTestRunner {
102
    // JUnit test runner implementation
103
}
104

105
@Config(
106
    sdk = {28, 29, 30},
107
    application = MyApplication.class,
108
    qualifiers = "xlarge-land-mdpi"
109
)
110
public @interface Config {
111
    // Configuration annotation
112
}
113
```
114

115
[Test Runner and Configuration](./test-runner.md)
116

117
### Component Lifecycle Management
118

119
Factory methods and controller classes for managing Android component lifecycles including Activities, Services, ContentProviders, and Fragments with full lifecycle control.
120

121
```java { .api }
122
public class Robolectric {
123
    public static <T extends Activity> ActivityController<T> buildActivity(Class<T> activityClass);
124
    public static <T extends Activity> ActivityController<T> buildActivity(Class<T> activityClass, Intent intent);
125
    public static <T extends Service> ServiceController<T> buildService(Class<T> serviceClass);
126
    public static <T extends ContentProvider> ContentProviderController<T> buildContentProvider(Class<T> contentProviderClass);
127
}
128
```
129

130
[Component Lifecycle Management](./component-lifecycle.md)
131

132
### Runtime Environment Control
133

134
Runtime environment management for accessing the Application context, controlling device configuration, managing threading, and manipulating system properties.
135

136
```java { .api }
137
public class RuntimeEnvironment {
138
    public static Application getApplication();
139
    public static void setQualifiers(String newQualifiers);
140
    public static void setFontScale(float fontScale);
141
    public static int getApiLevel();
142
    public static String getQualifiers();
143
}
144
```
145

146
[Runtime Environment Control](./runtime-environment.md)
147

148
### Shadow System
149

150
Access to shadow implementations of Android framework classes that provide controllable mock behavior for testing, with the ability to extract shadow objects and control their behavior.
151

152
```java { .api }
153
public class Shadows {
154
    public static <T> T shadowOf(Object instance);
155
    // Generated methods for each Android class:
156
    // public static ShadowActivity shadowOf(Activity activity);
157
    // public static ShadowApplication shadowOf(Application application);
158
    // public static ShadowView shadowOf(View view);
159
}
160
```
161

162
[Shadow System](./shadow-system.md)
163

164
### Looper and Threading Control
165

166
Comprehensive control over Android's Looper and threading behavior with multiple modes for different testing scenarios, from legacy scheduler-based control to realistic paused execution.
167

168
```java { .api }
169
@LooperMode(LooperMode.Mode.PAUSED)
170
public @interface LooperMode {
171
    enum Mode {
172
        LEGACY,    // @Deprecated scheduler-based control
173
        PAUSED,    // Realistic paused execution (recommended)
174
        INSTRUMENTATION_TEST  // Separate test thread
175
    }
176
}
177
```
178

179
[Looper and Threading Control](./looper-threading.md)