The Android Developer’s Cookbook: Building Applications with the Android SDK, Second Edition (2013)

---

Note that setActivityInitialTouchMode(false) must be used in order to use the setUp() method.

After the test values have been added, the test can be run by right-clicking on the test project and selecting Run As → Android JUnit Test. This will open up the JUnit view, which will display how the test performs, including runs, errors, failures, and a summary.

Recipe: Using Robotium

Robotium is a utility that helps developers write and execute various tests. To start using it, first download the .jar file from http://code.google.com/p/robotium/downloads/list and then include it in the test project (at the time of writing, the most current .jar is robotium-solo-3.6.jar).

To include it in a project, create a folder named libs at the root of the project and put the robotium-solo.3.6.jar file there. In Eclipse, refresh the project to make sure that the changes have been picked up. Navigate to the folder and right-click on the robotium-solo.3.6.jar file. In the context menu, click on Build Path → Add to Build Path.

If the .jar file is to be stored in a separate location, open the properties of the test project and choose Java Build Path and then click on Add (external) Jar. This will allow finding the .jar file and including it in a project.

After the .jar file has been added, open the class file being used for the test project. Inside this file, add the following import:

import com.jayway.android.robotium.solo.Solo;

Then, add a new variable:

private Solo solo;

The solo object is the main way to interact with Robotium; it contains all of the methods needed for testing. Then, add the following to the setUp() method:

solo = new Solo(getInstrumentation(), getActivity());

Now that the solo object has been initialized, it can be used in custom functions for testing.

The following is a sample function taken from the Robotium sample test project that shows how the solo object is used to perform testing:

public void testMenuSave() throws Exception {

solo.sendKey(Solo.MENU);
solo.clickOnText("More");
solo.clickOnText("Prefs");
solo.clickOnText("Edit File Extensions");
Assert.assertTrue(solo.searchText("rtf"));

solo.clickOnText("txt");
solo.clearEditText(2);
solo.enterText(2, "robotium");
solo.clickOnButton("Save");
solo.goBack();
solo.clickOnText("Edit File Extensions");
Assert.assertTrue(solo.searchText("application/robotium"));

}

More information about Robotium and an in-depth tutorial can be found at http://code.google.com/p/robotium/wiki/RobotiumTutorials.

Eclipse Built-In Debug Tools

The Eclipse IDE included with the ADT plugin is a user-friendly development environment. It includes a what-you-see-is-what-you-get (WYSIWYG) user interface and the tools needed to convert resource layout files into the necessary ingredients to build an Android executable. A step-by-step guide to setting up the configuration is included in the following recipe. The ADT version of Eclipse (3.7 Indigo as of this writing) is assumed, although most steps are the same between Eclipse versions.

Recipe: Specifying a Run Configuration

The run configuration is a separate profile for each application. It tells Eclipse how to run the project and start the activity and whether to install the application on the emulator or a connected device. The ADT automatically creates a run configuration for each application when it is first created, but it can be customized as described in this recipe.

To create a new run configuration or edit an existing one, select Run → Run Configurations... (or Debug Configurations...) in Eclipse to launch the Run Configurations menu shown in Figure 16.5. Inside the run configuration, there are three tabs related to application testing, which contain settings that must be set:

Android—Specify the project and activity to launch.

Target—Select the virtual device upon which the application will run. For the emulator environment, the launch parameters are specified here, such as the network speed and latency. This allows for a more realistic simulation of the wireless link conditions to test how the application behaves. Developers can also choose to wipe out the persistent storage of the emulator with every launch.

Common—Specify where the run configuration settings are saved and also whether the configuration is displayed in the Favorite menu.

Figure 16.5 The Run Configurations menu in Eclipse

After these settings are properly set, the application can be run on the target device with a single click of the Run button. If an actual Android device is not connected to the host computer or the target chosen is a virtual device, the emulator is launched to run the application.

Recipe: Using the DDMS

After the application is run on a target, the Dalvik Debug Monitoring Server (DDMS) can be opened to examine the status of the device, as shown in Figure 16.6. DDMS can be run from the command line or by selecting Window → Open Perspective → DDMS in Eclipse.

Figure 16.6 The DDMS control panel

Inside the DDMS are three panels that provide different kinds of debugging data:

Devices—Displays the connected Android devices, including emulators and actual Android devices.

Bottom panel—Contains two tabs: LogCat and Console. The LogCat tab shows all the logging data from the device in real time. It includes system log messages and user-generated log messages accessed using the Log class in applications. The Console tab may be familiar to Eclipse users, as this tab displays SystemOut messages as well as some errors during compilation or run-time.

