summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJoe Malin <jmalin@google.com>2010-10-18 17:07:45 -0700
committerJoe Malin <jmalin@google.com>2010-11-01 13:11:28 -0700
commit9a7eab8d0a98203941f64e705ba74ba9e3eb17f3 (patch)
treea59c8708ca7a64cb7109d83ece7b42dcfea58a3c
parent4f405ecee998e704023fcd6b1f67aae4f0b5979c (diff)
downloadframeworks_base-9a7eab8d0a98203941f64e705ba74ba9e3eb17f3.zip
frameworks_base-9a7eab8d0a98203941f64e705ba74ba9e3eb17f3.tar.gz
frameworks_base-9a7eab8d0a98203941f64e705ba74ba9e3eb17f3.tar.bz2
Doc Change: Documentation for MonkeyRunner tool
Change-Id: I6bf21fe1e406b771c9fe8c36be4ad60b522d088d
Diffstat
-rw-r--r--docs/html/guide/developing/tools/MonkeyDevice.jd1353
-rw-r--r--docs/html/guide/developing/tools/MonkeyImage.jd435
-rw-r--r--docs/html/guide/developing/tools/MonkeyRunner.jd445
-rw-r--r--docs/html/guide/developing/tools/index.jd70
-rw-r--r--docs/html/guide/developing/tools/monkeyrunner_concepts.jd308
-rw-r--r--docs/html/guide/guide_toc.cs62
-rw-r--r--docs/html/guide/topics/testing/index.jd14
-rwxr-xr-xdocs/html/guide/topics/testing/testing_android.jd44
8 files changed, 2668 insertions, 63 deletions
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 &lt;key&gt;. 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..0e10377 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,53 +37,53 @@ 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-
@@ -92,9 +92,9 @@ efficiency.
<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 &lt;module&gt;
+</pre>
+<p>
+ where <code>&lt;module&gt;</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 &lt;plugin_jar&gt; &lt;program_filename&gt; &lt;program_options&gt;
+</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 &lt;plugin_jar&gt;</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>&lt;program_filename&gt;</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>&lt;program_options&gt;</code>
+ </td>
+ <td>
+ (Optional) Flags and arguments for the program in &lt;program_file&gt;.
+ </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 &lt;format&gt; help.py &lt;outfile&gt;
+</pre>
+<p>
+The arguments are:
+</p>
+ <ul>
+ <li>
+ <code>&lt;format&gt;</code> is either <code>text</code> for plain text output
+ or <code>html</code> for HTML output.
+ </li>
+ <li>
+ <code>&lt;outfile&gt;</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 &lt;plugin_jar&gt;</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>
+&lt;jar jarfile=&quot;myplugin&quot; basedir="&#36;&#123;build.dir&#125;&quot;&gt;
+&lt;manifest&gt;
+&lt;attribute name=&quot;MonkeyRunnerStartupRunner&quot; value=&quot;com.myapp.myplugin&quot;/&gt;
+&lt;/manifest&gt;
+&lt;/jar&gt;
+
+
+</pre>
+<p>
+ To get access to monkeyrunner's runtime environment, the startup class can implement
+ <code>com.google.common.base.Predicate&lt;PythonInterpreter&gt;</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&lt;PythonInterpreter&gt; {
+ &#64;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 2b80342..a43e334 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -254,34 +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/admin/device-admin.html">
+ <span class="en">Device Administration</span>
+ </a> <span class="new">new!</span>
+ </li>
<li class="toggle-list">
<div>
- <a href="<?cs var:toroot ?>guide/topics/testing/index.html">
+ <a href="<?cs var:toroot?>guide/topics/testing/index.html">
<span class="en">Testing</span>
- </a> <span class="new">new!</span>
+ </a>
</div>
<ul>
- <li><a href="<?cs var:toroot?>guide/topics/testing/testing_android.html">
+ <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">
+ <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">
+ <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">
+ <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">
+ <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>
- <li><a href="<?cs var:toroot?>guide/topics/admin/device-admin.html">
- <span class="en">Device Administration</span>
- </a> <span class="new">new!</span>
- </li>
</ul>
</li>
@@ -336,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>
@@ -363,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>
diff --git a/docs/html/guide/topics/testing/index.jd b/docs/html/guide/topics/testing/index.jd
index b75656f..762a897 100644
--- a/docs/html/guide/topics/testing/index.jd
+++ b/docs/html/guide/topics/testing/index.jd
@@ -59,6 +59,20 @@ page.title=Testing
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>
diff --git a/docs/html/guide/topics/testing/testing_android.jd b/docs/html/guide/topics/testing/testing_android.jd
index 2a4c949..d4b0dcc 100755
--- a/docs/html/guide/topics/testing/testing_android.jd
+++ b/docs/html/guide/topics/testing/testing_android.jd
@@ -38,7 +38,7 @@ page.title=Testing Fundamentals
<a href="#TestResults">Seeing Test Results</a>
</li>
<li>
- <a href="#Monkeys">Monkey and MonkeyRunner</a>
+ <a href="#Monkeys">monkey and monkeyrunner</a>
</li>
<li>
<a href="#PackageNames">Working With Package Names</a>
@@ -77,6 +77,13 @@ page.title=Testing Fundamentals
<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>
@@ -112,10 +119,10 @@ page.title=Testing Fundamentals
</li>
<li>
The SDK also provides
- <a href="{@docRoot}guide/topics/testing/monkeyrunner.html">MonkeyRunner</a>, an API for
- testing devices with Jython scripts, and <a
- href="{@docRoot}guide/developing/tools/monkey.html">Monkey</a>, a command-line tool for
- stress-testing UIs by sending pseudo-random events to a device.
+ <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>
@@ -540,25 +547,28 @@ page.title=Testing Fundamentals
<a href="{@docRoot}guide/developing/testing/testing_otheride.html#RunTestsCommand">
Testing in Other IDEs</a>.
</p>
-<h2 id="Monkeys">Monkey and MonkeyRunner</h2>
+<h2 id="Monkeys">monkey and monkeyrunner</h2>
<p>
The SDK provides two tools for functional-level application testing:
</p>
<ul>
<li>
- <a href="{@docRoot}guide/developing/tools/monkey.html">Monkey</a> 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.
+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>
- <a href="{@docRoot}guide/topics/testing/monkeyrunner.html">MonkeyRunner</a> is a
- Jython API that you use in 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
- with Python, you can write a wide range of large, powerful, and complex tests.
+ 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>
generated by cgit v1.1 at 2025-02-09 11:41:23 +0000