CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-robolectric--robolectric

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.

Pending
Overview
Eval results
Files

runtime-environment.mddocs/

Runtime Environment Control

Runtime environment management providing access to the Application context, device configuration control, threading management, and system property manipulation in the simulated Android environment.

Capabilities

Application Management

Access and control the Application instance under test with support for lazy loading and custom Application classes.

public class RuntimeEnvironment {
    /**
     * Get reference to the Application under test.
     * May be created at setup time or lazily at call time based on LazyApplication setting.
     * Must be called on main/test thread if lazy loading is enabled.
     * 
     * Alternative: androidx.test.core.app.ApplicationProvider.getApplicationContext()
     * for cross-platform tests that work on JVM and real devices.
     */
    public static Application getApplication();
    
    /** Internal use only - sets Application supplier for lazy loading */
    public static void setApplicationSupplier(Supplier<Application> applicationSupplier);
    
    /** Returns the configured Application class */
    public static Class<? extends Application> getConfiguredApplicationClass();
    
    /** Sets the Application class to be used */
    public static void setConfiguredApplicationClass(Class<? extends Application> clazz);
}

Static Fields (Deprecated):

public class RuntimeEnvironment {
    /** 
     * @deprecated Use getApplication() instead
     * Incompatible with LazyApplication and may be removed
     */
    @Deprecated 
    public static Context systemContext;
    
    /** 
     * @deprecated Use getApplication() instead
     * Accessing directly is incompatible with LazyApplication
     */
    @Deprecated 
    public static volatile Application application;
}

Usage Example:

// Get application instance
Application app = RuntimeEnvironment.getApplication();
assertThat(app).isNotNull();

// Check application type
if (RuntimeEnvironment.getConfiguredApplicationClass() == MyCustomApplication.class) {
    MyCustomApplication customApp = (MyCustomApplication) app;
    customApp.doCustomSetup();
}

Device Configuration Management

Control device configuration including screen properties, locale settings, and resource qualifiers.

public class RuntimeEnvironment {
    /**
     * Returns qualifier string describing current Configuration of system resources.
     * Format follows Android resource qualifier rules:
     * https://developer.android.com/guide/topics/resources/providing-resources.html#QualifierRules
     */
    public static String getQualifiers();
    
    /**
     * Returns qualifier string for given configuration and display metrics.
     */
    public static String getQualifiers(Configuration configuration, DisplayMetrics displayMetrics);
    
    /**
     * Overrides current device configuration.
     * If qualifiers start with '+', overlays on prior configuration additively.
     * Otherwise uses default values for unspecified properties.
     * 
     * See: http://robolectric.org/device-configuration/
     */
    public static void setQualifiers(String newQualifiers);
    
    /** Sets font scale for the device */
    public static void setFontScale(float fontScale);
    
    /** Returns current font scale */
    public static float getFontScale();
}

Usage Examples:

// Check current configuration
String qualifiers = RuntimeEnvironment.getQualifiers();
assertThat(qualifiers).contains("mdpi");

// Change to tablet landscape configuration
RuntimeEnvironment.setQualifiers("xlarge-land-mdpi");

// Overlay additional qualifiers (additive)
RuntimeEnvironment.setQualifiers("+fr-rFR");  // Add French locale

// Test font scaling
RuntimeEnvironment.setFontScale(1.5f);
assertThat(RuntimeEnvironment.getFontScale()).isEqualTo(1.5f);

// Verify resources update
Resources resources = RuntimeEnvironment.getApplication().getResources();
Configuration config = resources.getConfiguration();
assertThat(config.fontScale).isEqualTo(1.5f);

Threading Management (Legacy Mode Only)

Thread management APIs for LEGACY looper mode. Not supported in PAUSED or INSTRUMENTATION_TEST modes.

public class RuntimeEnvironment {
    /**
     * @deprecated Not supported in realistic looper mode
     * Tests if given thread is currently set as main thread.
     */
    @Deprecated
    public static boolean isMainThread(Thread thread);
    
    /**
     * @deprecated Not supported in realistic looper mode  
     * Tests if current thread is main thread.
     */
    @Deprecated
    public static boolean isMainThread();
    
    /**
     * @deprecated Not supported in realistic looper mode
     * Retrieves main thread. Defaults to thread that initializes RuntimeEnvironment.
     */
    @Deprecated
    public static Thread getMainThread();
    
    /**
     * @deprecated Not supported in realistic looper mode
     * Sets the main thread.
     */
    @Deprecated
    public static void setMainThread(Thread newMainThread);
}

Activity Thread Management

Access to the ActivityThread for advanced runtime manipulation.

public class RuntimeEnvironment {
    /** Returns the activity thread object */
    public static Object getActivityThread();
    
    /** Sets the activity thread object */
    public static void setActivityThread(Object newActivityThread);
}

Usage Example:

// Access activity thread for advanced operations
Object activityThread = RuntimeEnvironment.getActivityThread();
// Cast and use as needed for specific test scenarios

