Instrumentation Tests: Testing on a Real Android Device

Why it exists

Some code simply cannot be tested on a developer's machine in isolation. Code that renders UI, accesses device hardware like a GPS, or interacts with Android system services needs a real Android environment to run. Local tests, which run on a standard Java Virtual Machine (JVM), would fail or require extensive, complex mocking to simulate this environment.

The mental model

Think of an instrumentation test as a test drive for your app in a real car on a real road, whereas a local unit test is like testing the engine on a stand in a workshop. The workshop test is fast and isolated, but it can't tell you how the car handles in traffic or on a bumpy road. Instrumentation tests run your test code directly on a device or emulator, giving it full access to the Android framework and the app's context.

How it works

When you run instrumentation tests, your build tools compile your test code into a separate APK (a test APK). This test APK is installed on the device alongside your main app's APK. A special test runner, AndroidJUnitRunner, then starts your app and executes the tests from the test APK. The test code can then interact with your app—clicking buttons, checking text, and verifying behavior—as if it were a user.

When to use it

Use instrumentation tests for anything that needs the Android framework. This includes three main areas: first, UI tests that verify user flows, button clicks, and screen content (using libraries like Espresso); second, tests for Android components like Activities, Services, and BroadcastReceivers; third, tests that depend on device hardware or specific Android APIs, like checking permissions or reading sensor data.

When not to use it

Do not use instrumentation tests for pure business logic. If a function simply transforms data, performs calculations, or validates input without touching any Android APIs, it should be a local unit test. Instrumentation tests are orders of magnitude slower to compile and run. Overusing them will make your test suite slow, flaky, and expensive to maintain.

One canonical example

A common Espresso test for a login screen. The test would find the username and password fields by their resource IDs, type text into them, then find the login button and perform a click. Finally, it would assert that a new Activity has appeared or that a welcome message is displayed. This entire sequence requires a running app with a rendered UI, which only an instrumentation test can provide.