0
# Component Lifecycle Management
1

2
Factory methods and controller classes for managing Android component lifecycles with precise control over creation, lifecycle transitions, and cleanup.
3

4
## Capabilities
5

6
### Activity Management
7

8
Factory methods and controller for managing Activity lifecycle with full control over creation, lifecycle states, and configuration changes.
9

10
```java { .api }
11
public class Robolectric {
12
    /**
13
     * Creates ActivityController for the given activity class.
14
     * Consider using androidx.test.core.app.ActivityScenario instead for higher-level APIs.
15
     */
16
    public static <T extends Activity> ActivityController<T> buildActivity(Class<T> activityClass);
17
    
18
    /**
19
     * Creates ActivityController with intent. Note: activity class is not determined by intent.
20
     * Consider using androidx.test.core.app.ActivityScenario instead for higher-level APIs.
21
     */
22
    public static <T extends Activity> ActivityController<T> buildActivity(Class<T> activityClass, Intent intent);
23
    
24
    /**
25
     * Creates ActivityController with intent and activity options.
26
     * Only Display ID is currently supported in options bundle.
27
     * Consider using androidx.test.core.app.ActivityScenario instead for higher-level APIs.
28
     */
29
    public static <T extends Activity> ActivityController<T> buildActivity(
30
        Class<T> activityClass, 
31
        Intent intent, 
32
        Bundle activityOptions);
33
    
34
    /**
35
     * @deprecated Use androidx.test.core.app.ActivityScenario instead
36
     * Simulates starting activity and returns its reference.
37
     */
38
    @Deprecated
39
    public static <T extends Activity> T setupActivity(Class<T> activityClass);
40
}
41
```
42

43
### ActivityController<T>
44

45
Low-level controller providing precise Activity lifecycle management. Implements AutoCloseable for resource cleanup.
46

47
```java { .api }
48
/**
49
 * ActivityController provides low-level APIs to control activity's lifecycle.
50
 * Using ActivityController directly is discouraged - use ActivityScenario instead.
51
 */
52
public class ActivityController<T extends Activity> 
53
    extends ComponentController<ActivityController<T>, T> 
54
    implements AutoCloseable {
55
    
56
    // Lifecycle state management
57
    public ActivityController<T> create();
58
    public ActivityController<T> create(Bundle savedInstanceState);
59
    public ActivityController<T> postCreate(Bundle savedInstanceState);
60
    public ActivityController<T> start();
61
    public ActivityController<T> restoreInstanceState(Bundle savedInstanceState);
62
    public ActivityController<T> resume();
63
    public ActivityController<T> postResume();
64
    public ActivityController<T> visible();
65
    public ActivityController<T> windowFocusChanged(boolean hasFocus);
66
    public ActivityController<T> userLeaving();
67
    public ActivityController<T> pause();
68
    public ActivityController<T> saveInstanceState(Bundle outState);
69
    public ActivityController<T> stop();
70
    public ActivityController<T> restart();
71
    public ActivityController<T> destroy();
72
    
73
    // Convenience methods
74
    public ActivityController<T> setup();  // create().start().postCreate().resume().visible()
75
    public T get();  // Returns the Activity instance
76
    
77
    // Configuration and intent handling
78
    public ActivityController<T> configurationChange(Configuration newConfiguration);
79
    public ActivityController<T> newIntent(Intent intent);
80
    public ActivityController<T> recreate();
81
    
82
    // AutoCloseable implementation
83
    public void close();
84
}
85
```
86

87
**Usage Example:**
88

89
```java
90
// Basic lifecycle control
91
ActivityController<MyActivity> controller = Robolectric.buildActivity(MyActivity.class);
92
MyActivity activity = controller.create().start().resume().get();
93

94
// Test activity state
95
assertThat(activity.isFinishing()).isFalse();
96

97
// Simulate configuration change
98
Configuration newConfig = new Configuration();
99
newConfig.orientation = Configuration.ORIENTATION_LANDSCAPE;
100
controller.configurationChange(newConfig);
101

102
// Complete lifecycle
103
controller.pause().stop().destroy();
104

105
// Or use try-with-resources for automatic cleanup
106
try (ActivityController<MyActivity> controller = Robolectric.buildActivity(MyActivity.class)) {
107
    MyActivity activity = controller.setup().get();
108
    // Test activity
109
} // Automatically calls controller.close()
110
```
111

112
### Service Management
113

