1*d57664e9SAndroid Build Coastguard Worker# Ravenwood 2*d57664e9SAndroid Build Coastguard Worker 3*d57664e9SAndroid Build Coastguard WorkerRavenwood is an officially-supported lightweight unit testing environment for Android platform code that runs on the host. 4*d57664e9SAndroid Build Coastguard Worker 5*d57664e9SAndroid Build Coastguard WorkerRavenwood’s focus on Android platform use-cases, improved maintainability, and device consistency distinguishes it from Robolectric, which remains a popular choice for app testing. 6*d57664e9SAndroid Build Coastguard Worker 7*d57664e9SAndroid Build Coastguard Worker## Background 8*d57664e9SAndroid Build Coastguard Worker 9*d57664e9SAndroid Build Coastguard WorkerExecuting tests on a typical Android device has substantial overhead, such as flashing the build, waiting for the boot to complete, and retrying tests that fail due to general flakiness. 10*d57664e9SAndroid Build Coastguard Worker 11*d57664e9SAndroid Build Coastguard WorkerIn contrast, defining a lightweight unit testing environment mitigates these issues by running directly from build artifacts (no flashing required), runs immediately (no booting required), and runs in an isolated environment (less flakiness). 12*d57664e9SAndroid Build Coastguard Worker 13*d57664e9SAndroid Build Coastguard Worker## Guiding principles 14*d57664e9SAndroid Build Coastguard WorkerHere’s a summary of the guiding principles for Ravenwood, aimed at addressing Robolectric design concerns and better supporting Android platform developers: 15*d57664e9SAndroid Build Coastguard Worker 16*d57664e9SAndroid Build Coastguard Worker* **API support for Ravenwood is opt-in.** Teams that own APIs decide exactly what, and how, they support their API functionality being available to tests. When an API hasn’t opted-in, the API signatures remain available for tests to compile against and/or mock, but they throw when called under a Ravenwood environment. 17*d57664e9SAndroid Build Coastguard Worker * _Contrasted with Robolectric which attempts to run API implementations as-is, causing maintenance pains as teams maintain or redesign their API internals._ 18*d57664e9SAndroid Build Coastguard Worker* **API support and customizations for Ravenwood appear directly inline with relevant code.** This improves maintenance of APIs by providing awareness of what code runs under Ravenwood, including the ability to replace code at a per-method level when Ravenwood-specific customization is needed. 19*d57664e9SAndroid Build Coastguard Worker * _Contrasted with Robolectric which maintains customized behavior in separate “Shadow” classes that are difficult for maintainers to be aware of._ 20*d57664e9SAndroid Build Coastguard Worker* **APIs supported under Ravenwood are tested to remain consistent with physical devices.** As teams progressively opt-in supporting APIs under Ravenwood, we’re requiring they bring along “bivalent” tests (such as the relevant CTS) to validate that Ravenwood behaves just like a physical device. 21*d57664e9SAndroid Build Coastguard Worker * _Contrasted with Robolectric, which has limited (and forked) testing of their environment, increasing their risk of accidental divergence over time and misleading “passing” signals._ 22*d57664e9SAndroid Build Coastguard Worker* **Ravenwood aims to support more “real” code.** As API owners progressively opt-in their code, they have the freedom to provide either a limited “fake” that is a faithful emulation of how a device behaves, or they can bring more “real” code that runs on physical devices. 23*d57664e9SAndroid Build Coastguard Worker * _Contrasted with Robolectric, where support for “real” code ends at the app process boundary, such as a call into `system_server`._ 24*d57664e9SAndroid Build Coastguard Worker 25*d57664e9SAndroid Build Coastguard Worker## More details 26*d57664e9SAndroid Build Coastguard Worker 27*d57664e9SAndroid Build Coastguard Worker* [Ravenwood for Test Authors](test-authors.md) 28*d57664e9SAndroid Build Coastguard Worker* [Ravenwood for API Maintainers](api-maintainers.md) 29