Top right panel—Contains six tabs: Threads, Heap, Allocation Tracker, Network Statistics, File Explorer, and the Emulator Control. These are mostly used to analyze the process and network bandwidth. The Emulator Control has several options for controlling voice and data format, network speed, and latency. It also contains options for creating fake phone calls (for testing), as well as GPS spoofing options to help with testing locations in the emulator. Clicking the device in the Devices tab can cause these four tabs to reflect the currently selected device/emulator’s running values, as shown in Figure 16.7.

Figure 16.7 The DDMS control panel with the File Explorer, LogCat, and Devices panels open

Recipe: Debugging through Breakpoints

Developers can also run applications in debug mode and insert breakpoints to freeze an application in run-time. First, the application needs to be launched in debug mode, which displays the dialog shown in Figure 16.8. If “Yes” is selected, it switches to the Debug perspective shown inFigure 16.9.

Figure 16.8 The Confirm Perspective Switch dialog box

Figure 16.9 The Debug perspective in Eclipse

The Debug perspective displays the source file in a window along with some other windows, including Variables, Breakpoints, Outline, and others. Developers can toggle a breakpoint by double-clicking in the left-hand margin next to the line where the code execution should freeze. A breakpoint is set when a small blue circle is present on that line.

Using breakpoints is a standard debug method for embedded programmers. The ability to stop at an instruction, step through functions, see variable values in memory, and modify values in run-time provides a powerful method to chase down complicated bugs and unexpected behavior.

Android SDK Debug Tools

The Android SDK provides multiple stand-alone tools for debugging. The Android Debug Bridge, LogCat, Hierarchy Viewer, and TraceView tools are discussed in the following recipes. They can be found in the tools/ directory of the Android SDK installation.

Recipe: Starting and Stopping the Android Debug Bridge

The Android Debug Bridge (ADB) provides a way to manage the state of an emulator instance or USB-connected Android device. The ADB is built of three components: a client, a server, and a daemon. The client component is initiated by the adb shell script on the development machine. The server component runs as a background process on the development machine. This server can be started or stopped using one of the following commands:

> adb start-server
> adb kill-server

The daemon component is a background process that runs on the emulator or Android device.

Recipe: Using LogCat

LogCat is the real-time logging tool Android provides. It collects all system and application log data in circular buffers, which can then be viewed and filtered. It can be accessed as a stand-alone tool or as part of the DDMS tool.

LogCat can be used in the device after executing the adb shell to log in to the device or by using the logcat command through the adb:

> [adb] logcat [<option>] ... [<filter-spec>] ...

All the messages that use the android.util.Log class have an associated tag and priority. The tag should be meaningful and related to what the activity does. The tag and priority make the logging data easier to read and filter. Possible tags are:

V—Verbose (lowest priority) displays as much information as possible in the logs.

D—Debug displays errors, information, and variable values.

I—Info displays information only, such as a connection status.

W—Warning displays warning messages that are not necessarily errors but deserve attention.

E—Error displays errors that occur during run-time.

F—Fatal displays information only when a crash occurs.

S—Silent is the highest priority, on which nothing is ever printed.

The logcat data has a multitude of information, and filters should be used to avoid overload by specifying the tag:priority argument to the logcat command:

> adb logcat ActivityManager:V *:S

This shows verbose (V) data on the ActivityManager while silencing (S) all other log commands.

A circular buffer system is used inside Android logging. By default, all information is logged to the main log buffer. There are two other buffers: one that contains radio/telephony-related messages and one that contains event-related messages. Different buffers can be enabled using the -bswitch:

> adb logcat -b events

This buffer also shows event-related messages:

I/menu_opened( 135): 0
I/notification_cancel( 74): [com.android.phone,1,0]
I/am_finish_activity( 74):
[1128378040,38,com.android.contacts/.DialtactsActivity,app-request]
I/am_pause_activity( 74):
[1128378040,com.android.contacts/.DialtactsActivity]
I/am_on_paused_called( 135): com.android.contacts.RecentCallsListActivity
I/am_on_paused_called( 135): com.android.contacts.DialtactsActivity
I/am_resume_activity( 74): [1127710848,2,com.android.launcher/.Launcher]
I/am_on_resume_called( 135): com.android.launcher.Launcher
I/am_destroy_activity( 74):
[1128378040,38,com.android.contacts/.DialtactsActivity]
I/power_sleep_requested( 74): 0
I/power_screen_state( 74): [0,1,468,1]
I/power_screen_broadcast_send( 74): 1
I/screen_toggled( 74): 0
I/am_pause_activity( 74): [1127710848,com.android.launcher/.Launcher]

Another example follows:

> adb logcat -b radio

This shows radio/telephony-related messages:

D/RILJ ( 132): [2981]< GPRS_REGISTRATION_STATE {1, null, null, 2}
D/RILJ ( 132): [2982]< REGISTRATION_STATE {1, null, null, 2, null, null,
null, null, null, null, null, null, null, null}
D/RILJ ( 132): [2983]< QUERY_NETWORK_SELECTION_MODE {0}
D/GSM ( 132): Poll ServiceState done: oldSS=[0 home T - Mobile T - Mo-
bile 31026 Unknown CSS not supported -1 -1RoamInd: -1DefRoamInd: -1]
newSS=[0 home T - Mobile T - Mobile 31026 Unknown CSS not supported -1 -
1RoamInd: -1DefRoamInd: -1] oldGprs=0 newGprs=0 oldType=EDGE newType=EDGE
D/RILJ ( 132): [UNSL]< UNSOL_NITZ_TIME_RECEIVED 10/06/26,21:49:56-28,1
I/GSM ( 132): NITZ: 10/06/26,21:49:56-28,1,237945599 start=237945602
delay=3
D/RILJ ( 132): [UNSL]< UNSOL_RESPONSE_NETWORK_STATE_CHANGED
D/RILJ ( 132): [2984]> OPERATOR
D/RILJ ( 132): [2985]> GPRS_REGISTRATION_STATE
D/RILJ ( 132): [2984]< OPERATOR {T - Mobile, T - Mobile, 31026}
D/RILJ ( 132): [2986]> REGISTRATION_STATE
D/RILJ ( 132): [2987]> QUERY_NETWORK_SELECTION_MODE
D/RILJ ( 132): [2985]< GPRS_REGISTRATION_STATE {1, null, null, 2}
D/RILJ ( 132): [2986]< REGISTRATION_STATE {1, null, null, 2, null, null,
null, null, null, null, null, null, null, null}
D/RILJ ( 132): [2987]< QUERY_NETWORK_SELECTION_MODE {0}

LogCat is useful when using Java-based Android applications. However, when applications involve native components, it is harder to trace. In this case, the native components should log to System.out or System.err. By default, the Android system sends stdout and stderr (system.out andsystem.err) output to /dev/null. These can be routed to a log file with the following ADB commands:

> adb shell stop
> adb shell setprop log.redirect-stdio true
> adb shell start

This stops a running emulator/device instance; use the shell command setprop to enable the redirection of output and restart the instance.

Recipe: Using the Hierarchy Viewer

A useful way to debug and understand the user interface is by using the Hierarchy Viewer. It provides a visual representation of the layout’s view hierarchy and a magnified inspector of the display (shown in the Pixel Perfect window). Please note that while the Hierarchy Viewer can still be used, many of the features it contained have been moved into the Android Debug Monitor, which also contains the DDMS.

The Hierarchy Viewer is accessed using the tool hierarchyviewer. Executing this program launches the interface shown in Figure 16.10. It displays a list of Android devices that are currently connected to the development machine. When a device is selected, a list of running programs on the device is shown. It is then possible to select the program intended for debug or user interface optimization.

Figure 16.10 The Hierarchy Viewer tool

After the program is selected, Load View Hierarchy can be selected to see the View Tree constructed by the Hierarchy Viewer. It contains four views:

Tree View pane—A hierarchy diagram of the views on the left

Tree Overview pane—A bird’s-eye view of the hierarchy diagram

Properties View pane—A list of the selected view’s properties on the top right

Layout View pane—A wire-frame drawing of the layout on the bottom right

This is shown in Figure 16.11.

Figure 16.11 The Layout View in the Hierarchy Viewer tool

These four views are used to display different information about the hierarchy to help optimize the UI. When one node of the view is selected, the properties view and wire-frame view are updated. In an Android system, there is a limitation on the View Tree that each application can generate. The depth of the tree cannot be deeper than 10 and the width of the tree cannot be broader than 50. In Android 1.5 or earlier, a stack overflow exception is thrown when the View Tree passes that limit. Although it is good to know the limitations, a shallow layout tree always makes applications run faster and smoother. This can be accomplished using merge or RelativeLayout instead of LinearLayout to optimize the View Tree.

Recipe: Using TraceView

TraceView is a tool to optimize performance. To leverage this tool, the Debug class needs to be implemented in the application. It creates log files containing the trace information for analysis. This recipe specifies a factorial method and another method that calls the factorial method. Listing 16.2 shows the main activity.

Listing 16.2. src/com/cookbook/android/debug/traceview/TestFactorial.java

package com.cookbook.android.debug.traceview;

import android.app.Activity;
import android.os.Bundle;
import android.os.Debug;
public class TestFactorial extends Activity {
public final String tag="testfactorial";
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
factorial(10);
}

public int factorial(int n) {

Debug.startMethodTracing(tag);
int result=1;
for(int i=1; i<=n; i++) {
result*=i;
}
Debug.stopMethodTracing();
return result;
}
}