114
Factory methods and controller for managing Service and IntentService lifecycles.
115

116
```java { .api }
117
public class Robolectric {
118
    /** Creates ServiceController for the given service class */
119
    public static <T extends Service> ServiceController<T> buildService(Class<T> serviceClass);
120
    
121
    /** Creates ServiceController with intent */
122
    public static <T extends Service> ServiceController<T> buildService(Class<T> serviceClass, Intent intent);
123
    
124
    /** Creates and sets up service (calls create()) */
125
    public static <T extends Service> T setupService(Class<T> serviceClass);
126
    
127
    /** Creates IntentServiceController for the given service class */
128
    public static <T extends IntentService> IntentServiceController<T> buildIntentService(Class<T> serviceClass);
129
    
130
    /** Creates IntentServiceController with intent */
131
    public static <T extends IntentService> IntentServiceController<T> buildIntentService(Class<T> serviceClass, Intent intent);
132
    
133
    /** Creates and sets up intent service */
134
    public static <T extends IntentService> T setupIntentService(Class<T> serviceClass);
135
}
136
```
137

138
### ServiceController<T>
139

140
Controller for managing Service lifecycle including binding and command handling.
141

142
```java { .api }
143
/**
144
 * Controller for managing Service lifecycle.
145
 */
146
public class ServiceController<T extends Service> 
147
    extends ComponentController<ServiceController<T>, T> {
148
    
149
    // Basic lifecycle
150
    public ServiceController<T> create();
151
    public ServiceController<T> destroy();
152
    public T get();
153
    
154
    // Binding lifecycle  
155
    public ServiceController<T> bind();
156
    public ServiceController<T> unbind();
157
    public ServiceController<T> rebind();
158
    
159
    // Command handling
160
    public ServiceController<T> startCommand(int flags, int startId);
161
    public ServiceController<T> startCommand(Intent intent, int flags, int startId);
162
}
163
```
164

165
### IntentServiceController<T>
166

167
Specialized controller for IntentService lifecycle management.
168

169
```java { .api }
170
/**
171
 * Controller for managing IntentService lifecycle.
172
 */
173
public class IntentServiceController<T extends IntentService> 
174
    extends ComponentController<IntentServiceController<T>, T> {
175
    
176
    public IntentServiceController<T> create();
177
    public IntentServiceController<T> destroy();  
178
    public T get();
179
    
180
    // IntentService automatically handles intents in background thread
181
}
182
```
183

184
**Usage Example:**
185

186
```java
187
// Service lifecycle
188
ServiceController<MyService> controller = Robolectric.buildService(MyService.class);
189
MyService service = controller.create().get();
190

191
// Test service startup
192
assertThat(service).isNotNull();
193

194
// Simulate binding
195
IBinder binder = controller.bind().get().onBind(new Intent());
196
assertThat(binder).isNotNull();
197

198
// Start command
199
Intent intent = new Intent("my.action");
200
controller.startCommand(intent, 0, 1);
201

202
// Cleanup
203
controller.unbind().destroy();
204
```
205

206
### ContentProvider Management
207

208
Factory methods and controller for ContentProvider lifecycle management.
209

210
```java { .api }
211
public class Robolectric {
212
    /** Creates ContentProviderController for the given provider class */
213
    public static <T extends ContentProvider> ContentProviderController<T> buildContentProvider(Class<T> contentProviderClass);
214
    
215
    /** Creates and sets up content provider */
216
    public static <T extends ContentProvider> T setupContentProvider(Class<T> contentProviderClass);
217
    
218
    /** Creates and sets up content provider with authority */
219
    public static <T extends ContentProvider> T setupContentProvider(Class<T> contentProviderClass, String authority);
220
}
221
```
222

223
### ContentProviderController<T>
224

225
Controller for managing ContentProvider lifecycle with authority configuration.
226

227
```java { .api }
228
/**
229
 * Controller for managing ContentProvider lifecycle.
230
 */
231
public class ContentProviderController<T extends ContentProvider> 
232
    extends ComponentController<ContentProviderController<T>, T> {
233
    
234
    public ContentProviderController<T> create();
235
    public ContentProviderController<T> create(String authority);
236
    public ContentProviderController<T> shutdown();
237
    public T get();
238
}
239
```
240

241
### Fragment Management (Deprecated)
242

243
Factory methods for Fragment controllers. Use androidx FragmentScenario instead.
244

