diff options
Diffstat (limited to 'docs')
49 files changed, 6229 insertions, 1479 deletions
diff --git a/docs/html/guide/developing/debug-tasks.jd b/docs/html/guide/developing/debug-tasks.jd index 500ef58..f0bf84c 100644 --- a/docs/html/guide/developing/debug-tasks.jd +++ b/docs/html/guide/developing/debug-tasks.jd @@ -40,10 +40,13 @@ your applications. Here are some tools that you'll use most often:</p> your application, which can help you profile the performance of your application.</dd> <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong></dt> <dd>Dumps a log of system - messages. The messages include a stack trace when the emulator throws an error, + messages. The messages include a stack trace when the device throws an error, as well as {@link android.util.Log} messages you've written from your application. To run - logcat, execute <code>adb logcat</code> or, from DDMS, select <strong>Device > Run - logcat</strong>. + logcat, execute <code>adb logcat</code> from your Android SDK {@code tools/} directory or, +from DDMS, select <strong>Device > Run + logcat</strong>. When using the <a href="{@docRoot}sdk/eclipse-adt.html">ADT plugin for +Eclipse</a>, you can also view logcat messages by opening the Logcat view, available from +<strong>Window > Show View > Other > Android > Logcat</strong>. <p>{@link android.util.Log} is a logging class you can use to print out messages to the logcat. You can read messages in real time if you run logcat on DDMS (covered next). Common logging methods include: @@ -148,72 +151,7 @@ following options (among others):</p> <h2 id="DebuggingWebPages">Debugging Web Pages</h2> -<p>If you're developing a web application for Android devices, you can debug your JavaScript in the -Android Browser using the Console APIs, which will output messages to logcat. If you're familiar -debugging web pages with Firefox's FireBug or WebKit's Web Inspector, then you're probably familiar -with the Console APIs. The Android Browser (and the {@link android.webkit.WebChromeClient}) supports -most of the same APIs.</p> - -<p>When you call a function from the Console APIs (in the DOM's {@code window.console} object), -you will see the output in logcat as a warning. For example, if your web page -executes the following JavaScript:</p> -<pre class="no-pretty-print"> -console.log("Hello World"); -</pre> -<p>Then the logcat output from the Android Browser will look like this:</p> -<pre class="no-pretty-print"> -W/browser ( 202): Console: Hello World http://www.example.com/hello.html :82 -</pre> - -<p>All Console messages from the Android Browser are tagged with the name "browser" on Android -platforms running API Level 7 or higher. On platforms running API Level 6 or lower, Browser -messages are tagged with the name "WebCore". The Android Browser also formats console messages -with the log message -preceded by "Console:" and then followed by the address and line number where the -message occurred. (The format for the address and line number will appear different from the example -above on platforms running API Level 6 or lower.)</p> - -<p>The Android Browser (and {@link android.webkit.WebChromeClient}) does not implement all of the -Console APIs provided by Firefox or other WebKit-based browsers. Primarily, you need to depend -on the basic text logging functions:</p> -<ul> - <li>{@code console.log(String)}</li> - <li>{@code console.info(String)}</li> - <li>{@code console.warn(String)}</li> - <li>{@code console.error(String)}</li> -</ul> -<p>Although the Android Browser may not fully implement other Console functions, they will not raise -run-time errors, but may not behave the same as they do on other desktop browsers.</p> - -<p>If you've implemented a custom {@link android.webkit.WebView} in your application, then in order -to receive messages that are sent through the Console APIs, you must provide a {@link -android.webkit.WebChromeClient} that implements the {@link -android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback -method. For example, assuming that the {@code myWebView} field references the {@link -android.webkit.WebView} in your application, you can log debug messages like this:</p> -<pre> -myWebView.setWebChromeClient(new WebChromeClient() { - public void onConsoleMessage(String message, int lineNumber, String sourceID) { - Log.d("MyApplication", message + " -- From line " + lineNumber + " of " + sourceID); - } -}); -</pre> -<p>The {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String) -onConsoleMessage()} method will be called each time one of the Console methods is called from -within your {@link android.webkit.WebView}.</p> -<p>When the "Hello World" log is executed through your {@link android.webkit.WebView}, it will -now look like this:</p> -<pre class="no-pretty-print"> -D/MyApplication ( 430): Hello World -- From line 82 of http://www.example.com/hello.html -</pre> - -<p class="note"><strong>Note:</strong> The {@link -android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback -method was added with API Level 7. If you are using a custom {@link -android.webkit.WebView} on a platform running API Level 6 or lower, then your Console messages will -automatically be sent to logcat with the "WebCore" logging tag.</p> - - +<p>See the <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a> document.</p> <h2 id="toptips">Top Debugging Tips</h2> diff --git a/docs/html/guide/developing/testing/index.jd b/docs/html/guide/developing/testing/index.jd index ea61cc3..2164705 100644 --- a/docs/html/guide/developing/testing/index.jd +++ b/docs/html/guide/developing/testing/index.jd @@ -1,6 +1,5 @@ page.title=Testing Overview @jd:body - <p> Android includes powerful tools for setting up and running test applications. Whether you are working in Eclipse with ADT or working from the command line, these tools @@ -9,7 +8,7 @@ page.title=Testing Overview </p> <p> If you aren't yet familiar with the Android testing framework, please read the topic - <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a> + <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a> before you get started. For a step-by-step introduction to Android testing, try the <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, Testing</a> diff --git a/docs/html/guide/developing/testing/testing_eclipse.jd b/docs/html/guide/developing/testing/testing_eclipse.jd index da1c0f0..ba7eaba 100644 --- a/docs/html/guide/developing/testing/testing_eclipse.jd +++ b/docs/html/guide/developing/testing/testing_eclipse.jd @@ -1,28 +1,23 @@ page.title=Testing In Eclipse, with ADT @jd:body - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#CreateTestProjectEclipse">Creating a Test Project</a></li> - <li><a href="#CreateTestAppEclipse">Creating a Test Application</a></li> - <li><a href="#RunTestEclipse">Running Tests</a></li> - </ol> - </div> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#CreateTestProjectEclipse">Creating a Test Project</a></li> + <li><a href="#CreateTestAppEclipse">Creating a Test Package</a></li> + <li><a href="#RunTestEclipse">Running Tests</a></li> + </ol> + </div> </div> <p> - This topic explains how create and run tests of Android applications in Eclipse with ADT. - - with the basic processes for creating and running applications with ADT, as described in - <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>. - - Before you read this topic, you should read about how to create a Android application with the - basic processes for creating and running applications with ADT, as described in - <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>. - You may also want to read - <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a>, - which provides an overview of the Android testing framework. + This topic explains how create and run tests of Android applications in Eclipse with ADT. + Before you read this topic, you should read about how to create a Android application with the + basic processes for creating and running applications with ADT, as described in + <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>. + You may also want to read + <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, + which provides an overview of the Android testing framework. </p> <p> ADT provides several features that help you set up and manage your testing environment @@ -32,20 +27,20 @@ page.title=Testing In Eclipse, with ADT <li> It lets you quickly create a test project and link it to the application under test. When it creates the test project, it automatically inserts the necessary - <code><instrumentation></code> element in the test application's manifest file. + <code><instrumentation></code> element in the test package's manifest file. </li> <li> It lets you quickly import the classes of the application under test, so that your tests can inspect them. </li> <li> - It lets you create run configurations for your test application and include in + It lets you create run configurations for your test package and include in them flags that are passed to the Android testing framework. </li> <li> - It lets you run your test application without leaving Eclipse. ADT builds both the - application under test and the test application automatically, installs them if - necessary to your device or emulator, runs the test application, and displays the + It lets you run your test package without leaving Eclipse. ADT builds both the + application under test and the test package automatically, installs them if + necessary to your device or emulator, runs the test package, and displays the results in a separate window in Eclipse. </li> </ul> @@ -55,305 +50,452 @@ page.title=Testing In Eclipse, with ADT <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a>. </p> <h2 id="CreateTestProjectEclipse">Creating a Test Project</h2> - <p> +<p> To set up a test environment for your Android application, you must first create a separate - application project that holds the test code. The new project follows the directory structure + project that holds the test code. The new project follows the directory structure used for any Android application. It includes the same types of content and files, such as - source code, resources, a manifest file, and so forth. The test application you + source code, resources, a manifest file, and so forth. The test package you create is connected to the application under test by an <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"> <code><instrumentation></code></a> element in its manifest file. - </p> - <p> - The <strong>New Android Test Project</strong> dialog makes it easy for you to generate a +</p> +<p> + The <em>New Android Test Project</em> dialog makes it easy for you to generate a new test project that has the proper structure, including the - <code><instrumentation></code> element in the manifest file. You can use the New Android - Test Project dialog to generate the test project at any time. The dialog appears just after you - create a new Android main application project, but you can also run it to create a test project - for a project that you created previously. - </p> + <code><instrumentation></code> element in the manifest file. You can use the New + Android Test Project dialog to generate the test project at any time. The dialog appears + just after you create a new Android main application project, but you can also run it to + create a test project for a project that you created previously. +</p> <p> - To create a test project in Eclipse with ADT: + To create a test project in Eclipse with ADT: </p> <ol> - <li> - In Eclipse, select <strong>File > New > Other</strong>. This - opens the Select a Wizard dialog. - </li> - <li> - In the dialog, in the Wizards drop-down list, - find the entry for Android, then click the toggle to the left. Select - Android Test Project, then at the bottom - of the dialog click Next. The New Android Test Project wizard appears. - </li> - <li> - Enter a project name. You may use any name, but you may want to - associate the name with the project name for your Application. One - way to do this is to take the Application's project name, append the - string "Test" to it, and then use this as the test case project name. - </li> - <li> - In the Test Target panel, set - An Existing Android Project, click - Browse, then select your Android application from - the list. You now see that the wizard has completed the Test - Target Package, Application Name, and - Package Name fields for you (the latter two are in - the Properties panel). - </li> - <li> - In the Build Target panel, select the Android SDK - platform that you will use to test your application. Make this the same as the - build target of the application under test. - </li> - <li> - Click Finish to complete the wizard. If - Finish is disabled, look - for error messages at the top of the wizard dialog, and then fix - any problems. - </li> + <li> + In Eclipse, select <strong>File > New > Other</strong>. This opens the <em>Select a + Wizard</em> dialog. + </li> + <li> + In the dialog, in the <em>Wizards</em> drop-down list, find the entry for Android, then + click the toggle to the left. Select <strong>Android Test Project</strong>, then at the + bottom of the dialog click <strong>Next</strong>. The <em>New Android Test Project</em> + wizard appears. + </li> + <li> + Next to <em>Test Project Name</em>, enter a name for the project. You may use any name, + but you may want to associate the name with the project name for the application under test. + One way to do this is to take the application's project name, append the string "Test" to + it, and then use this as the test package project name. + <p> + The name becomes part of the suggested project path, but you can change this in the + next step. + </p> + </li> + <li> + In the <em>Content</em> panel, examine the suggested path to the project. + If <em>Use default location</em> is set, then the wizard will suggest a path that is + a concatenation of the workspace path and the project name you entered. For example, + if your workspace path is <code>/usr/local/workspace</code> and your project name is + <code>MyTestApp</code>, then the wizard will suggest + <code>/usr/local/workspace/MyTestApp</code>. To enter your own + choice for a path, unselect <em>Use default location</em>, then enter or browse to the + path where you want your project. + <p> + To learn more about choosing the location of test projects, please read + <a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjectPaths"> + Testing Fundamentals</a>. + </p> + </li> + <li> + In the Test Target panel, set An Existing Android Project, click Browse, then select your + Android application from the list. You now see that the wizard has completed the Test + Target Package, Application Name, and Package Name fields for you (the latter two are in + the Properties panel). + </li> + <li> + In the Build Target panel, select the Android SDK platform that the application under test + uses. + </li> + <li> + Click Finish to complete the wizard. If Finish is disabled, look for error messages at the + top of the wizard dialog, and then fix any problems. + </li> </ol> +<h2 id="CreateTestAppEclipse">Creating a Test Package</h2> +<p> + Once you have created a test project, you populate it with a test package. This package does not + require an Activity, although you can define one if you wish. Although your test package can + combine Activity classes, test case classes, or ordinary classes, your main test case + should extend one of the Android test case classes or JUnit classes, because these provide the + best testing features. +</p> <p> + Test packages do not need to have an Android GUI. When you run the package in + Eclipse with ADT, its results appear in the JUnit view. Running tests and seeing the results is + described in more detail in the section <a href="#RunTestEclipse">Running Tests</a>. +</p> +<p> + To create a test package, start with one of Android's test case classes defined in + {@link android.test android.test}. These extend the JUnit + {@link junit.framework.TestCase TestCase} class. The Android test classes for Activity objects + also provide instrumentation for testing an Activity. To learn more about test case + classes, please read the topic <a href="{@docRoot}guide/topics/testing/testing_android.html"> + Testing Fundamentals</a>. </p> -<h2 id="CreateTestAppEclipse">Creating a Test Application</h2> <p> - Once you have created a test project, you populate it with a test - Android application. This application does not require an {@link android.app.Activity Activity}, - although you can define one if you wish. Although your test application can - combine Activities, Android test class extensions, JUnit extensions, or - ordinary classes, you should extend one of the Android test classes or JUnit classes, - because these provide the best testing features. + Before you create your test package, you choose the Java package identifier you want to use + for your test case classes and the Android package name you want to use. To learn more + about this, please read + <a href="{@docRoot}guide/topics/testing/testing_android.html#PackageNames"> + Testing Fundamentals</a>. </p> <p> - Test applications do not have an Android GUI. Instead, when you run the application in - Eclipse with ADT, its results appear in the JUnit view. If you run - your tests with {@link android.test.InstrumentationTestRunner InstrumentationTestRunner} (or a related test runner), - then it will run all the methods in each class. You can modify this behavior - by using the {@link junit.framework.TestSuite TestSuite} class. + To add a test case class to your project: </p> - +<ol> + <li> + In the <em>Project Explorer</em> tab, open your test project, then open the <em>src</em> + folder. + </li> + <li> + Find the Java package identifier set by the projection creation wizard. If you haven't + added classes yet, this node won't have any children, and its icon will not be filled in. + If you want to change the identifier value, right-click the identifier and select + <strong>Refactor</strong> > <strong>Rename</strong>, then enter the new name. + </li> + <li> + When you are ready, right-click the Java package identifier again and select + <strong>New</strong> > <strong>Class</strong>. This displays the <em>New Java Class</em> + dialog, with the <em>Source folder</em> and <em>Package</em> values already set. + </li> + <li> + In the <em>Name</em> field, enter a name for the test case class. One way to choose a + class name is to append the string "Test" to the class of the component you are testing. + For example, if you are testing the class MyAppActivity, your test case class + name would be MyAppActivityTest. Leave the modifiers set to <em>public</em>. + </li> + <li> + In the <em>Superclass</em> field, enter the name of the Android test case class you + are extending. You can also browse the available classes. + </li> + <li> + In <em>Which method stubs would you like to create?</em>, unset all the options, then + click <strong>Finish</strong>. You will set up the constructor manually. + </li> + <li> + Your new class appears in a new Java editor pane. + </li> +</ol> <p> - To create a test application, start with one of Android's test classes in the Java package {@link android.test android.test}. - These extend the JUnit {@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test classes - also provide instrumentation for testing. + You now have to ensure that the constructor is set up correctly. Create a constructor for your + class that has no arguments; this is required by JUnit. As the first statement in this + constructor, add a call to the base class' constructor. Each base test case class has its + own constructor signature. Refer to the class documentation in the documentation for + {@link android.test} for more information. </p> <p> - For test classes that extend {@link junit.framework.TestCase TestCase}, you probably want to override - the <code>setUp()</code> and <code>tearDown()</code> methods: + To control your test environment, you will want to override the <code>setUp()</code> and + <code>tearDown()</code> methods: </p> <ul> - <li> - <code>setUp()</code>: This method is invoked before any of the test methods in the class. - Use it to set up the environment for the test. You can use <code>setUp()</code> - to instantiate a new <code>Intent</code> object with the action <code>ACTION_MAIN</code>. You can - then use this intent to start the Activity under test. - <p class="note"><strong>Note:</strong> If you override this method, call - <code>super.setUp()</code> as the first statement in your code. - </p> - </li> - <li> - <code>tearDown()</code>: This method is invoked after all the test methods in the class. Use - it to do garbage collection and re-setting before moving on to the next set of tests. - <p class="note"><strong>Note:</strong> If you override this method, you must call - <code>super.tearDown()</code> as the <em>last</em> statement in your code.</p> - </li> + <li> + <code>setUp()</code>: This method is invoked before any of the test methods in the class. + Use it to set up the environment for the test (the test fixture. You can use + <code>setUp()</code> to instantiate a new Intent with the action <code>ACTION_MAIN</code>. + You can then use this intent to start the Activity under test. + </li> + <li> + <code>tearDown()</code>: This method is invoked after all the test methods in the class. Use + it to do garbage collection and to reset the test fixture. + </li> </ul> <p> - Another useful convention is to add the method <code>testPreConditions()</code> to your test - class. Use this method to test that the application under test is initialized correctly. If this - test fails, you know that that the initial conditions were in error. When this happens, further test - results are suspect, regardless of whether or not the tests succeeded. + Another useful convention is to add the method <code>testPreconditions()</code> to your test + class. Use this method to test that the application under test is initialized correctly. If this + test fails, you know that that the initial conditions were in error. When this happens, further + test results are suspect, regardless of whether or not the tests succeeded. </p> <p> - The Resources tab contains an <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> - tutorial with more information about creating test classes and methods. + The Resources tab contains an + <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> + tutorial with more information about creating test classes and methods. </p> <h2 id="RunTestEclipse">Running Tests</h2> -<div class="sidebox-wrapper"> - <div class="sidebox"> - <h2>Running tests from the command line</h2> - <p> - If you've created your tests in Eclipse, you can still run your tests and test - suites by using command-line tools included with the Android SDK. You may want to - do this, for example, if you have a large number of tests to run, if you have a - large test case, or if you want a fine level of control over which tests are run at - a particular time. - </p> - <p> - To run tests created in Eclipse with ADT with command-line tools, you must first - install additional files into the test project using the <code>android</code> tool's - "create test-project" option. To see how to do this, read the section - <a href="{@docRoot}guide/developing/testing/testing_otheride.html#CreateProject"> - Creating a test project</a> in the topic - <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other - IDEs</a>. - </p> + <div class="sidebox-wrapper"> + <div class="sidebox"> + <h2>Running tests from the command line</h2> + <p> + If you've created your tests in Eclipse, you can still run your tests and test + suites by using command-line tools included with the Android SDK. You may want + to do this, for example, if you have a large number of tests to run, if you + have a large test case, or if you want a fine level of control over which + tests are run at a particular time. + </p> + <p> + To run tests created in Eclipse with ADT with command-line tools, you must first + install additional files into the test project using the <code>android</code> + tool's "create test-project" option. To see how to do this, read + <a href="{@docRoot}guide/developing/testing/testing_otheride.html#CreateProject"> + Testing in Other IDEs</a>. + </p> + </div> </div> -</div> <p> - When you run a test application in Eclipse with ADT, the output appears in - an Eclipse view panel. You can run the entire test application, one class, or one - method of a class. To do this, Eclipse runs the <code>adb</code> command for running a test application, and - displays the output, so there is no difference between running tests inside Eclipse and running them from the command line. + When you run a test package in Eclipse with ADT, the output appears in the Eclipse JUnit view. + You can run the entire test package or one test case class. To do run tests, Eclipse runs the + <code>adb</code> command for running a test package, and displays the output, so there is no + difference between running tests inside Eclipse and running them from the command line. </p> <p> - As with any other application, to run a test application in Eclipse with ADT you must either attach a device to your - computer or use the Android emulator. If you use the emulator, you must have an Android Virtual Device (AVD) that uses - the same target + As with any other package, to run a test package in Eclipse with ADT you must either attach a + device to your computer or use the Android emulator. If you use the emulator, you must have an + Android Virtual Device (AVD) that uses the same target as the test package. </p> <p> - To run a test in Eclipse, you have two choices:</p> + To run a test in Eclipse, you have two choices:</p> +<ul> + <li> + Run a test just as you run an application, by selecting + <strong>Run As... > Android JUnit Test</strong> from the project's context menu or + from the main menu's <strong>Run</strong> item. + </li> + <li> + Create an Eclipse run configuration for your test project. This is useful if you want + multiple test suites, each consisting of selected tests from the project. To run + a test suite, you run the test configuration. + <p> + Creating and running test configurations is described in the next section. + </p> + </li> +</ul> +<p> + To create and run a test suite using a run configuration: +</p> <ol> - <li> - Run a test just as you run an application, by selecting - <strong>Run As... > Android JUnit Test</strong> from the project's context menu or - from the main menu's <strong>Run</strong> item. - </li> - <li> - Create an Eclipse run configuration for your test project. This is useful if you want multiple test suites, each consisting of selected tests from the project. To run - a test suite, you run the test configuration. - <p> - Creating and running test configurations is described in the next section. - </p> - </li> + <li> + In the Package Explorer, select the test project, then from the main menu, select + <strong>Run > Run Configurations...</strong>. The Run Configurations dialog appears. + </li> + <li> + In the left-hand pane, find the Android JUnit Test entry. In the right-hand pane, click the + Test tab. The Name: text box shows the name of your project. The Test class: dropdown box + shows one of the test classes in your project. + </li> + <li> + To run one test class, click Run a single test, then enter your project name in the + Project: text box and the class name in the Test class: text box. + <p> + To run all the test classes, click Run all tests in the selected project or package, + then enter the project or package name in the text box. + </p> + </li> + <li> + Now click the Target tab. + <ul> + <li> + Optional: If you are using the emulator, click Automatic, then in the Android + Virtual Device (AVD) selection table, select an existing AVD. + </li> + <li> + In the Emulator Launch Parameters pane, set the Android emulator flags you want to + use. These are documented in the topic + <a href="{@docRoot}guide/developing/tools/emulator.html#startup-options"> + Android Emulator</a>. + </li> + </ul> + </li> + <li> + Click the Common tab. In the Save As pane, click Local to save this run configuration + locally, or click Shared to save it to another project. + </li> + <li> + Optional: Add the configuration to the Run toolbar and the <strong>Favorites</strong> + menu: in the Display in Favorites pane click the checkbox next to Run. + </li> + <li> + Optional: To add this configuration to the <strong>Debug</strong> menu and toolbar, click + the checkbox next to Debug. + </li> + <li> + To save your settings, click Close.<br/> + <p class="note"><strong>Note:</strong> + Although you can run the test immediately by clicking Run, you should save the test + first and then run it by selecting it from the Eclipse standard toolbar. + </p> + </li> + <li> + On the Eclipse standard toolbar, click the down arrow next to the green Run arrow. This + displays a menu of saved Run and Debug configurations. + </li> + <li> + Select the test run configuration you just created. The test starts. + </li> </ol> -<p>To create and run a test suite using a run configuration:</p> -<ol> - <li> - In the Package Explorer, select the test - project, then from the main menu, select - <strong>Run > Run Configurations...</strong>. The - Run Configurations dialog appears. - </li> - <li> - In the left-hand pane, find the - Android JUnit Test entry. - In the right-hand pane, click the Test tab. - The Name: text box - shows the name of your project. The - Test class: dropdown box shows one your project's classes - test classes in your project. - </li> - <li> - To run one test class, click Run a single test, then enter your project - name in the Project: text box and the class name in the - Test class: text box. - <p> - To run all the test classes, - click Run all tests in the selected project or package, - then enter the project or package name in the text box. - </p> - </li> - <li> - Now click the Target tab. - <ul> - <li> - Optional: If you are using the emulator, click - Automatic, then in the Android Virtual Device (AVD) - selection table, select an existing AVD. - </li> - <li> - In the Emulator Launch Parameters pane, set the - Android emulator flags you want to use. These are documented in the topic - <a href="{@docRoot}guide/developing/tools/emulator.html#startup-options">Emulator Startup Options</a>. - </li> - </ul> - <li> - Click the Common tab. In the - Save As pane, click Local to save - this run configuration locally, or click Shared to - save it to another project. - </li> - <li> - Optional: Add the configuration to the Run toolbar and the <strong>Favorites</strong> - menu: in the Display in Favorites pane - click the checkbox next to Run. - </li> - <li> - Optional: To add this configuration to the <strong>Debug</strong> menu and toolbar, click - the checkbox next to Debug. - </li> - <li> - To save your settings, click Close.<br/> - <p class="note"><strong>Note:</strong> Although you can run the test immediately by - clicking Run, you should save the test first and then - run it by selecting it from the Eclipse standard toolbar.</p> - </li> - <li> - On the Eclipse standard toolbar, click the down arrow next to the - green Run arrow. This displays a menu of saved Run and Debug - configurations. - </li> - <li> - Select the test run configuration you just created. - </li> - <li> - The progress of your test appears in the Console view. - You should see the following messages, among others: - <ul> - <li> - <code>Performing Android.test.InstrumentationTestRunner JUnit launch</code><br> - The class name that proceeds "JUnit" depends on the Android instrumentation - class you have chosen. - </li> - <li> - If you are using an emulator and you have not yet started it, then you will see +<p> + The progress of your test appears in the Console view as a series of messages. Each message is + preceded by a timestamp and the <code>.apk</code> filename to which it applies. For example, + this message appears when you run a test to the emulator, and the emulator is not yet started: +</p> +<div class="sidebox-wrapper"> + <div class="sidebox"> + <h2>Message Examples</h2> + <p> + The examples shown in this section come from the + <a href="{@docRoot}resources/samples/SpinnerTest/index.html">SpinnerTest</a> + sample test package, which tests the + <a href="{@docRoot}resources/samples/Spinner/index.html">Spinner</a> + sample application. This test package is also featured in the + <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> + tutorial. + </p> + </div> +</div> +<pre> + [<em>yyyy-mm-dd hh:mm:ss</em> - <em>testfile</em>] Waiting for HOME ('android.process.acore') to be launched... +</pre> +<p> + In the following description of these messages, <code><em>devicename</em></code> is the name of + the device or emulator you are using to run the test, and <code><em>port</em></code> is the + port number for the device. The name and port number are in the format used by the + <code><a href="{@docRoot}guide/developing/tools/adb.html#devicestatus">adb devices</a></code> + command. Also, <code><em>testfile</em></code> is the <code>.apk</code> filename of the test + package you are running, and <em>appfile</em> is the filename of the application under test. +</p> +<ul> + <li> + If you are using an emulator and you have not yet started it, then Eclipse + first starts the emulator. When this is complete, you see the message: <p> - <code>Automatic Target Mode: launching new emulator with compatible - AVD <em>avdname</em></code><br>(where <em>avdname</em> is the name of - the AVD you are using.) + <code>HOME is up on device '<em>devicename</em>-<em>port</em>'</code> </p> - </li> - <li> - If you have not already installed your test application, then you will see + </li> + <li> + If you have not already installed your test package, then you see the message: <p> - <code>Uploading <em>testclass</em>.apk onto device '<em>device-id</em>'</code><br> - where <em>testclass</em> is the name of your unit test class and <em>device-id</em> - is the name and port for your test device or emulator, followed by the message <code>Installing <em>testclass</em>.apk</code> + <code>Uploading <em>testfile</em> onto device '<em>devicename</em>-<em>port</em>' + </code> </p> - </li> - <li> - <code>Launching instrumentation Android.test.InstrumentationTestRunner on device <em>device-id</em></code>.<br> - This indicates that Android's Instrumentation system is now testing your code. Again, the - instrumentation class name depends on the Android instrumentation class you have chosen. - </li> - <li> - <code>Test run complete</code>.<br> When you see this, your unit tests have finished. - </li> - </ul> -</ol> + <p> + then the message <code>Installing <em>testfile</em></code>. + </p> + <p> + and finally the message <code>Success!</code> + </p> + </li> +</ul> <p> - The test results appear in the JUnit view. This is divided into an upper summary pane, - and a lower stack trace pane. + The following lines are an example of this message sequence: </p> +<code> +[2010-07-01 12:44:40 - MyTest] HOME is up on device 'emulator-5554'<br> +[2010-07-01 12:44:40 - MyTest] Uploading MyTest.apk onto device 'emulator-5554'<br> +[2010-07-01 12:44:40 - MyTest] Installing MyTest.apk...<br> +[2010-07-01 12:44:49 - MyTest] Success!<br> +</code> +<br> +<ul> + <li> + Next, if you have not yet installed the application under test to the device or + emulator, you see the message + <p> + <code>Project dependency found, installing: <em>appfile</em></code> + </p> + <p> + then the message <code>Uploading <em>appfile</em></code> onto device + '<em>devicename</em>-<em>port</em>' + </p> + <p> + then the message <code>Installing <em>appfile</em></code> + </p> + <p> + and finally the message <code>Success!</code> + </p> + </li> +</ul> <p> - The upper pane contains test information. In the pane's header, you see the following - information: + The following lines are an example of this message sequence: </p> - <ul> - <li> - Total time elapsed for the test application (labeled Finished after <em>x</em> seconds). - </li> - <li> - Number of runs (Runs:) - the number of tests in the entire test class. - </li> - <li> - Number of errors (Errors:) - the number of program errors and exceptions encountered - during the test run. - </li> - <li> - Number of failures (Failures:) - the number of test failures encountered during the test - run. This is the number of assertion failures. A test can fail even if the program does - not encounter an error. - </li> - <li> - A progress bar. The progress bar extends from left to right as the tests run. If all the - tests succeed, the bar remains green. If a test fails, the bar turns from green to red. - </li> - </ul> +<code> +[2010-07-01 12:44:49 - MyTest] Project dependency found, installing: MyApp<br> +[2010-07-01 12:44:49 - MyApp] Uploading MyApp.apk onto device 'emulator-5554'<br> +[2010-07-01 12:44:49 - MyApp] Installing MyApp.apk...<br> +[2010-07-01 12:44:54 - MyApp] Success!<br> +</code> +<br> +<ul> + <li> + Next, you see the message + <code>Launching instrumentation <em>instrumentation_class</em> on device + <em>devicename</em>-<em>port</em></code> + <p> + <code>instrumentation_class</code> is the fully-qualified class name of the + instrumentation test runner you have specified (usually + {@link android.test.InstrumentationTestRunner}. + </p> + </li> + <li> + Next, as {@link android.test.InstrumentationTestRunner} builds a list of tests to run, + you see the message + <p> + <code>Collecting test information</code> + </p> + <p> + followed by + </p> + <p> + <code>Sending test information to Eclipse</code> + </p> + </li> + <li> + Finally, you see the message <code>Running tests</code>, which indicates that your tests + are running. At this point, you should start seeing the test results in the JUnit view. + When the tests are finished, you see the console message <code>Test run complete</code>. + This indicates that your tests are finished. + </li> +</ul> +<p> + The following lines are an example of this message sequence: +</p> +<code> +[2010-01-01 12:45:02 - MyTest] Launching instrumentation android.test.InstrumentationTestRunner on device emulator-5554<br> +[2010-01-01 12:45:02 - MyTest] Collecting test information<br> +[2010-01-01 12:45:02 - MyTest] Sending test information to Eclipse<br> +[2010-01-01 12:45:02 - MyTest] Running tests...<br> +[2010-01-01 12:45:22 - MyTest] Test run complete<br> +</code> +<br> +<p> + The test results appear in the JUnit view. This is divided into an upper summary pane, + and a lower stack trace pane. +</p> +<p> + The upper pane contains test information. In the pane's header, you see the following + information: +</p> +<ul> + <li> + Total time elapsed for the test package (labeled Finished after <em>x</em> seconds). + </li> + <li> + Number of runs (Runs:) - the number of tests in the entire test class. + </li> + <li> + Number of errors (Errors:) - the number of program errors and exceptions encountered + during the test run. + </li> + <li> + Number of failures (Failures:) - the number of test failures encountered during the test + run. This is the number of assertion failures. A test can fail even if the program does + not encounter an error. + </li> + <li> + A progress bar. The progress bar extends from left to right as the tests run. If all the + tests succeed, the bar remains green. If a test fails, the bar turns from green to red. + </li> +</ul> <p> The body of the upper pane contains the details of the test run. For each test case class that was run, you see a line with the class name. To look at the results for the individual @@ -363,8 +505,30 @@ page.title=Testing In Eclipse, with ADT pane and moves the focus to the first line of the test method. </p> <p> + The results of a successful test are shown in + <a href="#TestResults">Figure 1. Messages for a successful test</a>: +</p> +<a href="{@docRoot}images/testing/eclipse_test_results.png"> + <img src="{@docRoot}images/testing/eclipse_test_results.png" + alt="Messages for a successful test" height="327px" id="TestResults"/> +</a> +<p class="img-caption"> + <strong>Figure 1.</strong> Messages for a successful test +</p> +<p> The lower pane is for stack traces. If you highlight a failed test in the upper pane, the lower pane contains a stack trace for the test. If a line corresponds to a point in your test code, you can double-click it to display the code in an editor view pane, with the line highlighted. For a successful test, the lower pane is empty. </p> +<p> + The results of a failed test are shown in + <a href="#FailedTestResults">Figure 2. Messages for a test failure</a> +</p> +<a href="{@docRoot}images/testing/eclipse_test_run_failure.png"> + <img src="{@docRoot}images/testing/eclipse_test_run_failure.png" + alt="Messages for a test failure" height="372px" id="TestRun"/> +</a> +<p class="img-caption"> + <strong>Figure 2.</strong> Messages for a test failure +</p> diff --git a/docs/html/guide/developing/testing/testing_otheride.jd b/docs/html/guide/developing/testing/testing_otheride.jd index 2bdf4d0..523a8e5 100644 --- a/docs/html/guide/developing/testing/testing_otheride.jd +++ b/docs/html/guide/developing/testing/testing_otheride.jd @@ -2,122 +2,128 @@ page.title=Testing In Other IDEs @jd:body <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li> - <a href="#CreateTestProjectCommand">Working with Test Projects</a> - <ol> - <li> - <a href="#CreateTestProject">Creating a test project</a> - </li> - <li> - <a href="#UpdateTestProject">Updating a test project</a> - </li> - </ol> - </li> - <li> - <a href="#CreateTestApp">Creating a Test Application</a> - </li> - <li> - <a href="#RunTestsCommand">Running Tests</a> - <ol> - <li> - <a href="#RunTestsAnt">Quick build and run with Ant</a> - </li> - <li> - <a href="#RunTestsDevice">Running tests on a device or emulator</a> - </li> - </ol> - </li> - <li> - <a href="#AMSyntax">Using the Instrument Command</a> - <ol> - <li> - <a href="#AMOptionsSyntax">Instrument options</a> - </li> - <li> - <a href="#RunTestExamples">Instrument examples</a> - </li> - </ol> - </li> - - </ol> - <h2>See Also</h2> - <ol> - <li> - <a - href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a> - </li> - <li> - <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> - </li> - <li> - <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> - </li> - </ol> - </div> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li> + <a href="#CreateTestProjectCommand">Working with Test Projects</a> + <ol> + <li> + <a href="#CreateTestProject">Creating a test project</a> + </li> + <li> + <a href="#UpdateTestProject">Updating a test project</a> + </li> + </ol> + </li> + <li> + <a href="#CreateTestApp">Creating a Test Package</a> + </li> + <li> + <a href="#RunTestsCommand">Running Tests</a> + <ol> + <li> + <a href="#RunTestsAnt">Quick build and run with Ant</a> + </li> + <li> + <a href="#RunTestsDevice">Running tests on a device or emulator</a> + </li> + </ol> + </li> + <li> + <a href="#AMSyntax">Using the Instrument Command</a> + <ol> + <li> + <a href="#AMOptionsSyntax">Instrument options</a> + </li> + <li> + <a href="#RunTestExamples">Instrument examples</a> + </li> + </ol> + </li> + </ol> + <h2>See Also</h2> + <ol> + <li> + <a href="{@docRoot}guide/topics/testing/testing_android.html"> + Testing Fundamentals</a> + </li> + <li> + <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> + </li> + </ol> + </div> </div> <p> - This document describes how to create and run tests directly from the command line. - You can use the techniques described here if you are developing in an IDE other than Eclipse - or if you prefer to work from the command line. This document assumes that you already know how - to create a Android application in your programming environment. Before you start this - document, you should read the document <a - href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a>, - which provides an overview of Android testing. + This document describes how to create and run tests directly from the command line. + You can use the techniques described here if you are developing in an IDE other than Eclipse + or if you prefer to work from the command line. This document assumes that you already know how + to create a Android application in your programming environment. Before you start this + document, you should read the topic + <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, + which provides an overview of Android testing. </p> <p> - If you are developing in Eclipse with ADT, you can set up and run your tests -directly in Eclipse. For more information, please read <a - href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in Eclipse, with ADT</a>. + If you are developing in Eclipse with ADT, you can set up and run your tests + directly in Eclipse. For more information, please read + <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> + Testing in Eclipse, with ADT</a>. </p> <h2 id="CreateTestProjectCommand">Working with Test Projects</h2> <p> - You use the <code>android</code> tool to create test projects. - You also use <code>android</code> to convert existing test code into an Android test project, - or to add the <code>run-tests</code> Ant target to an existing Android test project. - These operations are described in more detail in the section <a - href="#UpdateTestProject">Updating a test project</a>. - The <code>run-tests</code> target is described in <a - href="#RunTestsAnt">Quick build and run with Ant</a>. + You use the <code>android</code> tool to create test projects. + You also use <code>android</code> to convert existing test code into an Android test project, + or to add the <code>run-tests</code> Ant target to an existing Android test project. + These operations are described in more detail in the section <a href="#UpdateTestProject"> + Updating a test project</a>. The <code>run-tests</code> target is described in + <a href="#RunTestsAnt">Quick build and run with Ant</a>. </p> <h3 id="CreateTestProject">Creating a test project</h3> <p> - To create a test project with the <code>android</code> tool, enter: -<pre>android create test-project -m <main_path> -n <project_name> -p <test_path></pre> + To create a test project with the <code>android</code> tool, enter: +</p> +<pre> +android create test-project -m <main_path> -n <project_name> -p <test_path> +</pre> <p> - You must supply all the flags. The following table explains them in detail: + You must supply all the flags. The following table explains them in detail: </p> <table> - <tr> - <th>Flag</th> - <th>Value</th> - <th>Description</th> - <tr> - <td><code>-m, --main</code></td> - <td> - Path to the project of the application under test, relative to the test application - directory. - </td> - <td> - For example, if the application under test is in <code>source/HelloAndroid</code>, and you - want to create the test project in <code>source/HelloAndroidTest</code>, then the value of - <code>--main</code> should be <code>../HelloAndroid</code>. - </td> - <tr> - <td><code>-n, --name</code></td> - <td>Name that you want to give the test project.</td> - <td> </td> - </tr> - <tr> - <td><code>-p, --path</code></td> - <td>Directory in which you want to create the new test project.</td> - <td> - The <code>android</code> tool creates the test project files and directory structure in this - directory. If the directory does not exist, <code>android</code> creates it. - </td> - </tr> + <tr> + <th>Flag</th> + <th>Value</th> + <th>Description</th> + </tr> + <tr> + <td><code>-m, --main</code></td> + <td> + Path to the project of the application under test, relative to the test package + directory. + </td> + <td> + For example, if the application under test is in <code>source/HelloAndroid</code>, and + you want to create the test project in <code>source/HelloAndroidTest</code>, then the + value of <code>--main</code> should be <code>../HelloAndroid</code>. + <p> + To learn more about choosing the location of test projects, please read + <a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjects"> + Testing Fundamentals</a>. + </p> + </td> + </tr> + <tr> + <td><code>-n, --name</code></td> + <td>Name that you want to give the test project.</td> + <td> </td> + </tr> + <tr> + <td><code>-p, --path</code></td> + <td>Directory in which you want to create the new test project.</td> + <td> + The <code>android</code> tool creates the test project files and directory structure + in this directory. If the directory does not exist, <code>android</code> creates it. + </td> + </tr> </table> <p> If the operation is successful, <code>android</code> lists to STDOUT the names of the files @@ -135,11 +141,10 @@ directly in Eclipse. For more information, please read <a are testing and control it with instrumentation. </p> <p> - For example, suppose you create the <a - href="{@docRoot}resources/tutorials/hello-world.html">Hello, World</a> tutorial application - in the directory <code>~/source/HelloAndroid</code>. In the tutorial, this application uses the - package name <code>com.example.helloandroid</code> and the activity name - <code>HelloAndroid</code>. You can to create the test for this in + For example, suppose you create the <a href="{@docRoot}resources/tutorials/hello-world.html"> + Hello, World</a> tutorial application in the directory <code>~/source/HelloAndroid</code>. + In the tutorial, this application uses the package name <code>com.example.helloandroid</code> + and the activity name <code>HelloAndroid</code>. You can to create the test for this in <code>~/source/HelloAndroidTest</code>. To do so, you enter: </p> <pre> @@ -196,7 +201,7 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd <p class="note"> <strong>Note:</strong> If you change the Android package name of the application under test, you must <em>manually</em> change the value of the <code><android:targetPackage></code> - attribute within the <code>AndroidManifest.xml</code> file of the test application. + attribute within the <code>AndroidManifest.xml</code> file of the test package. Running <code>android update test-project</code> does not do this. </p> <p> @@ -205,38 +210,38 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd <pre>android update-test-project -m <main_path> -p <test_path></pre> <table> -<tr> - <th>Flag</th> - <th>Value</th> - <th>Description</th> -</tr> -<tr> - <td><code>-m, --main</code></td> - <td>The path to the project of the application under test, relative to the test project</td> - <td> - For example, if the application under test is in <code>source/HelloAndroid</code>, and - the test project is in <code>source/HelloAndroidTest</code>, then the value for - <code>--main</code> is <code>../HelloAndroid</code>. - </td> -</tr> -<tr> - <td><code>-p, --path</code></td> - <td>The of the test project.</td> - <td> - For example, if the test project is in <code>source/HelloAndroidTest</code>, then the - value for <code>--path</code> is <code>HelloAndroidTest</code>. - </td> -</tr> + <tr> + <th>Flag</th> + <th>Value</th> + <th>Description</th> + </tr> + <tr> + <td><code>-m, --main</code></td> + <td>The path to the project of the application under test, relative to the test project</td> + <td> + For example, if the application under test is in <code>source/HelloAndroid</code>, and + the test project is in <code>source/HelloAndroidTest</code>, then the value for + <code>--main</code> is <code>../HelloAndroid</code>. + </td> + </tr> + <tr> + <td><code>-p, --path</code></td> + <td>The of the test project.</td> + <td> + For example, if the test project is in <code>source/HelloAndroidTest</code>, then the + value for <code>--path</code> is <code>HelloAndroidTest</code>. + </td> + </tr> </table> <p> If the operation is successful, <code>android</code> lists to STDOUT the names of the files and directories it has created. </p> -<h2 id="CreateTestApp">Creating a Test Application</h2> +<h2 id="CreateTestApp">Creating a Test Package</h2> <p> - Once you have created a test project, you populate it with a test application. + Once you have created a test project, you populate it with a test package. The application does not require an {@link android.app.Activity Activity}, - although you can define one if you wish. Although your test application can + although you can define one if you wish. Although your test package can combine Activities, Android test class extensions, JUnit extensions, or ordinary classes, you should extend one of the Android test classes or JUnit classes, because these provide the best testing features. @@ -248,7 +253,7 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd </p> <p> - To create a test application, start with one of Android's test classes in the Java package + To create a test package, start with one of Android's test classes in the Java package {@link android.test android.test}. These extend the JUnit {@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test classes also provide instrumentation for testing. @@ -282,24 +287,17 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd test results are suspect, regardless of whether or not the tests succeeded. </p> <p> - To learn more about creating test applications, see the topic <a - href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a>, + To learn more about creating test packages, see the topic <a + href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, which provides an overview of Android testing. If you prefer to follow a tutorial, try the <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> tutorial, which leads you through the creation of tests for an actual Android application. </p> <h2 id="RunTestsCommand">Running Tests</h2> <p> - If you are not developing in Eclipse with ADT, you need to run tests from the command line. - You can do this either with Ant or with the {@link android.app.ActivityManager ActivityManager} - command line interface. -</p> -<p> - You can also run tests from the command line even if you are using Eclipse with ADT to develop - them. To do this, you need to create the proper files and directory structure in the test - project, using the <code>android</code> tool with the option <code>create test-project</code>. - This is described in the section <a - href="#CreateTestProjectCommand">Working with Test Projects</a>. + You run tests from the command line, either with Ant or with an + <a href="{@docRoot}http://developer.android.com/guide/developing/tools/adb.html"> + Android Debug Bridge (adb)</a> shell. </p> <h3 id="RunTestsAnt">Quick build and run with Ant</h3> <p> @@ -316,57 +314,63 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd You can update an existing test project to use this feature. To do this, use the <code>android</code> tool with the <code>update test-project</code> option. This is described in the section <a href="#UpdateTestProject">Updating a test project</a>. +</p> <h3 id="RunTestsDevice">Running tests on a device or emulator</h3> <p> - When you run tests from the command line with the ActivityManager (<code>am</code>) - command-line tool, you get more options for choosing the tests to run than with any other - method. You can select individual test methods, filter tests according to their annotation, or - specify testing options. Since the test run is controlled entirely from a command line, you can - customize your testing with shell scripts in various ways. + When you run tests from the command line with + <a href="{@docRoot}http://developer.android.com/guide/developing/tools/adb.html"> + Android Debug Bridge (adb)</a>, you get more options for choosing the tests + to run than with any other method. You can select individual test methods, filter tests + according to their annotation, or specify testing options. Since the test run is controlled + entirely from a command line, you can customize your testing with shell scripts in various ways. +</p> +<p> + To run a test from the command line, you run <code>adb shell</code> to start a command-line + shell on your device or emulator, and then in the shell run the <code>am instrument</code> + command. You control <code>am</code> and your tests with command-line flags. </p> <p> - You run the <code>am</code> tool on an Android device or emulator using the - <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> - (<code>adb</code>) shell. When you do this, you use the ActivityManager - <code>instrument</code> option to run your test application using an Android test runner - (usually {@link android.test.InstrumentationTestRunner}). You set <code>am</code> - options with command-line flags. + As a shortcut, you can start an <code>adb</code> shell, call <code>am instrument</code>, and + specify command-line flags all on one input line. The shell opens on the device or emulator, + runs your tests, produces output, and then returns to the command line on your computer. </p> <p> - To run a test with <code>am</code>: + To run a test with <code>am instrument</code>: </p> <ol> - <li> - If necessary, re-build your main application and test application. - </li> - <li> - Install your test application and main application Android package files - (<code>.apk</code> files) to your current Android device or emulator</li> - <li> - At the command line, enter: + <li> + If necessary, rebuild your main application and test package. + </li> + <li> + Install your test package and main application Android package files + (<code>.apk</code> files) to your current Android device or emulator</li> + <li> + At the command line, enter: <pre> $ adb shell am instrument -w <test_package_name>/<runner_class> </pre> -<p> - where <code><test_package_name></code> is the Android package name of your test - application, and <code><runner_class></code> is the name of the Android test runner - class you are using. The Android package name is the value of the <code>package</code> - attribute of the <code>manifest</code> element in the manifest file - (<code>AndroidManifest.xml</code>) of your test application. The Android test runner - class is usually <code>InstrumentationTestRunner</code>. -</p> -<p>Your test results appear in <code>STDOUT</code>.</p> - </li> + <p> + where <code><test_package_name></code> is the Android package name of your test + application, and <code><runner_class></code> is the name of the Android test + runner class you are using. The Android package name is the value of the + <code>package</code> attribute of the <code>manifest</code> element in the manifest file + (<code>AndroidManifest.xml</code>) of your test package. The Android test runner + class is usually {@link android.test.InstrumentationTestRunner}. + </p> + <p> + Your test results appear in <code>STDOUT</code>. + </p> + </li> </ol> <p> - This operation starts an <code>adb</code> shell, then runs <code>am instrument</code> in it + This operation starts an <code>adb</code> shell, then runs <code>am instrument</code> with the specified parameters. This particular form of the command will run all of the tests - in your test application. You can control this behavior with flags that you pass to + in your test package. You can control this behavior with flags that you pass to <code>am instrument</code>. These flags are described in the next section. </p> -<h2 id="AMSyntax">Using the Instrument Command</h2> +<h2 id="AMSyntax">Using the am instrument Command</h2> <p> - The general syntax of the <code>am instrument</code> command is: + The general syntax of the <code>am instrument</code> command is: </p> <pre> am instrument [flags] <test_package>/<runner_class> @@ -391,11 +395,11 @@ $ adb shell am instrument -w <test_package_name>/<runner_class> <code><test_package></code> </td> <td> - The Android package name of the test application. + The Android package name of the test package. </td> <td> The value of the <code>package</code> attribute of the <code>manifest</code> - element in the test application's manifest file. + element in the test package's manifest file. </td> </tr> <tr> @@ -411,7 +415,7 @@ $ adb shell am instrument -w <test_package_name>/<runner_class> </tr> </table> <p> -The flags for <code>am instrument</code> are described in the following table: + The flags for <code>am instrument</code> are described in the following table: </p> <table> <tr> @@ -461,20 +465,21 @@ The flags for <code>am instrument</code> are described in the following table: <test_options> </td> <td> - Provides testing options , in the form of key-value pairs. The + Provides testing options as key-value pairs. The <code>am instrument</code> tool passes these to the specified instrumentation class via its <code>onCreate()</code> method. You can specify multiple occurrences of - <code>-e <test_options</code>. The keys and values are described in the next table. + <code>-e <test_options></code>. The keys and values are described in the + section <a href="#AMOptionsSyntax">am instrument options</a>. <p> - The only instrumentation class that understands these key-value pairs is - <code>InstrumentationTestRunner</code> (or a subclass). Using them with + The only instrumentation class that uses these key-value pairs is + {@link android.test.InstrumentationTestRunner} (or a subclass). Using them with any other class has no effect. </p> </td> </tr> </table> -<h3 id="AMOptionsSyntax">Instrument options</h3> +<h3 id="AMOptionsSyntax">am instrument options</h3> <p> The <code>am instrument</code> tool passes testing options to <code>InstrumentationTestRunner</code> or a subclass in the form of key-value pairs, @@ -484,123 +489,127 @@ The flags for <code>am instrument</code> are described in the following table: -e <key> <value> </pre> <p> - Where applicable, a <key> may have multiple values separated by a comma (,). + Some keys accept multiple values. You specify multiple values in a comma-separated list. For example, this invocation of <code>InstrumentationTestRunner</code> provides multiple values for the <code>package</code> key: +</p> <pre> -$ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 com.android.test/android.test.InstrumentationTestRunner +$ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \ +> com.android.test/android.test.InstrumentationTestRunner </pre> <p> The following table describes the key-value pairs and their result. Please review the <strong>Usage Notes</strong> following the table. </p> <table> -<tr> - <th>Key</th> - <th>Value</th> - <th>Description</th> -</tr> -<tr> - <td> - <code>package</code> - </td> - <td> - <Java_package_name> - </td> - <td> - The fully-qualified <em>Java</em> package name for one of the packages in the test - application. Any test case class that uses this package name is executed. Notice that this - is not an <em>Android</em> package name; a test application has a single Android package - name but may have several Java packages within it. - </td> -</tr> -<tr> - <td rowspan="2"><code>class</code></td> - <td><class_name></td> - <td> - The fully-qualified Java class name for one of the test case classes. Only this test case - class is executed. - </td> -</tr> -<tr> - <td><class_name><strong>#</strong>method name</td> - <td> - A fully-qualified test case class name, and one of its methods. Only this method is - executed. Note the hash mark (#) between the class name and the method name. - </td> -</tr> -<tr> - <td><code>func</code></td> - <td><code>true</code></td> - <td> - Runs all test classes that extend {@link android.test.InstrumentationTestCase}. - </td> -</tr> -<tr> - <td><code>unit</code></td> - <td><code>true</code></td> - <td> - Runs all test classes that do <em>not</em> extend either - {@link android.test.InstrumentationTestCase} or {@link android.test.PerformanceTestCase}. - </td> -</tr> -<tr> - <td><code>size</code></td> - <td>[<code>small</code> | <code>medium</code> | <code>large</code>] - </td> - <td> - Runs a test method annotated by size. The annotations are <code>@SmallTest</code>, - <code>@MediumTest</code>, and <code>@LargeTest</code>. - </td> -</tr> -<tr> - <td><code>perf</code></td> - <td><code>true</code></td> - <td> - Runs all test classes that implement {@link android.test.PerformanceTestCase}. - When you use this option, also specify the <code>-r</code> flag for - <code>am instrument</code>, so that the output is kept in raw format and not - re-formatted as test results. - </td> -</tr> -<tr> - <td><code>debug</code></td> - <td><code>true</code></td> - <td> - Runs tests in debug mode. - </td> -</tr> -<tr> - <td><code>log</code></td> - <td><code>true</code></td> - <td> - Loads and logs all specified tests, but does not run them. The test - information appears in <code>STDOUT</code>. Use this to verify combinations of other filters - and test specifications. - </td> -</tr> -<tr> - <td><code>emma</code></td> - <td><code>true</code></td> - <td> - Runs an EMMA code coverage analysis and writes the output to <code>/data//coverage.ec</code> - on the device. To override the file location, use the <code>coverageFile</code> key that - is described in the following entry. - <p class="note"> - <strong>Note:</strong> This option requires an EMMA-instrumented build of the test - application, which you can generate with the <code>coverage</code> target. - </p> - </td> -</tr> -<tr> - <td><code>coverageFile</code></td> - <td><code><filename></code></td> - <td> - Overrides the default location of the EMMA coverage file on the device. Specify this - value as a path and filename in UNIX format. The default filename is described in the - entry for the <code>emma</code> key. - </td> -</tr> + <tr> + <th>Key</th> + <th>Value</th> + <th>Description</th> + </tr> + <tr> + <td> + <code>package</code> + </td> + <td> + <Java_package_name> + </td> + <td> + The fully-qualified <em>Java</em> package name for one of the packages in the test + application. Any test case class that uses this package name is executed. Notice that + this is not an <em>Android</em> package name; a test package has a single + Android package name but may have several Java packages within it. + </td> + </tr> + <tr> + <td rowspan="2"><code>class</code></td> + <td><class_name></td> + <td> + The fully-qualified Java class name for one of the test case classes. Only this test + case class is executed. + </td> + </tr> + <tr> + <td><class_name><strong>#</strong>method name</td> + <td> + A fully-qualified test case class name, and one of its methods. Only this method is + executed. Note the hash mark (#) between the class name and the method name. + </td> + </tr> + <tr> + <td><code>func</code></td> + <td><code>true</code></td> + <td> + Runs all test classes that extend {@link android.test.InstrumentationTestCase}. + </td> + </tr> + <tr> + <td><code>unit</code></td> + <td><code>true</code></td> + <td> + Runs all test classes that do <em>not</em> extend either + {@link android.test.InstrumentationTestCase} or + {@link android.test.PerformanceTestCase}. + </td> + </tr> + <tr> + <td><code>size</code></td> + <td> + [<code>small</code> | <code>medium</code> | <code>large</code>] + </td> + <td> + Runs a test method annotated by size. The annotations are <code>@SmallTest</code>, + <code>@MediumTest</code>, and <code>@LargeTest</code>. + </td> + </tr> + <tr> + <td><code>perf</code></td> + <td><code>true</code></td> + <td> + Runs all test classes that implement {@link android.test.PerformanceTestCase}. + When you use this option, also specify the <code>-r</code> flag for + <code>am instrument</code>, so that the output is kept in raw format and not + re-formatted as test results. + </td> + </tr> + <tr> + <td><code>debug</code></td> + <td><code>true</code></td> + <td> + Runs tests in debug mode. + </td> + </tr> + <tr> + <td><code>log</code></td> + <td><code>true</code></td> + <td> + Loads and logs all specified tests, but does not run them. The test + information appears in <code>STDOUT</code>. Use this to verify combinations of other + filters and test specifications. + </td> + </tr> + <tr> + <td><code>emma</code></td> + <td><code>true</code></td> + <td> + Runs an EMMA code coverage analysis and writes the output to + <code>/data//coverage.ec</code> on the device. To override the file location, use the + <code>coverageFile</code> key that is described in the following entry. + <p class="note"> + <strong>Note:</strong> This option requires an EMMA-instrumented build of the test + application, which you can generate with the <code>coverage</code> target. + </p> + </td> + </tr> + <tr> + <td><code>coverageFile</code></td> + <td><code><filename></code></td> + <td> + Overrides the default location of the EMMA coverage file on the device. Specify this + value as a path and filename in UNIX format. The default filename is described in the + entry for the <code>emma</code> key. + </td> + </tr> </table> <strong><code>-e</code> Flag Usage Notes</strong> <ul> @@ -618,13 +627,13 @@ $ adb shell am instrument -w -e package com.android.test.package1,com.android.te The <code>func</code> key and <code>unit</code> key are mutually exclusive. </li> </ul> -<h3 id="RunTestExamples">Instrument examples</h3> +<h3 id="RunTestExamples">Usage examples</h3> <p> -Here are some examples of using <code>am instrument</code> to run tests. They are based on -the following structure:</p> +The following sections provide examples of using <code>am instrument</code> to run tests. +They are based on the following structure:</p> <ul> <li> - The test application has the Android package name <code>com.android.demo.app.tests</code> + The test package has the Android package name <code>com.android.demo.app.tests</code> </li> <li> There are three test classes: @@ -647,35 +656,35 @@ the following structure:</p> The test runner is {@link android.test.InstrumentationTestRunner}. </li> </ul> -<h4>Running the Entire Test Application</h4> +<h4>Running the entire test package</h4> <p> - To run all of the test classes in the test application, enter: + To run all of the test classes in the test package, enter: </p> <pre> $ adb shell am instrument -w com.android.demo.app.tests/android.test.InstrumentationTestRunner </pre> -<h4>Running All Tests in a Test Case Class</h4> +<h4>Running all tests in a test case class</h4> <p> To run all of the tests in the class <code>UnitTests</code>, enter: </p> <pre> $ adb shell am instrument -w \ --e class com.android.demo.app.tests.UnitTests \ -com.android.demo.app.tests/android.test.InstrumentationTestRunner +> -e class com.android.demo.app.tests.UnitTests \ +> com.android.demo.app.tests/android.test.InstrumentationTestRunner </pre> <p> <code>am instrument</code> gets the value of the <code>-e</code> flag, detects the <code>class</code> keyword, and runs all the methods in the <code>UnitTests</code> class. </p> -<h4>Selecting a Subset of Tests</h4> +<h4>Selecting a subset of tests</h4> <p> - To run all of the tests in <code>UnitTests</code>, and the <code>testCamera</code> method in - <code>FunctionTests</code>, enter: + To run all of the tests in <code>UnitTests</code>, and the <code>testCamera</code> method in + <code>FunctionTests</code>, enter: </p> <pre> $ adb shell am instrument -w \ --e class com.android.demo.app.tests.UnitTests,com.android.demo.app.tests.FunctionTests#testCamera \ -com.android.demo.app.tests/android.test.InstrumentationTestRunner +> -e class com.android.demo.app.tests.UnitTests,com.android.demo.app.tests.FunctionTests#testCamera \ +> com.android.demo.app.tests/android.test.InstrumentationTestRunner </pre> <p> You can find more examples of the command in the documentation for diff --git a/docs/html/guide/developing/tools/MonkeyDevice.jd b/docs/html/guide/developing/tools/MonkeyDevice.jd new file mode 100644 index 0000000..34bbba9 --- /dev/null +++ b/docs/html/guide/developing/tools/MonkeyDevice.jd @@ -0,0 +1,1353 @@ +page.title=MonkeyDevice +@jd:body +<style> + h4.jd-details-title {background-color: #DEE8F1;} +</style> +<p> + A monkeyrunner class that represents a device or emulator accessible by the workstation running +<code><a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a></code>. +</p> +<p> + This class is used to control an Android device or emulator. The methods send UI events, + retrieve information, install and remove applications, and run applications. +</p> +<p> + You normally do not have to create an instance of <code>MonkeyDevice</code>. Instead, you + use +<code><a href="{@docRoot}guide/developing/tools/MonkeyRunner.html#waitForConnection"> +MonkeyRunner.waitForConnection()</a></code> to create a new object from a connection to a device or +emulator. For example, instead of +using:</p> +<pre> +newdevice = MonkeyDevice() +</pre> +<p> + you would use: +</p> +<pre> +newdevice = MonkeyRunner.waitForConnection() +</pre> +<h2>Summary</h2> + <table id="constants" class="jd-sumtable" style="background-color: white;"> + <tr> + <th colspan="12" style="background-color: #E2E2E2">Constants</th> + </tr> + <tr class="api" style="background-color: white;"> + <td class="jd-typecol"><em>string</em></td> + <td class="jd-linkcol"><a href="#ACTION_DOWN">DOWN</a></td> + <td class="jd-descrcol" width="100%"> + Use this with the <code>type</code> argument of + <code><a href="#press">press()</a></code> or <code><a href="#touch">touch()</a> + </code> + to send a DOWN event. + </td> + </tr> + <tr class="api" style="background-color: white;"> + <td class="jd-typecol"><em>string</em></td> + <td class="jd-linkcol"><a href="#ACTION_UP">UP</a></td> + <td class="jd-descrcol" width="100%"> + Use this with the <code>type</code> argument of + <code><a href="#press">press()</a></code> or <code><a href="#touch">touch()</a> + </code> + to send an UP event. + </td> + </tr> + <tr class="api" style="background-color: white;"> + <td class="jd-typecol"><em>string</em></td> + <td class="jd-linkcol"><a href="#ACTION_DOWN_AND_UP">DOWN_AND_UP</a></td> + <td class="jd-descrcol" width="100%"> + Use this with the <code>type</code> argument of + <code><a href="#press">press()</a></code> or <code><a href="#touch">touch()</a> + </code> + to send a DOWN event immediately followed by an UP event. + </td> + </tr> + </table> +<table id="pubmethods" class="jd-sumtable"> + <tr> + <th colspan="12" style="background-color: #E2E2E2">Methods</th> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#broadcastIntent">broadcastIntent</a> + </span> + (<em>string</em> uri, + <em>string</em> action, + <em>string</em> data, + <em>string</em> mimetype, + <em>iterable</em> categories + <em>dictionary</em> extras, + <em>component</em> component, + <em>iterable</em> flags) + </nobr> + <div class="jd-descrdiv"> + Broadcasts an Intent to this device, as if the Intent were coming from an + application. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#drag">drag</a> + </span> + (<em>tuple</em> start, + <em>tuple</em> end, + <em>float</em> duration, + <em>integer</em> steps) + </nobr> + <div class="jd-descrdiv"> + Simulates a drag gesture (touch, hold, and move) on this device's screen. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>object</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#getProperty">getProperty</a> + </span> + (<em>string</em> key) + </nobr> + <div class="jd-descrdiv"> + Given the name of a system environment variable, returns its value for this device. + The available variable names are listed in the <a href="#getProperty"> + detailed description</a> of this method. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>object</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#getSystemProperty">getSystemProperty</a> + </span> + (<em>string</em> key) + </nobr> + <div class="jd-descrdiv"> +. The API equivalent of <code>adb shell getprop <key>. This is provided for use + by platform developers. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#installPackage">installPackage</a> + </span> + (<em>string</em> path) + </nobr> + <div class="jd-descrdiv"> + Installs the Android application or test package contained in packageFile onto this + device. If the application or test package is already installed, it is replaced. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>dictionary</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#instrument">instrument</a> + </span> + (<em>string</em> className, + <em>dictionary</em> args) + </nobr> + <div class="jd-descrdiv"> + Runs the specified component under Android instrumentation, and returns the results + in a dictionary whose exact format is dictated by the component being run. The + component must already be present on this device. + </div> + </td> + </tr> + <tr class="api"> + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#press">press</a> + </span> + (<em>string</em> name, + <em>dictionary</em> type) + </nobr> + <div class="jd-descrdiv"> + Sends the key event specified by type to the key specified by + keycode. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#reboot">reboot</a> + </span> + (<em>string</em> into) + </nobr> + <div class="jd-descrdiv"> + Reboots this device into the bootloader specified by bootloadType. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#removePackage">removePackage</a> + </span> + (<em>string</em> package) + </nobr> + <div class="jd-descrdiv"> + Deletes the specified package from this device, including its data and cache. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>object</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#shell">shell</a> + </span> + (<em>string</em> cmd) + </nobr> + <div class="jd-descrdiv"> + Executes an <code>adb</code> shell command and returns the result, if any. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#startActivity">startActivity</a> + </span> + (<em>string</em> uri, + <em>string</em> action, + <em>string</em> data, + <em>string</em> mimetype, + <em>iterable</em> categories + <em>dictionary</em> extras, + <em>component</em> component, + <em>flags</em>) + </nobr> + <div class="jd-descrdiv"> + Starts an Activity on this device by sending an Intent constructed from the + supplied arguments. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <code> + <a href="{@docRoot}guide/developing/tools/MonkeyImage.html"> + MonkeyImage + </a> + </code> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#takeSnapshot">takeSnapshot</a>() + </span> + </nobr> + <div class="jd-descrdiv"> + Captures the entire screen buffer of this device, yielding a + <code> + <a href="{@docRoot}guide/developing/tools/MonkeyImage.html"> + MonkeyImage + </a> + </code> object containing a screen capture of the current display. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#touch">touch</a> + </span> + (<em>integer</em> x, + <em>integer</em> y, + <em>integer</em> type) + </nobr> + <div class="jd-descrdiv"> + Sends a touch event specified by type to the screen location specified + by x and y. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#touch">type</a> + </span> + (<em>string</em> message) + </nobr> + <div class="jd-descrdiv"> + Sends the characters contained in message to this device, as if they + had been typed on the device's keyboard. This is equivalent to calling + <code><a href="#press">press()</a></code> for each keycode in <code>message</code> + using the key event type <code><a href="#ACTION_DOWN_AND_UP"></a>DOWN_AND_UP</code>. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#touch">wake</a> + </span> + () + </nobr> + <div class="jd-descrdiv"> + Wakes the screen of this device. + </div> + </td> + </tr> +</table> +<!-- ========= ENUM CONSTANTS DETAIL ======== --> +<h2>Constants</h2> +<A NAME="ACTION_DOWN"></a> +<div class="jd-details api"> + <h4 class="jd-details-title"> + <span class="normal"> + <em>string</em> + </span> + DOWN + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + <code><a href="#press">press()</a></code> or + <code><a href="#press">touch()</a></code> value. + Specifies that a DOWN event type should be sent to the device, corresponding to + pressing down on a key or touching the screen. + </p> + </div> + </div> +</div> +<A NAME="ACTION_UP"></A> +<div class="jd-details api"> + <h4 class="jd-details-title"> + <span class="normal"> + <em>string</em> + </span> + UP + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + <code><a href="#press">press()</a></code> or + <code><a href="#press">touch()</a></code> value. + Specifies that an UP event type should be sent to the device, corresponding to + releasing a key or lifting up from the screen. + </p> + </div> + </div> +</div> +<A NAME="ACTION_DOWN_AND_UP"></A> + +<div class="jd-details api"> + <h4 class="jd-details-title"> + <span class="normal"> + <em>string</em> + </span> + DOWN_AND_UP + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + <code><a href="#press">press()</a></code>, + <code><a href="#press">touch()</a></code> or + <code><a href="#type">type()</a></code> value. + Specifies that a DOWN event type followed by an UP event type should be sent to the + device, corresponding to typing a key or clicking the screen. + </p> + </div> + </div> +</div> +<!-- ========= METHOD DETAIL ======== --> +<!-- Public methods --> +<h2>Public Methods</h2> +<A NAME="broadcastIntent"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">broadcastIntent</span> + <span class="normal"> + ( + <em>string</em> uri, + <em>string</em> action, + <em>string</em> data, + <em>string</em> mimetype, + <em>iterable</em> categories + <em>dictionary</em> extras, + <em>component</em> component, + <em>iterable</em> flags) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Broadcasts an Intent to this device, as if the Intent were coming from an + application. See {@link android.content.Intent Intent} for more information about the + arguments. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>uri</th> + <td> + The URI for the Intent. + (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). + </td> + </tr> + <tr> + <th>action</th> + <td> + The action for this Intent + (see {@link android.content.Intent#setAction(java.lang.String) Intent.setAction()}). + </td> + </tr> + <tr> + <th>data</th> + <td> + The data URI for this Intent + (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). + </td> + </tr> + <tr> + <th>mimetype</th> + <td> + The MIME type for the Intent + (see {@link android.content.Intent#setType(java.lang.String) Intent.setType()}). + </td> + </tr> + <tr> + <th>categories</th> + <td> + An iterable data structure containing strings that define categories for this + Intent + (see + {@link android.content.Intent#addCategory(java.lang.String) Intent.addCategory()}). + </td> + </tr> + <tr> + <th>extras</th> + <td> + A dictionary of extra data for this Intent + (see {@link android.content.Intent#putExtra(java.lang.String,java.lang.String) + Intent.putExtra()} + for an example). + <p> + The key for each dictionary item should be a <em>string</em>. The item's value + can be any simple or structured data type. + </p> + </td> + </tr> + <tr> + <th>component</th> + <td> + The component for this Intent (see {@link android.content.ComponentName}). + Using this argument will direct the Intent to a specific class within a specific + Android package. + </td> + </tr> + <tr> + <th>flags</th> + <td> + An iterable data structure containing flags that control how the Intent is handled + (see {@link android.content.Intent#setFlags(int) Intent.setFlags()}). + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="drag"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">drag</span> + <span class="normal"> + ( + <em>tuple</em> start, + <em>tuple</em> end, + <em>float</em> duration, + <em>integer</em> steps) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Simulates a drag gesture (touch, hold, and move) on this device's screen. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>start</th> + <td> + The starting point of the drag gesture, in the form of a <em>tuple</em> + (x,y) where x and y are <em>integers</em>. + </td> + </tr> + <tr> + <th>end</th> + <td> + The end point of the drag gesture, in the form of a <em>tuple</em> (x,y) + where x and y are <em>integers</em>. + </td> + </tr> + <tr> + <th>duration</th> + <td>The duration of the drag gesture in seconds. The default is 1.0 seconds.</td> + </tr> + <tr> + <th>steps</th> + <td>The number of steps to take when interpolating points. The default is 10.</td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="getProperty"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>object</em> + </span> + <span class="sympad">getProperty</span> + <span class="normal"> + (<em>string</em> key) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Given the name of a system environment variable, returns its value for this device. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>key</th> + <td> + The name of the system environment variable. The available variable names are listed in + <a href="#table1">Table 1. Property variable names</a> at the end of this topic. + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + The value of the variable. The data format varies according to the variable requested. + </li> + </ul> + </div> + </div> +</div> +<A NAME="getSystemProperty"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>object</em> + </span> + <span class="sympad">getSystemProperty</span> + <span class="normal"> + (<em>string</em> key) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Synonym for <code><a href="#getProperty">getProperty()</a></code>. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>key</th> + <td> + The name of the system environment variable. The available variable names are listed in + <a href="#table1">Table 1. Property Variable Names</a>. + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + The value of the variable. The data format varies according to the variable requested. + </li> + </ul> + </div> + </div> +</div> +<A NAME="installPackage"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">installPackage</span> + <span class="normal"> + (<em>string</em> path) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Installs the Android application or test package contained in packageFile + onto this device. If the application or test package is already installed, it is + replaced. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>path</th> + <td> + The fully-qualified path and filename of the <code>.apk</code> file to install. + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="instrument"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>dictionary</em> + </span> + <span class="sympad">instrument</span> + <span class="normal"> + ( + <em>string</em> className, + <em>dictionary</em> args) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Runs the specified component with Android instrumentation, and returns the results + in a dictionary whose exact format is dictated by the component being run. The + component must already be present on this device. + </p> + <p> + Use this method to start a test case that uses one of Android's test case classes. + See <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing + Fundamentals</a> to learn more about unit testing with the Android testing + framework. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>className</th> + <td> + The name of an Android component that is already installed on this device, in the + standard form packagename/classname, where packagename is the + Android package name of a <code>.apk</code> file on this device, and + classname is the class name of an Android component (Activity, + ContentProvider, Service, or BroadcastReceiver) in that file. Both + packagename and classname must be fully qualified. See + {@link android.content.ComponentName} for more details. + </td> + </tr> + <tr> + <th>args</th> + <td> + A dictionary containing flags and their values. These are passed to the component as it + is started. If the flag does not take a value, set its dictionary value to an empty + string. + </td> + </tr> + </table> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + <p> + A dictionary containing the component's output. The contents of the dictionary + are defined by the component itself. + </p> + <p> + If you use {@link android.test.InstrumentationTestRunner} as the class name in + the componentName argument, then the result dictionary contains + the single key "stream". The value of "stream" is a <em>string</em> containing + the test output, as if <code>InstrumentationTestRunner</code> was run from the + command line. The format of this output is described in + <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> + Testing in Other IDEs</a>. + </p> + </li> + </ul> + </div> + </div> + </div> +</div> +<A NAME="press"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">press</span> + <span class="normal"> + (<em>string</em> name, + <em>integer</em> type) + </span> + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + Sends the key event specified by <code>type</code> to the key specified by + <code>keycode</code>. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>name</th> + <td> + The name of the keycode to send. See {@link android.view.KeyEvent} for a list of + keycode names. Use the keycode name, not its integer value. + </td> + </tr> + <tr> + <th>type</th> + <td> + The type of key event to send. The allowed values are <code><a href="#ACTION_DOWN"> + DOWN</a></code>, <code><a href="#ACTION_UP">UP</a></code>, and + <code><a href="#ACTION_DOWN_AND_UP">DOWN_AND_UP</a></code>. + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="reboot"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">reboot</span> + <span class="normal"> + (<em>string</em> bootloadType) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Reboots this device into the bootloader specified by <code>bootloadType</code>. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>into</th> + <td> + The type of bootloader to reboot into. The allowed values are + "bootloader", "recovery", or "None". + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="removePackage"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">removePackage</span> + <span class="normal"> + (<em>string</em> package) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Deletes the specified package from this device, including its data and cache. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>package</th> + <td> + The Android package name of an <code>.apk</code> file on this device. + </td> + </table> + </div> + </div> +</div> +<A NAME="shell"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>object</em> + </span> + <span class="sympad">shell</span> + <span class="normal"> + (<em>string</em> cmd) + </span> + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + Executes an <code>adb</code> shell command and returns the result, if any. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>cmd</th> + <td> + The command to execute in the <code>adb</code> shell. The form of these commands is + described in the topic <a href="{@docRoot}guide/developing/tools/adb.html">Android + Debug Bridge</a>. + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + The results of the command, if any. The format of the results is determined by the + command. + </li> + </ul> + </div> + </div> +</div> +<A NAME="startActivity"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">startActivity</span> + <span class="normal"> + ( + <em>string</em> uri, + <em>string</em> action, + <em>string</em> data, + <em>string</em> mimetype, + <em>iterable</em> categories + <em>dictionary</em> extras, + <em>component</em> component, + <em>iterable</em> flags) + </span> + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + Starts an Activity on this device by sending an Intent constructed from the + supplied arguments. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>uri</th> + <td> + The URI for the Intent. + (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). + </td> + </tr> + <tr> + <th>action</th> + <td> + The action for the Intent + (see {@link android.content.Intent#setAction(java.lang.String) Intent.setAction()}). + </td> + </tr> + <tr> + <th>data</th> + <td> + The data URI for the Intent + (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). + </td> + </tr> + <tr> + <th>mimetype</th> + <td> + The MIME type for the Intent + (see {@link android.content.Intent#setType(java.lang.String) Intent.setType()}). + </td> + </tr> + <tr> + <th>categories</th> + <td> + An iterable data structure containing strings that define categories for the + Intent + (see + {@link android.content.Intent#addCategory(java.lang.String) Intent.addCategory()}). + </td> + </tr> + <tr> + <th>extras</th> + <td> + A dictionary of extra data for the Intent + (see + {@link android.content.Intent#putExtra(java.lang.String,java.lang.String) + Intent.putExtra()} + for an example). + <p> + The key for each dictionary item should be a <em>string</em>. The item's value + can be any simple or structured data type. + </p> + </td> + </tr> + <tr> + <th>component</th> + <td> + The component for the Intent + (see {@link android.content.ComponentName}). Using this argument will direct the + Intent to a specific class within a specific Android package. + </td> + </tr> + <tr> + <th>flags</th> + <td> + An iterable data structure containing flags that control how the Intent is handled + (see {@link android.content.Intent#setFlags(int) Intent.setFlags()}). + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="takeSnapshot"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <code> + <a href="{@docRoot}guide/developing/tools/MonkeyImage.html"> + MonkeyImage + </a> + </code> + </span> + <span class="sympad">takeSnapshot</span> + <span class="normal"> + () + </span> + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + Captures the entire screen buffer of this device, yielding a + screen capture of the current display. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + A <a href="{@docRoot}guide/developing/tools/MonkeyImage.html"> + MonkeyImage</a> object containing the image of the current display. + </li> + </ul> + </div> + </div> +</div> +<A NAME="touch"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">touch</span> + <span class="normal"> + ( + <em>integer</em> x, + <em>integer</em> y, + <em>string</em> type) + </span> + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + Sends a touch event specified by type to the screen location specified + by x and y. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>x</th> + <td> + The horizontal position of the touch in actual device pixels, starting from the left of + the screen in its current orientation. + </td> + </tr> + <tr> + <th>y</th> + <td> + The vertical position of the touch in actual device pixels, starting from the top of + the screen in its current orientation. + </td> + </tr> + <tr> + <th>type</th> + <td> + The type of key event to send. The allowed values are <code><a href="#ACTION_DOWN"> + DOWN</a></code>, <code><a href="#ACTION_UP">UP</a></code>, and + <code><a href="#ACTION_DOWN_AND_UP">DOWN_AND_UP</a></code>. + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="type"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">type</span> + <span class="normal"> + (<em>string</em> message) + </span> + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + Sends the characters contained in message to this device, as if they + had been typed on the device's keyboard. This is equivalent to calling + <code><a href="#press">press()</a></code> for each keycode in <code>message</code> + using the key event type <code><a href="#ACTION_DOWN_AND_UP">DOWN_AND_UP</a></code>. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>message</th> + <td> + A string containing the characters to send. + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="wake"></A> +<div class="jd-details api"> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">wake</span> + <span class="normal"> + () + </span> + </h4> + <div class="jd-details-descr"> + <div class="jd-tagdata jd-tagdescr"> + <p> + Wakes the screen of this device. + </p> + </div> + </div> +</div> +<hr></hr> +<h2>Appendix</h2> + <p class="table-caption" id="table1"> + <strong>Table 1.</strong>Property variable names used with + <span class="sympad"><a href="#getProperty">getProperty()</a></span> and + <span class="sympad"><a href="#getSystemProperty">getSystemProperty()</a></span>. + </p> + <table> + <tr> + <th> + Property Group + </th> + <th> + Property + </th> + <th> + Description + </th> + <th> + Notes + </th> + </tr> + <tr> + <td rowspan="17"><code>build</code></td> + <td><code>board</code></td> + <td>Code name for the device's system board</td> + <td rowspan="17"> + See {@link android.os.Build} + </td> + </tr> + <tr> + <td><code>brand</code></td> + <td>The carrier or provider for which the OS is customized.</td> + </tr> + <tr> + <td><code>device</code></td> + <td>The device design name.</td> + </tr> + <tr> + <td><code>fingerprint</code></td> + <td>A unique identifier for the currently-running build.</td> + </tr> + <tr> + <td><code>host</code></td> + <td></td> + </tr> + <tr> + <td><code>ID</code></td> + <td>A changelist number or label.</td> + </tr> + <tr> + <td><code>model</code></td> + <td>The end-user-visible name for the device.</td> + </tr> + <tr> + <td><code>product</code></td> + <td>The overall product name.</td> + </tr> + <tr> + <td><code>tags</code></td> + <td>Comma-separated tags that describe the build, such as "unsigned" and "debug".</td> + </tr> + <tr> + <td><code>type</code></td> + <td>The build type, such as "user" or "eng".</td> + </tr> + <tr> + <td><code>user</code></td> + <td></td> + </tr> + <tr> + <td><code>CPU_ABI</code></td> + <td> + The name of the native code instruction set, in the form CPU type plus + ABI convention. + </td> + </tr> + <tr> + <td><code>manufacturer</code></td> + <td>The product/hardware manufacturer.</td> + </tr> + <tr> + <td><code>version.incremental</code></td> + <td> + The internal code used by the source control system to represent this version + of the software. + </td> + </tr> + <tr> + <td><code>version.release</code></td> + <td>The user-visible name of this version of the software.</td> + </tr> + <tr> + <td><code>version.sdk</code></td> + <td>The user-visible SDK version associated with this version of the OS.</td> + </tr> + <tr> + <td><code>version.codename</code></td> + <td> + The current development codename, or "REL" if this version of the software has been + released. + </td> + </tr> + <tr> + <td rowspan="3"><code>display</code></td> + <td><code>width</code></td> + <td>The device's display width in pixels.</td> + <td rowspan="3"> + See + {@link android.util.DisplayMetrics} for details. + </td> + </tr> + <tr> + <td><code>height</code></td> + <td>The device's display height in pixels.</td> + </tr> + <tr> + <td><code>density</code></td> + <td> + The logical density of the display. This is a factor that scales + DIP (Density-Independent Pixel) units to the device's resolution. DIP is adjusted so + that 1 DIP is equivalent to one pixel on a 160 pixel-per-inch display. For example, + on a 160-dpi screen, density = 1.0, while on a 120-dpi screen, density = .75. + <p> + The value does not exactly follow the real screen size, but is adjusted to + conform to large changes in the display DPI. See + {@link android.util.DisplayMetrics#density} for more details. + </p> + </td> + </tr> + <tr> + <td rowspan="6"><code>am.current</code></td> + <td><code>package</code></td> + <td>The Android package name of the currently running package.</td> + <td rowspan="6"> + The <code>am.current</code> keys return information about the currently-running + Activity. + </td> + </tr> + <tr> + <td><code>action</code></td> + <td> + The current activity's action. This has the same format as the <code>name</code> + attribute of the <code>action</code> element in a package manifest. + </td> + </tr> + <tr> + <td><code>comp.class</code></td> + <td> + The class name of the component that started the current Activity. See + <code><a href="#comppackage">comp.package</a></code> for more details.</td> + </tr> + <tr> + <td><a name="comppackage"><code>comp.package</code></a></td> + <td> + The package name of the component that started the current Activity. A component + is specified by a package name and the name of class that the package contains. + </td> + </tr> + <tr> + <td><code>data</code></td> + <td>The data (if any) contained in the Intent that started the current Activity.</td> + </tr> + <tr> + <td><code>categories</code></td> + <td>The categories specified by the Intent that started the current Activity.</td> + </tr> + <tr> + <td rowspan="3"><code>clock</code></td> + <td><code>realtime</code></td> + <td> + The number of milliseconds since the device rebooted, including deep-sleep + time. + </td> + <td rowspan="3"> + See {@link android.os.SystemClock} for more information. + </td> + </tr> + <tr> + <td><code>uptime</code></td> + <td> + The number of milliseconds since the device rebooted, <em>not</em> including + deep-sleep time + </td> + </tr> + <tr> + <td><code>millis</code></td> + <td>current time since the UNIX epoch, in milliseconds.</td> + </tr> + </table> diff --git a/docs/html/guide/developing/tools/MonkeyImage.jd b/docs/html/guide/developing/tools/MonkeyImage.jd new file mode 100644 index 0000000..ae85cb5 --- /dev/null +++ b/docs/html/guide/developing/tools/MonkeyImage.jd @@ -0,0 +1,435 @@ +page.title=MonkeyImage +@jd:body +<style> + h4.jd-details-title {background-color: #DEE8F1;} +</style> + +<p> + A monkeyrunner class to hold an image of the device or emulator's screen. The image is + copied from the screen buffer during a screenshot. This object's methods allow you to + convert the image into various storage formats, write the image to a file, copy parts of + the image, and compare this object to other <code>MonkeyImage</code> objects. +</p> +<p> + You do not need to create new instances of <code>MonkeyImage</code>. Instead, use +<code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html#takeSnapshot"> +MonkeyDevice.takeSnapshot()</a></code> to create a new instance from a screenshot. For example, use: +</p> +<pre> +newimage = MonkeyDevice.takeSnapshot() +</pre> +<h2>Summary</h2> +<table id="pubmethods" class="jd-sumtable"> + <tr> + <th colspan="12" style="background-color: #E2E2E2">Methods</th> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>string</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#convertToBytes">convertToBytes</a> + </span> + (<em>string</em> format) + </nobr> + <div class="jd-descrdiv"> + Converts the current image to a particular format and returns it as a + <em>string</em> that you can then access as an <em>iterable</em> of binary bytes. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>tuple</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#getRawPixel">getRawPixel</a> + </span> + (<em>integer</em> x, + <em>integer</em> y) + </nobr> + <div class="jd-descrdiv"> + Returns the single pixel at the image location (x,y), as an + a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b). + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>integer</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#getRawPixelInt">getRawPixelInt</a> + </span> + (<em>integer</em> x, + <em>integer</em> y) + </nobr> + <div class="jd-descrdiv"> + Returns the single pixel at the image location (x,y), as + a 32-bit <em>integer</em>. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <code> + <a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a> + </code> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#getSubImage">getSubImage</a> + </span> + (<em>tuple</em> rect) + </nobr> + <div class="jd-descrdiv"> + Creates a new <code>MonkeyImage</code> object from a rectangular selection of the + current image. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>boolean</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#sameAs">sameAs</a> + </span> + (<code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code> + other, + <em>float</em> percent) + </nobr> + <div class="jd-descrdiv"> + Compares this <code>MonkeyImage</code> object to another and returns the result of + the comparison. The <code>percent</code> argument specifies the percentage + difference that is allowed for the two images to be "equal". + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>void</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#writeToFile">writeToFile</a> + </span> + (<em>string</em> path, + <em>string</em> format) + </nobr> + <div class="jd-descrdiv"> + Writes the current image to the file specified by <code>filename</code>, in the + format specified by <code>format</code>. + </div> + </td> + </tr> +</table> +<!-- ========= METHOD DETAIL ======== --> +<!-- Public methods --> +<h2>Public Methods</h2> +<A NAME="convertToBytes"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>string</em> + </span> + <span class="sympad">convertToBytes</span> + <span class="normal"> + ( + <em>string</em> format) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Converts the current image to a particular format and returns it as a <em>string</em> + that you can then access as an <em>iterable</em> of binary bytes. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>format</th> + <td> + The desired output format. All of the common raster output formats are supported. + The default value is "png" (Portable Network Graphics). + </td> + </tr> + </table> + </div> +</div> +</div> +<A NAME="getRawPixel"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>tuple</em> + </span> + <span class="sympad">getRawPixel</span> + <span class="normal"> + (<em>integer</em> x, + <em>integer</em> y) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Returns the single pixel at the image location (x,y), as an + a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b). + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>x</th> + <td> + The horizontal position of the pixel, starting with 0 at the left of the screen in the + orientation it had when the screenshot was taken. + </td> + </tr> + <tr> + <th>y</th> + <td> + The vertical position of the pixel, starting with 0 at the top of the screen in the + orientation it had when the screenshot was taken. + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + A tuple of integers representing the pixel, in the form (a,r,g,b) where + a is the alpha channel value, and r, g, and b are the red, green, and blue values, + respectively. + </li> + </ul> + </div> + </div> +</div> +<A NAME="getRawPixelInt"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>tuple</em> + </span> + <span class="sympad">getRawPixelInt</span> + <span class="normal"> + (<em>integer</em> x, + <em>integer</em> y) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Returns the single pixel at the image location (x,y), as an + an <em>integer</em>. Use this method to economize on memory. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>x</th> + <td> + The horizontal position of the pixel, starting with 0 at the left of the screen in the + orientation it had when the screenshot was taken. + </td> + </tr> + <tr> + <th>y</th> + <td> + The vertical position of the pixel, starting with 0 at the top of the screen in the + orientation it had when the screenshot was taken. + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + The a,r,g, and b values of the pixel as 8-bit values combined into a 32-bit + integer, with a as the leftmost 8 bits, r the next rightmost, and so forth. + </li> + </ul> + </div> + </div> +</div> +<A NAME="getSubImage"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <code> + <a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a> + </code> + </span> + <span class="sympad">getSubImage</span> + <span class="normal"> + (<em>tuple</em> rect) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Creates a new <code>MonkeyImage</code> object from a rectangular selection of the + current image. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>rect</th> + <td> + A tuple (x, y, w, h) specifying the selection. x and y specify the 0-based pixel + position of the upper left-hand corner of the selection. w specifies the width of the + region, and h specifies its height, both in units of pixels. + <p> + The image's orientation is the same as the screen orientation at the time the + screenshot was made. + </p> + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + A new <code>MonkeyImage</code> object containing the selection. + </li> + </ul> + </div> + </div> +</div> +<A NAME="sameAs"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>boolean</em> + </span> + <span class="sympad">sameAs</span> + <span class="normal"> + ( + <code> + <a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a> + </code> otherImage, + <em>float</em> percent + ) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Compares this <code>MonkeyImage</code> object to another and returns the result of + the comparison. The <code>percent</code> argument specifies the percentage + difference that is allowed for the two images to be "equal". + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>other</th> + <td> + Another <code>MonkeyImage</code> object to compare to this one. + </td> + </tr> + <tr> + <th> + percent + </th> + <td> + A float in the range 0.0 to 1.0, inclusive, indicating + the percentage of pixels that need to be the same for the method to return + <code>true</code>. The default is 1.0, indicating that all the pixels + must match. + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + Boolean <code>true</code> if the images match, or boolean <code>false</code> otherwise. + </li> + </ul> + </div> + </div> +</div> +<A NAME="writeToFile"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">writeToFile</span> + <span class="normal"> + (<em>string</em> filename, + <em>string</em> format) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Writes the current image to the file specified by <code>filename</code>, in the + format specified by <code>format</code>. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>path</th> + <td> + The fully-qualified filename and extension of the output file. + </td> + </tr> + <tr> + <th> + format + </th> + <td> + The output format to use for the file. If no format is provided, then the + method tries to guess the format from the filename's extension. If no + extension is provided and no format is specified, then the default format of + "png" (Portable Network Graphics) is used. + </td> + </tr> + </table> + </div> + </div> +</div> diff --git a/docs/html/guide/developing/tools/MonkeyRunner.jd b/docs/html/guide/developing/tools/MonkeyRunner.jd new file mode 100644 index 0000000..871e06d --- /dev/null +++ b/docs/html/guide/developing/tools/MonkeyRunner.jd @@ -0,0 +1,445 @@ +page.title=MonkeyRunner +@jd:body +<style> + h4.jd-details-title {background-color: #DEE8F1;} +</style> +<p> + A monkeyrunner class that contains static utility methods. +</p> +<h2>Summary</h2> +<table id="pubmethods" class="jd-sumtable"> + <tr> + <th colspan="12" style="background-color: #E2E2E2">Methods</th> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#alert">alert</a> + </span> + (<em>string</em> message, + <em>string</em> title, + <em>string</em> okTitle) + </nobr> + <div class="jd-descrdiv"> + Displays an alert dialog to the process running the current + program. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>integer</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#choice">choice</a> + </span> + (<em>string</em> message, + <em>iterable</em> choices, + <em>string</em> title) + </nobr> + <div class="jd-descrdiv"> + Displays a dialog with a list of choices to the process running the current program. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#help">help</a> + </span> + (<em>string</em> format) + </nobr> + <div class="jd-descrdiv"> + Displays the monkeyrunner API reference in a style similar to that of Python's + <code>pydoc</code> tool, using the specified format. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <em>string</em> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#input">input</a> + </span> + (<em>string</em> message, + <em>string</em> initialValue, + <em>string</em> title, + <em>string</em> okTitle, + <em>string</em> cancelTitle) + </nobr> + <div class="jd-descrdiv"> + Displays a dialog that accepts input. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + void + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#sleep">sleep</a> + </span> + (<em>float</em> seconds) + </nobr> + <div class="jd-descrdiv"> + Pauses the current program for the specified number of seconds. + </div> + </td> + </tr> + <tr class="api" > + <td class="jd-typecol"> + <nobr> + <code> + <a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a> + </code> + </nobr> + </td> + <td class="jd-linkcol" width="100%"> + <nobr> + <span class="sympad"> + <a href="#waitForConnection">waitForConnection</a> + </span> + (<em>float</em> timeout, + <em>string</em> deviceId) + </nobr> + <div class="jd-descrdiv"> + Tries to make a connection between the <code>monkeyrunner</code> backend and the + specified device or emulator. + </div> + </td> + </tr> +</table> +<!-- ========= METHOD DETAIL ======== --> +<!-- Public methods --> +<h2>Public Methods</h2> +<A NAME="alert"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>string</em> + </span> + <span class="sympad">alert</span> + <span class="normal"> + ( + <em>string</em> message, + <em>string</em> title, + <em>string</em> okTitle) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Displays an alert dialog to the process running the current + program. The dialog is modal, so the program pauses until the user clicks the dialog's + button. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>message</th> + <td> + The message to display in the dialog. + </td> + </tr> + <tr> + <th>title</th> + <td> + The dialog's title. The default value is "Alert". + </td> + </tr> + <tr> + <th>okTitle</th> + <td> + The text displayed in the dialog button. The default value is "OK". + </td> + </tr> + </table> + </div> +</div> +</div> +<A NAME="choice"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>integer</em> + </span> + <span class="sympad">choice</span> + <span class="normal"> + (<em>string</em> message, + <em>iterable</em> choices, + <em>string</em> title) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Displays a dialog with a list of choices to the process running the current program. The + dialog is modal, so the program pauses until the user clicks one of the dialog's + buttons. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>message</th> + <td> + The prompt message displayed in the dialog. + </td> + </tr> + <tr> + <th>choices</th> + <td> + A Python iterable containing one or more objects that are displayed as strings. The + recommended form is an array of strings. + </td> + </tr> + <tr> + <th> + title + </th> + <td> + The dialog's title. The default is "Input". + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + If the user makes a selection and clicks the "OK" button, the method returns + the 0-based index of the selection within the iterable. + If the user clicks the "Cancel" button, the method returns -1. + </li> + </ul> + </div> + </div> +</div> +<A NAME="help"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">help</span> + <span class="normal"> + (<em>string</em> format) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Displays the monkeyrunner API reference in a style similar to that of Python's + <code>pydoc</code> tool, using the specified format. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>format</th> + <td> + The markup format to use in the output. The possible values are "text" for plain text + or "html" for HTML. + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="input"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <em>string</em> + </span> + <span class="sympad">input</span> + <span class="normal"> + (<em>string</em> message + <em>string</em> initialValue, + <em>string</em> title, + <em>string</em> okTitle, + <em>string</em> cancelTitle) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Displays a dialog that accepts input and returns it to the program. The dialog is + modal, so the program pauses until the user clicks one of the dialog's buttons. + </p> + <p> + The dialog contains two buttons, one of which displays the okTitle value + and the other the cancelTitle value. If the user clicks the okTitle button, + the current value of the input box is returned. If the user clicks the cancelTitle + button, an empty string is returned. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>message</th> + <td> + The prompt message displayed in the dialog. + </td> + </tr> + <tr> + <th>initialValue</th> + <td> + The initial value to display in the dialog. The default is an empty string. + </td> + </tr> + <tr> + <th>title</th> + <td> + The dialog's title. The default is "Input". + </td> + </tr> + <tr> + <th>okTitle</th> + <td> + The text displayed in the okTitle button. The default is "OK". + </td> + </tr> + <tr> + <th>cancelTitle</th> + <td> + The text displayed in the cancelTitle button. The default is "Cancel". + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + If the user clicks the okTitle button, then the method returns the current value of + the dialog's input box. If the user clicks the cancelTitle button, the method returns + an empty string. + </li> + </ul> + </div> + </div> +</div> +<A NAME="sleep"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + void + </span> + <span class="sympad">sleep</span> + <span class="normal"> + ( + <em>float</em> seconds + ) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Pauses the current program for the specified number of seconds. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>seconds</th> + <td> + The number of seconds to pause. + </td> + </tr> + </table> + </div> + </div> +</div> +<A NAME="waitForConnection"></A> +<div class="jd-details api "> + <h4 class="jd-details-title"> + <span class="normal"> + <code> + <a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a> + </code> + </span> + <span class="sympad">waitForConnection</span> + <span class="normal"> + (<em>float</em> timeout, + <em>string</em> deviceId) + </span> + </h4> + <div class="jd-details-descr"> + + <div class="jd-tagdata jd-tagdescr"> + <p> + Tries to make a connection between the <code>monkeyrunner</code> backend and the + specified device or emulator. + </p> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Arguments</h5> + <table class="jd-tagtable"> + <tr> + <th>timeout</th> + <td> + The number of seconds to wait for a connection. The default is to wait forever. + </td> + </tr> + <tr> + <th> + deviceId + </th> + <td> + A regular expression that specifies the serial number of the device or emulator. See + the topic + <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> + for a description of device and emulator serial numbers. + </td> + </tr> + </table> + </div> + <div class="jd-tagdata"> + <h5 class="jd-tagtitle">Returns</h5> + <ul class="nolist"> + <li> + A <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code> + instance for the device or emulator. Use this object to control and communicate with the + device or emulator. + </li> + </ul> + </div> + </div> +</div> diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd index 6e9fde1..899c0dc 100644 --- a/docs/html/guide/developing/tools/index.jd +++ b/docs/html/guide/developing/tools/index.jd @@ -3,27 +3,27 @@ page.title=Tools Overview <img src="{@docRoot}assets/images/android_wrench.png" alt="" align="right"> -<p>The Android SDK includes a variety of custom tools that help you develop mobile -applications on the Android platform. The most important of these are the Android -Emulator and the Android Development Tools plugin for Eclipse, but the SDK also -includes a variety of other tools for debugging, packaging, and installing your +<p>The Android SDK includes a variety of custom tools that help you develop mobile +applications on the Android platform. The most important of these are the Android +Emulator and the Android Development Tools plugin for Eclipse, but the SDK also +includes a variety of other tools for debugging, packaging, and installing your applications on the emulator. </p> - + <dl> <dt><a href="adt.html">Android Development Tools Plugin</a> (for the Eclipse IDE)</dt> - <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment, - making creating and debugging your Android applications easier and faster. If you - use Eclipse, the ADT plugin gives you an incredible boost in developing Android + <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment, + making creating and debugging your Android applications easier and faster. If you + use Eclipse, the ADT plugin gives you an incredible boost in developing Android applications.</dd> <dt><a href="emulator.html">Android Emulator</a></dt> - <dd>A QEMU-based device-emulation tool that you can use to design, + <dd>A QEMU-based device-emulation tool that you can use to design, debug, and test your applications in an actual Android run-time environment. </dd> <dt><a href="avd.html">Android Virtual Devices (AVDs)</a></dt> <dd>Virtual device configurations that you create, to model device characteristics in the Android Emulator. In each configuration, you can specify the Android platform to run, the hardware options, and the - emulator skin to use. Each AVD functions as an independent device with + emulator skin to use. Each AVD functions as an independent device with it's own storage for user data, SD card, and so on. </dd> <dt><a href="hierarchy-viewer.html">Hierarchy Viewer</a></dt> @@ -37,64 +37,69 @@ applications on the emulator. </p> efficiency. </dd> - <dt><a href="draw9patch.html">Draw 9-patch</a></dt> - <dd>The Draw 9-patch tool allows you to easily create a - {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched - versions of the image, and highlights the area in which content is allowed. - </dd> + <dt><a href="draw9patch.html">Draw 9-patch</a></dt> + <dd>The Draw 9-patch tool allows you to easily create a + {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched + versions of the image, and highlights the area in which content is allowed. + </dd> - <dt><a href="ddms.html" >Dalvik Debug Monitor + <dt><a href="ddms.html" >Dalvik Debug Monitor Service</a> (ddms)</dt> - <dd>Integrated with Dalvik, the Android platform's custom VM, this tool - lets you manage processes on an emulator or device and assists in debugging. - You can use it to kill processes, select a specific process to debug, - generate trace data, view heap and thread information, take screenshots - of the emulator or device, and more. </dd> - + <dd>Integrated with Dalvik, the Android platform's custom VM, this tool + lets you manage processes on an emulator or device and assists in debugging. + You can use it to kill processes, select a specific process to debug, + generate trace data, view heap and thread information, take screenshots + of the emulator or device, and more. </dd> + <dt><a href="adb.html" >Android Debug Bridge</a> (adb)</dt> - <dd>The adb tool lets you install your application's .apk files on an - emulator or device and access the emulator or device from a command line. - You can also use it to link a standard debugger to application code running + <dd>The adb tool lets you install your application's .apk files on an + emulator or device and access the emulator or device from a command line. + You can also use it to link a standard debugger to application code running on an Android emulator or device.</dd> - <dt><a href="aapt.html">Android Asset + <dt><a href="aapt.html">Android Asset Packaging Tool</a> (aapt)</dt> - <dd>The aapt tool lets you create .apk files containing the binaries and + <dd>The aapt tool lets you create .apk files containing the binaries and resources of Android applications.</dd> - <dt><a href="aidl.html" >Android Interface + <dt><a href="aidl.html" >Android Interface Description Language</a> (aidl)</dt> <dd>Lets you generate code for an interprocess interface, such as what a service might use.</dd> <dt><a href="adb.html#sqlite">sqlite3</a></dt> - <dd>Included as a convenience, this tool lets you access the SQLite data + <dd>Included as a convenience, this tool lets you access the SQLite data files created and used by Android applications.</dd> <dt><a href="traceview.html" >Traceview</a></dt> - <dd> This tool produces graphical analysis views of trace log data that you + <dd> This tool produces graphical analysis views of trace log data that you can generate from your Android application. </dd> <dt><a href="othertools.html#mksdcard">mksdcard</a></dt> - <dd>Helps you create a disk image that you can use with the emulator, + <dd>Helps you create a disk image that you can use with the emulator, to simulate the presence of an external storage card (such as an SD card).</dd> <dt><a href="othertools.html#dx">dx</a></dt> - <dd>The dx tool rewrites .class bytecode into Android bytecode + <dd>The dx tool rewrites .class bytecode into Android bytecode (stored in .dex files.)</dd> - <dt><a href="monkey.html">UI/Application + <dt><a href="monkey.html">UI/Application Exerciser Monkey</a></dt> <dd>The Monkey is a program that runs on your emulator or device and generates pseudo-random streams of user events such as clicks, touches, or gestures, as well as a number of system- level events. You can use the Monkey to stress-test applications that you are developing, in a random yet repeatable manner.</dd> + <dt><a href="monkeyrunner_concepts.html">monkeyrunner</a></dt> + <dd> + The monkeyrunner tool provides an API for writing Python programs that control an Android device + or emulator from outside of Android code. + </dd> <dt><a href="othertools.html#android">android</a></dt> <dd>A script that lets you manage AVDs and generate <a - href="http://ant.apache.org/" title="Ant">Ant</a> build files that + href="http://ant.apache.org/" title="Ant">Ant</a> build files that you can use to compile your Android applications. </dd> - + <dt><a href="zipalign.html">zipalign</a></dt> <dd>An important .apk optimization tool. This tool ensures that all uncompressed data starts with a particular alignment relative to the start of the file. This should always be used diff --git a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd new file mode 100644 index 0000000..1838905 --- /dev/null +++ b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd @@ -0,0 +1,308 @@ +page.title=monkeyrunner +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li> + <a href="#SampleProgram">A Simple monkeyrunner Program</a> + </li> + <li> + <a href="#APIClasses">The monkeyrunner API</a> + </li> + <li> + <a href="#RunningMonkeyRunner">Running monkeyrunner</a> + </li> + <li> + <a href="#Help">monkeyrunner Built-in Help</a> + </li> + <li> + <a href="#Plugins">Extending monkeyrunner with Plugins</a> + </li> + </ol> + <h2>See Also</h2> + <ol> + <li> + <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a> + </li> + </ol> + </div> +</div> +<p> + The monkeyrunner tool provides an API for writing programs that control an Android device + or emulator from outside of Android code. With monkeyrunner, you can write a Python program + that installs an Android application or test package, runs it, sends keystrokes to it, + takes screenshots of its user interface, and stores screenshots on the workstation. The + monkeyrunner tool is primarily designed to test applications and devices at the + functional/framework level and for running unit test suites, but you are free to use it for + other purposes. +</p> +<p> + The monkeyrunner tool is not related to the + <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, + also known as the <code>monkey</code> tool. The <code>monkey</code> tool runs in an + <code><a href="{@docRoot}guide/developing/tools/adb.html">adb</a></code> shell directly on the + device or emulator and generates pseudo-random streams of user and system events. In comparison, + the monkeyrunner tool controls devices and emulators from a workstation by sending specific + commands and events from an API. +</p> +<p> + The monkeyrunner tool provides these unique features for Android testing: +</p> +<ul> + <li> + Multiple device control: The monkeyrunner API can apply one or more + test suites across multiple devices or emulators. You can physically attach all the devices + or start up all the emulators (or both) at once, connect to each one in turn + programmatically, and then run one or more tests. You can also start up an emulator + configuration programmatically, run one or more tests, and then shut down the emulator. + </li> + <li> + Functional testing: monkeyrunner can run an automated start-to-finish test of an Android + application. You provide input values with keystrokes or touch events, and view the results + as screenshots. + </li> + <li> + Regression testing - monkeyrunner can test application stability by running an application + and comparing its output screenshots to a set of screenshots that are known to be correct. + </li> + <li> + Extensible automation - Since monkeyrunner is an API toolkit, you can develop an entire + system of Python-based modules and programs for controlling Android devices. Besides using + the monkeyrunner API itself, you can use the standard Python + <code><a href="http://docs.python.org/library/os.html">os</a></code> and + <code><a href="http://docs.python.org/library/subprocess.html">subprocess</a></code> + modules to call Android tools such as + <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>. + <p> + You can also add your own classes to the monkeyrunner API. This is described + in more detail in the section + <a href="#Plugins">Extending monkeyrunner with plugins</a>. + </p> + </li> +</ul> +<p> + The monkeyrunner tool uses <a href="http://www.jython.org/">Jython</a>, a + implementation of Python that uses the Java programming language. Jython allows the + monkeyrunner API to interact easily with the Android framework. With Jython you can + use Python syntax to access the constants, classes, and methods of the API. +</p> + +<h2 id="SampleProgram">A Simple monkeyrunner Program</h2> +<p> + Here is a simple monkeyrunner program that connects to a device, creating a + <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code> + object. Using the <code>MonkeyDevice</code> object, the program installs an Android application + package, runs one of its activities, and sends key events to the activity. + The program then takes a screenshot of the result, creating a + <code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code> object. + From this object, the program writes out a <code>.png</code> file containing the screenshot. +</p> +<pre> +# Imports the monkeyrunner modules used by this program +from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice + +# Connects to the current device, returning a MonkeyDevice object +device = MonkeyRunner.waitForConnection() + +# Installs the Android package. Notice that this method returns a boolean, so you can test +# to see if the installation worked. +device.installPackage('myproject/bin/MyApplication.apk') + +# Runs an activity in the application +device.startActivity(component='com.example.android.myapplication.MainActivity') + +# Presses the Menu button +device.press('KEYCODE_MENU','DOWN_AND_UP') + +# Takes a screenshot +result = device.takeSnapShot + +# Writes the screenshot to a file +result.writeToFile('myproject/shot1.png','png') +</pre> + +<h2 id="APIClasses">The monkeyrunner API</h2> +<p> + The monkeyrunner API is contained in three modules in the package + <code>com.android.monkeyrunner</code>: +</p> +<ul> + <li> + <code><a href="{@docRoot}guide/developing/tools/MonkeyRunner.html">MonkeyRunner</a></code>: + A class of utility methods for monkeyrunner programs. This class provides a method for + connecting monkeyrunner to a device or emulator. It also provides methods for + creating UIs for a monkeyrunner program and for displaying the built-in help. + </li> + <li> + <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>: + Represents a device or emulator. This class provides methods for installing and + uninstalling packages, starting an Activity, and sending keyboard or touch events to an + application. You also use this class to run test packages. + </li> + <li> + <code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code>: + Represents a screen capture image. This class provides methods for capturing screens, + converting bitmap images to various formats, comparing two MonkeyImage objects, and + writing an image to a file. + </li> +</ul> +<p> + In a Python program, you access each class as a Python module. The monkeyrunner tool + does not import these modules automatically. To import a module, use the + Python <code>from</code> statement: +</p> +<pre> +from com.android.monkeyrunner import <module> +</pre> +<p> + where <code><module></code> is the class name you want to import. You can import more + than one module in the same <code>from</code> statement by separating the module names with + commas. +</p> +<h2 id="RunningMonkeyRunner">Running monkeyrunner</h2> +<p> + You can either run monkeyrunner programs from a file, or enter monkeyrunner statements in + an interactive session. You do both by invoking the <code>monkeyrunner</code> command + which is found in the <code>tools/</code> subdirectory of your SDK directory. + If you provide a filename as an argument, the <code>monkeyrunner</code> command + runs the file's contents as a Python program; otherwise, it starts an interactive session. +</p> +<p> + The syntax of the <code>monkeyrunner</code> command is +</p> +<pre> +monkeyrunner -plugin <plugin_jar> <program_filename> <program_options> +</pre> +<p> +Table 1 explains the flags and arguments. +</p> +<p class="table-caption" id="table1"> + <strong>Table 1.</strong> <code>monkeyrunner</code> flags and arguments.</p> + +<table> + <tr> + <th>Argument</th> + <th>Description</th> + </tr> + <tr> + <td> + <nobr> + <code>-plugin <plugin_jar></code> + </nobr> + </td> + <td> + (Optional) Specifies a <code>.jar</code> file containing a plugin for monkeyrunner. + To learn more about monkeyrunner plugins, see + <a href="#Plugins">Extending monkeyrunner with plugins</a>. To specify more than one + file, include the argument multiple times. + </td> + </tr> + <tr> + <td> + <nobr> + <code><program_filename></code> + </nobr> + </td> + <td> + If you provide this argument, the <code>monkeyrunner</code> command runs the contents + of the file as a Python program. If the argument is not provided, the command starts an + interactive session. + </td> + </tr> + <tr> + <td> + <code><program_options></code> + </td> + <td> + (Optional) Flags and arguments for the program in <program_file>. + </td> + </tr> +</table> +<h2 id="Help">monkeyrunner Built-in Help</h2> +<p> + You can generate an API reference for monkeyrunner by running: +</p> +<pre> +monkeyrunner <format> help.py <outfile> +</pre> +<p> +The arguments are: +</p> + <ul> + <li> + <code><format></code> is either <code>text</code> for plain text output + or <code>html</code> for HTML output. + </li> + <li> + <code><outfile></code> is a path-qualified name for the output file. + </li> + </ul> +<h2 id="Plugins">Extending monkeyrunner with Plugins</h2> +<p> + You can extend the monkeyrunner API with classes you write in the Java programming language + and build into one or more <code>.jar</code> files. You can use this feature to extend the + monkeyrunner API with your own classes or to extend the existing classes. You can also use this + feature to initialize the monkeyrunner environment. +</p> +<p> + To provide a plugin to monkeyrunner, invoke the <code>monkeyrunner</code> command with the + <code>-plugin <plugin_jar></code> argument described in + <a href="#table1">table 1</a>. +</p> +<p> + In your plugin code, you can import and extend the the main monkeyrunner classes + <code>MonkeyDevice</code>, <code>MonkeyImage</code>, and <code>MonkeyRunner</code> in + <code>com.android.monkeyrunner</code> (see <a href="#APIClasses">The monkeyrunner API</a>). +</p> +<p> + Note that plugins do not give you access to the Android SDK. You can't import packages + such as <code>com.android.app</code>. This is because monkeyrunner interacts with the + device or emulator below the level of the framework APIs. +</p> +<h3>The plugin startup class</h3> +<p> + The <code>.jar</code> file for a plugin can specify a class that is instantiated before + script processing starts. To specify this class, add the key + <code>MonkeyRunnerStartupRunner</code> to the <code>.jar</code> file's + manifest. The value should be the name of the class to run at startup. The following + snippet shows how you would do this within an <code>ant</code> build script: +</p> +<pre> +<jar jarfile="myplugin" basedir="${build.dir}"> +<manifest> +<attribute name="MonkeyRunnerStartupRunner" value="com.myapp.myplugin"/> +</manifest> +</jar> + + +</pre> +<p> + To get access to monkeyrunner's runtime environment, the startup class can implement + <code>com.google.common.base.Predicate<PythonInterpreter></code>. For example, this + class sets up some variables in the default namespace: +</p> +<pre> +package com.android.example; + +import com.google.common.base.Predicate; +import org.python.util.PythonInterpreter; + +public class Main implements Predicate<PythonInterpreter> { + @Override + public boolean apply(PythonInterpreter anInterpreter) { + + /* + * Examples of creating and initializing variables in the monkeyrunner environment's + * namespace. During execution, the monkeyrunner program can refer to the variables "newtest" + * and "use_emulator" + * + */ + anInterpreter.set("newtest", "enabled"); + anInterpreter.set("use_emulator", 1); + + return true; + } +} +</pre> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 80595cb..a43e334 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -254,12 +254,45 @@ <li><a href="<?cs var:toroot?>guide/topics/search/searchable-config.html">Searchable Configuration</a></li> </ul> </li> - <li><a href="<?cs var:toroot?>guide/topics/testing/testing_android.html"> - <span class="en">Testing and Instrumentation</span> - </a></li> - <li><a href="<?cs var:toroot?>guide/topics/admin/device-admin.html"> + <li><a href="<?cs var:toroot?>guide/topics/admin/device-admin.html"> <span class="en">Device Administration</span> - </a> <span class="new">new!</span><!-- 10/8/10 --></li> + </a> <span class="new">new!</span> + </li> + <li class="toggle-list"> + <div> + <a href="<?cs var:toroot?>guide/topics/testing/index.html"> + <span class="en">Testing</span> + </a> + </div> + <ul> + <li> + <a href="<?cs var:toroot?>guide/topics/testing/testing_android.html"> + <span class="en">Testing Fundamentals</span></a> + <span class="new">new!</span> + </li> + <li> + <a href="<?cs var:toroot?>guide/topics/testing/activity_testing.html"> + <span class="en">Activity Testing</span></a> + <span class="new">new!</span> + </li> + <li> + <a href="<?cs var:toroot?>guide/topics/testing/contentprovider_testing.html"> + <span class="en">Content Provider Testing</span></a> + <span class="new">new!</span> + </li> + <li> + <a href="<?cs var:toroot?>guide/topics/testing/service_testing.html"> + <span class="en">Service Testing</span></a> + <span class="new">new!</span> + </li> + <li> + <a href="<?cs var:toroot ?>guide/topics/testing/what_to_test.html"> + <span class="en">What To Test</span></a> + <span class="new">new!</span> + </li> + + </ul> + </li> </ul> </li> @@ -314,6 +347,7 @@ <span class="en">Testing in Eclipse, with ADT</span> </a> </li> + <li> <a href="<?cs var:toroot ?>guide/developing/testing/testing_otheride.html"> <span class="en">Testing in Other IDEs</span> @@ -341,6 +375,34 @@ <li><a href="<?cs var:toroot ?>guide/developing/tools/layoutopt.html">layoutopt</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#mksdcard">mksdcard</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/monkey.html">Monkey</a></li> + <li class="toggle-list"> + <div> + <a href="<?cs var:toroot?>guide/developing/tools/monkeyrunner_concepts.html"> + <span class="en">monkeyrunner</span> + </a> + <span class="new">new!</span> + </div> + <ul> + <li> + <a href="<?cs var:toroot?>guide/developing/tools/MonkeyDevice.html"> + <span class="en">MonkeyDevice</span> + </a> + <span class="new">new!</span> + </li> + <li> + <a href="<?cs var:toroot?>guide/developing/tools/MonkeyImage.html"> + <span class="en">MonkeyImage</span> + </a> + <span class="new">new!</span> + </li> + <li> + <a href="<?cs var:toroot?>guide/developing/tools/MonkeyRunner.html"> + <span class="en">MonkeyRunner</span> + </a> + <span class="new">new!</span> + </li> + </ul> + </li> <li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html#sqlite">sqlite3</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/traceview.html" >Traceview</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/zipalign.html" >zipalign</a></li> @@ -450,6 +512,25 @@ </li> <li> + <h2><span class="en">Web Applications</span> + </h2> + <ul> + <li><a href="<?cs var:toroot ?>guide/webapps/targetting.html"> + <span class="en">Targetting Android Devices</span> + </a> <span class="new">new!</span><!-- 10/8/10 --></li> + <li><a href="<?cs var:toroot ?>guide/webapps/webview.html"> + <span class="en">Building Web Apps in WebView</span> + </a> <span class="new">new!</span><!-- 10/8/10 --></li> + <li><a href="<?cs var:toroot ?>guide/webapps/debugging.html"> + <span class="en">Debugging Web Apps</span> + </a> <span class="new">new!</span><!-- 10/8/10 --></li> + <li><a href="<?cs var:toroot ?>guide/webapps/best-practices.html"> + <span class="en">Best Practices for Web Apps</span> + </a> <span class="new">new!</span><!-- 10/8/10 --></li> + </ul> + </li> + + <li> <h2><span class="en">Appendix</span> <span class="de" style="display:none">Anhang</span> <span class="es" style="display:none">Apéndice</span> diff --git a/docs/html/guide/practices/design/performance.jd b/docs/html/guide/practices/design/performance.jd index 3e7c671..f5588ac 100644 --- a/docs/html/guide/practices/design/performance.jd +++ b/docs/html/guide/practices/design/performance.jd @@ -48,188 +48,39 @@ outside the scope of this document.</p> <h2 id="optimize_judiciously">Optimize Judiciously</h2> -<p>As you get started thinking about how to design your application, and as -you write it, consider -the cautionary points about optimization that Josh Bloch makes in his book -<em>Effective Java</em>. Here's "Item 47: Optimize Judiciously", excerpted from -the latest edition of the book with permission. Although Josh didn't have -Android application development in mind when writing this section — for -example, the <code style="color:black">java.awt.Component</code> class -referenced is not available in Android, and Android uses the -Dalvik VM, rather than a standard JVM — his points are still valid. </p> - -<blockquote> - -<p>There are three aphorisms concerning optimization that everyone should know. -They are perhaps beginning to suffer from overexposure, but in case you aren't -yet familiar with them, here they are:</p> - -<div style="padding-left:3em;padding-right:4em;"> - -<p style="margin-bottom:.5em;">More computing sins are committed in the name of -efficiency (without necessarily achieving it) than for any other single -reason—including blind stupidity.</p> -<p>—William A. Wulf <span style="font-size:80%;"><sup>1</sup></span></p> - -<p style="margin-bottom:.5em;">We should forget about small efficiencies, say -about 97% of the time: premature optimization is the root of all evil. </p> -<p>—Donald E. Knuth <span style="font-size:80%;"><sup>2</sup></span></p> - - -<p style="margin-bottom:.5em;">We follow two rules in the matter of optimization:</p> -<ul style="margin-bottom:0"> -<li>Rule 1. Don't do it.</li> -<li>Rule 2 (for experts only). Don't do it yet — that is, not until you have a -perfectly clear and unoptimized solution. </li> -</ul> -<p>—M. A. Jackson <span style="font-size:80%;"><sup>3</sup></span></p> -</div> - -<p>All of these aphorisms predate the Java programming language by two decades. -They tell a deep truth about optimization: it is easy to do more harm than good, -especially if you optimize prematurely. In the process, you may produce software -that is neither fast nor correct and cannot easily be fixed.</p> - -<p>Don't sacrifice sound architectural principles for performance. -<strong>Strive to write good programs rather than fast ones.</strong> If a good -program is not fast enough, its architecture will allow it to be optimized. Good -programs embody the principle of <em>information hiding</em>: where possible, -they localize design decisions within individual modules, so individual -decisions can be changed without affecting the remainder of the system (Item -13).</p> - -<p>This does <em>not</em> mean that you can ignore performance concerns until -your program is complete. Implementation problems can be fixed by later -optimization, but pervasive architectural flaws that limit performance can be -impossible to fix without rewriting the system. Changing a fundamental facet of -your design after the fact can result in an ill-structured system that is -difficult to maintain and evolve. Therefore you must think about performance -during the design process.</p> - -<p><strong>Strive to avoid design decisions that limit performance.</strong> The -components of a design that are most difficult to change after the fact are -those specifying interactions between modules and with the outside world. Chief -among these design components are APIs, wire-level protocols, and persistent -data formats. Not only are these design components difficult or impossible to -change after the fact, but all of them can place significant limitations on the -performance that a system can ever achieve.</p> - -<p><strong>Consider the performance consequences of your API design -decisions.</strong> Making a public type mutable may require a lot of needless -defensive copying (Item 39). Similarly, using inheritance in a public class -where composition would have been appropriate ties the class forever to its -superclass, which can place artificial limits on the performance of the subclass -(Item 16). As a final example, using an implementation type rather than an -interface in an API ties you to a specific implementation, even though faster -implementations may be written in the future (Item 52).</p> - -<p>The effects of API design on performance are very real. Consider the <code -style="color:black">getSize</code> method in the <code -style="color:black">java.awt.Component</code> class. The decision that this -performance-critical method was to return a <code -style="color:black">Dimension</code> instance, coupled with the decision that -<code style="color:black">Dimension</code> instances are mutable, forces any -implementation of this method to allocate a new <code -style="color:black">Dimension</code> instance on every invocation. Even though -allocating small objects is inexpensive on a modern VM, allocating millions of -objects needlessly can do real harm to performance.</p> - -<p>In this case, several alternatives existed. Ideally, <code -style="color:black">Dimension</code> should have been immutable (Item 15); -alternatively, the <code style="color:black">getSize</code> method could have -been replaced by two methods returning the individual primitive components of a -<code style="color:black">Dimension</code> object. In fact, two such methods -were added to the Component API in the 1.2 release for performance reasons. -Preexisting client code, however, still uses the <code -style="color:black">getSize</code> method and still suffers the performance -consequences of the original API design decisions.</p> - -<p>Luckily, it is generally the case that good API design is consistent with -good performance. <strong>It is a very bad idea to warp an API to achieve good -performance.</strong> The performance issue that caused you to warp the API may -go away in a future release of the platform or other underlying software, but -the warped API and the support headaches that come with it will be with you for -life.</p> - -<p>Once you've carefully designed your program and produced a clear, concise, -and well-structured implementation, <em>then</em> it may be time to consider -optimization, assuming you're not already satisfied with the performance of the -program.</p> - -<p>Recall that Jackson's two rules of optimization were "Don't do it," and "(for -experts only). Don't do it yet." He could have added one more: <strong>measure -performance before and after each attempted optimization.</strong> You may be -surprised by what you find. Often, attempted optimizations have no measurable -effect on performance; sometimes, they make it worse. The main reason is that -it's difficult to guess where your program is spending its time. The part of the -program that you think is slow may not be at fault, in which case you'd be -wasting your time trying to optimize it. Common wisdom says that programs spend -80 percent of their time in 20 percent of their code.</p> - -<p>Profiling tools can help you decide where to focus your optimization efforts. -Such tools give you runtime information, such as roughly how much time each -method is consuming and how many times it is invoked. In addition to focusing -your tuning efforts, this can alert you to the need for algorithmic changes. If -a quadratic (or worse) algorithm lurks inside your program, no amount of tuning -will fix the problem. You must replace the algorithm with one that is more -efficient. The more code in the system, the more important it is to use a -profiler. It's like looking for a needle in a haystack: the bigger the haystack, -the more useful it is to have a metal detector. The JDK comes with a simple -profiler and modern IDEs provide more sophisticated profiling tools.</p> - -<p>The need to measure the effects of attempted optimization is even greater on -the Java platform than on more traditional platforms, because the Java -programming language does not have a strong <em>performance model</em>. The -relative costs of the various primitive operations are not well defined. The -"semantic gap" between what the programmer writes and what the CPU executes is -far greater than in traditional statically compiled languages, which makes it -very difficult to reliably predict the performance consequences of any -optimization. There are plenty of performance myths floating around that turn -out to be half-truths or outright lies.</p> - -<p>Not only is Java's performance model ill-defined, but it varies from JVM -implementation to JVM implementation, from release to release, and from -processor to processor. If you will be running your program on multiple JVM -implementations or multiple hardware platforms, it is important that you measure -the effects of your optimization on each. Occasionally you may be forced to make -trade-offs between performance on different JVM implementations or hardware -platforms.</p> - -<p>To summarize, do not strive to write fast programs — strive to write -good ones; speed will follow. Do think about performance issues while you're -designing systems and especially while you're designing APIs, wire-level -protocols, and persistent data formats. When you've finished building the -system, measure its performance. If it's fast enough, you're done. If not, -locate the source of the problems with the aid of a profiler, and go to work -optimizing the relevant parts of the system. The first step is to examine your -choice of algorithms: no amount of low-level optimization can make up for a poor -choice of algorithm. Repeat this process as necessary, measuring the performance -after every change, until you're satisfied.</p> - -<p>—Excerpted from Josh Bloch's <em>Effective Java</em>, Second Ed. -(Addison-Wesley, 2008).</em></p> - -<p style="font-size:80%;margin-bottom:0;"><sup>1</sup> Wulf, W. A Case Against -the GOTO. <em>Proceedings of the 25th ACM National -Conference</em> 2 (1972): 791–797.</p> -<p style="font-size:80%;margin-bottom:0;"><sup>2</sup> Knuth, Donald. Structured -Programming with go to Statements. <em>Computing -Surveys 6</em> (1974): 261–301.</p> -<p style="font-size:80%"><sup>3</sup> Jackson, M. A. <em>Principles of Program -Design</em>, Academic Press, London, 1975. -ISBN: 0123790506.</p> - -</blockquote> - -<p>One of the trickiest problems you'll face when micro-optimizing Android -apps is that the "if you will be running your program on ... multiple hardware -platforms" clause above is always true. And it's not even generally the case -that you can say "device X is a factor F faster/slower than device Y". -This is especially true if one of the devices is the emulator, or one of the -devices has a JIT. If you want to know how your app performs on a given device, -you need to test it on that device. Drawing conclusions from the emulator is -particularly dangerous, as is attempting to compare JIT versus non-JIT -performance: the performance <em>profiles</em> can differ wildly.</p> +<p>This document is about Android-specific micro-optimization, so it assumes +that you've already used profiling to work out exactly what code needs to be +optimized, and that you already have a way to measure the effect (good or bad) +of any changes you make. You only have so much engineering time to invest, so +it's important to know you're spending it wisely. + +<p>(See <a href="#closing_notes">Closing Notes</a> for more on profiling and +writing effective benchmarks.) + +<p>This document also assumes that you made the best decisions about data +structures and algorithms, and that you've also considered the future +performance consequences of your API decisions. Using the right data +structures and algorithms will make more difference than any of the advice +here, and considering the performance consequences of your API decisions will +make it easier to switch to better implementations later (this is more +important for library code than for application code). + +<p>(If you need that kind of advice, see Josh Bloch's <em>Effective Java</em>, +item 47.)</p> + +<p>One of the trickiest problems you'll face when micro-optimizing an Android +app is that your app is pretty much guaranteed to be running on multiple +hardware platforms. Different versions of the VM running on different +processors running at different speeds. It's not even generally the case +that you can simply say "device X is a factor F faster/slower than device Y", +and scale your results from one device to others. In particular, measurement +on the emulator tells you very little about performance on any device. There +are also huge differences between devices with and without a JIT: the "best" +code for a device with a JIT is not always the best code for a device +without.</p> + +<p>If you want to know how your app performs on a given device, you need to +test on that device.</p> <a name="object_creation"></a> <h2>Avoid Creating Objects</h2> @@ -572,3 +423,11 @@ of its way to do the hard work for you, and even detect some cases where you're not measuring what you think you're measuring (because, say, the VM has managed to optimize all your code away). We highly recommend you use Caliper to run your own microbenchmarks.</p> + +<p>You may also find +<a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a> useful +for profiling, but it's important to realize that it currently disables the JIT, +which may cause it to misattribute time to code that the JIT may be able to win +back. It's especially important after making changes suggested by Traceview +data to ensure that the resulting code actually runs faster when run without +Traceview. diff --git a/docs/html/guide/practices/design/responsiveness.jd b/docs/html/guide/practices/design/responsiveness.jd index b811d1b..a00e3aa 100644 --- a/docs/html/guide/practices/design/responsiveness.jd +++ b/docs/html/guide/practices/design/responsiveness.jd @@ -99,6 +99,10 @@ responsive to input and thus avoid ANR dialogs caused by the 5 second input event timeout. These same practices should be followed for any other threads that display UI, as they are also subject to the same timeouts.</p> +<p>You can use {@link android.os.StrictMode} to help find potentially +long running operations such as network or database operations that +you might accidentally be doing your main thread.</p> + <p>The specific constraint on IntentReceiver execution time emphasizes what they were meant to do: small, discrete amounts of work in the background such as saving a setting or registering a Notification. So as with other methods diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd index 3d630c9..36e12f6 100755 --- a/docs/html/guide/topics/resources/localization.jd +++ b/docs/html/guide/topics/resources/localization.jd @@ -433,12 +433,12 @@ Menu > Settings > Locale & text > Select locale). </p> href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p>
<h4>Creating and using a custom locale</h4>
-<p>A "custom" locale is a language/region combination that the
-Android system image does not explicitly support. (For a list of supported
-locales, see the <a href="{@docRoot}sdk/android-{@sdkCurrentVersion}.html">Android
-Version Notes</a>.) You can test how your application will run in a custom
-locale by creating a custom locale in the emulator. There are two ways to do
-this:</p>
+<p>A "custom" locale is a language/region combination that the Android
+system image does not explicitly support. (For a list of supported locales in
+Android platforms see the Version Notes in the <a
+href="{@docRoot}sdk/index.html">SDK</a> tab). You can test
+how your application will run in a custom locale by creating a custom locale in
+the emulator. There are two ways to do this:</p>
<ul>
<li>Use the Custom Locale application, which is accessible from the
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 1d6ab25..d868599 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -129,9 +129,8 @@ Menu. See <a href="menu-resource.html">Menu Resource</a>.</td> <tr> <td><code>raw/</code></td> - <td><p>Arbitrary files to save in their raw form. Files in here are not compressed by the -system. To open these resources with a raw {@link java.io.InputStream}, call {@link -android.content.res.Resources#openRawResource(int) + <td><p>Arbitrary files to save in their raw form. To open these resources with a raw +{@link java.io.InputStream}, call {@link android.content.res.Resources#openRawResource(int) Resources.openRawResource()} with the resource ID, which is {@code R.raw.<em>filename</em>}.</p> <p>However, if you need access to original file names and file hierarchy, you might consider saving some resources in the {@code diff --git a/docs/html/guide/topics/security/security.jd b/docs/html/guide/topics/security/security.jd index dbc9866..de0c6e5 100644 --- a/docs/html/guide/topics/security/security.jd +++ b/docs/html/guide/topics/security/security.jd @@ -21,14 +21,15 @@ page.title=Security and Permissions </div> </div> -<p>Android is a multi-process system, in which each application (and parts of the -system) runs in its own process. Most security between applications and -the system is enforced at the process level through standard Linux facilities, -such as user and group IDs that are assigned to applications. -Additional finer-grained security features are provided -through a "permission" mechanism that enforces restrictions on the specific -operations that a particular process can perform, and per-URI permissions -for granting ad-hoc access to specific pieces of data.</p> +<p>Android is a privilege-separated operating system, in which each +application runs with a distinct system identity (Linux user ID and group +ID). Parts of the system are also separated into distinct identities. +Linux thereby isolates applications from each other and from the system.</p> + +<p>Additional finer-grained security features are provided through a +"permission" mechanism that enforces restrictions on the specific operations +that a particular process can perform, and per-URI permissions for granting +ad-hoc access to specific pieces of data.</p> <a name="arch"></a> <h2>Security Architecture</h2> @@ -38,39 +39,46 @@ application, by default, has permission to perform any operations that would adversely impact other applications, the operating system, or the user. This includes reading or writing the user's private data (such as contacts or e-mails), reading or writing another application's files, performing -network access, keeping the device awake, etc.<p> - -<p>An application's process runs in a security sandbox. The sandbox is designed -to prevent applications from disrupting each other, except by explicitly -declaring the <em>permissions</em> they need for additional capabilities not -provided by the basic sandbox. The system handles requests for permissions -in various ways, typically by automatically allowing or disallowing based on -certificates or by prompting the user. The permissions required by an -application are declared statically in that application, so they can be known -up-front at install time and will not change after that.</p> +network access, keeping the device awake, etc.</p> + +<p>Because the kernel sandboxes applications from each other, applications +must explicitly share resources and data. They do this by declaring the +<em>permissions</em> they need for additional capabilities not provided by +the basic sandbox. Applications statically declare the permissions they +require, and the Android system prompts the user for consent at the time the +application is installed. Android has no mechanism for granting permissions +dynamically (at run-time) because it complicates the user experience to the +detriment of security.</p> + +<p>The kernel is solely responsible for sandboxing applications from each +other. In particular the Dalvik VM is not a security boundary, and any app +can run native code (see <a href="/sdk/ndk/index.html">the Android NDK</a>). +All types of applications — Java, native, and hybrid — are +sandboxed in the same way and have the same degree of security from each +other.</p> <a name="signing"></a> <h2>Application Signing</h2> -<p>All Android applications (.apk files) must be signed with a certificate whose -private key is held by their developer. This certificate identifies the author -of the application. The certificate does <em>not</em> need to be signed by -a certificate authority: it is perfectly allowable, and typical, for Android -applications to use self-signed certificates. The certificate is used only -to establish trust relationships between applications, not for wholesale -control over whether an application can be installed. The most significant -ways that signatures impact security is by determining who can access -signature-based permissions and who can share user IDs.</p> - +<p>All Android applications (.apk files) must be signed with a certificate +whose private key is held by their developer. This certificate identifies +the author of the application. The certificate does <em>not</em> need to be +signed by a certificate authority: it is perfectly allowable, and typical, +for Android applications to use self-signed certificates. The purpose of +certificates in Android is to distinguish application authors. This allows +the system to grant or deny applications access to <a +href="/guide/topics/manifest/permission-element.html#plevel">signature-level +permissions</a> and to grant or deny an application's <a +href="/guide/topics/manifest/manifest-element.html#uid">request to be given +the same Linux identity</a> as another application.</p> <a name="userid"></a> <h2>User IDs and File Access</h2> -<p>Each Android package (.apk) file installed on the device is given its -own unique Linux user ID, creating a sandbox for it and preventing it from touching -other applications (or other applications from touching it). This user ID is -assigned to it when the application is installed on the device, and -remains constant for the duration of its life on that device.</p> +<p>At install time, Android gives each package a distinct Linux user ID. The +identity remains constant for the duration of the package's life on that +device. On a different device, the same package may have a different UID; +what matters is that each package has a distinct UID on a given device.</p> <p>Because security enforcement happens at the process level, the code of any two packages can not normally @@ -150,7 +158,7 @@ activities of other applications.</li> <li>Both sending and receiving broadcasts, to control who can receive your broadcast or who can send a broadcast to you.</li> <li>When accessing and operating on a content provider.</li> -<li>Binding or starting a service.</li> +<li>Binding to or starting a service.</li> </ul> diff --git a/docs/html/guide/topics/testing/activity_testing.jd b/docs/html/guide/topics/testing/activity_testing.jd new file mode 100644 index 0000000..6392ad7 --- /dev/null +++ b/docs/html/guide/topics/testing/activity_testing.jd @@ -0,0 +1,392 @@ +page.title=Activity Testing +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li> + <a href="#ActivityTestAPI">The Activity Testing API</a> + <ol> + <li> + <a href="#ActivityInstrumentationTestCase2">ActivityInstrumentationTestCase2</a> + </li> + <li> + <a href="#ActivityUnitTestCase">ActivityUnitTestCase</a> + </li> + <li> + <a href="#SingleLaunchActivityTestCase">SingleLaunchActivityTestCase</a> + </li> + <li> + <a href="#MockObjectNotes">Mock objects and activity testing</a> + </li> + <li> + <a href="#AssertionNotes">Assertions for activity testing</a> + </li> + </ol> + </li> + <li> + <a href="#WhatToTest">What to Test</a> + </li> + <li> + <a href="#NextSteps">Next Steps</a> + </li> + <li> + <a href="#UITesting">Appendix: UI Testing Notes</a> + <ol> + <li> + <a href="#RunOnUIThread">Testing on the UI thread</a> + </li> + <li> + <a href="#NotouchMode">Turning off touch mode</a> + </li> + <li> + <a href="#UnlockDevice">Unlocking the Emulator or Device</a> + </li> + <li> + <a href="#UITestTroubleshooting">Troubleshooting UI tests</a> + </li> + </ol> + </li> + </ol> +<h2>Key Classes</h2> + <ol> + <li>{@link android.test.InstrumentationTestRunner}</li> + <li>{@link android.test.ActivityInstrumentationTestCase2}</li> + <li>{@link android.test.ActivityUnitTestCase}</li> + </ol> +<h2>Related Tutorials</h2> + <ol> + <li> + <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> + Hello, Testing</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/developing/testing/testing_eclipse.html"> + Testing in Eclipse, with ADT</a> + </li> + <li> + <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> + Testing in Other IDEs</a> + </li> + </ol> + </div> +</div> +<p> + Activity testing is particularly dependent on the the Android instrumentation framework. + Unlike other components, activities have a complex lifecycle based on callback methods; these + can't be invoked directly except by instrumentation. Also, the only way to send events to the + user interface from a program is through instrumentation. +</p> +<p> + This document describes how to test activities using instrumentation and other test + facilities. The document assumes you have already read + <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, + the introduction to the Android testing and instrumentation framework. +</p> +<h2 id="ActivityTestAPI">The Activity Testing API</h2> +<p> + The activity testing API base class is {@link android.test.InstrumentationTestCase}, + which provides instrumentation to the test case subclasses you use for Activities. +</p> +<p> + For activity testing, this base class provides these functions: +</p> +<ul> + <li> + Lifecycle control: With instrumentation, you can start the activity under test, pause it, + and destroy it, using methods provided by the test case classes. + </li> + <li> + Dependency injection: Instrumentation allows you to create mock system objects such as + Contexts or Applications and use them to run the activity under test. This + helps you control the test environment and isolate it from production systems. You can + also set up customized Intents and start an activity with them. + </li> + <li> + User interface interaction: You use instrumentation to send keystrokes or touch events + directly to the UI of the activity under test. + </li> +</ul> +<p> + The activity testing classes also provide the JUnit framework by extending + {@link junit.framework.TestCase} and {@link junit.framework.Assert}. +</p> +<p> + The two main testing subclasses are {@link android.test.ActivityInstrumentationTestCase2} and + {@link android.test.ActivityUnitTestCase}. To test an Activity that is launched in a mode + other than <code>standard</code>, you use {@link android.test.SingleLaunchActivityTestCase}. +</p> +<h3 id="ActivityInstrumentationTestCase2">ActivityInstrumentationTestCase2</h3> +<p> + The {@link android.test.ActivityInstrumentationTestCase2} test case class is designed to do + functional testing of one or more Activities in an application, using a normal system + infrastructure. It runs the Activities in a normal instance of the application under test, + using a standard system Context. It allows you to send mock Intents to the activity under + test, so you can use it to test an activity that responds to multiple types of intents, or + an activity that expects a certain type of data in the intent, or both. Notice, though, that it + does not allow mock Contexts or Applications, so you can not isolate the test from the rest of + a production system. +</p> +<h3 id="ActivityUnitTestCase">ActivityUnitTestCase</h3> +<p> + The {@link android.test.ActivityUnitTestCase} test case class tests a single activity in + isolation. Before you start the activity, you can inject a mock Context or Application, or both. + You use it to run activity tests in isolation, and to do unit testing of methods + that do not interact with Android. You can not send mock Intents to the activity under test, + although you can call + {@link android.app.Activity#startActivity(Intent) Activity.startActivity(Intent)} and then + look at arguments that were received. +</p> +<h3 id="SingleLaunchActivityTestCase">SingleLaunchActivityTestCase</h3> +<p> + The {@link android.test.SingleLaunchActivityTestCase} class is a convenience class for + testing a single activity in an environment that doesn't change from test to test. + It invokes {@link junit.framework.TestCase#setUp() setUp()} and + {@link junit.framework.TestCase#tearDown() tearDown()} only once, instead of once per + method call. It does not allow you to inject any mock objects. +</p> +<p> + This test case is useful for testing an activity that runs in a mode other than + <code>standard</code>. It ensures that the test fixture is not reset between tests. You + can then test that the activity handles multiple calls correctly. +</p> +<h3 id="MockObjectNotes">Mock objects and activity testing</h3> +<p> + This section contains notes about the use of the mock objects defined in + {@link android.test.mock} with activity tests. +</p> +<p> + The mock object {@link android.test.mock.MockApplication} is only available for activity + testing if you use the {@link android.test.ActivityUnitTestCase} test case class. + By default, <code>ActivityUnitTestCase</code>, creates a hidden <code>MockApplication</code> + object that is used as the application under test. You can inject your own object using + {@link android.test.ActivityUnitTestCase#setApplication(Application) setApplication()}. +</p> +<h3 id="AssertionNotes">Assertions for activity testing</h3> +<p> + {@link android.test.ViewAsserts} defines assertions for Views. You use it to verify the + alignment and position of View objects, and to look at the state of ViewGroup objects. +</p> +<h2 id="WhatToTest">What To Test</h2> +<ul> + <li> + Input validation: Test that an activity responds correctly to input values in an + EditText View. Set up a keystroke sequence, send it to the activity, and then + use {@link android.view.View#findViewById(int)} to examine the state of the View. You can + verify that a valid keystroke sequence enables an OK button, while an invalid one leaves the + button disabled. You can also verify that the Activity responds to invalid input by + setting error messages in the View. + </li> + <li> + Lifecycle events: Test that each of your application's activities handles lifecycle events + correctly. In general, lifecycle events are actions, either from the system or from the + user, that trigger a callback method such as <code>onCreate()</code> or + <code>onClick()</code>. For example, an activity should respond to pause or destroy events + by saving its state. Remember that even a change in screen orientation causes the current + activity to be destroyed, so you should test that accidental device movements don't + accidentally lose the application state. + </li> + <li> + Intents: Test that each activity correctly handles the intents listed in the intent + filter specified in its manifest. You can use + {@link android.test.ActivityInstrumentationTestCase2} to send mock Intents to the + activity under test. + </li> + <li> + Runtime configuration changes: Test that each activity responds correctly to the + possible changes in the device's configuration while your application is running. These + include a change to the device's orientation, a change to the current language, and so + forth. Handling these changes is described in detail in the topic + <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime + Changes</a>. + </li> + <li> + Screen sizes and resolutions: Before you publish your application, make sure to test it on + all of the screen sizes and densities on which you want it to run. You can test the + application on multiple sizes and densities using AVDs, or you can test your application + directly on the devices that you are targeting. For more information, see the topic + <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>. + </li> +</ul> +<h2 id="NextSteps">Next Steps</h2> +<p> + To learn how to set up and run tests in Eclipse, please refer to <a + href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in + Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a + href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other + IDEs</a>. +</p> +<p> + If you want a step-by-step introduction to testing activities, try one of the + testing tutorials: +</p> +<ul> + <li> + The <a + href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, + Testing</a> tutorial introduces basic testing concepts and procedures in the + context of the Hello, World application. + </li> + <li> + The <a + href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity + Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. + It guides you through a more complex testing scenario that you develop against a + more realistic activity-oriented application. + </li> +</ul> +<h2 id="UITesting">Appendix: UI Testing Notes</h2> +<p> + The following sections have tips for testing the UI of your Android application, specifically + to help you handle actions that run in the UI thread, touch screen and keyboard events, and home + screen unlock during testing. +</p> +<h3 id="RunOnUIThread">Testing on the UI thread</h3> +<p> + An application's activities run on the application's <strong>UI thread</strong>. Once the + UI is instantiated, for example in the activity's <code>onCreate()</code> method, then all + interactions with the UI must run in the UI thread. When you run the application normally, it + has access to the thread and does not have to do anything special. +</p> +<p> + This changes when you run tests against the application. With instrumentation-based classes, + you can invoke methods against the UI of the application under test. The other test classes + don't allow this. To run an entire test method on the UI thread, you can annotate the thread + with <code>@UIThreadTest</code>. Notice that this will run <em>all</em> of the method statements + on the UI thread. Methods that do not interact with the UI are not allowed; for example, you + can't invoke <code>Instrumentation.waitForIdleSync()</code>. +</p> +<p> + To run a subset of a test method on the UI thread, create an anonymous class of type + <code>Runnable</code>, put the statements you want in the <code>run()</code> method, and + instantiate a new instance of the class as a parameter to the method + <code><em>appActivity</em>.runOnUiThread()</code>, where <code><em>appActivity</em></code> is + the instance of the application you are testing. +</p> +<p> + For example, this code instantiates an activity to test, requests focus (a UI action) for the + Spinner displayed by the activity, and then sends a key to it. Notice that the calls to + <code>waitForIdleSync</code> and <code>sendKeys</code> aren't allowed to run on the UI thread: +</p> +<pre> + private MyActivity mActivity; // MyActivity is the class name of the app under test + private Spinner mSpinner; + + ... + + protected void setUp() throws Exception { + super.setUp(); + mInstrumentation = getInstrumentation(); + + mActivity = getActivity(); // get a references to the app under test + + /* + * Get a reference to the main widget of the app under test, a Spinner + */ + mSpinner = (Spinner) mActivity.findViewById(com.android.demo.myactivity.R.id.Spinner01); + + ... + + public void aTest() { + /* + * request focus for the Spinner, so that the test can send key events to it + * This request must be run on the UI thread. To do this, use the runOnUiThread method + * and pass it a Runnable that contains a call to requestFocus on the Spinner. + */ + mActivity.runOnUiThread(new Runnable() { + public void run() { + mSpinner.requestFocus(); + } + }); + + mInstrumentation.waitForIdleSync(); + + this.sendKeys(KeyEvent.KEYCODE_DPAD_CENTER); +</pre> + +<h3 id="NotouchMode">Turning off touch mode</h3> +<p> + To control the emulator or a device with key events you send from your tests, you must turn off + touch mode. If you do not do this, the key events are ignored. +</p> +<p> + To turn off touch mode, you invoke + <code>ActivityInstrumentationTestCase2.setActivityTouchMode(false)</code> + <em>before</em> you call <code>getActivity()</code> to start the activity. You must invoke the + method in a test method that is <em>not</em> running on the UI thread. For this reason, you + can't invoke the touch mode method from a test method that is annotated with + <code>@UIThread</code>. Instead, invoke the touch mode method from <code>setUp()</code>. +</p> +<h3 id="UnlockDevice">Unlocking the emulator or device</h3> +<p> + You may find that UI tests don't work if the emulator's or device's home screen is disabled with + the keyguard pattern. This is because the application under test can't receive key events sent + by <code>sendKeys()</code>. The best way to avoid this is to start your emulator or device + first and then disable the keyguard for the home screen. +</p> +<p> + You can also explicitly disable the keyguard. To do this, + you need to add a permission in the manifest file (<code>AndroidManifest.xml</code>) and + then disable the keyguard in your application under test. Note, though, that you either have to + remove this before you publish your application, or you have to disable it with code in + the published application. +</p> +<p> + To add the the permission, add the element + <code><uses-permission android:name="android.permission.DISABLE_KEYGUARD"/></code> + as a child of the <code><manifest></code> element. To disable the KeyGuard, add the + following code to the <code>onCreate()</code> method of activities you intend to test: +</p> +<pre> + mKeyGuardManager = (KeyguardManager) getSystemService(KEYGUARD_SERVICE); + mLock = mKeyGuardManager.newKeyguardLock("<em>activity_classname</em>"); + mLock.disableKeyguard(); +</pre> +<p>where <code><em>activity_classname</em></code> is the class name of the activity.</p> +<h3 id="UITestTroubleshooting">Troubleshooting UI tests</h3> +<p> + This section lists some of the common test failures you may encounter in UI testing, and their + causes: +</p> +<dl> + <dt><code>WrongThreadException</code></dt> + <dd> + <p><strong>Problem:</strong></p> + For a failed test, the Failure Trace contains the following error message: + <code> + android.view.ViewRoot$CalledFromWrongThreadException: Only the original thread that created + a view hierarchy can touch its views. + </code> + <p><strong>Probable Cause:</strong></p> + This error is common if you tried to send UI events to the UI thread from outside the UI + thread. This commonly happens if you send UI events from the test application, but you don't + use the <code>@UIThread</code> annotation or the <code>runOnUiThread()</code> method. The + test method tried to interact with the UI outside the UI thread. + <p><strong>Suggested Resolution:</strong></p> + Run the interaction on the UI thread. Use a test class that provides instrumentation. See + the previous section <a href="#RunOnUIThread">Testing on the UI Thread</a> + for more details. + </dd> + <dt><code>java.lang.RuntimeException</code></dt> + <dd> + <p><strong>Problem:</strong></p> + For a failed test, the Failure Trace contains the following error message: + <code> + java.lang.RuntimeException: This method can not be called from the main application thread + </code> + <p><strong>Probable Cause:</strong></p> + This error is common if your test method is annotated with <code>@UiThreadTest</code> but + then tries to do something outside the UI thread or tries to invoke + <code>runOnUiThread()</code>. + <p><strong>Suggested Resolution:</strong></p> + Remove the <code>@UiThreadTest</code> annotation, remove the <code>runOnUiThread()</code> + call, or re-factor your tests. + </dd> +</dl> diff --git a/docs/html/guide/topics/testing/contentprovider_testing.jd b/docs/html/guide/topics/testing/contentprovider_testing.jd new file mode 100644 index 0000000..279e347 --- /dev/null +++ b/docs/html/guide/topics/testing/contentprovider_testing.jd @@ -0,0 +1,222 @@ +page.title=Content Provider Testing +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li> + <a href="#DesignAndTest">Content Provider Design and Testing</a> + </li> + <li> + <a href="#ContentProviderTestAPI">The Content Provider Testing API</a> + <ol> + <li> + <a href="#ProviderTestCase2">ProviderTestCase2 </a> + </li> + <li> + <a href="#MockObjects">Mock object classes</a> + </li> + </ol> + </li> + <li> + <a href="#WhatToTest">What To Test</a> + </li> + <li> + <a href="#NextSteps">Next Steps</a> + </li> + </ol> + <h2>Key Classes</h2> + <ol> + <li>{@link android.test.InstrumentationTestRunner}</li> + <li>{@link android.test.ProviderTestCase2}</li> + <li>{@link android.test.IsolatedContext}</li> + <li>{@link android.test.mock.MockContentResolver}</li> + </ol> + <h2>See Also</h2> + <ol> + <li> + <a + href="{@docRoot}guide/topics/testing/topics/testing_android.html"> + Testing Fundamentals</a> + </li> + <li> + <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> + Testing in Eclipse, with ADT</a> + </li> + <li> + <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> + Testing in Other IDEs</a> + </li> + </ol> + </div> +</div> +<p> + Content providers, which store and retrieve data and make it accessible across applications, + are a key part of the Android API. As an application developer you're allowed to provide your + own public providers for use by other applications. If you do, then you should test them + using the API you publish. +</p> +<p> + This document describes how to test public content providers, although the information is + also applicable to providers that you keep private to your own application. If you aren't + familiar with content providers or the Android testing framework, please read + <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>, + the guide to developing content providers, and + <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, + the introduction to the Android testing and instrumentation framework. +</p> +<h2 id="DesignAndTest">Content Provider Design and Testing</h2> +<p> + In Android, content providers are viewed externally as data APIs that provide + tables of data, with their internals hidden from view. A content provider may have many + public constants, but it usually has few if any public methods and no public variables. + This suggests that you should write your tests based only on the provider's public members. + A content provider that is designed like this is offering a contract between itself and its + users. +</p> +<p> + The base test case class for content providers, + {@link android.test.ProviderTestCase2}, allows you to test your content provider in an + isolated environment. Android mock objects such as {@link android.test.IsolatedContext} and + {@link android.test.mock.MockContentResolver} also help provide an isolated test environment. +</p> +<p> + As with other Android tests, provider test packages are run under the control of the test + runner {@link android.test.InstrumentationTestRunner}. The section + <a href="{@docRoot}guide/topics/testing/testing_android.html#InstrumentationTestRunner"> + Running Tests With InstrumentationTestRunner</a> describes the test runner in + more detail. The topic <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> + Testing in Eclipse, with ADT</a> shows you how to run a test package in Eclipse, and the + topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> + Testing in Other IDEs</a> + shows you how to run a test package from the command line. +</p> +<h2 id="ContentProviderTestAPI">Content Provider Testing API</h2> +<p> + The main focus of the provider testing API is to provide an isolated testing environment. This + ensures that tests always run against data dependencies set explicitly in the test case. It + also prevents tests from modifying actual user data. For example, you want to avoid writing + a test that fails because there was data left over from a previous test, and you want to + avoid adding or deleting contact information in a actual provider. +</p> +<p> + The test case class and mock object classes for provider testing set up this isolated testing + environment for you. +</p> +<h3 id="ProviderTestCase2">ProviderTestCase2</h3> +<p> + You test a provider with a subclass of {@link android.test.ProviderTestCase2}. This base class + extends {@link android.test.AndroidTestCase}, so it provides the JUnit testing framework as well + as Android-specific methods for testing application permissions. The most important + feature of this class is its initialization, which creates the isolated test environment. +</p> +<p> + The initialization is done in the constructor for {@link android.test.ProviderTestCase2}, which + subclasses call in their own constructors. The {@link android.test.ProviderTestCase2} + constructor creates an {@link android.test.IsolatedContext} object that allows file and + database operations but stubs out other interactions with the Android system. + The file and database operations themselves take place in a directory that is local to the + device or emulator and has a special prefix. +</p> +<p> + The constructor then creates a {@link android.test.mock.MockContentResolver} to use as the + resolver for the test. The {@link android.test.mock.MockContentResolver} class is described in + detail in the section + <a href="{@docRoot}guide/topics/testing/test_android#MockObjectClasses">Mock object classes</a>. +</p> +<p> + Lastly, the constructor creates an instance of the provider under test. This is a normal + {@link android.content.ContentProvider} object, but it takes all of its environment information + from the {@link android.test.IsolatedContext}, so it is restricted to + working in the isolated test environment. All of the tests done in the test case class run + against this isolated object. +</p> +<h3 id="MockObjects">Mock object classes</h3> +<p> + {@link android.test.ProviderTestCase2} uses {@link android.test.IsolatedContext} and + {@link android.test.mock.MockContentResolver}, which are standard mock object classes. To + learn more about them, please read + <a href="{@docRoot}guide/topics/testing/test_android#MockObjectClasses"> + Testing Fundamentals</a>. +</p> +<h2 id="WhatToTest">What To Test</h2> +<p> + The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> + lists general considerations for testing Android components. + Here are some specific guidelines for testing content providers. +</p> +<ul> + <li> + Test with resolver methods: Even though you can instantiate a provider object in + {@link android.test.ProviderTestCase2}, you should always test with a resolver object + using the appropriate URI. This ensures that you are testing the provider using the same + interaction that a regular application would use. + </li> + <li> + Test a public provider as a contract: If you intent your provider to be public and + available to other applications, you should test it as a contract. This includes + the following ideas: + <ul> + <li> + Test with constants that your provider publicly exposes. For + example, look for constants that refer to column names in one of the provider's + data tables. These should always be constants publicly defined by the provider. + </li> + <li> + Test all the URIs offered by your provider. Your provider may offer several URIs, + each one referring to a different aspect of the data. The + <a href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample, + for example, features a provider that offers one URI for retrieving a list of notes, + another for retrieving an individual note by it's database ID, and a third for + displaying notes in a live folder. + </li> + <li> + Test invalid URIs: Your unit tests should deliberately call the provider with an + invalid URI, and look for errors. Good provider design is to throw an + IllegalArgumentException for invalid URIs. + + </li> + </ul> + </li> + <li> + Test the standard provider interactions: Most providers offer six access methods: + query, insert, delete, update, getType, and onCreate(). Your tests should verify that all + of these methods work. These are described in more detail in the topic + <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. + </li> + <li> + Test business logic: Don't forget to test the business logic that your provider should + enforce. Business logic includes handling of invalid values, financial or arithmetic + calculations, elimination or combining of duplicates, and so forth. A content provider + does not have to have business logic, because it may be implemented by activities that + modify the data. If the provider does implement business logic, you should test it. + </li> +</ul> +<h2 id="NextSteps">Next Steps</h2> +<p> + To learn how to set up and run tests in Eclipse, please refer to <a + href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in + Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a + href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other + IDEs</a>. +</p> +<p> + If you want a step-by-step introduction to testing activities, try one of the + testing tutorials: +</p> +<ul> + <li> + The <a + href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, + Testing</a> tutorial introduces basic testing concepts and procedures in the + context of the Hello, World application. + </li> + <li> + The <a + href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity + Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. + It guides you through a more complex testing scenario that you develop against a + more realistic activity-oriented application. + </li> +</ul> diff --git a/docs/html/guide/topics/testing/index.jd b/docs/html/guide/topics/testing/index.jd new file mode 100644 index 0000000..762a897 --- /dev/null +++ b/docs/html/guide/topics/testing/index.jd @@ -0,0 +1,84 @@ +page.title=Testing +@jd:body +<p> + The Android development environment includes an integrated testing framework that helps you + test all aspects of your application. +</p> +<h4>Fundamentals</h4> +<p> + To start learning how to use the framework to create tests for your applications, please + read the topic <a href="{@docRoot}guide/topics/testing/testing_android.html"> + Testing Fundamentals</a>. +</p> +<h4>Concepts</h4> +<ul> + <li> + <a href="{@docRoot}guide/topics/testing/activity_testing.html"> + Activity Testing</a> focuses on testing activities. It describes how instrumentation allows + you to control activities outside the normal application lifecycle. It also lists + activity-specific features you should test, and it provides tips for testing Android + user interfaces. + </li> + <li> + <a href="{@docRoot}guide/topics/testing/contentprovider_testing.html"> + Content Provider Testing</a> focuses on testing content providers. It describes the + mock system objects you can use, provides tips for designing providers so that they + can be tested, and lists provider-specific features you should test. + </li> + <li> + <a href="{@docRoot}guide/topics/testing/service_testing.html"> + Service Testing</a> focuses on testing services. It also lists service-specific features + you should test. + </li> + <li> + <a href="{@docRoot}guide/topics/testing/what_to_test.html">What to Test</a> + is an overview of the types of testing you should do. It focuses on testing + system-wide aspects of Android that can affect every component in your application. + </li> +</ul> +<h4>Procedures</h4> +<ul> + <li> + The topic <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> + Testing in Eclipse, with ADT</a> describes how to create and run tests in Eclipse with ADT. + </li> + <li> + The topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> + Testing in other IDEs</a> describes how to create and run tests with command-line tools. + </li> +</ul> +<h4>Tutorials</h4> +<ul> + <li> + The <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> + Hello, Testing</a> tutorial introduces basic testing concepts and procedures. + </li> + <li> + For a more advanced tutorial, try + <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>, + which guides you through a more complex testing scenario. + </li> +</ul> +<h4>Tools</h4> +<ul> + <li> + The + <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, + usually called Monkey, is a command-line tool that sends pseudo-random + streams of keystrokes, touches, and gestures to a device. + </li> + <li> + The <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a> tool + is an API and execution environment. You use monkeyrunner with Python programs + to test applications and devices. + </li> +</ul> +<h4>Samples</h4> +<ul> + <li> + The <a href="{@docRoot}resources/samples/AlarmServiceTest.html">Alarm Service Test</a> + is a test package for the <a href="{@docRoot}resources/samples/Alarm.html">Alarm</a> + sample application. It provides a simple example of unit + testing a {@link android.app.Service}. + </li> +</ul> diff --git a/docs/html/guide/topics/testing/service_testing.jd b/docs/html/guide/topics/testing/service_testing.jd new file mode 100644 index 0000000..3979f3c --- /dev/null +++ b/docs/html/guide/topics/testing/service_testing.jd @@ -0,0 +1,178 @@ +page.title=Service Testing +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li> + <a href="#DesignAndTest">Service Design and Testing</a> + </li> + <li> + <a href="#ServiceTestCase">ServiceTestCase</a> + </li> + <li> + <a href="#MockObjects">Mock object classes</a> + </li> + <li> + <a href="#TestAreas">What to Test</a> + </li> + </ol> + <h2>Key Classes</h2> + <ol> + <li>{@link android.test.InstrumentationTestRunner}</li> + <li>{@link android.test.ServiceTestCase}</li> + <li>{@link android.test.mock.MockApplication}</li> + <li>{@link android.test.RenamingDelegatingContext}</li> + </ol> + <h2>Related Tutorials</h2> + <ol> + <li> + <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> + Hello, Testing</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/developing/testing/testing_eclipse.html"> + Testing in Eclipse, with ADT</a> + </li> + <li> + <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> + Testing in Other IDEs</a> + </li> + </ol> + </div> +</div> +<p> + Android provides a testing framework for Service objects that can run them in + isolation and provides mock objects. The test case class for Service objects is + {@link android.test.ServiceTestCase}. Since the Service class assumes that it is separate + from its clients, you can test a Service object without using instrumentation. +</p> +<p> + This document describes techniques for testing Service objects. If you aren't familiar with the + Service class, please read <a href="{@docRoot}guide/topics/fundamentals.html"> + Application Fundamentals</a>. If you aren't familiar with Android testing, please read + <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, + the introduction to the Android testing and instrumentation framework. +</p> +<h2 id="DesignAndTest">Service Design and Testing</h2> +<p> + When you design a Service, you should consider how your tests can examine the various states + of the Service lifecycle. If the lifecycle methods that start up your Service, such as + {@link android.app.Service#onCreate() onCreate()} or + {@link android.app.Service#onStartCommand(Intent, int, int) onStartCommand()} do not normally + set a global variable to indicate that they were successful, you may want to provide such a + variable for testing purposes. +</p> +<p> + Most other testing is facilitated by the methods in the {@link android.test.ServiceTestCase} + test case class. For example, the {@link android.test.ServiceTestCase#getService()} method + returns a handle to the Service under test, which you can test to confirm that the Service is + running even at the end of your tests. +</p> +<h2 id="ServiceTestCase">ServiceTestCase</h2> +<p> + {@link android.test.ServiceTestCase} extends the JUnit {@link junit.framework.TestCase} class + with with methods for testing application permissions and for controlling the application and + Service under test. It also provides mock application and Context objects that isolate your + test from the rest of the system. +</p> +<p> + {@link android.test.ServiceTestCase} defers initialization of the test environment until you + call {@link android.test.ServiceTestCase#startService(Intent) ServiceTestCase.startService()} or + {@link android.test.ServiceTestCase#bindService(Intent) ServiceTestCase.bindService()}. This + allows you to set up your test environment, particularly your mock objects, before the Service + is started. +</p> +<p> + Notice that the parameters to <code>ServiceTestCase.bindService()</code>are different from + those for <code>Service.bindService()</code>. For the <code>ServiceTestCase</code> version, + you only provide an Intent. Instead of returning a boolean, + <code>ServiceTestCase.bindService()</code> returns an object that subclasses + {@link android.os.IBinder}. +</p> +<p> + The {@link android.test.ServiceTestCase#setUp()} method for {@link android.test.ServiceTestCase} + is called before each test. It sets up the test fixture by making a copy of the current system + Context before any test methods touch it. You can retrieve this Context by calling + {@link android.test.ServiceTestCase#getSystemContext()}. If you override this method, you must + call <code>super.setUp()</code> as the first statement in the override. +</p> +<p> + The methods {@link android.test.ServiceTestCase#setApplication(Application) setApplication()} + and {@link android.test.AndroidTestCase#setContext(Context)} setContext()} allow you to set + a mock Context or mock Application (or both) for the Service, before you start it. These mock + objects are described in <a href="#MockObjects">Mock object classes</a>. +</p> +<p> + By default, {@link android.test.ServiceTestCase} runs the test method + {@link android.test.AndroidTestCase#testAndroidTestCaseSetupProperly()}, which asserts that + the base test case class successfully set up a Context before running. +</p> +<h2 id="MockObjects">Mock object classes</h2> +<p> + <code>ServiceTestCase</code> assumes that you will use a mock Context or mock Application + (or both) for the test environment. These objects isolate the test environment from the + rest of the system. If you don't provide your own instances of these objects before you + start the Service, then {@link android.test.ServiceTestCase} will create its own internal + instances and inject them into the Service. You can override this behavior by creating and + injecting your own instances before starting the Service +</p> +<p> + To inject a mock Application object into the Service under test, first create a subclass of + {@link android.test.mock.MockApplication}. <code>MockApplication</code> is a subclass of + {@link android.app.Application} in which all the methods throw an Exception, so to use it + effectively you subclass it and override the methods you need. You then inject it into the + Service with the + {@link android.test.ServiceTestCase#setApplication(Application) setApplication()} method. + This mock object allows you to control the application values that the Service sees, and + isolates it from the real system. In addition, any hidden dependencies your Service has on + its application reveal themselves as exceptions when you run the test. +</p> +<p> + You inject a mock Context into the Service under test with the + {@link android.test.AndroidTestCase#setContext(Context) setContext()} method. The mock + Context classes you can use are described in more detail in + <a href="{@docRoot}guide/topics/testing/testing_android.html#MockObjectClasses"> + Testing Fundamentals</a>. +</p> +<h2 id="TestAreas">What to Test</h2> +<p> + The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> + lists general considerations for testing Android components. + Here are some specific guidelines for testing a Service: +</p> +<ul> + <li> + Ensure that the {@link android.app.Service#onCreate()} is called in response to + {@link android.content.Context#startService(Intent) Context.startService()} or + {@link android.content.Context#bindService(Intent,ServiceConnection,int) Context.bindService()}. + Similarly, you should ensure that {@link android.app.Service#onDestroy()} is called in + response to {@link android.content.Context#stopService(Intent) Context.stopService()}, + {@link android.content.Context#unbindService(ServiceConnection) Context.unbindService()}, + {@link android.app.Service#stopSelf()}, or + {@link android.app.Service#stopSelfResult(int) stopSelfResult()}. + </li> + <li> + Test that your Service correctly handles multiple calls from + <code>Context.startService()</code>. Only the first call triggers + <code>Service.onCreate()</code>, but all calls trigger a call to + <code>Service.onStartCommand()</code>. + <p> + In addition, remember that <code>startService()</code> calls don't + nest, so a single call to <code>Context.stopService()</code> or + <code>Service.stopSelf()</code> (but not <code>stopSelf(int)</code>) + will stop the Service. You should test that your Service stops at the correct point. + </p> + </li> + <li> + Test any business logic that your Service implements. Business logic includes checking for + invalid values, financial and arithmetic calculations, and so forth. + </li> +</ul> diff --git a/docs/html/guide/topics/testing/testing_android.jd b/docs/html/guide/topics/testing/testing_android.jd index 935aaf9..d4b0dcc 100755 --- a/docs/html/guide/topics/testing/testing_android.jd +++ b/docs/html/guide/topics/testing/testing_android.jd @@ -1,4 +1,4 @@ -page.title=Testing and Instrumentation +page.title=Testing Fundamentals @jd:body <div id="qv-wrapper"> @@ -6,65 +6,62 @@ page.title=Testing and Instrumentation <h2>In this document</h2> <ol> <li> - <a href="#Overview">Overview</a> + <a href="#TestStructure">Test Structure</a> + </li> + <li> + <a href="#TestProjects">Test Projects</a> </li> <li> <a href="#TestAPI">The Testing API</a> <ol> <li> - <a href="#Extensions">JUnit test case classes</a> + <a href="#JUnit">JUnit</a> + </li> + <li> + <a href="#Instrumentation">Instrumentation</a> </li> <li> - <a href="#Instrumentation">Instrumentation test case classes</a> + <a href="#TestCaseClasses">Test case classes</a> </li> <li> - <a href="#Assert">Assert classes</a> + <a href="#AssertionClasses">Assertion classes</a> </li> <li> - <a href="#MockObjects">Mock object classes</a> + <a href="#MockObjectClasses">Mock object classes</a> </li> - <li> - <a href="#InstrumentationTestRunner">Instrumentation Test Runner</a> - </li> </ol> </li> <li> - <a href="#TestEnviroment">Working in the Test Environment</a> + <a href="#InstrumentationTestRunner">Running Tests</a> </li> <li> - <a href="#TestAreas">What to Test</a> + <a href="#TestResults">Seeing Test Results</a> </li> <li> - <a href="#UITesting">Appendix: UI Testing Notes</a> - <ol> - <li> - <a href="#RunOnUIThread">Testing on the UI thread</a> - </li> - <li> - <a href="#NotouchMode">Turning off touch mode</a> - </li> - <li> - <a href="#UnlockDevice">Unlocking the Emulator or Device</a> - </li> - <li> - <a href="#UITestTroubleshooting">Troubleshooting UI tests</a> - </li> - </ol> + <a href="#Monkeys">monkey and monkeyrunner</a> + </li> + <li> + <a href="#PackageNames">Working With Package Names</a> + </li> + <li> + <a href="#WhatToTest">What To Test</a> + </li> + <li> + <a href="#NextSteps">Next Steps</a> </li> </ol> <h2>Key classes</h2> <ol> <li>{@link android.test.InstrumentationTestRunner}</li> - <li>{@link android.test.ActivityInstrumentationTestCase2}</li> - <li>{@link android.test.ActivityUnitTestCase}</li> - <li>{@link android.test.ApplicationTestCase}</li> - <li>{@link android.test.ProviderTestCase2}</li> - <li>{@link android.test.ServiceTestCase}</li> + <li>{@link android.test}</li> + <li>{@link android.test.mock}</li> + <li>{@link junit.framework}</li> </ol> <h2>Related tutorials</h2> <ol> <li> - <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, Testing</a> + <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> + Hello, Testing</a> </li> <li> <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> @@ -73,445 +70,594 @@ page.title=Testing and Instrumentation <h2>See also</h2> <ol> <li> - <a href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in Eclipse, with ADT</a> + <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> + Testing in Eclipse, with ADT</a> </li> <li> - <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a> + <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> + Testing in Other IDEs</a> + </li> + <li> + <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html"> + monkeyrunner</a> + </li> + <li> + <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a> </li> </ol> </div> </div> - -<p>Android includes a powerful set of testing tools that extend the -industry-standard JUnit test framework with features specific to the Android -environment. Although you can test an Android application with JUnit, the -Android tools allow you to write much more sophisticated tests for every aspect -of your application, both at the unit and framework levels.</p> - -<p>Key features of the Android testing environment include:</p> - +<p> + The Android testing framework, an integral part of the development environment, + provides an architecture and powerful tools that help you test every aspect of your application + at every level from unit to framework. +</p> +<p> + The testing framework has these key features: +</p> <ul> - <li>Android extensions to the JUnit framework that provide access to Android -system objects.</li> - <li>An instrumentation framework that lets tests control and examine the -application.</li> - <li>Mock versions of commonly-used Android system objects.</li> - <li>Tools for running single tests or test suites, with or without -instrumentation.</li> - <li>Support for managing tests and test projects in the ADT Plugin for Eclipse -and at the command line.</li> + <li> + Android test suites are based on JUnit. You can use plain JUnit to test a class that doesn't + call the Android API, or Android's JUnit extensions to test Android components. If you're + new to Android testing, you can start with general-purpose test case classes such as {@link + android.test.AndroidTestCase} and then go on to use more sophisticated classes. + </li> + <li> + The Android JUnit extensions provide component-specific test case classes. These classes + provide helper methods for creating mock objects and methods that help you control the + lifecycle of a component. + </li> + <li> + Test suites are contained in test packages that are similar to main application packages, so + you don't need to learn a new set of tools or techniques for designing and building tests. + </li> + <li> + The SDK tools for building and tests are available in Eclipse with ADT, and also in + command-line form for use with other IDES. These tools get information from the project of + the application under test and use this information to automatically create the build files, + manifest file, and directory structure for the test package. + </li> + <li> + The SDK also provides + <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a>, an API + testing devices with Python programs, and <a + href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, + a command-line tool for stress-testing UIs by sending pseudo-random events to a device. + </li> </ul> +<p> + This document describes the fundamentals of the Android testing framework, including the + structure of tests, the APIs that you use to develop tests, and the tools that you use to run + tests and view results. The document assumes you have a basic knowledge of Android application + programming and JUnit testing methodology. +</p> +<p> + The following diagram summarizes the testing framework: +</p> +<div style="width: 70%; margin-left:auto; margin-right:auto;"> +<a href="{@docRoot}images/testing/test_framework.png"> + <img src="{@docRoot}images/testing/test_framework.png" + alt="The Android testing framework"/> +</a> +</div> +<h2 id="TestStructure">Test Structure</h2> +<p> + Android's build and test tools assume that test projects are organized into a standard + structure of tests, test case classes, test packages, and test projects. +</p> +<p> + Android testing is based on JUnit. In general, a JUnit test is a method whose + statements test a part of the application under test. You organize test methods into classes + called test cases (or test suites). Each test is an isolated test of an individual module in + the application under test. Each class is a container for related test methods, although it + often provides helper methods as well. +</p> +<p> + In JUnit, you build one or more test source files into a class file. Similarly, in Android you + use the SDK's build tools to build one or more test source files into class files in an + Android test package. In JUnit, you use a test runner to execute test classes. In Android, you + use test tools to load the test package and the application under test, and the tools then + execute an Android-specific test runner. +</p> +<h2 id="TestProjects">Test Projects</h2> +<p> + Tests, like Android applications, are organized into projects. +</p> +<p> + A test project is a directory or Eclipse project in which you create the source code, manifest + file, and other files for a test package. The Android SDK contains tools for Eclipse with ADT + and for the command line that create and update test projects for you. The tools create the + directories you use for source code and resources and the manifest file for the test package. + The command-line tools also create the Ant build files you need. +</p> +<p> + You should always use Android tools to create a test project. Among other benefits, + the tools: +</p> + <ul> + <li> + Automatically set up your test package to use + {@link android.test.InstrumentationTestRunner} as the test case runner. You must use + <code>InstrumentationTestRunner</code> (or a subclass) to run JUnit tests. + </li> + <li> + Create an appropriate name for the test package. If the application + under test has a package name of <code>com.mydomain.myapp</code>, then the + Android tools set the test package name to <code>com.mydomain.myapp.test</code>. This + helps you identify their relationship, while preventing conflicts within the system. + </li> + <li> + Automatically create the proper build files, manifest file, and directory + structure for the test project. This helps you to build the test package without + having to modify build files and sets up the linkage between your test package and + the application under test. + The + </li> + </ul> +<p> + You can create a test project anywhere in your file system, but the best approach is to + add the test project so that its root directory <code>tests/</code> is at the same level + as the <code>src/</code> directory of the main application's project. This helps you find the + tests associated with an application. For example, if your application project's root directory + is <code>MyProject</code>, then you should use the following directory structure: +</p> +<pre class="classic no-pretty-print"> + MyProject/ + AndroidManifest.xml + res/ + ... (resources for main application) + src/ + ... (source code for main application) ... + tests/ + AndroidManifest.xml + res/ + ... (resources for tests) + src/ + ... (source code for tests) +</pre> +<h2 id="TestAPI">The Testing API</h2> +<p> + The Android testing API is based on the JUnit API and extended with a instrumentation + framework and Android-specific testing classes. +</p> +<h3 id="JUnit">JUnit</h3> +<p> + You can use the JUnit {@link junit.framework.TestCase TestCase} class to do unit testing on + a plain Java object. <code>TestCase</code> is also the base class for + {@link android.test.AndroidTestCase}, which you can use to test Android-dependent objects. + Besides providing the JUnit framework, AndroidTestCase offers Android-specific setup, + teardown, and helper methods. +</p> +<p> + You use the JUnit {@link junit.framework.Assert} class to display test results. + The assert methods compare values you expect from a test to the actual results and + throw an exception if the comparison fails. Android also provides a class of assertions that + extend the possible types of comparisons, and another class of assertions for testing the UI. + These are described in more detail in the section <a href="#AssertionClasses"> + Assertion classes</a> +</p> +<p> + To learn more about JUnit, you can read the documentation on the + <a href="http://www.junit.org">junit.org</a> home page. + Note that the Android testing API supports JUnit 3 code style, but not JUnit 4. Also, you must + use Android's instrumented test runner {@link android.test.InstrumentationTestRunner} to run + your test case classes. This test runner is described in the + section <a href="#InstrumentationTestRunner">Running Tests</a>. +</p> +<h3 id="Instrumentation">Instrumentation</h3> +<p> + Android instrumentation is a set of control methods or "hooks" in the Android system. These hooks + control an Android component independently of its normal lifecycle. They also control how + Android loads applications. +</p> +<p> + Normally, an Android component runs in a lifecycle determined by the system. For example, an + Activity object's lifecycle starts when the Activity is activated by an Intent. The object's + <code>onCreate()</code> method is called, followed by <code>onResume()</code>. When the user + starts another application, the <code>onPause()</code> method is called. If the Activity + code calls the <code>finish()</code> method, the <code>onDestroy()</code> method is called. + The Android framework API does not provide a way for your code to invoke these callback + methods directly, but you can do so using instrumentation. +</p> +<p> + Also, the system runs all the components of an application into the same + process. You can allow some components, such as content providers, to run in a separate process, + but you can't force an application to run in the same process as another application that is + already running. +</p> +<p> + With Android instrumentation, though, you can invoke callback methods in your test code. + This allows you to run through the lifecycle of a component step by step, as if you were + debugging the component. The following test code snippet demonstrates how to use this to + test that an Activity saves and restores its state: +</p> +<a name="ActivitySnippet"></a> +<pre> + // Start the main activity of the application under test + mActivity = getActivity(); -<p>This document is an overview of the Android testing environment and the way -you use it. The document assumes you have a basic knowledge of Android -application programming and JUnit testing methodology.</p> - -<h2 id="Overview">Overview</h2> - -<p> At the heart of the Android testing environment is an instrumentation -framework that your test application uses to precisely control the application -under test. With instrumentation, you can set up mock system objects such as -Contexts before the main application starts, control your application at various -points of its lifecycle, send UI events to the application, and examine the -application's state during its execution. The instrumentation framework -accomplishes this by running both the main application and the test application -in the same process. </p> - -<p>Your test application is linked to the application under test by means of an -<a -href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><code><instrumentation></code></a> -element in the test application's manifest file. The attributes of the element -specify the package name of the application under test and also tell Android how -to run the test application. Instrumentation is described in more detail in the -section <a href="#InstrumentationTestRunner">Instrumentation Test -Runner</a>.</p> - -<p>The following diagram summarizes the Android testing environment:</p> - -<img src="{@docRoot}images/testing/android_test_framework.png"/> + // Get a handle to the Activity object's main UI widget, a Spinner + mSpinner = (Spinner)mActivity.findViewById(com.android.example.spinner.R.id.Spinner01); -<p>In Android, test applications are themselves Android applications, so you -write them in much the same way as the application you are testing. The SDK -tools help you create a main application project and its test project at the same -time. You can run Android tests within Eclipse with ADT or from the command -line. Eclipse with ADT provides an extensive set of tools for creating tests, -running them, and viewing their results. You can also use the <code>adb</code> -tool to run tests, or use a built-in Ant target.</p> + // Set the Spinner to a known position + mActivity.setSpinnerPosition(TEST_STATE_DESTROY_POSITION); -<p>To learn how to set up and run tests in Eclipse, please refer to <a -href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in -Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a -href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other -IDEs</a>.</p> + // Stop the activity - The onDestroy() method should save the state of the Spinner + mActivity.finish(); -<p>If you want a step-by-step introduction to Android testing, try one of the -testing tutorials:</p> + // Re-start the Activity - the onResume() method should restore the state of the Spinner + mActivity = getActivity(); -<ul> - <li>The <a -href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, -Testing</a> tutorial introduces basic testing concepts and procedures in the -context of the Hello, World application.</li> - <li>The <a -href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity -Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. -It guides you through a more complex testing scenario that you develop against a -more realistic application.</li> -</ul> + // Get the Spinner's current position + int currentPosition = mActivity.getSpinnerPosition(); -<h2 id="TestAPI">The Testing API</h2> + // Assert that the current position is the same as the starting position + assertEquals(TEST_STATE_DESTROY_POSITION, currentPosition); +</pre> <p> - For writing tests and test applications in the Java programming language, Android provides a - testing API that is based in part on the JUnit test framework. Adding to that, Android includes - a powerful instrumentation framework that lets your tests access the state and runtime objects - of the application under tests. + The key method used here is + {@link android.test.ActivityInstrumentationTestCase2#getActivity()}, which is a + part of the instrumentation API. The Activity under test is not started until you call this + method. You can set up the test fixture in advance, and then call this method to start the + Activity. </p> -<p>The sections below describe the major components of the testing API available in Android.</p> -<h3 id="Extensions">JUnit test case classes</h3> <p> - Some of the classes in the testing API extend the JUnit {@link junit.framework.TestCase TestCase} but do not use the instrumentation framework. These classes - contain methods for accessing system objects such as the Context of the application under test. With this Context, you can look at its resources, files, databases, - and so forth. The base class is {@link android.test.AndroidTestCase}, but you usually use a subclass associated with a particular component. + Also, instrumentation can load both a test package and the application under test into the + same process. Since the application components and their tests are in the same process, the + tests can invoke methods in the components, and modify and examine fields in the components. +</p> +<h3 id="TestCaseClasses">Test case classes</h3> <p> - The subclasses are: + Android provides several test case classes that extend {@link junit.framework.TestCase} and + {@link junit.framework.Assert} with Android-specific setup, teardown, and helper methods. </p> - <ul> - <li> - {@link android.test.ApplicationTestCase} - A class for testing an entire application. It allows you to inject a mock Context into the application, - set up initial test parameters before the application starts, and examine the application after it finishes but before it is destroyed. - </li> - <li> - {@link android.test.ProviderTestCase2} - A class for isolated testing of a single {@link android.content.ContentProvider}. Since it is restricted to using a - {@link android.test.mock.MockContentResolver} for the provider, and it injects an {@link android.test.IsolatedContext}, your provider testing is isolated - from the rest of the OS. - </li> - <li> - {@link android.test.ServiceTestCase} - a class for isolated testing of a single {@link android.app.Service}. You can inject a mock Context or - mock Application (or both), or let Android provide you a full Context and a {@link android.test.mock.MockApplication}. - </li> - </ul> -<h3 id="Instrumentation">Instrumentation test case classes</h3> +<h4 id="AndroidTestCase">AndroidTestCase</h4> <p> - The API for testing activities extends the JUnit {@link junit.framework.TestCase TestCase} class and also uses the instrumentation framework. With instrumentation, - Android can automate UI testing by sending events to the application under test, precisely control the start of an activity, and monitor the state of the - activity during its life cycle. + A useful general test case class, especially if you are + just starting out with Android testing, is {@link android.test.AndroidTestCase}. It extends + both {@link junit.framework.TestCase} and {@link junit.framework.Assert}. It provides the + JUnit-standard <code>setUp()</code> and <code>tearDown()</code> methods, as well as well as + all of JUnit's Assert methods. In addition, it provides methods for testing permissions, and a + method that guards against memory leaks by clearing out certain class references. </p> +<h4 id="ComponentTestCase">Component-specific test cases</h4> <p> - The base class is {@link android.test.InstrumentationTestCase}. All of its subclasses have the ability to send a keystroke or touch event to the UI of the application - under test. The subclasses can also inject a mock Intent. - The subclasses are: + A key feature of the Android testing framework is its component-specific test case classes. + These address specific component testing needs with methods for fixture setup and + teardown and component lifecycle control. They also provide methods for setting up mock objects. + These classes are described in the component-specific testing topics: </p> - <ul> +<ul> <li> - {@link android.test.ActivityTestCase} - A base class for activity test classes. + <a href="{@docRoot}guide/topics/testing/activity_testing.html">Activity Testing</a> </li> <li> - {@link android.test.SingleLaunchActivityTestCase} - A convenience class for testing a single activity. - It invokes {@link junit.framework.TestCase#setUp() setUp()} and {@link junit.framework.TestCase#tearDown() tearDown()} only - once, instead of once per method call. Use it when all of your test methods run against the same activity. + <a href="{@docRoot}guide/topics/testing/contentprovider_testing.html"> + Content Provider Testing</a> </li> <li> - {@link android.test.SyncBaseInstrumentation} - A class that tests synchronization of a content provider. It uses instrumentation to cancel and disable - existing synchronizations before starting the test synchronization. + <a href="{@docRoot}guide/topics/testing/service_testing.html">Service Testing</a> </li> +</ul> +<p> + Android does not provide a separate test case class for BroadcastReceiver. Instead, test a + BroadcastReceiver by testing the component that sends it Intent objects, to verify that the + BroadcastReceiver responds correctly. +</p> +<h4 id="ApplicationTestCase">ApplicationTestCase</h4> +<p> + You use the {@link android.test.ApplicationTestCase} test case class to test the setup and + teardown of {@link android.app.Application} objects. These objects maintain the global state of + information that applies to all the components in an application package. The test case can + be useful in verifying that the <application> element in the manifest file is correctly + set up. Note, however, that this test case does not allow you to control testing of the + components within your application package. +</p> +<h4 id="InstrumentationTestCase">InstrumentationTestCase</h4> +<p> + If you want to use instrumentation methods in a test case class, you must use + {@link android.test.InstrumentationTestCase} or one of its subclasses. The + {@link android.app.Activity} test cases extend this base class with other functionality that + assists in Activity testing. +</p> + +<h3 id="AssertionClasses">Assertion classes</h3> +<p> + Because Android test case classes extend JUnit, you can use assertion methods to display the + results of tests. An assertion method compares an actual value returned by a test to an + expected value, and throws an AssertionException if the comparison test fails. Using assertions + is more convenient than doing logging, and provides better test performance. +</p> +<p> + Besides the JUnit {@link junit.framework.Assert} class methods, the testing API also provides + the {@link android.test.MoreAsserts} and {@link android.test.ViewAsserts} classes: +</p> +<ul> <li> - {@link android.test.ActivityUnitTestCase} - This class does an isolated test of a single activity. With it, you can inject a mock context or application, or both. - It is intended for doing unit tests of an activity, and is the activity equivalent of the test classes described in <a href="#Extensions">JUnit test case classes</a>. - <p> Unlike the other instrumentation classes, this test class cannot inject a mock Intent.</p> + {@link android.test.MoreAsserts} contains more powerful assertions such as + {@link android.test.MoreAsserts#assertContainsRegex}, which does regular expression + matching. </li> <li> - {@link android.test.ActivityInstrumentationTestCase2} - This class tests a single activity within the normal system environment. - You cannot inject a mock Context, but you can inject mock Intents. Also, you can run a test method on the UI thread (the main thread of the application under test), - which allows you to send key and touch events to the application UI. + {@link android.test.ViewAsserts} contains useful assertions about Views. For example + it contains {@link android.test.ViewAsserts#assertHasScreenCoordinates} that tests if a View + has a particular X and Y position on the visible screen. These asserts simplify testing of + geometry and alignment in the UI. </li> - </ul> -<h3 id="Assert">Assert classes</h3> -<p> - Android also extends the JUnit {@link junit.framework.Assert} class that is the basis of <code>assert()</code> calls in tests. - There are two extensions to this class, {@link android.test.MoreAsserts} and {@link android.test.ViewAsserts}: -</p> -<ul> - <li> - The <code>MoreAsserts</code> class contains more powerful assertions such as {@link android.test.MoreAsserts#assertContainsRegex} that does regular expression matching. - </li> - <li> - The {@link android.test.ViewAsserts} class contains useful assertions about Android Views, such as {@link android.test.ViewAsserts#assertHasScreenCoordinates} that tests if a View has a particular X and Y - position on the visible screen. These asserts simplify testing of geometry and alignment in the UI. - </li> </ul> -<h3 id="MockObjects">Mock object classes</h3> - <p> - Android has convenience classes for creating mock system objects such as applications, contexts, content resolvers, and resources. Android also provides - methods in some test classes for creating mock Intents. Use these mocks to facilitate dependency injection, since they are easier to use than creating their - real counterparts. These convenience classes are found in {@link android.test} and {@link android.test.mock}. They are: - </p> - <ul> - <li> - {@link android.test.IsolatedContext} - Mocks a Context so that the application using it runs in isolation. - At the same time, it has enough stub code to satisfy OS code that tries to communicate with contexts. This class is useful in unit testing. - </li> - <li> - {@link android.test.RenamingDelegatingContext} - Delegates most context functions to an existing, normal context while changing the default file and database - names in the context. Use this to test file and database operations with a normal system context, using test names. - </li> - <li> - {@link android.test.mock.MockApplication}, {@link android.test.mock.MockContentResolver}, {@link android.test.mock.MockContext}, - {@link android.test.mock.MockDialogInterface}, {@link android.test.mock.MockPackageManager}, - {@link android.test.mock.MockResources} - Classes that create mock Android system objects for use in testing. They expose only those methods that are - useful in managing the object. The default implementations of these methods simply throw an Exception. You are expected to extend the classes and - override any methods that are called by the application under test. - </li> - </ul> -<h3 id="InstrumentationTestRunner">Instrumentation Test Runner</h3> +<h3 id="MockObjectClasses">Mock object classes</h3> <p> - Android provides a custom class for running tests with instrumentation called called - {@link android.test.InstrumentationTestRunner}. This class - controls of the application under test, runs the test application and the main application in the same process, and routes - test output to the appropriate place. Using instrumentation is key to the ability of <code>InstrumentationTestRunner</code> to control the entire test - environment at runtime. Notice that you use this test runner even if your test class does not itself use instrumentation. + To facilitate dependency injection in testing, Android provides classes that create mock system + objects such as {@link android.content.Context} objects, + {@link android.content.ContentProvider} objects, {@link android.content.ContentResolver} + objects, and {@link android.app.Service} objects. Some test cases also provide mock + {@link android.content.Intent} objects. You use these mocks both to isolate tests + from the rest of the system and to facilitate dependency injection for testing. These classes + are found in the Java packages {@link android.test} and {@link android.test.mock}. </p> <p> - When you run a test application, you first run a system utility called Activity Manager. Activity Manager uses the instrumentation framework to start and control the test runner, which in turn uses instrumentation to shut down any running instances - of the main application, starts the test application, and then starts the main application in the same process. This allows various aspects of the test application to work directly with the main application. + Mock objects isolate tests from a running system by stubbing out or overriding + normal operations. For example, a {@link android.test.mock.MockContentResolver} + replaces the normal resolver framework with its own local framework, which is isolated + from the rest of the system. MockContentResolver also also stubs out the + {@link android.content.ContentResolver#notifyChange(Uri, ContentObserver, boolean)} method + so that observer objects outside the test environment are not accidentally triggered. </p> <p> - If you are developing in Eclipse, the ADT plugin assists you in the setup of <code>InstrumentationTestRunner</code> or other test runners. - The plugin UI prompts you to specify the test runner class to use, as well as the package name of the application under test. - The plugin then adds an <code><instrumentation></code> element with appropriate attributes to the manifest file of the test application. - Eclipse with ADT automatically starts a test application under the control of Activity Manager using instrumentation, - and redirects the test output to the Eclipse window's JUnit view. + Mock object classes also facilitate dependency injection by providing a subclass of the + normal object that is non-functional except for overrides you define. For example, the + {@link android.test.mock.MockResources} object provides a subclass of + {@link android.content.res.Resources} in which all the methods throw Exceptions when called. + To use it, you override only those methods that must provide information. </p> <p> - If you prefer working from the command line, you can use Ant and the <code>android</code> - tool to help you set up your test projects. To run tests with instrumentation, you can access the - Activity Manager through the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug - Bridge</a> (<code>adb</code>) tool and the output is directed to <code>STDOUT</code>. + These are the mock object classes available in Android: </p> -<h2 id="TestEnviroment">Working in the Test Environment</h2> +<h4 id="SimpleMocks">Simple mock object classes</h4> <p> - The tests for an Android application are contained in a test application, which itself is an Android application. A test application resides in a separate Android project that has the - same files and directories as a regular Android application. The test project is linked to the project of the application it tests - (known as the application under test) by its manifest file. + {@link android.test.mock.MockApplication}, {@link android.test.mock.MockContext}, + {@link android.test.mock.MockContentProvider}, {@link android.test.mock.MockCursor}, + {@link android.test.mock.MockDialogInterface}, {@link android.test.mock.MockPackageManager}, and + {@link android.test.mock.MockResources} provide a simple and useful mock strategy. They are + stubbed-out versions of the corresponding system object class, and all of their methods throw an + {@link java.lang.UnsupportedOperationException} exception if called. To use them, you override + the methods you need in order to provide mock dependencies. </p> +<p class="Note"><strong>Note:</strong> + {@link android.test.mock.MockContentProvider} + and {@link android.test.mock.MockCursor} are new as of API level 8. +</p> +<h4 id="ResolverMocks">Resolver mock objects</h4> <p> - Each test application contains one or more test case classes based on an Android class for a - particular type of component. The test case class contains methods that define tests on some part of the application under test. When you run the test application, Android - starts it, loads the application under test into the same process, and then invokes each method in the test case class. + {@link android.test.mock.MockContentResolver} provides isolated testing of content providers by + masking out the normal system resolver framework. Instead of looking in the system to find a + content provider given an authority string, MockContentResolver uses its own internal table. You + must explicitly add providers to this table using + {@link android.test.mock.MockContentResolver#addProvider(String,ContentProvider)}. </p> <p> - The tools and procedures you use with testing depend on the development environment you are using. If you use Eclipse, then the ADT plug in for Eclipse provides tools that - allow you to develop and run tests entirely within Eclipse. This is documented in the topic <a href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in Eclipse, with ADT</a>. - If you use another development environment, then you use Android's command-line tools, as documented in the topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a>. + With this feature, you can associate a mock content provider with an authority. You can create + an instance of a real provider but use test data in it. You can even set the provider for an + authority to <code>null</code>. In effect, a MockContentResolver object isolates your test + from providers that contain real data. You can control the + function of the provider, and you can prevent your test from affecting real data. </p> -<h3 id="TestProjects">Working with test projects</h3> +<h3 id="ContextMocks">Contexts for testing</h3> <p> - To start testing an Android application, you create a test project for it using Android tools. The tools create the project directory and the files and subdirectories needed. - The tools also create a manifest file that links the application in the test project to the application under test. The procedure for creating a test project in Eclipse with - ADT is documented in <a href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in Eclipse, with ADT</a>. The procedure for creating a test project for use with development - tools other than Eclipse is documented in <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a>. + Android provides two Context classes that are useful for testing: </p> -<h3 id="TestClasses">Working with test case classes</h3> +<ul> + <li> + {@link android.test.IsolatedContext} provides an isolated {@link android.content.Context}, + File, directory, and database operations that use this Context take place in a test area. + Though its functionality is limited, this Context has enough stub code to respond to + system calls. + <p> + This class allows you to test an application's data operations without affecting real + data that may be present on the device. + </p> + </li> + <li> + {@link android.test.RenamingDelegatingContext} provides a Context in which + most functions are handled by an existing {@link android.content.Context}, but + file and database operations are handled by a {@link android.test.IsolatedContext}. + The isolated part uses a test directory and creates special file and directory names. + You can control the naming yourself, or let the constructor determine it automatically. + <p> + This object provides a quick way to set up an isolated area for data operations, + while keeping normal functionality for all other Context operations. + </p> + </li> +</ul> +<h2 id="InstrumentationTestRunner">Running Tests</h2> <p> - A test application contains one or more test case classes that extend an Android test case class. You choose a test case class based on the type of Android component you are testing and the - tests you are doing. A test application can test different components, but each test case class is designed to test a single type of component. - The Android test case classes are described in the section <a href="#TestAPI">The Testing API</a>. + Test cases are run by a test runner class that loads the test case class, set ups, + runs, and tears down each test. An Android test runner must also be instrumented, so that + the system utility for starting applications can control how the test package + loads test cases and the application under test. You tell the Android platform + which instrumented test runner to use by setting a value in the test package's manifest file. </p> <p> - Some Android components have more than one associated test case class. In this case, you choose among the available classes based on the type of tests you want to do. For activities, - for example, you have the choice of either {@link android.test.ActivityInstrumentationTestCase2} or {@link android.test.ActivityUnitTestCase}. + {@link android.test.InstrumentationTestRunner} is the primary Android test runner class. It + extends the JUnit test runner framework and is also instrumented. It can run any of the test + case classes provided by Android and supports all possible types of testing. +</p> <p> - <code>ActivityInstrumentationTestCase2</code> is designed to do functional testing, so it tests activities in a normal system infrastructure. You can inject mocked Intents, but not - mocked Contexts. In general, you can't mock dependencies for the activity under test. + You specify <code>InstrumentationTestRunner</code> or a subclass in your test package's + manifest file, in the <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"> + instrumentation</a> element. Also, <code>InstrumentationTestRunner</code> code resides + in the shared library <code>android.test.runner</code>, which is not normally linked to + Android code. To include it, you must specify it in a + <a href="{@docRoot}guide/topics/manifest/uses-library-element.html">uses-library</a> element. + You do not have to set up these elements yourself. Both Eclipse with ADT and the + <code>android</code> command-line tool construct them automatically and add them to your + test package's manifest file. +</p> +<p class="Note"> + <strong>Note:</strong> If you use a test runner other than + <code>InstrumentationTestRunner</code>, you must change the <instrumentation> + element to point to the class you want to use. </p> <p> - In comparison, <code>ActivityUnitTestCase</code> is designed for unit testing, so it tests activities in an isolated system infrastructure. You can inject mocked or wrappered dependencies for - the activity under test, particularly mocked Contexts. On the other hand, when you use this test case class the activity under test runs in isolation and can't interact with other activities. + To run {@link android.test.InstrumentationTestRunner}, you use internal system classes called by + Android tools. When you run a test in Eclipse with ADT, the classes are called automatically. + When you run a test from the command line, you run these classes with + <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge (adb)</a>. </p> <p> - As a rule of thumb, if you wanted to test an activity's interaction with the rest of Android, you would use <code>ActivityInstrumentationTestCase2</code>. If you wanted to do regression testing - on an activity, you would use <code>ActivityUnitTestCase</code>. + The system classes load and start the test package, kill any processes that + are running an instance of the application under test, and then load a new instance of the + application under test. They then pass control to + {@link android.test.InstrumentationTestRunner}, which runs + each test case class in the test package. You can also control which test cases and + methods are run using settings in Eclipse with ADT, or using flags with the command-line tools. </p> -<h3 id="Tests">Working with test methods</h3> <p> - Each test case class provides methods that you use to set up the test environment and control the application under test. For example, all test case classes provide the JUnit {@link junit.framework.TestCase#setUp() setUp()} - method that you can override to set up fixtures. In addition, you add methods to the class to define individual tests. Each method you add is run once each time you run the test application. If you override the <code>setUp()</code> - method, it runs before each of your methods. Similarly, the JUnit {@link junit.framework.TestCase#tearDown() tearDown()} method is run once after each of your methods. + Neither the system classes nor {@link android.test.InstrumentationTestRunner} run + the application under test. Instead, the test case does this directly. It either calls methods + in the application under test, or it calls its own methods that trigger lifecycle events in + the application under test. The application is under the complete control of the test case, + which allows it to set up the test environment (the test fixture) before running a test. This + is demonstrated in the previous <a href="#ActivitySnippet">code snippet</a> that tests an + Activity that displays a Spinner widget. </p> <p> - The test case classes give you substantial control over starting and stopping components. For this reason, you have to specifically tell Android to start a component before you run tests against it. For example, you use the - {@link android.test.ActivityInstrumentationTestCase2#getActivity()} method to start the activity under test. You can call this method once during the entire test case, or once for each test method. You can even destroy the - activity under test by calling its {@link android.app.Activity#finish()} method and then restart it with <code>getActivity()</code> within a single test method. + To learn more about running tests, please read the topics + <a href="{@docRoot}guide/developing/testing/testing_eclipse.html""> + Testing in Eclipse, with ADT</a> or + <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> + Testing in Other IDes</a>. </p> -<h3 id="RunTests">Running tests and seeing the results</h3> +<h2 id="TestResults">Seeing Test Results</h2> <p> - To run your tests, you build your test project and then run the test application using the system utility Activity Manager with instrumentation. You provide to Activity Manager the name of the test runner (usually - {@link android.test.InstrumentationTestRunner}) you specified for your application; the name includes both your test application's package name and the test runner class name. Activity Manager loads and starts your - test application, kills any instances of the application under test, loads an instance of the application under test into the same process as the test application, and then passes control to the first test case - class in your test application. The test runner then takes control of the tests, running each of your test methods against the application under test until all the methods in all the classes have been run. + The Android testing framework returns test results back to the tool that started the test. + If you run a test in Eclipse with ADT, the results are displayed in a new JUnit view pane. If + you run a test from the command line, the results are displayed in <code>STDOUT</code>. In + both cases, you see a test summary that displays the name of each test case and method that + was run. You also see all the assertion failures that occurred. These include pointers to the + line in the test code where the failure occurred. Assertion failures also list the expected + value and actual value. </p> <p> - If you run a test within Eclipse with ADT, the output appears in a new JUnit view pane. If you run a test from the command line, the output goes to STDOUT. + The test results have a format that is specific to the IDE that you are using. The test + results format for Eclipse with ADT is described in + <a href="{@docRoot}guide/developing/testing/testing_eclipse.html#RunTestEclipse"> + Testing in Eclipse, with ADT</a>. The test results format for tests run from the + command line is described in + <a href="{@docRoot}guide/developing/testing/testing_otheride.html#RunTestsCommand"> + Testing in Other IDEs</a>. </p> -<h2 id="TestAreas">What to Test</h2> +<h2 id="Monkeys">monkey and monkeyrunner</h2> <p> - In addition to the functional areas you would normally test, here are some areas - of Android application testing that you should consider: + The SDK provides two tools for functional-level application testing: </p> - <ul> - <li> - Activity lifecycle events: You should test that your activities handle lifecycle events correctly. For example - an activity should respond to pause or destroy events by saving its state. Remember that even a change in screen orientation - causes the current activity to be destroyed, so you should test that accidental device movements don't accidentally lose the - application state. - </li> - <li> - Database operations: You should ensure that database operations correctly handle changes to the application's state. - To do this, use mock objects from the package {@link android.test.mock android.test.mock}. - </li> - <li> - Screen sizes and resolutions: Before you publish your application, make sure to test it on all of the - screen sizes and densities on which you want it to run. You can test the application on multiple sizes and densities using - AVDs, or you can test your application directly on the devices that you are targeting. For more information, see - the topic <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>. - </li> - </ul> + <ul> + <li> +The <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, + usually called "monkey", is a command-line tool that sends pseudo-random streams of + keystrokes, touches, and gestures to a device. You run it with the + <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb) tool. + You use it to stress-test your application and report back errors that are encountered. + You can repeat a stream of events by running the tool each time with the same random + number seed. + </li> + <li> + The <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a> tool + is an API and execution environment for test programs written in Python. The API + includes functions for connecting to a device, installing and uninstalling packages, + taking screenshots, comparing two images, and running a test package against an + application. Using the API, you can write a wide range of large, powerful, and complex + tests. You run programs that use the API with the <code>monkeyrunner</code> command-line + tool. + </li> + </ul> +<h2 id="PackageNames">Working With Package names</h2> <p> - When possible, you should run these tests on an actual device. If this is not possible, you can - use the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> with - <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> configured for - the hardware, screens, and versions you want to test. + In the test environment, you work with both Android application package names and + Java package identifiers. Both use the same naming format, but they represent substantially + different entities. You need to know the difference to set up your tests correctly. </p> -<h2 id="UITesting">Appendix: UI Testing Notes</h2> <p> - The following sections have tips for testing the UI of your Android application, specifically - to help you handle actions that run in the UI thread, touch screen and keyboard events, and home - screen unlock during testing. + An Android package name is a unique system name for a <code>.apk</code> file, set by the + "android:package" attribute of the <manifest> element in the package's + manifest. The Android package name of your test package must be different from the + Android package name of the application under test. By default, Android tools create the + test package name by appending ".test" to the package name of the application under test. </p> -<h3 id="RunOnUIThread">Testing on the UI thread</h3> <p> - An application's activities run on the application's <strong>UI thread</strong>. Once the - UI is instantiated, for example in the activity's <code>onCreate()</code> method, then all - interactions with the UI must run in the UI thread. When you run the application normally, it - has access to the thread and does not have to do anything special. + The test package also uses an Android package name to target the application package it + tests. This is set in the "android:targetPackage" attribute of the + <instrumentation> element in the test package's manifest. </p> <p> - This changes when you run tests against the application. With instrumentation-based classes, - you can invoke methods against the UI of the application under test. The other test classes don't allow this. - To run an entire test method on the UI thread, you can annotate the thread with <code>@UIThreadTest</code>. - Notice that this will run <em>all</em> of the method statements on the UI thread. Methods that do not interact with the UI - are not allowed; for example, you can't invoke <code>Instrumentation.waitForIdleSync()</code>. + A Java package identifier applies to a source file. This package name reflects the directory + path of the source file. It also affects the visibility of classes and members to each other. </p> <p> - To run a subset of a test method on the UI thread, create an anonymous class of type - <code>Runnable</code>, put the statements you want in the <code>run()</code> method, and instantiate a new - instance of the class as a parameter to the method <code><em>appActivity</em>.runOnUiThread()</code>, where - <code><em>appActivity</em></code> is the instance of the app you are testing. + Android tools that create test projects set up an Android test package name for you. + From your input, the tools set up the test package name and the target package name for the + application under test. For these tools to work, the application project must already exist. </p> <p> - For example, this code instantiates an activity to test, requests focus (a UI action) for the Spinner displayed - by the activity, and then sends a key to it. Notice that the calls to <code>waitForIdleSync</code> and <code>sendKeys</code> - aren't allowed to run on the UI thread:</p> -<pre> - private MyActivity mActivity; // MyActivity is the class name of the app under test - private Spinner mSpinner; - - ... - - protected void setUp() throws Exception { - super.setUp(); - mInstrumentation = getInstrumentation(); - - mActivity = getActivity(); // get a references to the app under test - - /* - * Get a reference to the main widget of the app under test, a Spinner - */ - mSpinner = (Spinner) mActivity.findViewById(com.android.demo.myactivity.R.id.Spinner01); - - ... - - public void aTest() { - /* - * request focus for the Spinner, so that the test can send key events to it - * This request must be run on the UI thread. To do this, use the runOnUiThread method - * and pass it a Runnable that contains a call to requestFocus on the Spinner. - */ - mActivity.runOnUiThread(new Runnable() { - public void run() { - mSpinner.requestFocus(); - } - }); - - mInstrumentation.waitForIdleSync(); - - this.sendKeys(KeyEvent.KEYCODE_DPAD_CENTER); -</pre> - -<h3 id="NotouchMode">Turning off touch mode</h3> + By default, these tools set the Java package identifier for the test class to be the same + as the Android package identifier. You may want to change this if you want to expose + members in the application under test by giving them package visibility. If you do this, + change only the Java package identifier, not the Android package names, and change only the + test case source files. Do not change the Java package name of the generated + <code>R.java</code> class in your test package, because it will then conflict with the + <code>R.java</code> class in the application under test. Do not change the Android package name + of your test package to be the same as the application it tests, because then their names + will no longer be unique in the system. +</p> +<h2 id="WhatToTest">What to Test</h2> <p> - To control the emulator or a device with key events you send from your tests, you must turn off - touch mode. If you do not do this, the key events are ignored. + The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> + describes the key functionality you should test in an Android application, and the key + situations that might affect that functionality. </p> <p> - To turn off touch mode, you invoke <code>ActivityInstrumentationTestCase2.setActivityTouchMode(false)</code> - <em>before</em> you call <code>getActivity()</code> to start the activity. You must invoke the method in a test method - that is <em>not</em> running on the UI thread. For this reason, you can't invoke the touch mode method - from a test method that is annotated with <code>@UIThread</code>. Instead, invoke the touch mode method from <code>setUp()</code>. + Most unit testing is specific to the Android component you are testing. + The topics <a href="{@docRoot}guide/topics/testing/activity_testing.html">Activity Testing</a>, + <a href="{@docRoot}guide/topics/testing/contentprovider_testing.html"> + Content Provider Testing</a>, and <a href="{@docRoot}guide/topics/testing/service_testing.html"> + Service Testing</a> each have a section entitled "What To Test" that lists possible testing + areas. </p> -<h3 id="UnlockDevice">Unlocking the emulator or device</h3> <p> - You may find that UI tests don't work if the emulator's or device's home screen is disabled with the keyguard pattern. - This is because the application under test can't receive key events sent by <code>sendKeys()</code>. The best - way to avoid this is to start your emulator or device first and then disable the keyguard for the home screen. + When possible, you should run these tests on an actual device. If this is not possible, you can + use the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> with + <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> configured for + the hardware, screens, and versions you want to test. </p> +<h2 id="NextSteps">Next Steps</h2> <p> - You can also explicitly disable the keyguard. To do this, - you need to add a permission in the manifest file (<code>AndroidManifest.xml</code>) and - then disable the keyguard in your application under test. Note, though, that you either have to remove this before - you publish your application, or you have to disable it programmatically in the published app. + To learn how to set up and run tests in Eclipse, please refer to <a + href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in + Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a + href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other + IDEs</a>. </p> <p> - To add the the permission, add the element <code><uses-permission android:name="android.permission.DISABLE_KEYGUARD"/></code> - as a child of the <code><manifest></code> element. To disable the KeyGuard, add the following code - to the <code>onCreate()</code> method of activities you intend to test: + If you want a step-by-step introduction to Android testing, try one of the + testing tutorials or sample test packages: </p> -<pre> - mKeyGuardManager = (KeyguardManager) getSystemService(KEYGUARD_SERVICE); - mLock = mKeyGuardManager.newKeyguardLock("<em>activity_classname</em>"); - mLock.disableKeyguard(); -</pre> -<p>where <code><em>activity_classname</em></code> is the class name of the activity.</p> -<h3 id="UITestTroubleshooting">Troubleshooting UI tests</h3> -<p> - This section lists some of the common test failures you may encounter in UI testing, and their causes: -</p> -<dl> - <dt><code>WrongThreadException</code></dt> - <dd> - <p><strong>Problem:</strong></p> - For a failed test, the Failure Trace contains the following error message: - <code> - android.view.ViewRoot$CalledFromWrongThreadException: Only the original thread that created a view hierarchy can touch its views. - </code> - <p><strong>Probable Cause:</strong></p> - This error is common if you tried to send UI events to the UI thread from outside the UI thread. This commonly happens if you send UI events - from the test application, but you don't use the <code>@UIThread</code> annotation or the <code>runOnUiThread()</code> method. The test method tried to interact with the UI outside the UI thread. - <p><strong>Suggested Resolution:</strong></p> - Run the interaction on the UI thread. Use a test class that provides instrumentation. See the previous section <a href="#RunOnUIThread">Testing on the UI Thread</a> - for more details. - </dd> - <dt><code>java.lang.RuntimeException</code></dt> - <dd> - <p><strong>Problem:</strong></p> - For a failed test, the Failure Trace contains the following error message: - <code> - java.lang.RuntimeException: This method can not be called from the main application thread - </code> - <p><strong>Probable Cause:</strong></p> - This error is common if your test method is annotated with <code>@UiThreadTest</code> but then tries to - do something outside the UI thread or tries to invoke <code>runOnUiThread()</code>. - <p><strong>Suggested Resolution:</strong></p> - Remove the <code>@UiThreadTest</code> annotation, remove the <code>runOnUiThread()</code> call, or re-factor your tests. - </dd> -</dl> +<ul> + <li> + The <a + href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, + Testing</a> tutorial introduces basic testing concepts and procedures in the + context of the Hello, World application. + </li> + <li> + The <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity + Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. + It guides you through a more complex testing scenario that you develop against a + more realistic application. + </li> + <li> + The sample test package <a href="{@docRoot}resources/samples/AlarmServiceTest"}> + Alarm Service Test</a> is an example of testing a {@link android.app.Service}. It contains + a set of unit tests for the Alarm Service sample application's {@link android.app.Service}. + </li> +</ul> diff --git a/docs/html/guide/topics/testing/what_to_test.jd b/docs/html/guide/topics/testing/what_to_test.jd new file mode 100644 index 0000000..e13538a --- /dev/null +++ b/docs/html/guide/topics/testing/what_to_test.jd @@ -0,0 +1,84 @@ +page.title=What To Test +@jd:body +<p> + As you develop Android applications, knowing what to test is as important as knowing how to + test. This document lists some most common Android-related situations that you should consider + when you test, even at the unit test level. This is not an exhaustive list, and you consult the + documentation for the features that you use for more ideas. The + <a href="http://groups.google.com/group/android-developers">android-developers</a> Google Groups + site is another resource for information about testing. +</p> +<h2 id="Tests">Ideas for Testing</h2> +<p> + The following sections are organized by behaviors or situations that you should test. Each + section contains a scenario that further illustrates the situation and the test or tests you + should do. +</p> +<h4>Change in orientation</h4> +<p> + For devices that support multiple orientations, Android detects a change in orientation when + the user turns the device so that the display is "landscape" (long edge is horizontal) instead + of "portrait" (long edge is vertical). +</p> +<p> + When Android detects a change in orientation, its default behavior is to destroy and then + re-start the foreground Activity. You should consider testing the following: +</p> +<ul> + <li> + Is the screen re-drawn correctly? Any custom UI code you have should handle changes in the + orientation. + </li> + <li> + Does the application maintain its state? The Activity should not lose anything that the + user has already entered into the UI. The application should not "forget" its place in the + current transaction. + </li> +</ul> +<h4>Change in configuration</h4> +<p> + A situation that is more general than a change in orientation is a change in the device's + configuration, such as a change in the availability of a keyboard or a change in system + language. +</p> +<p> + A change in configuration also triggers the default behavior of destroying and then restarting + the foreground Activity. Besides testing that the application maintains the UI and its + transaction state, you should also test that the application updates itself to respond + correctly to the new configuration. +</p> +<h4>Battery life</h4> +<p> + Mobile devices primarily run on battery power. A device has finite "battery budget", and when it + is gone, the device is useless until it is recharged. You need to write your application to + minimize battery usage, you need to test its battery performance, and you need to test the + methods that manage battery usage. +</p> +<p> + Techniques for minimizing battery usage were presented at the 2010 Google I/O conference in the + presentation + <a href="http://code.google.com/events/io/2009/sessions/CodingLifeBatteryLife.html"> + Coding for Life -- Battery Life, That Is</a>. This presentation describes the impact on battery + life of various operations, and the ways you can design your application to minimize these + impacts. When you code your application to reduce battery usage, you also write the + appropriate unit tests. +</p> +<h4>Dependence on external resources</h4> +<p> + If your application depends on network access, SMS, Bluetooth, or GPS, then you should + test what happens when the resource or resources are not available. +</p> +<p> + For example, if your application uses the network,it can notify the user if access is + unavailable, or disable network-related features, or do both. For GPS, it can switch to + IP-based location awareness. It can also wait for WiFi access before doing large data transfers, + since WiFi transfers maximize battery usage compared to transfers over 3G or EDGE. +</p> +<p> + You can use the emulator to test network access and bandwidth. To learn more, please see + <a href="{@docRoot}guide/developing/tools/emulator.html#netspeed">Network Speed Emulation</a>. + To test GPS, you can use the emulator console and {@link android.location.LocationManager}. To + learn more about the emulator console, please see + <a href="{@docRoot}/guide/developing/tools/emulator.html#console"> + Using the Emulator Console</a>. +</p> diff --git a/docs/html/guide/webapps/best-practices.jd b/docs/html/guide/webapps/best-practices.jd new file mode 100644 index 0000000..1bde5bf --- /dev/null +++ b/docs/html/guide/webapps/best-practices.jd @@ -0,0 +1,90 @@ +page.title=Best Practices for Web Apps +@jd:body + +<style> +.bold li { + font-weight:bold; +} +.bold li * { + font-weight:normal; +} +</style> + +<p>Developing web pages and web applications for mobile devices presents a different set of +challenges compared to developing a web page for the typical +desktop web browser. To help you get started, the following is a list of practices you should +follow in order to provide the most effective web application for Android and other mobile +devices.</p> + +<ol class="bold"> + +<li>Redirect mobile devices to a dedicated mobile version of your web site + <p>There are several ways you can redirect requests to the mobile version of your web site, using +server-side redirects. Most often, this is done by "sniffing" the User Agent +string provided by the web browser. To determine whether to serve a mobile version of your site, you +should simply look for the "mobile" string in the User Agent, which matches a wide variety of mobile +devices. If necessary, you can also identify the specific operating system in the User Agent string +(such as "Android 2.1").</p> +</li> + + +<li>Use a valid markup DOCTYPE that's appropriate for mobile devices + <p>The most common markup language used for mobile web sites is <a +href="http://www.w3.org/TR/2008/REC-xhtml-basic-20080729/">XHTML Basic</a>. This standard +ensures specific markup for your web site that works best on mobile devices. For instance, it does +not allow HTML frames or nested tables, which perform poorly on mobile devices. Along with the +DOCTYPE, be sure to declare the appropriate character encoding for the document (such as +UTF-8).</p> + <p>For example:</p> +<pre> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" + "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> +</pre> + + <p>Also be sure that your web page markup is valid against the declared DOCTYPE. Use a +validator, such as the one available at +<a href="http://validator.w3.org/">http://validator.w3.org</a>.</p> +</li> + + +<li>Use viewport meta data to properly resize your web page + <p>In your document {@code <head>}, you should provide meta data that specifies how you +want the browser's viewport to render your web page. For example, your viewport meta data can +specify the height and width for the browser's viewport, the initial web page scale and even the +target screen density.</p> + <p>For example:</p> +<pre> +<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no"> +</pre> + <p>For more information about how to use viewport meta data for Android-powered devices, read <a +href="{@docRoot}guide/webapps/targetting.html">Targetting Android Devices</a>.</p> +</li> + + +<li>Avoid multiple file requests + <p>Because mobile devices typically have a connection speed far slower than a desktop +computer, you should make your web pages load as fast as possible. One way to speed it up is to +avoid loading extra files such as stylesheets and script files in the {@code +<head>}. Instead, provide your CSS and JavaScript directly in the <head> (or +at the end of the <body>, for scripts that you don't need until the page is loaded). +Alternatively, you should optimize the size and speed of your files by compressing them with tools +like <a href="http://code.google.com/p/minify/">Minify</a>.</p> +</li> + + +<li>Use a vertical linear layout + <p>Avoid the need for the user to scroll left and right while navigating your web +page. Scrolling up and down is easier for the user and makes your web page simpler.</p> +</li> + +</ol> + +<p>For a more thorough guide to creating great mobile web applications, see the W3C's <a +href="http://www.w3.org/TR/mobile-bp/">Mobile Web Best Practices</a>. For other guidance on +improving the speed of your web site (for mobile and desktop), see Yahoo!'s guide to <a +href="http://developer.yahoo.com/performance/index.html#rules">Exceptional Performance</a> and +Google's speed tutorials in <a href="http://code.google.com/speed/articles/">Let's make the web +faster</a>.</p> + + diff --git a/docs/html/guide/webapps/debugging.jd b/docs/html/guide/webapps/debugging.jd new file mode 100644 index 0000000..098e17c --- /dev/null +++ b/docs/html/guide/webapps/debugging.jd @@ -0,0 +1,158 @@ +page.title=Debugging Web Apps +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>You can debug your web app using console methods in JavaScript</li> + <li>If debugging in a custom WebView, you need to implement a callback method to handle debug +messages</li> +</ul> + +<h2>In this document</h2> +<ol> + <li><a href="#Browser">Using Console APIs in the Android Browser</a></li> + <li><a href="#WebView">Using Console APIs in WebView</a></li> +</ol> + +<h2>See also</h2> +<ol> + <li><a href="{@docRoot}guide/developing/debug-tasks.html">Debugging Tasks</a></li> +</ol> + +</div> +</div> + +<p>If you're developing a web application for Android, you can debug your JavaScript +using the {@code console} JavaScript APIs, which output messages to logcat. If you're familiar with +debugging web pages with Firebug or Web Inspector, then you're probably familiar +with using {@code console} (such as {@code console.log()}). Android's WebKit framework supports most +of the same APIs, so you can receive logs from your web page when debugging in Android's Browser +or in your own {@link android.webkit.WebView}.</p> + + + +<h2 id="Browser">Using Console APIs in the Android Browser</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h2>Logcat</h2> + <p>Logcat is a tool that dumps a log of system messages. The messages include a stack trace when +the device throws an error, as well as log messages written from your application and +those written using JavaScript {@code console} APIs.</p> + <p>To run logcat and view messages, execute +{@code adb logcat} from your Android SDK {@code tools/} directory, or, from DDMS, select +<strong>Device > Run logcat</strong>. When using the <a href="{@docRoot}sdk/eclipse-adt.html">ADT +plugin for Eclipse</a>, you can also view logcat messages by opening the Logcat view, available from +<strong>Window > Show View > Other > Android > Logcat</strong>.</p> + <p>See <a href="{@docRoot}guide/developing/debug-tasks.html">Debugging +Tasks</a> for more information about logcat.</p> +</div> +</div> + +<p>When you call a {@code console} function (in the DOM's {@code window.console} object), +the output appears in logcat. For example, if your web page executes the following +JavaScript:</p> +<pre> +console.log("Hello World"); +</pre> +<p>Then the logcat message looks something like this:</p> +<pre class="no-pretty-print"> +Console: Hello World http://www.example.com/hello.html :82 +</pre> + +<p>The format of the message might appear different depending on which version of Android you're +using. On Android 2.1 and higher, console messages from the Android Browser +are tagged with the name "browser". On Android 1.6 and lower, Android Browser +messages are tagged with the name "WebCore".</p> + +<p>Android's WebKit does not implement all of the console APIs available in other desktop browsers. +You can, however, use the basic text logging functions:</p> +<ul> + <li>{@code console.log(String)}</li> + <li>{@code console.info(String)}</li> + <li>{@code console.warn(String)}</li> + <li>{@code console.error(String)}</li> +</ul> + +<p>Other console functions don't raise errors, but might not behave the same as what you +expect from other web browsers.</p> + + + +<h2 id="WebView">Using Console APIs in WebView</h2> + +<p>If you've implemented a custom {@link android.webkit.WebView} in your application, all the +same console APIs are supported when debugging your web page in WebView. On Android +1.6 and lower, console messages are automatically sent to logcat with the +"WebCore" logging tag. If you're targetting Android 2.1 (API Level 7) or higher, then you must +provide a {@link android.webkit.WebChromeClient} +that implements the {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String) +onConsoleMessage()} callback method, in order for console messages to appear in logcat.</p> + +<p>Additionally, the {@link +android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} method introduced in API +Level 7 has been deprecated in favor of {@link +android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} in API Level 8.</p> + +<p>Whether you're developing for Android 2.1 (API Level 7) or Android 2.2 (API Level 8 or +greater), you must implement {@link android.webkit.WebChromeClient} and override the appropriate +{@link +android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback +method. Then, apply the {@link android.webkit.WebChromeClient} to your {@link +android.webkit.WebView} with {@link android.webkit.WebView#setWebChromeClient(WebChromeClient) +setWebChromeClient()}. + +<p>Using API Level 7, this is how your code for {@link +android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} might look:</p> + +<pre> +WebView myWebView = (WebView) findViewById(R.id.webview); +myWebView.setWebChromeClient(new WebChromeClient() { + public void onConsoleMessage(String message, int lineNumber, String sourceID) { + Log.d("MyApplication", message + " -- From line " + + lineNumber + " of " + + sourceID); + } +}); +</pre> + +<p>With API Level 8 or greater, your code for {@link +android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} might look like this:</p> + +<pre> +WebView myWebView = (WebView) findViewById(R.id.webview); +myWebView.setWebChromeClient(new WebChromeClient() { + public boolean onConsoleMessage(ConsoleMessage cm) { + Log.d("MyApplication", cm.{@link android.webkit.ConsoleMessage#message()} + " -- From line " + + cm.{@link android.webkit.ConsoleMessage#lineNumber()} + " of " + + cm.{@link android.webkit.ConsoleMessage#sourceId()} ); + return true; + } +}); +</pre> + +<p>The {@link android.webkit.ConsoleMessage} also includes a {@link +android.webkit.ConsoleMessage.MessageLevel MessageLevel} to indicate the type of console message +being delivered. You can query the message level with {@link +android.webkit.ConsoleMessage#messageLevel()} to determine the severity of the message, then +use the appropriate {@link android.util.Log} method or take other appropriate actions.</p> + +<p>Whether you're using {@link +android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} or {@link +android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)}, when you execute a console method +in your web page, Android calls the appropriate {@link +android.webkit.WebChromeClient#onConsoleMessage(String,int,String) +onConsoleMessage()} method so you can report the error. For example, with the example code above, +a logcat message is printed that looks like this:</p> + +<pre class="no-pretty-print"> +Hello World -- From line 82 of http://www.example.com/hello.html +</pre> + + + + + + diff --git a/docs/html/guide/webapps/targetting.jd b/docs/html/guide/webapps/targetting.jd new file mode 100644 index 0000000..844b9ca --- /dev/null +++ b/docs/html/guide/webapps/targetting.jd @@ -0,0 +1,419 @@ +page.title=Targetting Android Devices +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>You can target your web page for different screens using viewport metadata, CSS, and +JavaScript</li> + <li>Techniques in this document work for Android 2.0 and greater</li> +</ul> + +<h2>In this document</h2> +<ol> +<li><a href="#Metadata">Using Viewport Metadata</a> + <ol> + <li><a href="#ViewportSize">Defining the viewport size</a></li> + <li><a href="#ViewportScale">Defining the viewport scale</a></li> + <li><a href="#ViewportDensity">Defining the viewport target density</a></li> + </ol> +</li> +<li><a href="#DensityCSS">Targetting Device Density with CSS</a></li> +<li><a href="#DensityJS">Targetting Device Density with JavaScript</a></li> +</ol> + +</div> +</div> + + +<p>If you're developing a web application for Android or redesigning one for mobile devices, you +should account for some factors that affect the way the Android Browser renders your web page by +default. There are two fundamental factors that you should account for:</p> + +<dl> + <dt>The size of the viewport and scale of the web page</dt> + <dd>When the Android Browser loads a web page, the default behavior is to load the +page in "overview mode," which provides a zoomed-out perspective of the web page. You can override +this behavior for your web page by defining the default dimensions of the viewport or the initial +scale of the viewport. You can also control how much the user can zoom in and out of your web +page, if at all. + <p>However, the user can also disable overview mode in the +Browser settings, so you should not assume that your page will load in overview mode. You +should instead customize the viewport size and/or scale as appropriate for your page.</p></dd> + + <dt>The device's screen density</dt> + <dd>The screen density (the number of pixels per inch) on an Android-powered device affects +the resolution and size at which a web page is displayed. (There are three screen density +categories: low, medium, and high.) The Android Browser compensates for variations in the screen +density by scaling a web page so that all devices display the web page at the same perceivable size +as a medium-density screen. If graphics are an important element of your web design, you +should pay close attention to the scaling that occurs on different densities, because image scaling +can produce artifacts (blurring and pixelation). + <p>To provide the best visual representation on all +screen densities, you should control how scaling occurs by providing viewport metadata about +your web page's target screen density and providing alternative graphics for different screen +densities, which you can apply to different screens using CSS or JavaScript.</p></dd> +</dl> + +<p>The rest of this document describes how you can account for these effects, and how to target +your web page for specific screen configurations.</p> + +<p class="note"><strong>Note:</strong> The features described in this document are supported +by the Android Browser application on Android 2.0 and greater. Third-party web browsers running on +Android might not support these techniques for controlling the viewport size and targetting +screen densities.</p> + + + +<h2 id="Metadata">Using Viewport Metadata</h2> + +<p>The viewport is the area in which the Android Browser +draws a web page. Although the viewport's visible area matches the size of the screen, +the viewport has its own dimensions that determine the number of pixels available to a web page. +That is, the number of pixels available to a web page before it exceeds the screen area is +defined by the dimensions of the viewport, +not the dimensions of the device screen. For example, although a device screen might have a width of +480 pixels, the viewport can have a width of 800 pixels, so that a web page designed to be 800 +pixels wide is completely visible on the screen.</p> + +<p>You can define properties of the viewport for your web page using the {@code "viewport"} +property in an HTML {@code <meta>} tag (which must +be placed in your document {@code <head>}). You can define multiple viewport properties in the +{@code <meta>} tag's {@code content} attribute. For example, you can define the height and +width of the viewport, the initial scale of the page, and the target screen density. +Each viewport property in the {@code content} attribute must be separated by a comma.</p> + +<p>For example, the following snippet from an HTML document specifies that the viewport width +should exactly match the device screen width and that the ability to zoom should be disabled:</p> + +<pre> +<head> + <title>Example</title> + <meta name="viewport" content="width=device-width, user-scalable=no" /> +</head> +</pre> + +<p>That's an example of just two viewport properties. The following syntax shows all of the +supported viewport properties and the general types of values accepted by each one:</p> + +<pre> +<meta name="viewport" + content=" + <b>height</b> = [<em>pixel_value</em> | device-height] , + <b>width</b> = [<em>pixel_value</em> | device-width ] , + <b>initial-scale</b> = <em>float_value</em> , + <b>minimum-scale</b> = <em>float_value</em> , + <b>maximum-scale</b> = <em>float_value</em> , + <b>user-scalable</b> = [yes | no] , + <b>target-densitydpi</b> = [<em>dpi_value</em> | device-dpi | + high-dpi | medium-dpi | low-dpi] + " /> +</pre> + +<p>The following sections discuss how to use each of these viewport properties and exactly what the +accepted values are.</p> + +<div class="figure" style="width:300px"> + <img src="{@docRoot}images/webapps/compare-default.png" alt="" height="300" /> + <p class="img-caption"><strong>Figure 1.</strong> A web page with no viewport metadata and an +image that's 320 pixels wide (the viewport is 800 pixels wide, by default).</p> +</div> + + +<div class="figure" style="width:300px"> + <img src="{@docRoot}images/webapps/compare-width400.png" alt="" height="300" /> + <p class="img-caption"><strong>Figure 2.</strong> A web page with viewport {@code width=400} +(the image in the web page is 320 pixels wide).</p> +</div> + + +<h3 id="ViewportSize">Defining the viewport size</h3> + +<p>Viewport's {@code height} and {@code width} properties allow you to specify the size of the +viewport (the number of pixels available to the web page before it goes off screen). By default, the +Android Browser's minimum viewport width is 800 pixels, so if your web +page specifies its size to be 320 pixels wide, then your page renders smaller than the visible +screen (even if the physical screen is 320 pixels wide, because the viewport simulates a +drawable area that's 800 pixels wide), as shown in figure 1. So, you should explicitly define the +viewport {@code width} to match the width for which you have designed your web page.</p> + +<p class="note"><strong>Note:</strong> Width values that are greater than 10,000 are ignored and +values less than (or equal to) 320 result in a value equal to the device-width. Height values that +are greater then 10,000 or less than 200 are also ignored.</p> + +<p>For example, if your web page is designed to be exactly 320 pixels wide, then you might +want to specify that for the viewport width:</p> + +<pre> +<meta name="viewport" content="width=320" /> +</pre> + +<p>In this case, your web page exactly fits the screen width, because the web page width and +viewport width are the same.</p> + +<p>To demonstrate how this property affects the size of +your web page, figure 2 shows a web page that contains an image that's 320 pixels wide, but with the +viewport width set to 400.</p> + + +<p class="note"><strong>Note:</strong> If you set the viewport width to match your web page width +and the device screen width does <em>not</em> match those dimensions, then the web page +still fits the screen even if the device has a high or low-density screen, because the +Android Browser scales web pages to match the perceived size on a medium-density +screen, by default (as you can see in figure 2, when comparing the hdpi device to the mdpi device). +Screen densities are discussed more in <a href="#ViewportDensity">Defining the viewport target +density</a>.</p> + + +<h4>Automatic sizing</h4> + +<p>As an alternative to specifying the viewport dimensions with exact pixels, you can set the +viewport size to always match the dimensions of the device screen, by defining the +viewport properties {@code height} +and {@code width} with the values {@code device-height} and {@code device-width}, respectively. This +is appropriate when you're developing a web application that has a fluid width (not fixed width), +but you want it to appear as if it's fixed (to perfectly fit every screen as +if the web page width is set to match each screen). For example:</p> + +<pre> +<meta name="viewport" content="width=device-width" /> +</pre> + +<p>This results in the viewport width matching whatever the current screen width is, as shown in +figure 3. It's important to notice that, this results in images being scaled to fit the screen +when the current device does not match the <a href="#ViewportDensity">target +density</a>, which is medium-density if you don't specify otherwise. As a result, the image +displayed on the high-density device in figure 3 is scaled up in order to match the width +of a screen with a medium-density screen.</p> + +<div class="figure" style="width:300px"> + <img src="{@docRoot}images/webapps/compare-initialscale.png" alt="" height="300" /> + <p class="img-caption"><strong>Figure 3.</strong> A web page with viewport {@code +width=device-width} <em>or</em> {@code initial-scale=1.0}.</p> +</div> + +<p class="note"><strong>Note:</strong> If you instead want {@code +device-width} and {@code device-height} to match the physical screen pixels for every device, +instead of scaling your web page to match the target density, then you must also include +the {@code target-densitydpi} property with a value of {@code device-dpi}. This is discussed more in +the section about <a href="#ViewportDensity">Defining the viewport density</a>. Otherwise, simply +using {@code device-height} and {@code device-width} to define the viewport size makes your web page +fit every device screen, but scaling occurs on your images in order to adjust for different screen +densities.</p> + + + +<h3 id="ViewportScale">Defining the viewport scale</h3> + +<p>The scale of the viewport defines the level of zoom applied to the web page. Viewport +properties allow you to specify the scale of your web page in the following ways:</p> +<dl> + <dt>{@code initial-scale}</dt> + <dd>The initial scale of the page. The value is a float that indicates a multiplier for your web +page size, relative to the screen size. For example, if you set the initial scale to "1.0" then the +web page is displayed to match the resolution of the <a href="#ViewportDensity">target +density</a> 1-to-1. If set to "2.0", then the page is enlarged (zoomed in) by a factor of 2. + <p>The default initial scale is calculated to fit the web page in the viewport size. +Because the default viewport width is 800 pixels, if the device screen resolution is less than +800 pixels wide, the initial scale is something less than 1.0, by default, in order to fit the +800-pixel-wide page on the screen.</p></dd> + + <dt>{@code minimum-scale}</dt> + <dd>The minimum scale to allow. The value is a float that indicates the minimum multiplier for +your web page size, relative to the screen size. For example, if you set this to "1.0", then the +page can't zoom out because the minimum size is 1-to-1 with the <a href="#ViewportDensity">target +density</a>.</dd> + + <dt>{@code maximum-scale}</dt> + <dd>The maximum scale to allow for the page. The value is a float that indicates the +maximum multiplier for your web page size, +relative to the screen size. For example, if you set this to "2.0", then the page can't +zoom in more than 2 times the target size.</dd> + + <dt>{@code user-scalable}</dt> + <dd>Whether the user can change the scale of the page at all (zoom in and out). Set to {@code yes} +to allow scaling and {@code no} to disallow scaling. The default is {@code yes}. If you set +this to {@code no}, then the {@code minimum-scale} and {@code maximum-scale} are ignored, +because scaling is not possible.</dd> +</dl> + +<p>All scale values must be within the range 0.01–10.</p> + +<p>For example:</p> + +<pre> +<meta name="viewport" content="initial-scale=1.0" /> +</pre> + +<p>This metadata sets the initial scale to be full sized, relative to the viewport's target +density.</p> + + + + +<h3 id="ViewportDensity">Defining the viewport target density</h3> + +<p>The density of a device's screen is based on the screen resolution. There are three screen +density categories supported by Android: low (ldpi), medium (mdpi), and high (mdpi). A screen +with low density has fewer available pixels per inch, whereas a screen with high density has more +pixels per inch (compared to a medium density screen). The Android Browser targets a medium density +screen by default.</p> + + +<div class="figure" style="width:300px"> + <img src="{@docRoot}images/webapps/compare-initialscale-devicedpi.png" alt="" height="300" /> + <p class="img-caption"><strong>Figure 4.</strong> A web page with viewport {@code +width=device-width} and {@code target-densitydpi=device-dpi}.</p> +</div> + + +<p>Because the default target density is medium, when users have a device with a low or high density +screen, the Android Browser scales web pages (effectively zooms the pages) so they display at a +size that matches the perceived appearance on a medium density screen. Specifically, the Android +Browser applies approximately 1.5x scaling to web pages on a high density screen +(because its screen pixels are smaller) and approximately 0.75x scaling to pages on a low density +screen (because its screen pixels are bigger).</p> + +<p>Due to this default scaling, figures 1, 2, and 3 show the example web page at the same physical +size on both the high and medium density device (the high-density device shows the +web page with a default scale factor that is 1.5 times larger than the actual pixel resolution, to +match the target density). This can introduce some undesirable artifacts in your images. +For example, although an image appears the same size on a medium and high-density device, the image +on the high-density device appears more blurry, because the image is designed to be 320 pixels +wide, but is drawn with 480 pixels.</p> + +<p>You can change the target screen density for your web page using the {@code target-densitydpi} +viewport property. It accepts the following values:</p> + +<ul> +<li><code>device-dpi</code> - Use the device's native dpi as the target dpi. Default scaling never +occurs.</li> +<li><code>high-dpi</code> - Use hdpi as the target dpi. Medium and low density screens scale down +as appropriate.</li> +<li><code>medium-dpi</code> - Use mdpi as the target dpi. High density screens scale up and low +density screens scale down. This is the default target density.</li> +<li><code>low-dpi</code> - Use ldpi as the target dpi. Medium and high density screens scale up +as appropriate.</li> +<li><em><code><value></code></em> - Specify a dpi value to use as the target dpi. Values must +be within the range 70–400.</li> +</ul></p> + +<p>For example, to prevent the Android Browser from scaling of your web page for different screen +densities, set +the {@code target-densitydpi} viewport property to {@code device-dpi}. When you do, the Android +Browser does not scale the page and, instead, displays your web page to match the current screen +density. In this case, you should also define the viewport width to match the device width, so your +web page naturally fits the screen size. For example:</p> + +<pre> +<meta name="viewport" content="target-densitydpi=device-dpi, width=device-width" /> +</pre> + +<p>Figure 4 shows a web page using these viewport settings—the high-density device +now displays the page smaller because its physical pixels are smaller than those on the +medium-density device, so no scaling occurs and the 320-pixel-wide image is drawn using exactly 320 +pixels on both screens. (This is how you should define your viewport if +you want to customize your web page based on screen density and provide different image assets for +different densities, <a href="#DensityCSS">with CSS</a> or +<a href="#DensityJS">with JavaScript</a>.)</p> + + +<h2 id="DensityCSS">Targetting Device Density with CSS</h2> + +<p>The Android Browser supports a CSS media feature that allows you to create styles for specific +screen densities—the <code>-webkit-device-pixel-ratio</code> CSS media feature. The +value you apply to this feature should be either +"0.75", "1", or "1.5", to indicate that the styles are for devices with low density, medium density, +or high density screens, respectively.</p> + +<p>For example, you can create separate stylesheets for each density:</p> + +<pre> +<link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 1.5)" href="hdpi.css" /> +<link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 1.0)" href="mdpi.css" /> +<link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 0.75)" href="ldpi.css" /> +</pre> + + +<div class="figure" style="width:300px"> + <img src="{@docRoot}images/webapps/compare-width-devicedpi-css.png" alt="" height="300" /> + <p class="img-caption"><strong>Figure 5.</strong> A web page with CSS that's targetted to +specific screen densities using the {@code -webkit-device-pixel-ratio} media feature. Notice +that the hdpi device shows a different image that's applied in CSS.</p> +</div> + +<p>Or, specify the different styles in one stylesheet:</p> + +<pre class="no-pretty-print"> +#header { + background:url(medium-density-image.png); +} + +@media screen and (-webkit-device-pixel-ratio: 1.5) { + // CSS for high-density screens + #header { + background:url(high-density-image.png); + } +} + +@media screen and (-webkit-device-pixel-ratio: 0.75) { + // CSS for low-density screens + #header { + background:url(low-density-image.png); + } +} +</pre> + +<p class="note"><strong>Note:</strong> The default style for {@code #header} applies the image +designed for medium-density devices in order to support devices running a version of Android less +than 2.0, which do not support the {@code -webkit-device-pixel-ratio} media feature.</p> + +<p>The types of styles you might want to adjust based on the screen density depend on how you've +defined your viewport properties. To provide fully-customized styles that tailor your web page for +each of the supported densities, you should set your viewport properties so the viewport width and +density match the device. That is:</p> + +<pre> +<meta name="viewport" content="target-densitydpi=device-dpi, width=device-width" /> +</pre> + +<p>This way, the Android Browser does not perform scaling on your web page and the viewport width +matches the screen width exactly. On its own, these viewport properties create results shown in +figure 4. However, by adding some custom CSS using the {@code -webkit-device-pixel-ratio} media +feature, you can apply different styles. For example, figure 5 shows a web page with these viewport +properties and also some CSS added that applies a high-resolution image for high-density +screens.</p> + + + +<h2 id="DensityJS">Targetting Device Density with JavaScript</h2> + +<p>The Android Browser supports a DOM property that allows you to query the density of the current +device—the <code>window.devicePixelRatio</code> DOM property. The value of this property +specifies the scaling factor used for the current device. For example, if the value +of <code>window.devicePixelRatio</code> is "1.0", then the device is considered a medium density +device and no scaling is applied by default; if the value is "1.5", then the device is +considered a high density device and the page is scaled 1.5x by default; if the value +is "0.75", then the device is considered a low density device and the page is scaled +0.75x by default. Of course, the scaling that the Android Browser applies is based on the web page's +target density—as described in the section about <a href="#ViewportDensity">Defining the +viewport target density</a>, the default target is medium-density, but you can change the +target to affect how your web page is scaled for different screen densities.</p> + +<p>For example, here's how you can query the device density with JavaScript:</p> + +<pre> +if (window.devicePixelRatio == 1.5) { + alert("This is a high-density screen"); +} else if (window.devicePixelRation == 0.75) { + alert("This is a low-density screen"); +} +</pre> + + + + + + + diff --git a/docs/html/guide/webapps/webview.jd b/docs/html/guide/webapps/webview.jd new file mode 100644 index 0000000..ed28f21 --- /dev/null +++ b/docs/html/guide/webapps/webview.jd @@ -0,0 +1,328 @@ +page.title=Building Web Apps in WebView +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>Use {@link android.webkit.WebView} to display web pages in your Android application +layout</li> + <li>You can create interfaces from your JavaScript to your client-side Android code</li> +</ul> + +<h2>In this document</h2> +<ol> + <li><a href="#AddingWebView">Adding a WebView to Your Application</a></li> + <li><a href="#UsingJavaScript">Using JavaScript in WebView</a> + <ol> + <li><a href="#EnablingJavaScript">Enabling JavaScript</a></li> + <li><a href="#BindingJavaScript">Binding JavaScript code to Android code</a></li> + </ol> + </li> + <li><a href="#HandlingNavigation">Handling Page Navigation</a> + <ol> + <li><a href="#NavigatingHistory">Navigating web page history</a></li> + </ol> + </li> +</ol> + +<h2>Key classes</h2> +<ol> + <li>{@link android.webkit.WebView}</li> + <li>{@link android.webkit.WebSettings}</li> + <li>{@link android.webkit.WebViewClient}</li> +</ol> + +<h2>Related tutorials</h2> +<ol> + <li><a href="{@docRoot}resources/tutorials/views/hello-webview.html">Web View</a></li> +</ol> + +</div> +</div> + +<p>If you want to deliver a web application (or just a web page) as a part of a client application, +you can do it using {@link android.webkit.WebView}. The {@link android.webkit.WebView} class is an +extension of Android's {@link android.view.View} class that allows you to display web pages as a +part of your activity layout. It does <em>not</em> include any features of a fully developed web +browser, such as navigation controls or an address bar. All that {@link android.webkit.WebView} +does, by default, is show a web page.</p> + +<p>A common scenario in which using {@link android.webkit.WebView} is helpful is when you want to +provide information in your application that you might need to update, such as an end-user agreement +or a user guide. Within your Android application, you can create an {@link android.app.Activity} +that contains a {@link android.webkit.WebView}, then use that to display your document that's +hosted online.</p> + +<p>Another scenario in which {@link android.webkit.WebView} can help is if your application provides +data to the user that +always requires an Internet connection to retrieve data, such as email. In this case, you might +find that it's easier to build a {@link android.webkit.WebView} in your Android application that +shows a web page with all +the user data, rather than performing a network request, then parsing the data and rendering it in +an Android layout. Instead, you can design a web page that's tailored for Android devices +and then implement a {@link android.webkit.WebView} in your Android application that loads the web +page.</p> + +<p>This document shows you how to get started with {@link android.webkit.WebView} and how to do some +additional things, such as handle page navigation and bind JavaScript from your web page to +client-side code in your Android application.</p> + + + +<h2 id="AddingWebView">Adding a WebView to Your Application</h2> + +<p>To add a {@link android.webkit.WebView} to your Application, simply include the {@code +<WebView>} element in your activity layout. For example, here's a layout file in which the +{@link android.webkit.WebView} fills the screen:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<WebView xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/webview" + android:layout_width="fill_parent" + android:layout_height="fill_parent" +/> +</pre> + +<p>To load a web page in the {@link android.webkit.WebView}, use {@link +android.webkit.WebView#loadUrl(String) loadUrl()}. For example:</p> + +<pre> +WebView myWebView = (WebView) findViewById(R.id.webview); +myWebView.loadUrl("http://www.example.com"); +</pre> + +<p>Before this will work, however, your application must have access to the Internet. To get +Internet access, request the {@link android.Manifest.permission#INTERNET} permission in your +manifest file. For example:</p> + +<pre> +<manifest ... > + <uses-permission android:name="android.permission.INTERNET" /> + ... +</manifest> +</pre> + +<p>That's all you need for a basic {@link android.webkit.WebView} that displays a web page.</p> + + + + +<h2 id="UsingJavaScript">Using JavaScript in WebView</h2> + +<p>If the web page you plan to load in your {@link android.webkit.WebView} use JavaScript, you +must enable JavaScript for your {@link android.webkit.WebView}. Once JavaScript is enabled, you can +also create interfaces between your application code and your JavaScript code.</p> + + +<h3 id="EnablingJavaScript">Enabling JavaScript</h3> + +<p>JavaScript is disabled in a {@link android.webkit.WebView} by default. You can enable it +through the {@link +android.webkit.WebSettings} attached to your {@link android.webkit.WebView}. You can retrieve {@link +android.webkit.WebSettings} with {@link android.webkit.WebView#getSettings()}, then enable +JavaScript with {@link android.webkit.WebSettings#setJavaScriptEnabled(boolean) +setJavaScriptEnabled()}.</p> + +<p>For example:</p> + +<pre> +WebView myWebView = (WebView) findViewById(R.id.webview); +WebSettings webSettings = myWebView.getSettings(); +webSettings.setJavaScriptEnabled(true); +</pre> + +<p>{@link android.webkit.WebSettings} provides access to a variety of other settings that you might +find useful. For example, if you're developing a web application +that's designed specifically for the {@link android.webkit.WebView} in your Android application, +then you can define a +custom user agent string with {@link android.webkit.WebSettings#setUserAgentString(String) +setUserAgentString()}, then query the custom user agent in your web page to verify that the +client requesting your web page is actually your Android application.</p> + +from your Android SDK {@code tools/} directory +<h3 id="BindingJavaScript">Binding JavaScript code to Android code</h3> + +<p>When developing a web application that's designed specifically for the {@link +android.webkit.WebView} in your Android +application, you can create interfaces between your JavaScript code and client-side Android code. +For example, your JavaScript code can call a method in your Android code to display a {@link +android.app.Dialog}, instead of using JavaScript's {@code alert()} function.</p> + +<p>To bind a new interface between your JavaScript and Android code, call {@link +android.webkit.WebView#addJavascriptInterface(Object,String) addJavascriptInterface()}, passing it +a class instance to bind to your JavaScript and an interface name that your JavaScript can call to +access the class.</p> + +<p>For example, you can include the following class in your Android application:</p> + +<pre> +public class JavaScriptInterface { + Context mContext; + + /** Instantiate the interface and set the context */ + JavaScriptInterface(Context c) { + mContext = c; + } + + /** Show a toast from the web page */ + public void showToast(String toast) { + Toast.makeText(mContext, toast, Toast.LENGTH_SHORT).show(); + } +} +</pre> + +<p>In this example, the {@code JavaScriptInterface} class allows the web page to create a {@link +android.widget.Toast} message, using the {@code showToast()} method.</p> + +<p>You can bind this class to the JavaScript that runs in your {@link android.webkit.WebView} with +{@link android.webkit.WebView#addJavascriptInterface(Object,String) addJavascriptInterface()} and +name the interface {@code Android}. For example:</p> + +<pre> +WebView webView = (WebView) findViewById(R.id.webview); +webView.addJavascriptInterface(new JavaScriptInterface(this), "Android"); +</pre> + +<p>This creates an interface called {@code Android} for JavaScript running in the {@link +android.webkit.WebView}. At this point, your web application has access to the {@code +JavaScriptInterface} class. For example, here's some HTML and JavaScript that creates a toast +message using the new interface when the user clicks a button:</p> + +<pre> +<input type="button" value="Say hello" onClick="showAndroidToast('Hello Android!')" /> + +<script type="text/javascript"> + function showAndroidToast(toast) { + Android.showToast(toast); + } +</script> +</pre> + +<p>There's no need to initialize the {@code Android} interface from JavaScript. The {@link +android.webkit.WebView} automatically makes it +available to your web page. So, at the click of the button, the {@code showAndroidToast()} +function uses the {@code Android} interface to call the {@code JavaScriptInterface.showToast()} +method.</p> + +<p class="note"><strong>Note:</strong> The object that is bound to your JavaScript runs in +another thread and not in the thread in which it was constructed.</p> + +<p class="caution"><strong>Caution:</strong> Using {@link +android.webkit.WebView#addJavascriptInterface(Object,String) addJavascriptInterface()} allows +JavaScript to control your Android application. This can be a very useful feature or a dangerous +security issue. When the HTML in the {@link android.webkit.WebView} is untrustworthy (for example, +part or all of the HTML +is provided by an unknown person or process), then an attacker can include HTML that executes +your client-side code and possibly any code of the attacker's choosing. As such, you should not use +{@link android.webkit.WebView#addJavascriptInterface(Object,String) addJavascriptInterface()} unless +you wrote all of the HTML and JavaScript that appears in your {@link android.webkit.WebView}. You +should also not allow the user to +navigate to other web pages that are not your own, within your {@link android.webkit.WebView} +(instead, allow the user's +default browser application to open foreign links—by default, the user's web browser +opens all URL links, so be careful only if you handle page navigation as described in the +following section).</p> + + + + +<h2 id="HandlingNavigation">Handling Page Navigation</h2> + +<p>When the user clicks a link from a web page in your {@link android.webkit.WebView}, the default +behavior is +for Android to launch an application that handles URLs. Usually, the default web browser opens and +loads the destination URL. However, you can override this behavior for your {@link +android.webkit.WebView}, +so links open within your {@link android.webkit.WebView}. You can then allow the user to navigate +backward and forward through their web page history that's maintained by your {@link +android.webkit.WebView}.</p> + +<p>To open links clicked by the user, simply provide a {@link +android.webkit.WebViewClient} for your {@link android.webkit.WebView}, using {@link +android.webkit.WebView#setWebViewClient(WebViewClient) setWebViewClient()}. For example:</p> + +<pre> +WebView myWebView = (WebView) findViewById(R.id.webview); +myWebView.{@link android.webkit.WebView#setWebViewClient(WebViewClient) setWebViewClient}(new WebViewClient()); +</pre> + +<p>That's it. Now all links the user clicks load in your {@link android.webkit.WebView}.</p> + +<p>If you want more control over where a clicked link load, create your own {@link +android.webkit.WebViewClient} that overrides the {@link +android.webkit.WebViewClient#shouldOverrideUrlLoading(WebView,String) +shouldOverrideUrlLoading()} method. For example:</p> + +<pre> +private class MyWebViewClient extends WebViewClient { + @Override + public boolean {@link android.webkit.WebViewClient#shouldOverrideUrlLoading(WebView,String) shouldOverrideUrlLoading}(WebView view, String url) { + if (Uri.parse(url).getHost().equals("www.example.com")) { + // This is my web site, so do not override; let my WebView load the page + return false; + } + // Otherwise, the link is not for a page on my site, so launch another Activity that handles URLs + Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url)); + startActivity(intent); + return true; + } +} +</pre> + +<p>Then create an instance of this new {@link android.webkit.WebViewClient} for the {@link +android.webkit.WebView}:</p> + +<pre> +WebView myWebView = (WebView) findViewById(R.id.webview); +myWebView.{@link android.webkit.WebView#setWebViewClient(WebViewClient) setWebViewClient}(new MyWebViewClient()); +</pre> + +<p>Now when the user clicks a link, the system calls +{@link android.webkit.WebViewClient#shouldOverrideUrlLoading(WebView,String) +shouldOverrideUrlLoading()}, which checks whether the URL host matches a specific domain (as defined +above). If it does match, then the method returns false in order to <em>not</em> override the URL +loading (it allows the {@link android.webkit.WebView} to load the URL as usual). If the URL host +does not match, then an {@link android.content.Intent} is created to +launch the default Activity for handling URLs (which resolves to the user's default web +browser).</p> + + + + +<h3 id="NavigatingHistory">Navigating web page history</h3> + +<p>When your {@link android.webkit.WebView} overrides URL loading, it automatically accumulates a +history of visited web +pages. You can navigate backward and forward through the history with {@link +android.webkit.WebView#goBack()} and {@link android.webkit.WebView#goForward()}.</p> + +<p>For example, here's how your {@link android.app.Activity} can use the device BACK key to navigate +backward:</p> + +<pre> +@Override +public boolean {@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown}(int keyCode, KeyEvent event) { + // Check if the key event was the BACK key and if there's history + if ((keyCode == KeyEvent.KEYCODE_BACK) && myWebView.{@link android.webkit.WebView#canGoBack() canGoBack}() { + myWebView.{@link android.webkit.WebView#goBack() goBack}(); + return true; + } + // If it wasn't the BACK key or there's no web page history, bubble up to the default + // system behavior (probably exit the activity) + return super.onKeyDown(keyCode, event); +} +</pre> + +<p>The {@link android.webkit.WebView#canGoBack()} method returns +true if there is actually web page history for the user to visit. Likewise, you can use {@link +android.webkit.WebView#canGoForward()} to check whether there is a forward history. If you don't +perform this check, then once the user reaches the end of the history, {@link +android.webkit.WebView#goBack()} or {@link android.webkit.WebView#goForward()} does nothing.</p> + + + + + + diff --git a/docs/html/images/axis_device.png b/docs/html/images/axis_device.png Binary files differnew file mode 100644 index 0000000..f1f666a --- /dev/null +++ b/docs/html/images/axis_device.png diff --git a/docs/html/images/axis_globe.png b/docs/html/images/axis_globe.png Binary files differnew file mode 100644 index 0000000..dccb58b --- /dev/null +++ b/docs/html/images/axis_globe.png diff --git a/docs/html/images/testing/android_test_framework.png b/docs/html/images/testing/android_test_framework.png Binary files differindex 6f80530..459975c 100755 --- a/docs/html/images/testing/android_test_framework.png +++ b/docs/html/images/testing/android_test_framework.png diff --git a/docs/html/images/testing/eclipse_test_results.png b/docs/html/images/testing/eclipse_test_results.png Binary files differnew file mode 100644 index 0000000..105e149 --- /dev/null +++ b/docs/html/images/testing/eclipse_test_results.png diff --git a/docs/html/images/testing/eclipse_test_run_failure.png b/docs/html/images/testing/eclipse_test_run_failure.png Binary files differnew file mode 100644 index 0000000..8111127 --- /dev/null +++ b/docs/html/images/testing/eclipse_test_run_failure.png diff --git a/docs/html/images/testing/test_framework.png b/docs/html/images/testing/test_framework.png Binary files differnew file mode 100644 index 0000000..fbc5fc2 --- /dev/null +++ b/docs/html/images/testing/test_framework.png diff --git a/docs/html/images/webapps/compare-default.png b/docs/html/images/webapps/compare-default.png Binary files differnew file mode 100644 index 0000000..9495a05 --- /dev/null +++ b/docs/html/images/webapps/compare-default.png diff --git a/docs/html/images/webapps/compare-initialscale-devicedpi.png b/docs/html/images/webapps/compare-initialscale-devicedpi.png Binary files differnew file mode 100644 index 0000000..6bb758a --- /dev/null +++ b/docs/html/images/webapps/compare-initialscale-devicedpi.png diff --git a/docs/html/images/webapps/compare-initialscale.png b/docs/html/images/webapps/compare-initialscale.png Binary files differnew file mode 100644 index 0000000..2232d5b --- /dev/null +++ b/docs/html/images/webapps/compare-initialscale.png diff --git a/docs/html/images/webapps/compare-width-devicedpi-css.png b/docs/html/images/webapps/compare-width-devicedpi-css.png Binary files differnew file mode 100644 index 0000000..bb4ab31 --- /dev/null +++ b/docs/html/images/webapps/compare-width-devicedpi-css.png diff --git a/docs/html/images/webapps/compare-width400.png b/docs/html/images/webapps/compare-width400.png Binary files differnew file mode 100644 index 0000000..669a234 --- /dev/null +++ b/docs/html/images/webapps/compare-width400.png diff --git a/docs/html/resources/faq/framework.jd b/docs/html/resources/faq/framework.jd index f4b8db0..4a7a3fc 100644 --- a/docs/html/resources/faq/framework.jd +++ b/docs/html/resources/faq/framework.jd @@ -68,12 +68,17 @@ Preferences</a> storage mechanism.</p> <p>For sharing complex non-persistent user-defined objects for short duration, the following approaches are recommended: </p> - <h4>The android.app.Application class</h4> - <p>The android.app.Application is a base class for those who need to -maintain global application state. It can be accessed via -getApplication() from any Activity or Service. It has a couple of -life-cycle methods and will be instantiated by Android automatically if -your register it in AndroidManifest.xml.</p> + <h4>Singleton class</h4> + <p>You can take advantage of the fact that your application +components run in the same process through the use of a singleton. +This is a class that is designed to have only one instance. It +has a static method with a name such as <code>getInstance()</code> +that returns the instance; the first time this method is called, +it creates the global instance. Because all callers get the same +instance, they can use this as a point of interaction. For +example activity A may retrieve the instance and call setValue(3); +later activity B may retrieve the instance and call getValue() to +retrieve the last set value.</p> <h4>A public static field/method</h4> <p>An alternate way to make data accessible across Activities/Services is to use <em>public static</em> @@ -90,18 +95,6 @@ Long based on a counter or time stamp) to the recipient activity via intent extras. The recipient activity retrieves the object using this key.</p> - <h4>A Singleton class</h4> - <p>There are advantages to using a static Singleton, such as you can -refer to them without casting getApplication() to an -application-specific class, or going to the trouble of hanging an -interface on all your Application subclasses so that your various -modules can refer to that interface instead. </p> -<p>But, the life cycle of a static is not well under your control; so -to abide by the life-cycle model, the application class should initiate and -tear down these static objects in the onCreate() and onTerminate() methods -of the Application Class</p> -</p> - <h3>Persistent Objects</h3> <p>Even while an application appears to continue running, the system @@ -146,15 +139,11 @@ call.</p> <h2>If an Activity starts a remote service, is there any way for the Service to pass a message back to the Activity?</h2> -<p>The remote service can define a callback interface and register it with the -clients to callback into the clients. The -{@link android.os.RemoteCallbackList RemoteCallbackList} class provides methods to -register and unregister clients with the service, and send and receive -messages.</p> - -<p>The sample code for remote service callbacks is given in <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">ApiDemos/RemoteService</a></p> - +<p>See the {@link android.app.Service} documentation's for examples of +how clients can interact with a service. You can take advantage of the +fact that your components run in the same process to greatly simplify +service interaction from the generic remote case, as shown by the "Local +Service Sample". In some cases techniques like singletons may also make sense. <a name="6" id="6"></a> diff --git a/docs/html/sdk/adding-components.jd b/docs/html/sdk/adding-components.jd index 63c577e..755f200 100644 --- a/docs/html/sdk/adding-components.jd +++ b/docs/html/sdk/adding-components.jd @@ -6,7 +6,7 @@ page.title=Adding SDK Components <div id="qv"> <h2>Quickview</h2> <ul> - <li>Use the Android SDK and AVD Manager to + <li>Use the Android SDK and AVD Manager to set up your SDK and keep it up-to-date.</li> </ul> @@ -25,7 +25,7 @@ page.title=Adding SDK Components <p>Adding and updating components in your Android SDK is fast and easy. To perform an update, use the <strong>Android SDK and AVD Manager</strong> to install or update the individual SDK components that you need. The Android SDK -and AVD Manager tool is included in the <a href="index.html">Android SDK +and AVD Manager tool is included in the <a href="index.html">Android SDK download</a>.</p> <p>It only takes a couple of clicks to install individual versions of the @@ -53,19 +53,19 @@ a new version of the platform. See the revisions listed in the <a href="{@docRoot}sdk/tools-notes.html">SDK Tools</a> document for ADT Plugin compatibility.</p> -<div style="TEXT-ALIGN:left; width:600px;"> -<img src="{@docRoot}images/sdk_manager_packages.png" -style="padding-bottom:0;margin-bottom:0;" /> +<div style="TEXT-ALIGN:left; width:600px;"> +<img src="{@docRoot}images/sdk_manager_packages.png" +style="padding-bottom:0;margin-bottom:0;" /> <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 -1em;"><strong>Figure 1.</strong> The Android SDK and AVD Manager's +1em;"><strong>Figure 1.</strong> The Android SDK and AVD Manager's <strong>Available Packages</strong> panel, which shows the SDK components that are available for you to download into your environment. </p> -</div> +</div> <h2 id="launching">Launching the Android SDK and AVD Manager</h2> -<p>The Android SDK and AVD Manager is the tool that you use to install and +<p>The Android SDK and AVD Manager is the tool that you use to install and upgrade SDK components in your development environment. </p> <p>You can access the tool in any of three ways:</p> @@ -83,15 +83,15 @@ follow these steps to access the Android SDK and AVD Manager tool:</p> <ol> <li>Open Eclipse</li> -<li>Select <strong>Window</strong> > <strong>Android SDK and AVD +<li>Select <strong>Window</strong> > <strong>Android SDK and AVD Manager</strong>.</li> </ol> -<h4>Launching from the setup script (Windows only)</h4> +<h4>Launching from the SDK Manager script (Windows only)</h4> <p>For Windows only, the SDK includes a script that invokes the Android SDK and -AVD Manager. To launch the tool using the script, double-click "SDK -Setup.exe" at the root of the the SDK directory.</p> +AVD Manager. To launch the tool using the script, double-click {@code SDK +Manager.exe} at the root of the the SDK directory.</p> <h4>Launching from a command line</h4> @@ -100,37 +100,39 @@ and AVD Manager tool from the command line: </p> <ol> <li>Navigate to the <code><<em>sdk</em>>/tools/</code> directory.</li> -<li>Execute the {@code android} tool command with no options. +<li>Execute the {@code android} tool command with no options. <pre style="width:400px">$ android</pre></li> </ol> <h2 id="InstallingComponents">Installing SDK Components</h2> -<p class="caution"><strong>Important:</strong> Before you install SDK components, -we recommend that you disable any antivirus programs that may be running on -your computer.</p> +<p class="caution"><strong>Caution:</strong> Before you install SDK components, +we recommend that you disable any antivirus software that may be running on +your computer. There are cases in which antivirus software on Windows is known to interfere with the +installation process, so we suggest you disable your antivirus until installation is +complete.</p> <p>Follow these steps to install new SDK components in your environment:</p> <ol> <li>Launch the Android SDK and AVD Manager as described in the section above.</li> <li>Select <strong>Available Packages</strong> in the left panel. - This will reveal all of the components that are currently available for download + This will reveal all of the components that are currently available for download from the SDK repository.</li> <li>Select the component(s) you'd like to install and click <strong>Install - Selected</strong>. If you aren't sure which packages to select, read <a + Selected</strong>. If you aren't sure which packages to select, read <a href="installing.html#which">Which components do I need?</a>.</li> <li>Verify and accept the components you want and click <strong>Install Accepted</strong>. The components will now be installed into your existing Android SDK directories.</li> </ol> -<p>New platforms are automatically saved into the +<p>New platforms are automatically saved into the <code><<em>sdk</em>>/platforms/</code> directory of your SDK; new add-ons are saved in the <code><<em>sdk</em>>/add-ons/</code> -directory; samples are saved in the -<code><<em>sdk</em>>/samples/android-<<em>level</em>>/</code>; +directory; samples are saved in the +<code><<em>sdk</em>>/samples/android-<<em>level</em>>/</code>; and new documentation is saved in the existing <code><<em>sdk</em>>/docs/</code> directory (old docs are replaced).</p> @@ -184,10 +186,10 @@ if there is dependency that you need to address. </p> <h2 id="AddingSites">Adding New Sites</h2> <p>By default, <strong>Available Packages</strong> only shows the default -repository site, which offers platforms, SDK tools, documentation, the -Google APIs Add-on, and other components. You can add other sites that host +repository site, which offers platforms, SDK tools, documentation, the +Google APIs Add-on, and other components. You can add other sites that host their own Android SDK add-ons, then download the SDK add-ons -from those sites.</p> +from those sites.</p> <p>For example, a mobile carrier or device manufacturer might offer additional API libraries that are supported by their own Android-powered devices. In order @@ -199,7 +201,7 @@ Manager:</p> <ol> <li>Select <strong>Available Packages</strong> in the left panel.</li> - <li>Click <strong>Add Site</strong> and enter the URL of the + <li>Click <strong>Add Site</strong> and enter the URL of the {@code repository.xml} file. Click <strong>OK</strong>.</li> </ol> <p>Any SDK components available from the site will now be listed under diff --git a/docs/html/sdk/adt_download.jd b/docs/html/sdk/adt_download.jd index 8220d91..3da576a 100644 --- a/docs/html/sdk/adt_download.jd +++ b/docs/html/sdk/adt_download.jd @@ -24,8 +24,8 @@ ADT Installation</a>.</p> <tr> <td>0.9.9</td> <td><a href="http://dl-ssl.google.com/android/ADT-0.9.9.zip">ADT-0.9.9.zip</a></td> - <td><nobr>{@adtZipBytes} bytes</nobr></td> - <td>{@adtZipChecksum}</td> + <td><nobr>8301681 bytes</nobr></td> + <td>7deff0c9b25940a74cea7a0815a3bc36</td> <td>Requires SDK Tools, Revision 7 <em><nobr>September 2010</nobr></em></td> </tr> <tr> diff --git a/docs/html/sdk/android-1.5.jd b/docs/html/sdk/android-1.5.jd index 0c16b60..9ed798c 100644 --- a/docs/html/sdk/android-1.5.jd +++ b/docs/html/sdk/android-1.5.jd @@ -2,8 +2,6 @@ page.title=Android 1.5 Platform sdk.platform.version=1.5 sdk.platform.apiLevel=3 sdk.platform.majorMinor=major -sdk.platform.releaseDate=April 2009 -sdk.platform.deployableDate=May 2009 @jd:body @@ -43,7 +41,7 @@ Differences Report »</a> </li> <em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p> <p>Android {@sdkPlatformVersion} is a {@sdkPlatformMajorMinor} platform release -deployable to Android-powered handsets starting in {@sdkPlatformDeployableDate}. +deployable to Android-powered handsets starting in May 2009. The release includes new features for users and developers, as well as changes in the Android framework API. </p> diff --git a/docs/html/sdk/android-1.6.jd b/docs/html/sdk/android-1.6.jd index c4e08ff..a01a5f6 100644 --- a/docs/html/sdk/android-1.6.jd +++ b/docs/html/sdk/android-1.6.jd @@ -2,8 +2,6 @@ page.title=Android 1.6 Platform sdk.platform.version=1.6 sdk.platform.apiLevel=4 sdk.platform.majorMinor=minor -sdk.platform.releaseDate=December 2009 -sdk.platform.deployableDate=October 2009 @jd:body @@ -43,7 +41,7 @@ Differences Report »</a> </li> <em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p> <p>Android {@sdkPlatformVersion} is a {@sdkPlatformMajorMinor} platform release -deployable to Android-powered handsets since {@sdkPlatformDeployableDate}. +deployable to Android-powered handsets since October 2009. The platform includes new features for users and developers, as well as changes in the Android framework API. </p> diff --git a/docs/html/sdk/android-2.0.1.jd b/docs/html/sdk/android-2.0.1.jd index cacb6bf..0c8afb6 100644 --- a/docs/html/sdk/android-2.0.1.jd +++ b/docs/html/sdk/android-2.0.1.jd @@ -2,8 +2,6 @@ page.title=Android 2.0.1, Release 1 sdk.platform.version=2.0.1 sdk.platform.apiLevel=6 sdk.platform.majorMinor=minor -sdk.platform.releaseDate=December 2009 -sdk.platform.deployableDate=December 2009 @jd:body @@ -44,7 +42,7 @@ differences report »</a> </li> <em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p> <p>Android {@sdkPlatformVersion} is a {@sdkPlatformMajorMinor} platform release -deployable to Android-powered handsets starting in {@sdkPlatformDeployableDate}. +deployable to Android-powered handsets starting in December 2009. This release includes minor API changes, bug fixes and framework behavioral changes. For information on changes and fixes, see the <a href="#api">Framework API</a> section.</p> diff --git a/docs/html/sdk/android-2.0.jd b/docs/html/sdk/android-2.0.jd index a430f34..2c31923 100644 --- a/docs/html/sdk/android-2.0.jd +++ b/docs/html/sdk/android-2.0.jd @@ -2,8 +2,6 @@ page.title=Android 2.0, Release 1 sdk.platform.version=2.0 sdk.platform.apiLevel=5 sdk.platform.majorMinor=major -sdk.platform.releaseDate=October 2009 -sdk.platform.deployableDate=November 2009 @jd:body @@ -38,7 +36,7 @@ sdk.platform.deployableDate=November 2009 <em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p> <p>Android {@sdkPlatformVersion} is a {@sdkPlatformMajorMinor} platform release -deployable to Android-powered handsets starting in {@sdkPlatformDeployableDate}. +deployable to Android-powered handsets starting in November 2009. The release includes new features for users and developers, as well as changes in the Android framework API. </p> diff --git a/docs/html/sdk/android-2.1.jd b/docs/html/sdk/android-2.1.jd index cd48a72..6eba6f0 100644 --- a/docs/html/sdk/android-2.1.jd +++ b/docs/html/sdk/android-2.1.jd @@ -2,7 +2,6 @@ page.title=Android 2.1 Platform sdk.platform.version=2.1 sdk.platform.apiLevel=7 sdk.platform.majorMinor=minor -sdk.platform.deployableDate=January 2010 @jd:body @@ -42,7 +41,7 @@ Differences Report »</a> </li> <em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p> <p>Android {@sdkPlatformVersion} is a {@sdkPlatformMajorMinor} platform release -deployable to Android-powered handsets starting in {@sdkPlatformDeployableDate}. +deployable to Android-powered handsets starting in January 2010. This release includes new API changes and bug fixes. For information on changes, see the <a href="#api">Framework API</a> section.</p> diff --git a/docs/html/sdk/android-2.2.jd b/docs/html/sdk/android-2.2.jd index fe06206..063a10f 100644 --- a/docs/html/sdk/android-2.2.jd +++ b/docs/html/sdk/android-2.2.jd @@ -471,4 +471,4 @@ emulator skins are:</p> <p>For more information about how to develop an application that displays and functions properly on all Android-powered devices, see <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple -Screens</a>.</p>
\ No newline at end of file +Screens</a>.</p> diff --git a/docs/html/sdk/eclipse-adt.jd b/docs/html/sdk/eclipse-adt.jd index 00db2ec..9f3c8b0 100644 --- a/docs/html/sdk/eclipse-adt.jd +++ b/docs/html/sdk/eclipse-adt.jd @@ -1,5 +1,9 @@ page.title=ADT Plugin for Eclipse sdk.preview=0 +adt.zip.version=0.9.9 +adt.zip.download=ADT-0.9.9.zip +adt.zip.bytes=8301681 +adt.zip.checksum=7deff0c9b25940a74cea7a0815a3bc36 @jd:body diff --git a/docs/html/sdk/index.jd b/docs/html/sdk/index.jd index 7016eee..2e59801 100644 --- a/docs/html/sdk/index.jd +++ b/docs/html/sdk/index.jd @@ -1,27 +1,27 @@ page.title=Android SDK sdk.redirect=0 -sdk.win_download=android-sdk_r07-windows.zip -sdk.win_bytes=23669664 -sdk.win_checksum=69c40c2d2e408b623156934f9ae574f0 +sdk.win_installer=installer_r08-windows.exe +sdk.win_installer_bytes=TODO +sdk.win_installer_checksum=TODO -sdk.mac_download=android-sdk_r07-mac_x86.zip -sdk.mac_bytes=19229546 -sdk.mac_checksum=0f330ed3ebb36786faf6dc72b8acf819 +sdk.win_download=android-sdk_r08-windows.zip +sdk.win_bytes=TODO +sdk.win_checksum=TODO -sdk.linux_download=android-sdk_r07-linux_x86.tgz -sdk.linux_bytes=17114517 -sdk.linux_checksum=e10c75da3d1aa147ddd4a5c58bfc3646 +sdk.mac_download=android-sdk_r08-mac_x86.zip +sdk.mac_bytes=TODO +sdk.mac_checksum=TODO + +sdk.linux_download=android-sdk_r08-linux_x86.tgz +sdk.linux_bytes=TODO +sdk.linux_checksum=TODO @jd:body <h2 id="quickstart">Quick Start</h2> -<p>The steps below provide an overview of how to get started with the Android -SDK. For detailed instructions, start with the <a -href="{@docRoot}sdk/installing.html">Installing the SDK</a> guide. </p> - <p><strong>1. Prepare your development computer</strong></p> <p>Read the <a href="{@docRoot}sdk/requirements.html">System Requirements</a> @@ -34,38 +34,37 @@ install the <a href="http://java.sun.com/javase/downloads/index.jsp">JDK</a> <p><strong>2. Download and install the SDK starter package</strong></p> -<p>Select a starter package from the table at the top of this page and download -it to your development computer. To install the SDK, simply unpack the starter -package to a safe location and then add the location to your PATH. </p> +<p>Download a starter package from the table above onto your development computer. +If you're using Windows, we recommend that you download the installer (the {@code .exe} file), +which will launch a Wizard to guide you through the installation and check your computer for +required software. Otherwise, download the SDK starter package ({@code .zip} or {@code .tgz}) +appropriate for your system, unpack it to a safe location, then add the location to your PATH +environment variable. </p> <p><strong>3. Install the ADT Plugin for Eclipse</strong></p> -<p>If you are developing in Eclipse, set up a remote update site at -<code>https://dl-ssl.google.com/android/eclipse/</code>. Install the Android -Development Tools (ADT) Plugin, restart Eclipse, and set the "Android" -preferences in Eclipse to point to the SDK install location. For detailed -instructions, see <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin +<p>If you are developing in Eclipse, add a new remote update site with the URL +<code>https://dl-ssl.google.com/android/eclipse/</code>. Install the Android +Development Tools (ADT) Plugin from that site, restart Eclipse, and set the "Android" +preferences in Eclipse to point to the Android SDK directory (installed in the previous step). For +detailed instructions to setup Eclipse, see <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin for Eclipse</a>.</p> <p><strong>4. Add Android platforms and other components to your SDK</strong></p> -<p>Use the Android SDK and AVD Manager, included in the SDK starter package, to -add one or more Android platforms (for example, Android 1.6 or Android 2.2) and -other components to your SDK. If you aren't sure what to add, see <a +<p>Launch the <em>Android SDK and AVD Manager</em> by executing {@code SDK Manager.exe} (Windows) or +{@code android} (Mac/Linux) from the SDK's {@code tools/} directory (if you used the Windows +installer, this is launched for you when the Wizard is complete). Add some Android platforms +(such as Android 1.6 and Android 2.3) and other components (such as documentation) to your SDK. If +you aren't sure what to add, see <a href="installing.html#which">Which components do I need?</a></p> -<p>To launch the Android SDK and AVD Manager on Windows, execute <code>SDK -Setup.exe</code>, at the root of the SDK directory. On Mac OS X or Linux, -execute the <code>android</code> tool in the <code><sdk>/tools/</code> -folder. For detailed instructions, see <a -href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p> - <p><strong>Done!</strong></p> -<p>If you are new to Android, you can use the <a -href="{@docRoot}resources/tutorials/hello-world.html">Hello World</a> tutorial to -get started quickly. <a href="{@docRoot}sdk/installing.html#NextSteps">Next -Steps</a> offers other suggestions of how to begin.</p> +<p>To write your first Android application, see the <a +href="{@docRoot}resources/tutorials/hello-world.html">Hello World</a> tutorial. Also see <a +href="{@docRoot}sdk/installing.html#NextSteps">Next +Steps</a> for other suggestions about how to get started.</p> -<p>For a more detailed guide to installing and setting up the SDK, read <a +<p>For a more detailed guide to installing and setting up the SDK, read <a href="installing.html">Installing the SDK</a>.</p> diff --git a/docs/html/sdk/installing.jd b/docs/html/sdk/installing.jd index 73190a0..8484bea 100644 --- a/docs/html/sdk/installing.jd +++ b/docs/html/sdk/installing.jd @@ -29,20 +29,20 @@ sdk.preview=0 </div> </div> -<p>This page describes how to install the Android SDK +<p>This page describes how to install the Android SDK and set up your development environment for the first time.</p> -<p>If you encounter any problems during installation, see the +<p>If you encounter any problems during installation, see the <a href="#troubleshooting">Troubleshooting</a> section at the bottom of this page.</p> <h4>Updating?</h4> -<p>If you are currently using the Android 1.6 SDK or later and want to update -to the latest tools or platforms, you do not need to install a new SDK. Instead, -you can simply update the individual components in your SDK using the -Android SDK and AVD Manager tool. For information about how to do that, see <a -href="{@docRoot}sdk/adding-components.html#UpdatingComponents">Updating SDK +<p>If you are currently using the Android 1.6 SDK or later and want to update +to the latest tools or platforms, you do not need to install a new SDK. Instead, +you can simply update the individual components in your SDK using the +Android SDK and AVD Manager tool. For information about how to do that, see <a +href="{@docRoot}sdk/adding-components.html#UpdatingComponents">Updating SDK Components</a></p> <p>If you are using Android 1.5 SDK or earlier, you should install a new SDK as @@ -54,65 +54,71 @@ SDK environment. </p> <p>Before getting started with the Android SDK, take a moment to confirm that your development computer meets the <a href="requirements.html">System -Requirements</a>. In particular, you may need to install the <a -href="http://java.sun.com/javase/downloads/index.jsp">JDK</a> before +Requirements</a>. In particular, you may need to install the <a +href="http://java.sun.com/javase/downloads/index.jsp">JDK</a> before continuing, if it's not already installed on your computer. </p> <p>If you will be developing in Eclipse with the Android Development Tools (ADT) Plugin — the recommended path if you are new to Android — make sure that you have a suitable version of Eclipse -installed on your computer (3.4 or newer is recommended). If you need -to install Eclipse, you can download it from this location: </p> - +installed on your computer (3.4 or newer is recommended). If you need +to install Eclipse, you can download it from this location: </p> + <p style="margin-left:2em;"><a href= -"http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/</a></p> - -<p>A Java or RCP version of Eclipse is recommended. For Eclipse 3.5, the -"Eclipse Classic" version is recommended.</p> +"http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/</a></p> + +<p>A Java or RCP version of Eclipse is recommended. For Eclipse 3.5, the +"Eclipse Classic" version is recommended.</p> <h2 id="Installing">Step 2. Downloading the SDK Starter Package</h2> <p>The first step in setting up your environment for developing Android applications is downloading the Android SDK starter package. The starter package is not a full -development environment — it includes only the core SDK Tools, which you can -use to download the rest of the SDK components. </p> +development environment — it includes only the core SDK Tools, which you can +use to download the rest of the SDK components (such as the platform system images). </p> <p>You can get the latest version of the SDK starter package from the <a href="{@docRoot}sdk/index.html">SDK download page</a>. Make sure to download the package that is appropriate for your development computer.</p> -<p>After downloading, unpack the Android SDK archive to a safe location on your -machine. By default, the SDK files are unpacked into a directory named -<code>android-sdk-<machine-platform></code>. Make a note of the name and +<p class="note"><strong>Note:</strong> If you're using Windows, we recommend that you download +the SDK installer (the {@code .exe} file from the download table). It will guide you through the +installation process and check your computer for the required software.</p> + +<p>If you downloaded a {@code .zip} of {@code .tgz} (instead of using the SDK installer), unpack the +Android SDK archive to a safe location on your machine. By default, the SDK files are unpacked into +a directory named <code>android-sdk-<machine-platform></code>.</p> + +<p>Make a note of the name and location of the unpacked SDK directory on your system — you will need to -refer to the SDK directory later, when setting up the ADT plugin or when using -the SDK tools.</p> - -<p>Optionally, you may want to add the location of the SDK's primary -<code>tools</code> directory to your system <code>PATH</code>. The primary -<code>tools/</code> directory is located at the root of the SDK folder. Adding -<code>tools</code> to your path lets you run Android Debug Bridge (adb) and the -other command line <a +refer to the SDK directory later, when setting up the ADT plugin and when using +the SDK tools from command line.</p> + +<p>Optionally, you might want to add the location of the SDK's primary +<code>tools</code> directory and the additional {@code platform-tools/} directory to your system +<code>PATH</code>. Both tool directories are located at the root of the SDK folder. Adding +<code>tools/</code> and {@code platform-tools/} to your path lets you run Android Debug Bridge (adb) +and the other command line <a href="{@docRoot}guide/developing/tools/index.html">tools</a> without needing to -supply the full path to the tools directory. </p> +supply the full path to the tool directories. </p> <ul> <li>On Linux, edit your <code>~/.bash_profile</code> or <code>~/.bashrc</code> file. Look for a line that sets the PATH environment variable and add the - full path to the <code>tools/</code> directory to it. If you don't + full path to the <code>tools/</code> and {@code platform-tools/} directories to it. If you don't see a line setting the path, you can add one:</li> - <ul><code>export PATH=${PATH}:<em><your_sdk_dir></em>/tools</code></ul> + <ul><code>export PATH=${PATH}:<your_sdk_dir>/tools:<your_sdk_dir>/platform-tools</code></ul> <li>On a Mac OS X, look in your home directory for <code>.bash_profile</code> and - proceed as for Linux. You can create the <code>.bash_profile</code> if + proceed as for Linux. You can create the <code>.bash_profile</code> if you haven't already set one up on your machine. </li> - <li>On Windows, right-click on My Computer, and select Properties. + <li>On Windows, right-click on My Computer, and select Properties. Under the Advanced tab, hit the Environment Variables button, and in the - dialog that comes up, double-click on Path (under System Variables). Add the full path to the - <code>tools/</code> directory to the path. </li> + dialog that comes up, double-click on Path (under System Variables). Add the full path to the + <code>tools/</code> and {@code platform-tools/} directories to the path. </li> </ul> <p>If you will be using the Eclipse IDE as your development environment, the @@ -203,11 +209,11 @@ access to powerful mapping capabilities through the <code>com.google.android.maps</code> library. You can also add additional repositories, so that you can download other SDK add-ons, where available. </li> -<li><strong>USB Driver for Windows</strong> — Contains driver files +<li><strong>USB Driver for Windows</strong> — Contains driver files that you can install on your Windows computer, so that you can run and debug your applications on an actual device. You <em>do not</em> need the USB driver unless you plan to debug your application on an actual Android-powered device. If you -develop on Mac OS X or Linux, you do not need a special driver to debug +develop on Mac OS X or Linux, you do not need a special driver to debug your application on an Android-powered device.</li> <li><strong>Samples</strong> — Contains the sample code and apps available @@ -226,15 +232,15 @@ Manager, shown in Figure 1, to browse the SDK repository, select new or updated components for download, and then install the selected components in your SDK environment. </p> -<div style="TEXT-ALIGN:left;width:600px;"> -<img src="/images/sdk_manager_packages.png" -style="padding-bottom:0;margin-bottom:0;" /> +<div style="TEXT-ALIGN:left;width:600px;"> +<img src="/images/sdk_manager_packages.png" +style="padding-bottom:0;margin-bottom:0;" /> <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 -1em;"><strong>Figure 1.</strong> The Android SDK and AVD Manager's +1em;"><strong>Figure 1.</strong> The Android SDK and AVD Manager's <strong>Available Packages</strong> panel, which shows the SDK components that are available for you to download into your environment. </p> -</div> +</div> <h3 id="which">Which components do I need?</h3> @@ -257,8 +263,8 @@ recommended or full development environment: </p> <td style="font-size:.9em;background-color:#FFE;color:gray">SDK Tools</td> <td style="font-size:.9em;background-color:#FFE;color:gray">If you've installed the SDK starter package, then you already have this component preinstalled. The -SDK Tools component is required — you can't develop or build an application -without it. </td> +SDK Tools and the SDK Platform-tools components are required — you can't develop or build an +application without these. Make sure you keep these up to date.</td> </tr> <tr> @@ -324,8 +330,8 @@ applications on different platforms by running in an Android Virtual Device to add components, see the <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a> document. </p> -<p>For revision notes and other detailed information about individual SDK -components, see the documents listed under "Downloadable SDK Components" in +<p>For revision notes and other detailed information about individual SDK +components, see the documents listed under "Downloadable SDK Components" in the navigation at left.</p> @@ -335,7 +341,7 @@ the navigation at left.</p> and add-ons that you need, open the SDK directory and take a look at what's inside.</p> -<p>The table below describes the full SDK directory contents, with components +<p>The table below describes the full SDK directory contents, with components installed. </p> <table> @@ -351,10 +357,19 @@ devices. </td> <tr> <td colspan="3"><code>docs/</code></td> <td>A full set of documentation in HTML format, including the Developer's Guide, -API Reference, and other information. To read the documentation, load the +API Reference, and other information. To read the documentation, load the file <code>offline.html</code> in a web browser.</td> </tr> <tr> +<td colspan="3"><code>platform-tools/</code></td> +<td>Contains development tools that may be updated with each platform release (from the <em>Android +SDK Platform-tools</em> component). Tools in here include {@code adb}, {@code dexdump}, and others +others that you don't typically use directly. These tools are separate from the generic development +tools in the {@code tools/} directory, because these tools may be updated in order to support new +features in the latest Android platform, whereas the other tools have no dependencies on the +platform version.</td> +</tr> +<tr> <td colspan="3"><code>platforms/</code></td> <td>Contains a set of Android platform versions that you can develop applications against, each in a separate directory. </td> @@ -362,7 +377,7 @@ applications against, each in a separate directory. </td> <tr> <td style="width:2em;border-bottom-color:white;"></td> <td colspan="2"><code><em><platform></em>/</code></td> -<td>Platform version directory, for example "android-1.6". All platform version +<td>Platform version directory, for example "android-1.6". All platform version directories contain a similar set of files and subdirectory structure.</td> </tr> @@ -376,8 +391,8 @@ directories contain a similar set of files and subdirectory structure.</td> <td style="width:2em;border-bottom-color:white;"></td> <td style="width:2em;border-bottom-color:white;"></td> <td><code>images/</code></td> -<td>Storage area for default disk images, including the Android system image, -the default userdata image, the default ramdisk image, and more. The images +<td>Storage area for default disk images, including the Android system image, +the default userdata image, the default ramdisk image, and more. The images are used in emulator sessions.</td> </tr> <tr> @@ -397,7 +412,8 @@ designed for a specific screen resolution.</td> <td style="width:2em;border-bottom-color:white;"></td> <td style="width:2em;border-bottom-color:white;"></td> <td><code>tools/</code></td> -<td>Any development tools that are specific to the platform version.</td> +<td>This directory is used only by SDK Tools r7 and below for development tools that are specific to +this platform version—it's not used by SDK Tools r8 and above.</td> </tr> <tr> <td style="width:2em;"></td> @@ -411,18 +427,21 @@ version.</td> <td>Sample code and apps that are specific to platform version.</td> </tr> <td colspan="3"><code>tools/</code></td> -<td>Contains the set of development and profiling tools available to you, such -as the emulator, the <code>android</code> tool, adb, ddms, and more.</td> +<td>Contains the set of development and profiling tools that are platform-independent, such +as the emulator, the AVD and SDK Manager, adb, ddms, hierarchyviewer and more. The tools in +this directory may be updated at any time (from the <em>Android SDK Tools</em> component), +independent of platform releases, whereas the tools in {@code platform-tools/} may be updated based +on the latest platform release.</td> </tr> <tr> <td colspan="3"><code>SDK Readme.txt</code></td> -<td>A file that explains how to perform the initial setup of your SDK, -including how to launch the Android SDK and AVD Manager tool on all +<td>A file that explains how to perform the initial setup of your SDK, +including how to launch the Android SDK and AVD Manager tool on all platforms</td> </tr> <tr> -<td colspan="3"><code>SDK Setup.exe</code></td> -<td>Windows SDK only. A shortcut that launches the Android SDK and AVD +<td colspan="3"><code>SDK Manager.exe</code></td> +<td>Windows SDK only. A shortcut that launches the Android SDK and AVD Manager tool, which you use to add components to your SDK. </td> </tr> <!--<tr> @@ -447,7 +466,7 @@ begin developing applications. Here are a few ways you can get started: </p> </li> </ul> -<p class="caution">Following the Hello World tutorial is an essential +<p class="caution">Following the Hello World tutorial is an essential first step in getting started with Android development. </p> <p><strong>Learn about Android</strong></p> @@ -481,20 +500,20 @@ Android-powered device to run and test your application.</li> <ul> <li>The <a href="{@docRoot}resources/tutorials/notepad/index.html"> - Notepad Tutorial</a> shows you how to build a full Android application - and provides helpful commentary on the Android system and API. The + Notepad Tutorial</a> shows you how to build a full Android application + and provides helpful commentary on the Android system and API. The Notepad tutorial helps you bring together the important design - and architectural concepts in a moderately complex application. + and architectural concepts in a moderately complex application. </li> </ul> -<p class="caution">Following the Notepad tutorial is an excellent +<p class="caution">Following the Notepad tutorial is an excellent second step in getting started with Android development. </p> <p><strong>Explore some code</strong></p> <ul> <li>The Android SDK includes sample code and applications for each platform -version. You can browse the samples in the <a +version. You can browse the samples in the <a href="{@docRoot}resources/index.html">Resources</a> tab or download them into your SDK using the Android SDK and AVD Manager. Once you've downloaded the samples, you'll find them in @@ -517,7 +536,7 @@ samples, you'll find them in <ul> <li>If you need help installing and configuring Java on your - development machine, you might find these resources helpful: + development machine, you might find these resources helpful: <ul> <li><a href="https://help.ubuntu.com/community/Java">https://help.ubuntu.com/community/Java </a></li> <li><a href="https://help.ubuntu.com/community/Java">https://help.ubuntu.com/community/JavaInstallation</a></li> @@ -537,7 +556,7 @@ samples, you'll find them in eclipse.org (<a href="http://www.eclipse.org/downloads/">http://www.eclipse.org/ downloads/</a>). A Java or RCP version of Eclipse is recommended.</li> - <li>Follow the steps given in previous sections to install the SDK + <li>Follow the steps given in previous sections to install the SDK and the ADT plugin. </li> </ol> </li> diff --git a/docs/knowntags.txt b/docs/knowntags.txt new file mode 100644 index 0000000..5bebabb --- /dev/null +++ b/docs/knowntags.txt @@ -0,0 +1,38 @@ +# Copyright (C) 2010 The Android Open Source Project +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# +# The grandfathered list. We should get rid of these if possible. +# +@ToBeFixed +@stable +@com.intel.drl.spec_ref +@ar.org.fitc.spec_ref + +# Something about CTS? +@cts + +# Auto-generated info about the SDK +@sdkCurrent +@sdkCurrentVersion +@sdkCurrentRelId +@sdkPlatformVersion +@sdkPlatformApiLevel +@sdkPlatformMajorMinor +@sdkPlatformReleaseDate +@sdkPlatformDeployableDate +@adtZipVersion +@adtZipDownload +@adtZipBytes +@adtZipChecksum |
