- Developing Android unit and instrumentation tests — Tutorial
- 1. Introduction into Android testing
- 1.1. Testing Android applications
- 1.2. What to test on Android applications
- 1.3. Tooling support for Android testing
- 1.4. Android project organization for tests
- 2. Android unit testing
- 2.1. Unit testing in Android
- 2.2. Required dependencies in the Gradle build file
- 2.3. Running the unit tests
- 2.3.1. Using Gradle
- 2.3.2. Using Android Studio
- 2.4. Location of test reports
- 2.5. Activating default return values for mocked methods in android.jar
- 3. Exercise: Create unit test
- 3.1. Preparation: Create Android project
- 3.2. Add JUnit dependency
- 3.3. Create test
- 3.4. Run unit tests
- 4. Writing tests to run on the Android device
- 4.1. Instrumentation tests
- 4.2. How the Android system executes tests
- 4.3. Mocking objects in Android
- 4.4. Location of instrumentation tests
- 4.5. Define dependencies and testInstrumentationRunner in the Gradle build file
- 4.6. Using the @RunWith(AndroidJUnit4.class)
- 4.7. Run the tests on Android
- 4.8. Location of test reports
- 4.9. How to replace the application for instrumentation tests
- Build and run your app
- Change the run/debug configuration
- Change the build variant
- Build your project
- Monitor the build process
- Apply Changes
- Requirements
- Use Apply Changes
- Enable Run fallback for Apply Changes
- Platform-dependent changes
- Limitations of Apply Changes
- Code changes that require app restart
- Libraries and plugins
- Code that directly references content in an installed APK
Developing Android unit and instrumentation tests — Tutorial
This tutorial describes how to write unit and instrumentation tests for your Android application. It describes how to execute these tests via Android studio and Gradle. This tutorial assumes that you are familiar with Android programming in general.
1. Introduction into Android testing
1.1. Testing Android applications
Android applications run on a variety of devices. Also the Android framework and the surrounding open source frameworks evolve at a high speed. To ensure that you application works well, it is import to write software tests. This helps you to enhance and maintain the Android application.
Unit testing for Android can be classified into:
Local unit tests — tests which can run on the JVM.
Instrumented unit tests — tests which require the Android system.
Local unit tests run much faster compared to the time required to deploy and run tests on an Android device. Prefer writing local unit tests and only run tests on Android, if you require a real Android system.
If you write local unit test and have dependencies to Android API, you need to replace them, e.g., via a mocking framework like Mockito.
1.2. What to test on Android applications
Your test should focus on the business logic of your application. A good rule of thumb is to have the following distribution of tests:
70-80 % unit tests to ensure stability of your code basis
20-30 % functional tests to ensure that the application really works
some cross functional tests if your application integrates intensively with other Application components
You should test your application at least on one device with the lowest possible configuration. In addition you should test on one device with the highest available configuration, e.g., pixel density, screen resolution to ensure that it works fine on these devices.
1.3. Tooling support for Android testing
The Android Testing Support library (ATSL) project from Google provides tooling for Android testing. For example, it ( AndroidJUnitRunner ).
If you run local unit tests, a special version of the android.jar (also known as the Android mockable jar ) is created by the tooling. This modified JAR file is provided to the unit test so that all fields, methods and classes are available. Any call to the Android mockable JAR results, by default, in an exception, but you can configure Android to return default values. See Activating default return values for mocked methods in android.jar for details.
The library provides a JUnit 4-compatible test runner ( AndroidJUnitRunner ), the Espresso test framework and the UI Automator test framework. Espresso test framework can be used to test the User Interface of your application. UI Automator allows to write cross application functional tests.
AndroidJunitRunner provides access to the instrumentation API, via the InstrumentationRegistery .
InstrumentationRegistry.getInstrumentation() , returns the Instrumentation currently running.
InstrumentationRegistry.getContext() , returns the Context of this Instrumentation’s package.
InstrumentationRegistry.getTargetContext() , returns the application Context of the target application.
InstrumentationRegistry.getArguments() , returns a copy of arguments Bundle that was passed to this Instrumentation. This is useful when you want to access the command line arguments passed to the instrumentation for your test.
It also gives access to the life cycle via the ActivityLifecycleMonitorRegistry .
1.4. Android project organization for tests
The following is the default directory structure for your application and test code:
app/src/main/java — for your source code of your main application build
app/src/test/java — for any unit test which can run on the JVM
app/src/androidTest/java — for any test which should run on an Android device
If you follow this conversion, the Android build system runs your tests on the correct target (JVM or Android device).
If you receive the following error message: «error duplicate files in path. Path in archive: LICENSE.txt» you can add the following to your app/gradle.build file.
2. Android unit testing
2.1. Unit testing in Android
A unit test verifies in isolation the functionality of a certain component. For example, assume a button in an Android activity is used to start another activity. A unit test would determine, if the corresponding intent was issued, not if the second activity was started
A unit tests for an Android application can be:
local unit test — which runs on the JVM
Android unit test — which runs on the Android runtime
If they run on the JVM, they are executed against a modified version of the android.jar Android library. In this version all final modifiers have been stripped off. This makes it easier to use mocking libraries, like Mockito.
The local unit tests of an Android project should be located in the app/src/test folder.
2.2. Required dependencies in the Gradle build file
To use JUnit tests for your Android application, you need to add it as dependency to your Gradle build file.
2.3. Running the unit tests
2.3.1. Using Gradle
Run your unit tests with the gradlew test command.
2.3.2. Using Android Studio
To run a unit test, right-click on your test class in the Project window and select Run.
2.4. Location of test reports
The Test reports are created in the app/build/reports/tests/debug/ directory. The index.html gives an overview and links to the individual test pages.
2.5. Activating default return values for mocked methods in android.jar
By default, all calls to methods in the modified android.jar file throw exceptions. This default should ensure that your unit tests only test your code and do not depend on any particular behavior of the Android platform. If you want to configure a certain behavior, you can use a mocking framework to replace these call.
You can also instruct the Gradle build system to return default values for method calls in the `android.jar`with the following configuration in your Gradle build file.
3. Exercise: Create unit test
In this exercise you learn how to create a simple JUnit4 test for an Android project.
3.1. Preparation: Create Android project
Create the Android project as described in Android temperature converter.
3.2. Add JUnit dependency
Ensure you have the dependency to Junit in your app/build.gradle file.
3.3. Create test
In your app/src/test directory create the following two test methods for the ConverterUtil class.
3.4. Run unit tests
Ensure your unit tests are correctly implemented by running test tests. They should run successfully.
4. Writing tests to run on the Android device
4.1. Instrumentation tests
The Android testing API provides hooks into the Android component and application life cycle. These hooks are called the instrumentation API and allow your tests to control the life cycle and user interaction events.
Under normal circumstances your application cannot control the life cycle events and the user drives the application. For example, if Android creates your activity the onCreate() method is called. Or if the user presses a button your corresponding code is called. Via instrumentation you can control these events via your test code. For example, your instrumentation test can start the activity. Afterwards, it can call the finish() and restart the activity to test if the instance state of the activity is correctly restored.
Instrumented unit tests are unit tests that run on Android devices and emulators instead of running on the Java virtual machine. These tests have access to the real device and its resources and are useful to unit test functionality which cannot be easily mocked by mocking frameworks. An example is a test which validates a Parcelable implementation.
An instrumentation-based test class allows you to send key events (or touch events) to the application under test.
With user interface testing framework like Espresso, the developer rarely has to use the instrumentation API directly.
4.2. How the Android system executes tests
The InstrumentationTestRunner is the base test runner for Android tests. This test runner starts and loads the test methods. Via the instrumentation API it communicates with the Android system. If you start a test for an Android application, the Android system kills any process of the application under test and then loads a new instance. It does not start the application, this is the responsibility of the test methods. The test method controls the life cycle of the components of the application.
The test runner also calls the onCreate() method of the application and activity under test during its initialization.
4.3. Mocking objects in Android
The mocking framework Mockito can also be used for instrumentation tests. This allows you to replace parts of the Android system which are not interesting for the test. The Android framework provided in the past specialized mocking classes but these are not necessary anymore.
4.4. Location of instrumentation tests
As described in Android project organization for tests the unit tests of an Android project should be located in the app/src/androidTest/java folder.
4.5. Define dependencies and testInstrumentationRunner in the Gradle build file
To use JUnit tests for your Android application you need to add the dependency to JUnit to your Gradle build file. You also need to specify android.support.test.runner.AndroidJUnitRunner as testInstrumentationRunner in the build file.
4.6. Using the @RunWith(AndroidJUnit4.class)
It is also recommended annotating the test with the @RunWith(AndroidJUnit4.class) annotation. AndroidJUnit4 extends JUnit4, so if you use pure Junit4 syntax and ActivityTestRule it is not required. But you need it, if you want to run, i.e., Espresso tests with ActivityTestRule and JUnit4.
4.7. Run the tests on Android
Run your local unit tests via Gradle with the gradlew connectedCheck command.
To run your local unit tests via Android Studio, right-click on your test class in the Project window and select Run.
4.8. Location of test reports
The test reports are created in the app/build/reports/androidTests/connected/ directory. The index.html gives an overview and links to the individual test pages.
4.9. How to replace the application for instrumentation tests
You can replace the application class for the instrumentation tests by overriding the AndroidJUnitRunner and its newApplication method.
Источник
Build and run your app
Android Studio sets up new projects to deploy to the Android Emulator or a connected device with just a few clicks. Once your app is installed, you can use Apply Changes to deploy certain code and resource changes without building a new APK.
To build and run your app, follow these steps:
- In the toolbar, select your app from the run configurations drop-down menu.
From the target device drop-down menu, select the device that you want to run your app on.
If you don’t have any devices configured, then you need to either connect a device via USB or create an AVD to use the Android Emulator.
Click Run .
Change the run/debug configuration
When you run your app for the first time, Android Studio uses a default run configuration. The run configuration specifies whether to deploy your app from an APK or an Android App Bundle, the module to run, package to deploy, activity to start, target device, emulator settings, logcat options, and more.
The default run/debug configuration builds an APK, launches the default project activity, and uses the Select Deployment Target dialog for target device selection. If the default settings don’t suit your project or module, you can customize the run/debug configuration, or even create a new one, at the project, default, and module levels. To edit a run/debug configuration, select Run > Edit Configurations. For more information, see Create and Edit Run/Debug Configurations.
Change the build variant
By default, Android Studio builds the debug version of your app, which is intended for use only during development, when you click Run.
To change the build variant Android Studio uses, select Build > Select Build Variant in the menu bar.
For projects without native/C++ code, the Build Variants panel has two columns: Module and Active Build Variant. The Active Build Variant value for the module determines which build variant the IDE deploys to your connected device and is visible in the editor.
Figure 1. The Build Variants panel has two columns for projects that do not have native/C++ code
To switch between variants, click the Active Build Variant cell for a module and choose the desired variant from the list field.
For projects with native/C++ code, the Build Variants panel has three columns: Module, Active Build Variant, and Active ABI. The Active Build Variant value for the module determines the build variant that the IDE deploys to your device and is visible in the editor. For native modules, the Active ABI value determines the ABI that the editor uses, but does not impact what is deployed.
Figure 2. The Build Variants panel adds the Active ABI column for projects with native/C++ code
To change the build variant or ABI, click the cell for the Active Build Variant or Active ABI column and choose the desired variant or ABI from the list. After you change the selection, the IDE syncs your project automatically. Changing either column for an app or library module will apply the change to all dependent rows.
By default, new projects are set up with two build variants: a debug and release variant. You need to build the release variant to prepare your app for public release.
To build other variations of your app, each with different features or device requirements, you can define additional build variants.
Conflicts in Android Studio’s Build Variants dialog
In Android Studio’s Build Variants dialog, you might see error messages indicating conflicts between build variants, such as the following:
This error does not indicate a build issue with Gradle – it is only indicating that the Android Studio IDE itself cannot resolve symbols between the variants of the selected modules.
For example, if you have a module M1 that depends on variant v1 of module M2 , but M2 has variant v2 selected in the IDE, you have unresolved symbols in the IDE. Let’s say that M1 depends on a class Foo which is only available in v1 . When v2 is selected, that class is not known by the IDE and it will fail to resolve it and show errors in the code of M1 .
These error messages appear because the IDE cannot load code for multiple variants simultaneously. In terms of your app’s build, however, the variant selected in this dialog will have no effect because Gradle builds your app with the source code specified in your Gradle build recipes, not based on what’s currently loaded in the IDE.
Build your project
The Run button builds and deploys your app to a device. However, to build your app to share or upload to Google Play, you’ll need to use one of the options in the Build menu to compile parts or all of your project. Before you select any of the build options listed in table 1, make sure you first select the build variant you want to use.
Table 1. Build options in the Build menu.
Menu Item | Description |
---|---|
Make Module | Compiles all source files in the selected module that have been modified since the last build, and all modules the selected module depends on recursively. The compilation includes dependent source files and any associated build tasks. You can select the module to build by selecting either the module name or one of its files in the Project window. |
Make Project | Makes all modules. |
Clean Project | Deletes all intermediate/cached build files. |
Rebuild Project | Runs Clean Project for the selected build variant and produces an APK. |
Build Bundle(s) / APK(s) > Build APK(s) | |
Build Bundle(s) / APK(s) > Build Bundle(s) | |
Brings up a dialog with a wizard to set up a new signing configuration, and build either a signed app bundle or APK. You need to sign your app with a release key before you can upload it to the Play Console. For more information about app signing, see Sign your app. |
Note: The Run button builds an APK with testOnly=»true» , which means the APK can only be installed via adb (which Android Studio uses). If you want a debuggable APK that people can install without adb, select your debug variant and click Build Bundle(s) / APK(s) > Build APK(s).
For details about the tasks that Gradle executes for each command, open the Build window as described in the next section. For more information about Gradle and the build process, see Configure Your Build.
Monitor the build process
You can view details about the build process by clicking View > Tool Windows > Build (or by clicking Build in the tool window bar). The window displays the tasks that Gradle executes in order to build your app, as shown in figure 3.
Figure 3. The Build output window in Android Studio
- Build tab: Displays the tasks Gradle executes as a tree, where each node represents either a build phase or a group of task dependencies. If you receive build-time or compile-time errors, inspect the tree and select an element to read the error output, as shown in figure 4.
Figure 4. Inspect the Build output window for error messages
If your build variants use product flavors, Gradle also invokes tasks to build those product flavors. To view the list of all available build tasks, click View > Tool Windows > Gradle (or click Gradle in the tool window bar).
If an error occurs during the build process, Gradle may recommend some command-line options to help you resolve the issue, such as —stacktrace or —debug . To use command-line options with your build process:
- Open the Settings or Preferences dialog:
- On Windows or Linux, select File >Settings from the menu bar.
- On Mac OSX, select Android Studio >Preferences from the menu bar.
- Navigate to Build, Execution, Deployment >Compiler.
- In the text field next to Command-line Options, enter your command-line options.
- Click OK to save and exit.
Gradle applies these command-line options the next time you try building your app.
Apply Changes
In Android Studio 3.5 and higher, Apply Changes lets you push code and resource changes to your running app without restarting your app—and, in some cases, without restarting the current activity. This flexibility helps you control how much of your app is restarted when you want to deploy and test small, incremental changes while preserving your device’s current state. Apply Changes uses capabilities in the Android JVMTI implementation that are supported on devices running Android 8.0 (API level 26) or higher. To learn more about how Apply Changes works, see Android Studio Project Marble: Apply Changes.
Requirements
Apply Changes actions are only available when you meet the following conditions:
- You build the APK of your app using a debug build variant.
- You deploy your app to a target device or emulator that runs Android 8.0 (API level 26) or higher.
Use Apply Changes
Use the following options when you want to deploy your changes to a compatible device:
Apply Changes and Restart Activity
Attempts to apply both your resource and code changes by restarting your activity but without restarting your app. Generally, you can use this option when you’ve modified code in the body of a method or modified an existing resource.
You can also perform this action by pressing Ctrl+Alt+F10 (or Control+Shift+Command+R on macOS).
Apply Code Changes
Attempts to apply only your code changes without restarting anything. Generally, you can use this option when you’ve modified code in the body of a method but you have not modified any resources. If you’ve modified both code and resources, use Apply Changes and Restart Activity instead.
You can also perform this action by pressing Ctrl+F10 (or Control+Command+R on macOS).
Run
Deploys all changes and restarts the app. Use this option when the changes that you have made cannot be applied using either of the Apply Changes options. To learn more about the types of changes that require an app restart, see Limitations of Apply Changes.
Enable Run fallback for Apply Changes
After you’ve clicked either Apply Changes and Restart Activity or Apply Code Changes, Android Studio builds a new APK and determines whether the changes can be applied. If the changes can’t be applied and would cause Apply Changes to fail, Android Studio prompts you to Run your app again instead. However, if you don’t want to be prompted every time this occurs, you can configure Android Studio to automatically rerun your app when changes can’t be applied.
To enable this behavior, follow these steps:
Open the Settings or Preferences dialog:
- On Windows or Linux, select File > Settings from the menu bar.
- On macOS, select Android Studio > Preferences from the menu bar.
Navigate to Build, Execution, Deployment > Deployment.
Select the checkboxes to enable automatic Run fallback for either of the Apply Changes actions.
Click OK.
Platform-dependent changes
Some features of Apply Changes depend on specific versions of the Android platform. To apply these kinds of changes, your app must be deployed to a device running that version of Android (or higher).
Type of change | Minimum platform version |
---|---|
Adding a method | Android 11 |
Limitations of Apply Changes
Apply Changes is designed to speed up the app deployment process. However, there are some limitations for when it can be used. If you encounter any issues while using Apply Changes, file a bug.
Code changes that require app restart
Some code and resource changes cannot be applied until the app is restarted, including the following:
- Adding or removing a field
- Removing a method
- Changing method signatures
- Changing modifiers of methods or classes
- Changing class inheritance
- Changing values in enums
- Adding or removing a resource
- Changing the app manifest
- Changing native libraries (SO files)
Libraries and plugins
Some libraries and plugins automatically make changes to your app’s manifest files or to resources that are referenced in the manifest. These automatic updates can interfere with Apply Changes in the following ways:
- If a library or plugin makes changes to your app’s manifest, you can’t use either Apply Code Changes or Apply Changes and Restart Activity and have to restart your app before you can see your changes.
- If a library or plugin makes changes to your app’s resource files, you can’t use Apply Code Changes , and you must use Apply Changes and Restart Activity to see your changes.
You can avoid these limitations by disabling all automatic updates for your debug build variants.
For example, Crashlytics updates app resources with a unique build ID during every build, which prevents you from using Apply Code Changes and requires you to restart your app’s activity to see your changes. You can disable this behavior so that you can use Apply Code Changes alongside Crashlytics with your debug builds.
Code that directly references content in an installed APK
If your code directly references content from your app’s APK that’s installed on the device, that code can cause crashes or misbehave after clicking Apply Code Changes . This behavior occurs because when you click Apply Code Changes, the underlying APK on the device is replaced during installation. In these cases, you can click Apply Changes and Restart Activity or Run , instead.
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Источник