Doc Change: Documentation for MonkeyRunner tool

Change-Id: I6bf21fe1e406b771c9fe8c36be4ad60b522d088d

1 files changed, 308 insertions, 0 deletions

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>