| page.title=Hello, Testing |
| parent.title=Tutorials |
| parent.link=../../browser.html?tag=tutorial |
| @jd:body |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li> |
| <a href="#CreateTestProject">Creating the Test Project</a> |
| </li> |
| <li> |
| <a href="#CreateTestClass">Creating the Test Case Class</a> |
| <ol> |
| <li> |
| <a href="#CreateTestCaseClassFile">Adding the test case class file</a> |
| </li> |
| <li> |
| <a href="#CreateConstructor">Adding the test case constructor</a> |
| </li> |
| <li> |
| <a href="#CreateSetUp">Adding a setup method</a> |
| </li> |
| <li> |
| <a href="#CreatePreConditions">Adding a preconditions test</a> |
| </li> |
| <li> |
| <a href="#CreateText">Adding a unit test</a> |
| </li> |
| <li> |
| <a href="#CompleteTest">The finished test case class</a> |
| </li> |
| </ol> |
| </li> |
| <li> |
| <a href="#RunTest">Running the Tests and Seeing the Results</a> |
| </li> |
| <li> |
| <a href="#NextSteps">Next Steps</a> |
| </li> |
| </ol> |
| <h2>Related Tutorials</h2> |
| <ol> |
| <li> |
| <a href="{@docRoot}resources/tutorials/hello-world.html">Hello, World</a> |
| </li> |
| <li> |
| <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> |
| </li> |
| </ol> |
| <h2>See Also</h2> |
| <ol> |
| <li> |
| <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> |
| </li> |
| <li> |
| {@link android.test.ActivityInstrumentationTestCase2} |
| </li> |
| <li> |
| {@link android.test.InstrumentationTestRunner} |
| </li> |
| </ol> |
| |
| </div> |
| </div> |
| <p> |
| Android offers a powerful but easy-to-use testing framework that is well integrated with the SDK tools. Because writing |
| tests is an important part of any development effort, this tutorial introduces the basics of testing and helps you get started testing quickly. |
| |
| To keep things simple, this tutorial builds on the <a href="{@docRoot}resources/tutorials/hello-world.html">Hello World</a> tutorial, which you may have already completed. |
| It guides you through the process of setting up a test project, adding a test, and running the test against the Hello World application, all from inside the Eclipse environment. |
| Of course, when you are done with this tutorial, you will want to create a test project for your own app and add various types of tests to it. |
| </p> |
| <p> |
| If you'd like to read an overview of the test and instrumentation framework and the core test case classes available, look at |
| the <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> topic. |
| If you prefer a more advanced testing tutorial, try the |
| <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> tutorial. |
| </p> |
| <h2 id="Prerequisites">Prerequisites</h2> |
| <p> |
| This tutorial and its code depend on the Hello World tutorial. If you haven't completed that tutorial already, |
| do so now. You will learn the fundamentals of Android application development, and you will |
| have an Android application that is ready to be tested. The tutorial guides you through the |
| setup of an Android test project using the ADT Plugin for Eclipse and other SDK tools. |
| You will need an SDK development platform that is version 1.5 |
| (API level 3) or higher. |
| </p> |
| <p> |
| If you aren't developing in Eclipse with ADT or you would like to run tests directly from the |
| command line, please see the topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a> |
| for instructions. |
| </p> |
| <h2 id="CreateTestProject">Creating the Test Project</h2> |
| <p> |
| In the Hello World tutorial you created Android application project called |
| HelloAndroid. A test of an Android application is also an Android |
| application, and you create it within an Eclipse project. The Eclipse with ADT |
| <strong>New Android Test Project</strong> dialog creates a new test project and the |
| framework of a new test application at the same time. |
| </p> |
| <p> |
| To create the test project and test application framework in Eclipse with ADT, follow these steps |
| </p> |
| <ol> |
| <li> |
| In Eclipse, select <strong>New</strong> > <strong>Project</strong> > <strong>Android</strong> > <strong>Android Test Project</strong>. |
| <p> |
| <a href="{@docRoot}images/testing/hwtest_new_test_project_menu.png"> |
| <img alt="New Android Test Project menu" src="{@docRoot}images/testing/hwtest_new_test_project_menu.png" style="height:230px"/> |
| </a> |
| </p> |
| <p> |
| The New Android Test Project dialog appears. |
| </p> |
| </li> |
| <li> |
| Set the following values: |
| <ul> |
| <li> |
| <em>Test Project Name:</em> "HelloAndroidTest" |
| </li> |
| <li> |
| <em>Test Target:</em> Set "An existing Android project", click Browse, and then |
| select "HelloAndroid" from the list of projects. |
| </li> |
| <li> |
| <em>Build Target:</em> Set a target whose platform is Android 1.5 or above. |
| </li> |
| <li> |
| <em>Application name:</em> "HelloAndroidTest" |
| </li> |
| <li> |
| <em>Package name:</em> "<code>com.example.helloandroid.test</code>" |
| </li> |
| </ul> |
| <p> |
| The dialog should now look like this: |
| </p> |
| <a href="{@docRoot}images/testing/hwtest_new_test_project_dialog_complete_callouts.png"> |
| <img alt="New Android Test Project dialog with entries" src="{@docRoot}images/testing/hwtest_new_test_project_dialog_complete_callouts.png" style="height:230px"/> |
| </a> |
| </li> |
| <li> |
| Click Finish. The new project appears in the Package Explorer. |
| </li> |
| </ol> |
| <h2 id="CreateTestClass">Creating the Test Case Class</h2> |
| <p> |
| You now have a test project HelloAndroidTest, and the basic structure of a test application |
| also called HelloAndroidTest. The basic structure includes all the files and directories you |
| need to build and run a test application, <em>except for</em> the class that contains |
| your tests (the <strong>test case class</strong>). |
| </p> |
| <p> |
| The next step is to define the test case class. In this tutorial, you define a test case class |
| that extends one of Android's test case classes designed for Activities. The class contains |
| definitions for four methods: |
| </p> |
| <ol> |
| <li> |
| <code>HelloAndroidTest</code>: This defines the constructor for the class. It is |
| required by the Android testing framework. |
| </li> |
| <li> |
| <code>setUp()</code>: This overrides the JUnit <code>setUp()</code> method. You use |
| it to initialize the environment before each test runs. |
| </li> |
| <li> |
| <code>testPreconditions()</code>: This defines a small test that ensures the Hello, Android |
| application starts up correctly. |
| </li> |
| <li> |
| <code>testText()</code>: This tests that what is displayed on the screen is the |
| same as what is contained in the application's string resources. It is an example of |
| a real unit test you would perform against an application's UI. |
| </li> |
| </ol> |
| <p> |
| The following sections contain the code for the test case class and its methods. |
| </p> |
| |
| <h3 id="CreateTestCaseClassFile">Adding the test case class file</h3> |
| <p> |
| To add the Java file for the test case class, follow these steps |
| </p> |
| <ol> |
| <li> |
| In Eclipse, open the HelloAndroidTest project if it is not already open. |
| </li> |
| <li> |
| Within HelloAndroidTest, expand the <code>src/</code> folder and |
| then find the package icon for <code>com.example.helloandroid.test</code>. |
| Right-click on the package icon and select <strong>New</strong> > <strong>Class</strong>: |
| <p> |
| <a href="{@docRoot}images/testing/hwtest_create_test_class_menu_callouts.png"> |
| <img alt="Menu for creating a new class in the test application" src="{@docRoot}images/testing/hwtest_create_test_class_menu_callouts.png" style="height:230px"/> |
| </a> |
| </p> |
| <p> |
| The New Java Class dialog appears. |
| </p> |
| </li> |
| <li> |
| In the dialog, enter the following: |
| <ul> |
| <li> |
| <em>Name:</em> "HelloAndroidTest". This becomes the name of your test class. |
| </li> |
| <li> |
| <em>Superclass:</em> "<code>android.test.ActivityInstrumentationTestCase2<HelloAndroid></code>". |
| The superclass is parameterized by an Activity class name. |
| <p> |
| The dialog should now look like this: |
| </p> |
| <a href="{@docRoot}images/testing/hwtest_new_test_class_dialog_complete_callouts.png"> |
| <img alt="New Java Class dialog with entries" src="{@docRoot}images/testing/hwtest_new_test_class_dialog_complete_callouts.png" style="height:230px"/> |
| </a> |
| </li> |
| </ul> |
| <p> |
| Do not change any of the other settings. Click Finish. |
| </p> |
| </li> |
| <li> |
| You now have a new file <code>HelloAndroidTest.java</code> in the project. |
| This file contains the class <code>HelloAndroidTest</code>, |
| which extends the Activity test case class |
| <code>ActivityInstrumentationTestCase2<T></code>. You parameterize the |
| class with <code>HelloAndroid</code>, which is the class name of the activity under test. |
| </li> |
| <li> |
| Open <code>HelloAndroidTest.java</code>. It should look like this: |
| <pre class="prettyprint"> |
| package com.example.helloandroid.test; |
| |
| import android.test.ActivityInstrumentationTestCase2; |
| |
| public class HelloAndroidTest extends ActivityInstrumentationTestCase2<HelloAndroid> { |
| } |
| </pre> |
| </li> |
| <li> |
| The test case class depends on the <code>HelloAndroid</code> class, which is not |
| yet imported. To import the class, add the following line just before the current |
| <code>import</code> statement: |
| <pre class="prettyprint"> |
| import com.example.helloandroid.HelloAndroid; |
| </pre> |
| </li> |
| </ol> |
| <h3 id="CreateConstructor">Adding the test case constructor</h3> |
| <p> |
| The test case class constructor is used by the Android testing framework when you run the test. |
| It calls the super constructor with parameters that tell the framework what Android application |
| should be tested. |
| </p> |
| <p> |
| Add the following constructor method immediately after the class definition: |
| </p> |
| <pre class="prettyprint"> |
| public HelloAndroidTest() { |
| super("com.example.helloandroid", HelloAndroid.class); |
| } |
| </pre> |
| <p> |
| Save the file <code>HelloAndroidTest.java</code>. |
| </p> |
| <h3 id="CreateSetUp">Adding a setup method</h3> |
| <p> |
| The <code>setUp()</code> method overrides the JUnit {@link junit.framework.TestCase#setUp() setUp()} |
| method, which the Android testing framework calls prior to running each test method. You use |
| <code>setUp()</code> to initialize variables and prepare the test environment. For this |
| test case, the <code>setUp()</code> method starts the Hello, Android application, |
| retrieves the text being displayed on the screen, and retrieves the text string in the |
| resource file. |
| </p> |
| <p> |
| First, add the following code immediately after the constructor method: |
| </p> |
| <pre class="prettyprint"> |
| @Override |
| protected void setUp() throws Exception { |
| super.setUp(); |
| mActivity = this.getActivity(); |
| mView = (TextView) mActivity.findViewById(com.example.helloandroid.R.id.textview); |
| resourceString = mActivity.getString(com.example.helloandroid.R.string.hello); |
| } |
| </pre> |
| <p> |
| For this code to work, you must also add some class members and another import statement. To |
| add the class members, add the following code immediately after the class definition: |
| </p> |
| <pre class="prettyprint"> |
| private HelloAndroid mActivity; |
| private TextView mView; |
| private String resourceString; |
| </pre> |
| <p> |
| To add the import statement, add the following statement just after the import for |
| <code>android.test.ActivityInstrumentationTestCase2</code>: |
| </p> |
| <pre class="prettyprint"> |
| import android.widget.TextView; |
| </pre> |
| <h3 id="CreatePreConditions">Adding a preconditions test</h3> |
| <p> |
| A preconditions test checks the initial application conditions prior to executing other tests. |
| It's similar to <code>setUp()</code>, but with less overhead, since it only runs once. |
| </p> |
| <p> |
| Although a preconditions test can check for a variety of different conditions, |
| in this application it only needs to check whether the application under test is |
| initialized properly and the target TextView exists. |
| To do this, it calls the inherited |
| {@link junit.framework.Assert#assertNotNull(Object) assertNotNull()} |
| method, passing a reference to the TextView. |
| The test succeeds only if the object reference is not null. |
| </p> |
| <pre class="prettyprint"> |
| public void testPreconditions() { |
| assertNotNull(mView); |
| } |
| </pre> |
| <h3 id="CreateText">Adding a unit test</h3> |
| <p> |
| Now add a simple unit test to the test case class. |
| The method <code>testText()</code> will call a |
| {@link junit.framework.Assert JUnit Assert} |
| method to check whether the target TextView is displaying the expected text. |
| </p> |
| <p> |
| For this example, the test expects that the TextView is |
| displaying the string resource that was originally declared for it in HelloAndroid's |
| <code>main.xml</code> file, referred to by the resource ID <code>hello</code>. |
| The call to |
| {@link junit.framework.Assert#assertEquals(String, String) assertEquals(String,String)} |
| compares the expected value, read directly from the <code>hello</code>string resource, |
| to the text displayed by the TextView, obtained from the |
| TextView's <code>getText()</code> method. The test succeeds only if the strings match. |
| </p> |
| <p> |
| To add this test, add the following code |
| immediately after the <code>testPreconditions()</code> method: |
| </p> |
| <pre class="prettyprint"> |
| public void testText() { |
| assertEquals(resourceString,(String)mView.getText()); |
| } |
| </pre> |
| <h3 id="CompleteTest">The finished test case class</h3> |
| <p> |
| You have now finished writing the test. This is what the complete test case class |
| should look like: |
| </p> |
| <pre class="prettyprint"> |
| package com.example.helloandroid.test; |
| |
| import com.example.helloandroid.HelloAndroid; |
| import android.test.ActivityInstrumentationTestCase2; |
| import android.widget.TextView; |
| |
| public class HelloAndroidTest extends ActivityInstrumentationTestCase2<HelloAndroid> { |
| private HelloAndroid mActivity; // the activity under test |
| private TextView mView; // the activity's TextView (the only view) |
| private String resourceString; |
| |
| public HelloAndroidTest() { |
| super("com.example.helloandroid", HelloAndroid.class); |
| } |
| @Override |
| protected void setUp() throws Exception { |
| super.setUp(); |
| mActivity = this.getActivity(); |
| mView = (TextView) mActivity.findViewById(com.example.helloandroid.R.id.textview); |
| resourceString = mActivity.getString(com.example.helloandroid.R.string.hello); |
| } |
| public void testPreconditions() { |
| assertNotNull(mView); |
| } |
| public void testText() { |
| assertEquals(resourceString,(String)mView.getText()); |
| } |
| } |
| </pre> |
| <h2 id="RunTest">Running the Tests and Seeing the Results</h2> |
| <p> |
| You can now run the tests you've created against the Hello, Android application. In Eclipse with |
| ADT, you run a test application as an <strong>Android JUnit test</strong> rather than a regular |
| Android application. |
| </p> |
| <p> |
| To run the test application as an Android JUnit test, in the Package Explorer right-click |
| the HelloAndroidTest project and select <strong>Run As</strong> > <strong>Android JUnit Test</strong> |
| </p> |
| <a href="{@docRoot}images/testing/hwtest_runas_menu_callouts.png"> |
| <img alt="Menu to run Hello, World as an Android JUnit test" |
| src="{@docRoot}images/testing/hwtest_runas_menu_callouts.png" style="height:230px"> |
| </a> |
| <p> |
| The ADT plugin then launches the test application and the application |
| under test on a the target emulator or device. When both applications are running, |
| the testing framework runs the tests and reports the results in the JUnit view of Eclipse, |
| which appears by default as a tab next to the Package Explorer. |
| </p> |
| <p> |
| As shown below, the JUnit view shows test results in two separate panes: |
| an upper pane summarizes the tests that were run and a lower pane reports the failure traces |
| for the tests. In this case, the tests in this example have run successfully, so there is no |
| failure reported in the view: |
| </p> |
| <a href="{@docRoot}images/testing/hwtest_junit_success.png"> |
| <img src="{@docRoot}images/testing/hwtest_junit_success.png" |
| alt="JUnit test run success" style="height:230px"/> |
| </a> |
| <p> |
| The upper pane summarizes the test: |
| </p> |
| <ul> |
| <li> |
| "Finished after <em>x</em> seconds": How long the test took to run. |
| </li> |
| <li> |
| "Runs": The number of tests run. |
| </li> |
| <li> |
| "Errors:": The number of program errors and exceptions encountered during |
| the test run. |
| </li> |
| <li> |
| "Failures:": The number of assertion failures encountered during the |
| test run. |
| </li> |
| <li> |
| A progress bar. The progress bar extends from left to right as the tests run. |
| <p> |
| If all the tests succeed, the bar remains green. |
| If a test fails, the bar turns from green to red. |
| </p> |
| </li> |
| <li> |
| A test method summary. Below the bar, you see a line for each class in the |
| test application, labeled by its fully-qualified class name. |
| To look at the results for the individual methods in a test case class, |
| click the arrow at the left of the class to expand the line. |
| You see the name of each test method. To the right of the method name, you see the |
| time needed to run that method. You can look at the method's code by |
| double-clicking its name. |
| </li> |
| </ul> |
| <p> |
| The lower pane contains the failure trace. If all the tests are successful, |
| this pane is empty. If some tests fail, then if you select a failed test in the |
| upper pane, the lower view contains a stack trace for the test. |
| </p> |
| <h2 id="NextSteps">Next Steps</h2> |
| <p> |
| This simple example test application has shown you how to create a test project, |
| create a test class and test cases, and then run the tests against a target application. |
| Now that you are familiar with these fundamentals, here are some suggested next steps: |
| </p> |
| <p> |
| <strong>Learn more about testing on Android</strong> |
| </p> |
| <ul> |
| <li> |
| The |
| <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> |
| document in the <em>Dev Guide</em> provides an overview of how testing on Android works. |
| If you are just getting started with Android testing, reading that document will |
| help you understand the tools available to you, so that you can develop effective |
| tests. |
| </li> |
| </ul> |
| <p> |
| <strong>Learn more about the testing classes available in Android</strong> |
| </p> |
| <ul> |
| <li> |
| For an overview of the types of testing classes you can use, |
| browse through the reference documentation for |
| {@link android.test.ActivityInstrumentationTestCase2}, |
| {@link android.test.ProviderTestCase2}, |
| {@link android.test.ServiceTestCase}, and |
| {@link junit.framework.Assert}. |
| </li> |
| </ul> |
| <p> |
| <strong>Explore the Android instrumentation framework</strong> |
| </p> |
| <ul> |
| <li> |
| The {@link android.test.InstrumentationTestRunner} class contains the code that Android uses |
| to run tests against an application. The {@link android.test.InstrumentationTestCase} class |
| is the base class for test case classes that use additional instrumentation features. |
| </li> |
| </ul> |
| <p> |
| <strong>Follow the Activity Testing tutorial</strong> |
| </p> |
| <ul> |
| <li> |
| The <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> |
| tutorial is an excellent follow-up to this tutorial. |
| It guides you through a more complex testing scenario that you develop against a |
| more realistic application. |
| </li> |
| </ul> |