API Features | Contributors

Android instrumentations are powerful tools for automating android applications and make a nice fit for automated acceptance testing.

Positron provides an instrumentation and some support classes to help writing acceptance tests. It is provided as a jar that gets bundled with your application. Acceptance tests are written in junit, extending a custom base class.

Get Started

First, download the jar and include it in your application. For example, an eclipse user might create a vendor/positron directory and move the jar into it. Then, after refreshing eclipse, right-click the jar in the Package Explorer view and select Build Path -> Add to Build Path.

Create a subclass of positron.Positron in the same java package as is listed in your AndroidManifests.xml file in the package attribute. This is necessary due to current limitations of the <instrumentation> tag, which can currently only use relative class names.

package bolt.client;

import acceptance.AcceptanceTests;
import junit.framework.TestSuite;

/**
 * Subclass positron to add tests and place it in bolt's package, so <instrumentation> tag accepts it.
 * @author philhsmith
 */
public class Positron extends positron.Positron {
	@Override
	protected TestSuite suite() {
		TestSuite suite = new TestSuite();
		suite.addTestSuite(AcceptanceTests.class);
		return suite;
	}
}

The subclass can be used to provide a little configuration. Override suite() to declare which tests to run. Override setUpSuite() and tearDownSuite() to perform one-time initialization and tear-down.

Now declare this new subclass in your AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="bolt.client">
        
    <instrumentation class=".Positron" android:targetPackage="bolt.client"
    	android:label="Bolt Acceptance Tests"/>
    
    <application android:icon="@drawable/icon" android:theme="@android:style/Theme.Dark">

    ...

Acceptance tests extend positron.TestCase. It is a junit.framework.TestCase that is equipped with most of the methods of an Instrumentation, plus a few others.

public class InstallABolt extends TestCase {
	private final static String TAG = "InstallABolt";

	protected String getString(int id) { return getTargetContext().getString(id); }

	public void test() {
		startActivity(new Intent(getString(R.string.action_MAIN)).addLaunchFlags(Intent.NEW_TASK_LAUNCH));
		pause();

		// 1.
		assertEquals(getString(R.string.title_search), activity().getTitle());

		// 2.
		ListView results = (ListView)activity().findViewById(R.id.search_results);
		assertEquals(0, results.getAdapter().getCount());

		EditText queryBox = (EditText)activity().findViewById(R.id.search_query);
		assertEquals(queryBox, activity().getCurrentFocus());

		sendString("acceptance test");
		click();

		// 3.
		assertEquals(4, results.getAdapter().getCount());
	}

	public void tearDown() { finishAll(); }
}

Eclipse's junit runner can't run positron acceptance tests. You may want to move your acceptance tests out of the way, say by putting them into a different source folder from your pure unit tests. Then modify your junit run target to point at the right directory instead of running all tests in the project.

To run your test suite, call adb shell "/system/bin/am instrument -w bolt.client/.Positron". Here, as will the previous examples, replace "bolt.client" with the name of your own package, and ".Positron" with the name of your positron subclass. Don't forget the leading period! The test results are currently outputted to the system log, which you can view with adb logcat.

If you are using eclipse you can also create a 'Java Application' run target:

Since this simple java class doesn't (yet) integrate with the eclipse plugin, you need to declare where the android sdk is. The easiest way may be to define the ANDROID_HOME environment variable containing the absolute path to the sdk root (just as it appears in the eclipse preferences dialog.)

On the arguments tab, you need to provide your application's package name, just as it appears in the targetPackage attribute of the <instrumentation> tag.

If you chose to name your subclass something other than "Positron", supply that name as the second parameter (include a leading period.) If you chose to not define the ANDROID_HOME environment variable, you can supply the absolute path to the sdk root as the third parameter.

Eclipse users can see the logcat output using the Android 'DDMS' perspective:

API Features | Contributors