MonkeyRunner

舊版 monkeyrunner 工具提供用於編寫程式的 API，讓您透過 Android 程式碼以外的方式控制 Android 裝置或模擬器。

monkeyrunner 工具主要用於在功能/架構層級測試應用程式和裝置，以及執行單元測試套件，但您可以將其用於其他用途。使用 monkeyrunner 即可編寫 Python 程式，用來安裝 Android 應用程式或測試套件、執行套件、傳送按鍵動作、擷取使用者介面的螢幕截圖，並將螢幕截圖儲存到工作站。

注意：monkeyrunner API 未經維護。建議您改用 App Crawler 工具或 UI Automator 測試架構。

monkeyrunner 工具與 UI/Application Exerciser Monkey 無關，也稱為 monkey 工具。monkey 工具會直接在裝置或模擬器的 adb 殼層中執行，並產生一連串偽隨機的使用者事件和系統事件。相較之下，monkeyrunner 工具會透過 API 傳送特定指令和事件，從工作站控制裝置和模擬器。

monkeyrunner 工具提供下列可用於 Android 測試的功能：

• 多重裝置控制：monkeyrunner API 可以在多部裝置或模擬器中套用一或多個測試套件。您可以實際連接所有裝置或者一次啟動所有模擬器 (也可以同時採用這兩種裝置)，以程式輔助方式逐一連接至所有裝置，然後執行一或多項測試。您也可以用程式輔助方式啟動模擬器設定，執行一或多項測試，然後關閉模擬器。
• 功能測試：monkeyrunner 可對 Android 應用程式執行自動化的開始至結束測試。您可使用按鍵動作或觸控事件提供輸入值，然後透過螢幕截圖查看結果。
• 迴歸測試：monkeyrunner 可執行應用程式，並將輸出內容的螢幕截圖與一組已知正確的螢幕截圖進行比較，測試應用程式的穩定性。
• 可擴充的自動化作業：由於 monkeyrunner 是 API 工具包，因此您可以開發一套控制 Android 裝置的系統，其中包含以 Python 為基礎的模組和程式。除了使用 monkeyrunner API，您也可以使用標準 Python os 和 subprocess 模組呼叫 Android 工具，例如 Android Debug Bridge。

  此外，您也可以在 monkeyrunner API 中自行加入類別。如需進一步的詳細說明，請參閱「使用外掛程式擴充 monkeyrunner」一節。

monkeyrunner 工具採用 Jython，這是使用 Java 程式設計語言的 Python 實作方式。Jython 可讓 monkeyrunner API 與 Android 架構輕鬆互動。您可透過 Jython 使用 Python 語法來存取 API 的常數、類別和方法。

簡易的 monkeyrunner 程式

下列是連線至某部裝置的簡易 monkeyrunner 程式，會建立 MonkeyDevice 物件。程式會使用 MonkeyDevice 物件安裝 Android 應用程式套件，執行其中一項活動，並將重要事件傳送至活動。程式接著會擷取結果的螢幕截圖，並建立 MonkeyImage 物件。程式會透過這個物件寫出包含螢幕截圖的 PNG 檔案。

# 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
# whether the installation worked.
device.installPackage('myproject/bin/MyApplication.apk')

# Sets a variable with the package's internal name.
package = 'com.example.android.myapplication'

# Sets a variable with the name of an Activity in the package.
activity = 'com.example.android.myapplication.MainActivity'

# Sets the name of the component to start.
runComponent = package + '/' + activity

# Runs the component.
device.startActivity(component=runComponent)

# Presses the Menu button.
device.press('KEYCODE_MENU', MonkeyDevice.DOWN_AND_UP)

# Takes a screenshot.
result = device.takeSnapshot()

# Writes the screenshot to a file.
result.writeToFile('myproject/shot1.png','png')

monkeyrunner API

monkeyrunner API 包含在 com.android.monkeyrunner 套件的三個模組中：

