0
# Test Runner and Configuration
1

2
Core test execution framework providing JUnit integration and comprehensive configuration options for controlling Robolectric's Android simulation behavior.
3

4
## Capabilities
5

6
### RobolectricTestRunner
7

8
JUnit test runner that loads and runs tests in a sandboxed Android environment, providing the foundation for all Robolectric tests.
9

10
```java { .api }
11
/**
12
 * Loads and runs a test in a SandboxClassLoader to provide Android runtime simulation.
13
 * Use as @RunWith(RobolectricTestRunner.class) on test classes.
14
 */
15
public class RobolectricTestRunner extends SandboxTestRunner {
16
    // Constructor creates sandboxed test environment
17
    public RobolectricTestRunner(Class<?> testClass) throws InitializationError;
18
}
19
```
20

21
**Usage Example:**
22

23
```java
24
@RunWith(RobolectricTestRunner.class)
25
public class MyAndroidTest {
26
    @Test
27
    public void testSomething() {
28
        // Test code runs in Android simulation
29
    }
30
}
31
```
32

33
### ParameterizedRobolectricTestRunner
34

35
Parameterized test runner for running the same test across multiple configurations or data sets.
36

37
```java { .api }
38
/**
39
 * Parameterized test runner extending RobolectricTestRunner.
40
 * Allows running tests with different parameters or configurations.
41
 */
42
public class ParameterizedRobolectricTestRunner extends RobolectricTestRunner {
43
    public ParameterizedRobolectricTestRunner(Class<?> testClass) throws InitializationError;
44
}
45
```
46

47
### @Config Annotation
48

49
Primary configuration annotation for controlling test behavior at the class or method level.
50

51
```java { .api }
52
/**
53
 * Configuration settings that can be used on a per-class or per-test basis.
54
 * Controls Android simulation parameters and test environment setup.
55
 */
56
@Documented
57
@Inherited
58
@Retention(RetentionPolicy.RUNTIME)
59
@Target({ElementType.TYPE, ElementType.METHOD})
60
public @interface Config {
61
    
62
    /** Android SDK levels to emulate. Will also be set as Build.VERSION.SDK_INT */
63
    int[] sdk() default {};
64
    
65
    /** Minimum Android SDK level for multi-version tests */
66
    int minSdk() default -1;
67
    
68
    /** Maximum Android SDK level for multi-version tests */
69
    int maxSdk() default -1;
70
    
71
    /** Font scale factor (default 1.0f). Users can adjust this in Android U+ */
72
    float fontScale() default 1.0f;
73
    
74
    /** 
75
     * @deprecated Android manifest file path
76
     * Use build system integration instead
77
     */
78
    @Deprecated
79
    String manifest() default "--default";
80
    
81
    /** Application class to use, overrides AndroidManifest.xml setting */
82
    Class<? extends Application> application() default DefaultApplication.class;
83
    
84
    /** 
85
     * @deprecated Java package name for R.class
86
     * Override applicationId in build system instead
87
     */
88
    @Deprecated
89
    String packageName() default "";
90
    
91
    /** 
92
     * Device configuration qualifiers like "fr-normal-port-hdpi"
93
     * If prefixed with '+', overlays on broader-scoped qualifiers
94
     */
95
    String qualifiers() default "";
96
    
97
    /** 
98
     * @deprecated Resource directory path
99
     * Use build system integration instead
100
     */
101
    @Deprecated
102
    String resourceDir() default "res";
103
    
104
    /** 
105
     * @deprecated Asset directory path  
106
     * Use build system integration instead
107
     */
108
    @Deprecated
109
    String assetDir() default "assets";
110
    
111
    /** Additional shadow classes to enable */
112
    Class<?>[] shadows() default {};
113
    
114
    /** Additional instrumented packages */
115
    String[] instrumentedPackages() default {};
116
    
117
    /** 
118
     * @deprecated Android library dependencies
119
     * Use build system integration instead
120
     */
121
    @Deprecated
122
    String[] libraries() default {};
123
}
124
```
125

126
**Configuration Constants:**
127

128
```java { .api }
129
public @interface Config {
130
    // Special values
131
    String NONE = "--none";
132
    String DEFAULT_VALUE_STRING = "--default";
133
    int DEFAULT_VALUE_INT = -1;
134
    
135
    // SDK constants
136
    int ALL_SDKS = -2;      // Run on all supported SDKs
137
    int TARGET_SDK = -3;    // Use target SDK
138
    int OLDEST_SDK = -4;    // Use oldest supported SDK  
139
    int NEWEST_SDK = -5;    // Use newest supported SDK
140
    
141
    // Default configuration values
142
    String DEFAULT_MANIFEST_NAME = "AndroidManifest.xml";
143
    String DEFAULT_RES_FOLDER = "res";
144
    String DEFAULT_ASSET_FOLDER = "assets";
145
    Class<? extends Application> DEFAULT_APPLICATION = DefaultApplication.class;
146
}
147
```
148

