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 ossubprocess 模組呼叫 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 旗標和引數

引數 說明
-plugin <plugin_jar> (選用) 指定 JAR 檔案,其中包含適用於 monkeyrunner 的外掛程式。如要進一步瞭解 monkeyrunner 外掛程式,請參閱「使用外掛程式擴充 monkeyrunner」一節。如要指定多個檔案,請多次加入引數。
<program_filename> 如果提供這個引數,monkeyrunner 指令會以 Python 程式形式執行檔案內容。否則,指令會啟動互動工作階段。
<program_options> (選用) <program_file>. 中程式的旗標和引數

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 類別 MonkeyDeviceMonkeyImageMonkeyRunner (詳情請參閱「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>。例如,以下類別會在預設命名空間中設定幾個變數:

Kotlin

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
    }
}

Java

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;
    }
}