• MonkeyRunner：適用於 monkeyrunner 程式的公用程式方法所屬類別。這個類別提供將 monkeyrunner 連線至裝置或模擬器的方法，同時提供為 monkeyrunner 程式建立使用者介面以及顯示內建說明的方法。
• MonkeyDevice：代表裝置或模擬器。這個類別提供各種方法，用於安裝及解除安裝套件、啟動 Activity，以及將鍵盤或觸控事件傳送到應用程式。您也可以使用這個類別執行測試套件。
• MonkeyImage：代表螢幕畫面擷取圖片。這個類別提供各種方法，用於擷取螢幕畫面、將點陣圖圖片轉換為不同格式、比較兩個 MonkeyImage 物件，以及將圖片寫入檔案。

在 Python 程式中，您能夠以 Python 模組的形式存取每個類別。monkeyrunner 工具不會自動匯入這些模組。如要匯入模組，請使用 Python from 陳述式：

from com.android.monkeyrunner import <module>

其中 <module> 是要匯入的類別名稱。您可以在同一個 from 陳述式中匯入多個模組，只需以半形逗號分隔模組名稱即可。

執行 monkeyrunner

如要執行 monkeyrunner 程式，可以透過檔案或是在互動工作階段中輸入 monkeyrunner 陳述式。這兩種做法都必須叫用 monkeyrunner 指令，這個指令位於 SDK 目錄的 tools/ 子目錄中。如果提供檔案名稱做為引數，monkeyrunner 指令會以 Python 程式形式執行檔案內容；否則，指令會啟動互動工作階段。

以下是 monkeyrunner 指令的語法：

monkeyrunner -plugin <plugin_jar> <program_filename> <program_options>

表 1 說明 monkeyrunner 旗標和引數。

表 1. monkeyrunner 旗標和引數

monkeyrunner 內建說明

您可執行以下指令為 monkeyrunner 產生 API 參考資料：

monkeyrunner help.py <format> <outfile>

引數如下：

• <format> 是純文字輸出的 text，或用於 HTML 輸出的 html。
• <outfile> 是輸出檔案的完整路徑名稱。

使用外掛程式擴充 monkeyrunner

使用以 Java 編寫的類別，並建構為一或多個 JAR 檔案，即可擴充 monkeyrunner API。您可以透過這項功能，使用自己的類別擴充 monkeyrunner API，或是擴充現有類別。此外，這項功能也可以用來初始化 monkeyrunner 環境。

如要提供 monkeyrunner 外掛程式，請依表 1 所述，使用 -plugin <plugin_jar> 引數叫用 monkeyrunner 指令。

在外掛程式程式碼中，您可在 com.android.monkeyrunner 匯入及擴充主要的 monkeyrunner 類別 MonkeyDevice、MonkeyImage 和 MonkeyRunner (詳情請參閱「monkeyrunner API」一節)。

請注意，您無法透過外掛程式存取 Android SDK。您無法匯入 com.android.app 等套件。這是因為 monkeyrunner 會與架構 API 層級下方的裝置或模擬器互動。

外掛程式啟動類別

外掛程式的 JAR 檔案可以指定在指令碼處理開始前例項化的類別。如要指定這個類別，請將 MonkeyRunnerStartupRunner 這個鍵新增至 JAR 檔案的資訊清單，並使用啟動時要執行的類別名稱做為值。下列程式碼片段說明如何透過 ant 建構指令碼指定這個類別：

<jar jarfile="myplugin" basedir="${build.dir}">
<manifest>
<attribute name="MonkeyRunnerStartupRunner" value="com.myapp.myplugin"/>
</manifest>
</jar>

如要存取 monkeyrunner 工具的執行階段環境，啟動類別可實作 com.google.common.base.Predicate<PythonInterpreter>。例如，以下類別會在預設命名空間中設定幾個變數：

package com.android.example

import com.google.common.base.Predicate
import org.python.util.PythonInterpreter

class Main: Predicate<PythonInterpreter> {

    override fun apply(anInterpreter: PythonInterpreter): Boolean {
        /*
         * 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
    }
}

package com.android.example;

import com.google.common.base.Predicate;
import org.python.util.PythonInterpreter;

public class Main implements Predicate<PythonInterpreter> {
    @Override
    public boolean apply(PythonInterpreter anInterpreter) {

        /*
        * Examples of creating and initializing variables in the monkeyrunner environment's
        * namespace. During execution, the monkeyrunner program can refer to the variables "newtest"
        * and "use_emulator"
        *
        */
        anInterpreter.set("newtest", "enabled");
        anInterpreter.set("use_emulator", 1);

        return true;
    }
}