149
**Usage Examples:**
150

151
```java
152
// Single SDK version
153
@Config(sdk = 28)
154
public class MyTest { }
155

156
// Multiple SDK versions
157
@Config(sdk = {28, 29, 30})
158
public class CrossVersionTest { }
159

160
// SDK range
161
@Config(minSdk = 21, maxSdk = 30)
162
public class RangeTest { }
163

164
// Device configuration
165
@Config(qualifiers = "xlarge-land-mdpi")
166
public class TabletTest { }
167

168
// Custom application
169
@Config(application = MyCustomApplication.class)
170
public class CustomAppTest { }
171

172
// Additional shadows
173
@Config(shadows = {MyCustomShadow.class})
174
public class CustomShadowTest { }
175

176
// Method-level override
177
@Config(sdk = 28)
178
public class MyTest {
179
    @Config(sdk = 30)  // Overrides class-level config
180
    @Test
181
    public void newSdkTest() { }
182
}
183
```
184

185
### Config.Builder
186

187
Programmatic configuration builder for creating Config instances dynamically.
188

189
```java { .api }
190
/**
191
 * Builder for creating Config instances programmatically.
192
 * Useful for dynamic configuration or test parameterization.
193
 */
194
public static class Builder {
195
    public Builder();
196
    public Builder(Config config);
197
    
198
    public Builder setSdk(int... sdk);
199
    public Builder setMinSdk(int minSdk);
200
    public Builder setMaxSdk(int maxSdk);
201
    public Builder setManifest(String manifest);
202
    public Builder setQualifiers(String qualifiers);
203
    public Builder setFontScale(float fontScale);
204
    
205
    /** @deprecated Use build system integration */
206
    @Deprecated
207
    public Builder setPackageName(String packageName);
208
    
209
    /** @deprecated Use build system integration */
210
    @Deprecated  
211
    public Builder setResourceDir(String resourceDir);
212
    
213
    /** @deprecated Use build system integration */
214
    @Deprecated
215
    public Builder setAssetDir(String assetDir);
216
    
217
    public Builder setShadows(Class<?>... shadows);
218
    public Builder setInstrumentedPackages(String... instrumentedPackages);
219
    public Builder setApplication(Class<? extends Application> application);
220
    
221
    /** @deprecated Use build system integration */
222
    @Deprecated
223
    public Builder setLibraries(String... libraries);
224
    
225
    public Builder overlay(Config overlayConfig);
226
    public Implementation build();
227
    
228
    public static Builder defaults();
229
    public static boolean isDefaultApplication(Class<? extends Application> clazz);
230
}
231
```
232

233
### Config.Implementation
234

235
Concrete implementation of the Config annotation interface.
236

237
```java { .api }
238
/**
239
 * Concrete implementation of Config annotation.
240
 * Can be created from Properties or programmatically.
241
 */
242
public static class Implementation implements Config {
243
    public Implementation(/* parameters for all config values */);
244
    
245
    public static Config fromProperties(Properties properties);
246
    
247
    // Implements all Config interface methods
248
    public int[] sdk();
249
    public int minSdk();
250
    public int maxSdk();
251
    public String manifest();
252
    public float fontScale();
253
    public Class<? extends Application> application();
254
    public String qualifiers();
255
    public String packageName();
256
    public String resourceDir();
257
    public String assetDir();
258
    public Class<?>[] shadows();
259
    public String[] instrumentedPackages();
260
    public String[] libraries();
261
}
262
```
263

264
**Usage Example:**
265

266
```java
267
// Create from properties
268
Properties props = new Properties();
269
props.setProperty("sdk", "28,29,30");
270
props.setProperty("qualifiers", "xlarge-land");
271
Config config = Config.Implementation.fromProperties(props);
272

273
// Create with builder
274
Config config = new Config.Builder()
275
    .setSdk(28, 29, 30)
276
    .setQualifiers("xlarge-land-mdpi")
277
    .setApplication(MyApplication.class)
278
    .build();
279
```
280

281
## Configuration Hierarchy
282

283
Configuration follows a hierarchy where more specific configurations override broader ones:
284

285
1. **Global** - System properties and robolectric.properties files
286
2. **Package** - package-info.java annotations
287
3. **Class** - Class-level @Config annotations  
288
4. **Method** - Method-level @Config annotations
289

290
Method-level configurations have the highest precedence and will override all others.
291

292
## Robolectric Properties
293

294
Configure Robolectric globally using system properties or robolectric.properties files:
295

296
```properties
297
# robolectric.properties
298
sdk=21,28,29,30
299
minSdk=21
300
maxSdk=30
301
qualifiers=normal-hdpi
302
```
303

304
System properties use the `robolectric.` prefix:
305

306
```bash
307
-Drobolectric.sdk=28
308
-Drobolectric.qualifiers=xlarge-land-mdpi
309
```