# Instrumentation for Android and AWS Device Farm
<a name="test-types-android-instrumentation"></a>

Device Farm provides support for Instrumentation (JUnit, Espresso, Robotium, or any Instrumentation-based tests) for Android.

Device Farm also provides a sample Android application and links to working tests in three Android automation frameworks, including Instrumentation (Espresso). The [Device Farm sample app for Android](https://github.com/awslabs/aws-device-farm-sample-app-for-android) is available for download on GitHub.

For more information about testing in Device Farm, see [Test frameworks and built-in tests in AWS Device Farm](test-types.md).

**Topics**
+ [What is instrumentation?](#test-types-android-instrumentation-what-is)
+ [Considerations for Android instrumentation tests](#test-types-android-instrumentation-settings)
+ [Standard mode test parsing](#test-types-android-standard-mode-test-parse)
+ [Integrating Android Instrumentation with Device Farm](test-types-android-instrumentation-integrate.md)

## What is instrumentation?
<a name="test-types-android-instrumentation-what-is"></a>

Android instrumentation makes it possible for you to invoke callback methods in your test code so you can run through the lifecycle of a component step by step, as if you were debugging the component. For more information, see [Instrumented tests](https://developer.android.com/studio/test/test-in-android-studio#test_types_and_locations) in the *Test types and locations* section of the *Android Developer Tools* documentation.

## Considerations for Android instrumentation tests
<a name="test-types-android-instrumentation-settings"></a>

When using Android instrumentation, consider the following recommendations and notes.

**Check Android OS Compatibility**  
 Check the [Android documentation ](https://developer.android.com/jetpack/androidx/releases/test#orchestrator-1.5.0), to ensure Instrumentation is compatible with your Android OS version. 

**Running from the Command Line**  
 To run Instrumentation tests from the command line, please follow the [Android documentation.](https://developer.android.com/training/testing/instrumented-tests/androidx-test-libraries/runner#enable-command) 

**System Animations**  
 Per the [Android documentation for Espresso testing](https://developer.android.com/training/testing/espresso), it is recommended that system animations are turned off when testing on real devices. Device Farm automatically disables **Window Animation Scale**, **Transition Animation Scale**, and **Animator Duration Scale** settings when it executes with the [android.support.test.runner.AndroidJUnitRunner](http://developer.android.com/reference/android/support/test/runner/AndroidJUnitRunner.html) instrumentation test runner.

**Test Recorders**  
Device Farm supports frameworks, such as Robotium, that have record-and-playback scripting tools.

## Standard mode test parsing
<a name="test-types-android-standard-mode-test-parse"></a>

In the standard mode of a run, Device Farm parses your test suite and identifies the unique test classes and methods that it will run. This is done through a tool called [Dex Test Parser](https://github.com/linkedin/dex-test-parser). 

When given an Android instrumentation .apk file as input, the parser returns the fully qualified method names of the tests that match JUnit 3 and JUnit 4 conventions. 

To test this in a local environment: 

1. Download the [https://github.com/linkedin/dex-test-parser](https://github.com/linkedin/dex-test-parser) binary.

1. Run the following command to get the list of test methods that will run on Device Farm:

   ```
   java -jar parser.jar path/to/apk path/for/output
   ```

# Integrating Android Instrumentation with Device Farm
<a name="test-types-android-instrumentation-integrate"></a>

**Note**  
Use the following instructions to integrate Android instrumentation tests with AWS Device Farm. For more information about using instrumentation tests in Device Farm, see [Instrumentation for Android and AWS Device Farm](test-types-android-instrumentation.md). 

## Upload your Android instrumentation tests
<a name="test-types-android-instrumentation-upload"></a>

Use the Device Farm console to upload your tests.

1. Sign in to the Device Farm console at [https://console.aws.amazon.com/devicefarm](https://console.aws.amazon.com/devicefarm).

1. On the Device Farm navigation panel, choose **Mobile Device Testing**, then choose **Projects**.

1. In the list of projects, choose the project that you want to upload your tests to.
**Tip**  
You can use the search bar to filter the project list by name.  
To create a project, follow the instructions in [Creating a project in AWS Device Farm](how-to-create-project.md).

1. Select **Create run**.

1. Under **Select app**, in the **App selection options** section, select **Upload own app**.

1. Browse to and choose your Android app file. The file must be an .apk file.

1. Under **Configure test**, in the **Select test framework** section, choose **Instrumentation**, and then select **Choose File**.

1. Browse to and choose the .apk file that contains your tests.

1. Complete the remaining instructions to select devices and start the run.

## (Optional) Take screenshots in Android instrumentation tests
<a name="test-types-android-instrumentation-screenshots"></a>

You can take screenshots as part of your Android Instrumentation tests.

To take screenshots, call one of the following methods:
+ For Robotium, call the `takeScreenShot` method (for example, `solo.takeScreenShot();`).
+ For Spoon, call the `screenshot` method, for example:

  ```
  Spoon.screenshot(activity, "initial_state");
  /* Normal test code... */
  Spoon.screenshot(activity, "after_login");
  ```

During a test run, Device Farm gets screenshots from the following locations on the devices, if they exist, and then adds them to the test reports:
+ `/sdcard/robotium-screenshots`
+ `/sdcard/test-screenshots`
+ `/sdcard/Download/spoon-screenshots/test-class-name/test-method-name`
+ `/data/data/application-package-name/app_spoon-screenshots/test-class-name/test-method-name`