API Level Information

Access to the current Android API level being simulated.

public class RuntimeEnvironment {
    /** Returns the Android API level being simulated */
    public static int getApiLevel();
}

Usage Example:

// Check API level for conditional test logic
int apiLevel = RuntimeEnvironment.getApiLevel();
if (apiLevel >= Build.VERSION_CODES.Q) {
    // Test API 29+ specific functionality
}

// Assert expected API level
assertThat(RuntimeEnvironment.getApiLevel()).isEqualTo(28);

Scheduler Management (Legacy Mode Only)

Master scheduler management for LEGACY looper mode. Deprecated in favor of PAUSED looper mode.

public class RuntimeEnvironment {
    /**
     * @deprecated Use PAUSED Looper mode instead
     * Retrieves current master scheduler used by main Looper and optionally all Loopers.
     */
    @Deprecated
    public static Scheduler getMasterScheduler();
    
    /**
     * @deprecated Use PAUSED Looper mode instead  
     * Sets current master scheduler. Primarily for Robolectric core setup.
     * Changing during test will have unpredictable results.
     */
    @Deprecated
    public static void setMasterScheduler(Scheduler masterScheduler);
}

File System Management

Temporary directory management for test file operations.

public class RuntimeEnvironment {
    /** Sets the temporary directory for test operations */
    public static void setTempDirectory(TempDirectory tempDirectory);
    
    /** Returns the current temporary directory */
    public static TempDirectory getTempDirectory();
}

Usage Example:

// Get temp directory for test files
TempDirectory tempDir = RuntimeEnvironment.getTempDirectory();
File testFile = tempDir.create("test-data.txt");

// Write test data
Files.write(testFile.toPath(), "test data".getBytes());

Android Framework JAR Management

Management of the Android framework JAR path for advanced scenarios.

public class RuntimeEnvironment {
    /** Sets the path to Android framework JAR */
    public static void setAndroidFrameworkJarPath(Path localArtifactPath);
    
    /** Returns the path to Android framework JAR */
    public static Path getAndroidFrameworkJarPath();
}

System Resources Management

Internal system resource management for compile-time resources.

public class RuntimeEnvironment {
    /** Internal use only - sets compile-time system resources supplier */
    public static void setCompileTimeSystemResources(Supplier<Path> compileTimeSystemResourcesSupplier);
    
    /** @deprecated Obsolete, do not use */
    @Deprecated
    public static Path getCompileTimeSystemResourcesPath();
}

Device Configuration Examples

Screen Size and Density

// Phone configurations
RuntimeEnvironment.setQualifiers("normal-mdpi");      // Standard phone
RuntimeEnvironment.setQualifiers("normal-hdpi");      // High-DPI phone
RuntimeEnvironment.setQualifiers("normal-xhdpi");     // Extra high-DPI phone
RuntimeEnvironment.setQualifiers("normal-xxhdpi");    // XX high-DPI phone

// Tablet configurations  
RuntimeEnvironment.setQualifiers("large-mdpi");       // 7" tablet
RuntimeEnvironment.setQualifiers("xlarge-mdpi");      // 10" tablet

Orientation

// Portrait (default)
RuntimeEnvironment.setQualifiers("normal-port-mdpi");

// Landscape
RuntimeEnvironment.setQualifiers("normal-land-mdpi");

Locale and Language

// English (default)
RuntimeEnvironment.setQualifiers("en-rUS");

// Other languages
RuntimeEnvironment.setQualifiers("fr-rFR");   // French
RuntimeEnvironment.setQualifiers("es-rES");   // Spanish
RuntimeEnvironment.setQualifiers("ja-rJP");   // Japanese

// Add language to existing configuration
RuntimeEnvironment.setQualifiers("+es-rES");

Night Mode

// Light mode (default)
RuntimeEnvironment.setQualifiers("notnight");

// Dark mode
RuntimeEnvironment.setQualifiers("night");

// Add to existing configuration
RuntimeEnvironment.setQualifiers("+night");

Complex Configurations

// Large tablet in landscape with high DPI and French locale
RuntimeEnvironment.setQualifiers("fr-rFR-xlarge-land-xhdpi");

// Phone in dark mode with extra large font
RuntimeEnvironment.setQualifiers("normal-port-night-mdpi");
RuntimeEnvironment.setFontScale(1.3f);

Migration Notes

For modern Robolectric usage:

  1. Use PAUSED Looper Mode: Avoid deprecated threading and scheduler APIs
  2. Use ApplicationProvider: Prefer androidx.test.core.app.ApplicationProvider.getApplicationContext() for cross-platform compatibility
  3. Avoid Direct Field Access: Use getApplication() instead of accessing application field directly
  4. Configuration via Annotations: Use @Config annotations instead of programmatic configuration where possible

Install with Tessl CLI

npx tessl i tessl/maven-org-robolectric--robolectric

docs

component-lifecycle.md

index.md

looper-threading.md

runtime-environment.md

shadow-system.md

test-runner.md

tile.json