245
```java { .api }
246
public class Robolectric {
247
    /**
248
     * @deprecated Native Fragments deprecated in Android P. Use androidx.fragment.app.testing.FragmentScenario
249
     */
250
    @Deprecated
251
    public static <T extends Fragment> FragmentController<T> buildFragment(Class<T> fragmentClass);
252
    
253
    /** 
254
     * @deprecated Use FragmentScenario instead
255
     */
256
    @Deprecated  
257
    public static <T extends Fragment> FragmentController<T> buildFragment(Class<T> fragmentClass, Bundle arguments);
258
    
259
    /**
260
     * @deprecated Bad practice to depend on specific activity. Use FragmentScenario instead
261
     */
262
    @Deprecated
263
    public static <T extends Fragment> FragmentController<T> buildFragment(
264
        Class<T> fragmentClass, 
265
        Class<? extends Activity> activityClass);
266
    
267
    /** @deprecated Use FragmentScenario instead */
268
    @Deprecated
269
    public static <T extends Fragment> FragmentController<T> buildFragment(Class<T> fragmentClass, Intent intent);
270
    
271
    /** @deprecated Use FragmentScenario instead */
272
    @Deprecated  
273
    public static <T extends Fragment> FragmentController<T> buildFragment(
274
        Class<T> fragmentClass, 
275
        Intent intent, 
276
        Bundle arguments);
277
    
278
    /** @deprecated Use FragmentScenario instead */
279
    @Deprecated
280
    public static <T extends Fragment> FragmentController<T> buildFragment(
281
        Class<T> fragmentClass, 
282
        Class<? extends Activity> activityClass, 
283
        Intent intent);
284
    
285
    /** @deprecated Use FragmentScenario instead */
286
    @Deprecated
287
    public static <T extends Fragment> FragmentController<T> buildFragment(
288
        Class<T> fragmentClass, 
289
        Class<? extends Activity> activityClass, 
290
        Bundle arguments);
291
    
292
    /** @deprecated Use FragmentScenario instead */
293
    @Deprecated
294
    public static <T extends Fragment> FragmentController<T> buildFragment(
295
        Class<T> fragmentClass, 
296
        Class<? extends Activity> activityClass, 
297
        Intent intent, 
298
        Bundle arguments);
299
}
300
```
301

302
### BackupAgent Management
303

304
Factory methods and controller for BackupAgent lifecycle management.
305

306
```java { .api }
307
public class Robolectric {
308
    /** Creates BackupAgentController for the given backup agent class */
309
    public static <T extends BackupAgent> BackupAgentController<T> buildBackupAgent(Class<T> backupAgentClass);
310
    
311
    /** Creates and sets up backup agent */
312
    public static <T extends BackupAgent> T setupBackupAgent(Class<T> backupAgentClass);
313
}
314
```
315

316
### BackupAgentController<T>
317

318
Controller for managing BackupAgent lifecycle.
319

320
```java { .api }
321
/**
322
 * Controller for managing BackupAgent lifecycle.
323
 */
324
public class BackupAgentController<T extends BackupAgent> 
325
    extends ComponentController<BackupAgentController<T>, T> {
326
    
327
    public BackupAgentController<T> create();
328
    public T get();
329
}
330
```
331

332
### ComponentController<C, T>
333

334
Abstract base class for all component controllers providing common functionality.
335

336
```java { .api }
337
/**
338
 * Base class for all component controllers.
339
 */
340
public abstract class ComponentController<C extends ComponentController<C, T>, T> {
341
    protected final C myself;
342
    protected T component;
343
    protected final ShadowLooper shadowMainLooper;
344
    protected Intent intent;
345
    protected boolean attached;
346
    
347
    public ComponentController(T component);
348
    public ComponentController(T component, Intent intent);
349
    
350
    public abstract T get();
351
}
352
```
353

354
## Best Practices
355

356
1. **Use Modern Alternatives**: Prefer `ActivityScenario` and `FragmentScenario` from AndroidX Test for higher-level, more maintainable tests.
357

358
2. **Proper Lifecycle Management**: Always call lifecycle methods in the correct order that matches Android framework behavior.
359

360
3. **Resource Cleanup**: Use try-with-resources or explicit cleanup to avoid memory leaks in tests.
361

362
4. **Thread Safety**: Component creation and lifecycle methods must be called on the main thread.
363

364
5. **Configuration Changes**: Use `configurationChange()` instead of recreating activities to test configuration changes properly.