MonkeyDevice

MonkeyRunner 類別代表執行 monkeyrunner 的工作站可存取的裝置或模擬器。

這個類別可用來控制 Android 裝置或模擬器。方法會傳送 UI 事件、擷取資訊、安裝及移除應用程式,以及執行應用程式。

你通常不需要建立 MonkeyDevice 的執行個體。而是使用 MonkeyRunner.waitForConnection(),進而從連線的裝置或模擬器建立新物件。下列個體一般不會用到:

newdevice = MonkeyDevice()

而是改用:

newdevice = MonkeyRunner.waitForConnection()

摘要

常數
string DOWN 使用這個字串搭配 press()touch() type 引數,以傳送 DOWN 事件。
string UP 使用這個字串搭配 press()touch() type 引數,以傳送 UP 事件。
string DOWN_AND_UP 使用這個字串搭配 press()touch() type 引數,在 UP 事件後立即傳送 DOWN 事件。
方法
void broadcastIntent(string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, iterable flags)
本語法將以應用程式的角色,向這部裝置廣播「意圖」。
void drag(tuple start, tuple end, float duration, integer steps)
本語法將在裝置的螢幕上,模擬輕觸、按住及滑動的手勢。
object getProperty(string key)
根據系統環境變數名稱回傳該裝置的值。在本方法的詳細說明中,已列出可用的變數名稱。
object getSystemProperty(string key)
相當於 adb shell getprop <key>. This is provided for use by platform developers. 的 API
void installPackage(string path)
本語法將在這部裝置上安裝 packageFile 中的 Android 應用程式或測試套件。先前安裝的應用程式或測試套件將被取代。
dictionary instrument(string className、dictionary args)
利用 Android 檢測工具執行特定元件,其回傳的結果與執行元件會是相同的字典資料結構。執行裝置必須先安裝好該元件。
void press(string name,dictionary type)
本語法會將把類型指定的 key event 傳送至按鍵碼指定的 key。
void (string into)
本語法將用 bootload 類型指定的系統啟動載入程式,重新啟動此裝置。
void removePackage(string package)
將這部裝置中指定的套件與其資料和快取一併刪除。
object shell(string cmd)
本裝置將執行 adb 殼層指令,並回傳結果 (如果有的話)。
void startActivity(string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, flags)
本語法會將透過既有引數建構的「意圖」,在這部裝置上啟用活動。
MonkeyImage takeSnapshot()
本語法將擷取裝置整個螢幕緩衝區,並得到包含當前螢幕畫面的 MonkeyImage 物件。
void touch(integer x, integer y, integer type)
本語法會將類型指定的觸控事件傳送至 x 和 y 在螢幕上的位置。
void type(string message)
使用本語法會將把訊息中的字元以鍵盤輸入的方式傳送至這部裝置。相當於使用 key event 類型的 DOWN_AND_UP 呼叫 message 每個按鍵碼的 press()
void wake()
本語法將喚醒這部裝置的螢幕。

常數

string DOWN

press()touch() 的值。本語法在傳送 DOWN 事件類型至裝置時,可指明按下按鍵或輕觸螢幕。

string UP

press()touch() 的值。本語法在傳送 UP 事件類型至裝置時,指明要發布的 key,或將畫面往上滑。

string DOWN_AND_UP

press()touch()type() 值。在傳送 DOWN 事件類型之後,緊接著傳送 UP 事件類型至裝置。本語法將指明要按下的按鍵,或是按一下螢幕。

公用方法

void broadcastIntent(string uri, string action, string data, string mimetype, iterable categories, dictionary extras, component component, iterable flags)

本語法將以應用程式的角色,向這部裝置廣播「意圖」。如要瞭解更多引數,請參閱 Intent

引數
uri 「意圖」的 URI。請參閱 Intent.setData()
action 請參閱 Intent.setAction() 以瞭解本「意圖」的動作。
data 請參閱 Intent.setData() 以瞭解本「意圖」的 URI 資料。
MIME 類型 如需瞭解「意圖」的 MIME 類型,請參閱 Intent.setType()
categories 可疊代資料結構包含了定義本「意圖」類別的字串 (請參閱 Intent.addCategory())。
extras 本「意圖」額外的字典結構資料 (如需範例,請參閱 Intent.putExtra())。

每個字典項目的鍵值應為字串。項目的鍵值可以是任何簡易資料或任何一種結構化資料。

component 請參閱 ComponentName 瞭解本「意圖」的元件。如果使用這個引數,系統會將「意圖」導向特定 Android 套件中的特定類別。
flag 迭代資料架構,包含「意圖」處理方式的控制標記 (請參閱 Intent.setFlags())。

void drag(tuple start, tuple end, float duration, integer steps)

本語法將在裝置的螢幕上模擬輕觸、按住及滑動的手勢。

引數
start 拖曳手勢的起點,設定語法為 tuple (x,y),其中 x 和 y 需為整數
end 拖曳手勢的結束點,設定語法為 tuple (x,y),其中 x 和 y 需為整數
duration 設定拖曳手勢的持續時間 (單位為秒)。預設是 1.0 秒。
steps 從起點到終點需要的步數。預設值為 10 步。

object getProperty(string key)

根據系統環境變數名稱回傳該裝置的值。

引數
key 系統環境變數的名稱。可用變數名稱皆列於表 1 屬性變數名稱可見於本主題結尾處。
回傳
  • 變數的值。資料格式會因要求的變數而有所變化。

object getSystemProperty(string key)

getProperty() 語法相同。

引數
key 系統環境變數的名稱。可用變數名稱皆列於表 1 屬性變數名稱
回傳
  • 變數的值。資料格式會因要求的變數而有所變化。

void installPackage(string path)

本語法將在這部裝置上,安裝 packageFile 中的 Android 應用程式或測試套件。先前安裝的應用程式或測試套件將被取代。

引數
path 即將安裝的 .apk 檔案完整路徑和檔案名稱。

dictionary instrument(string className, dictionary args)

利用 Android 檢測工具執行特定元件,其回傳的結果與執行元件會是相同的字典資料結構。執行裝置必須先安裝好該元件。

您可以使用這個方法執行測試案例,其類別屬於 Android 測試案例類別之一。如要瞭解如何透過 Android 測試架構進行單元測試,請參閱「測試基礎知識」一文。

引數
className 已安裝在本裝置的 Android 元件名稱 (如標準格式套件/類別) 套件名稱與本裝置 .apk 檔案的 Android 套件名相同,且類別名稱為該檔案中 Android 元件的類別名稱 (Activity、ContentProvider、Service 或 BroadcastReceiver)。套件和類別的名稱都必須完全符合相關規定。如需詳情,請參閱 ComponentName
args 字典,內容包含標記和值。開始測試時,字典的值會傳送至元件。如果標記未設定任何值,請將其字典值設為空白字串。
回傳
  • 字典,內容包含元件輸出的內容。而字典內容由元件本身決定。

    在元件名稱引數中,如使用 InstrumentationTestRunner 作為類別名稱,那麼字典會包含單一鍵「stream」。而「stream」的值,會包含測試輸出內容的 string,形同從指令列執行 InstrumentationTestRunner 一樣。如需此輸出內容的格式說明,請參閱「使用其他 IDE 中的測試」一節。

void press(string name, integer type)

type 指定的 key event 將傳送至 keycode 指定的 key。

引數
name 即將傳送的按鍵碼名稱。如需按鍵碼名單,請參閱 KeyEvent。使用按鍵碼名稱,而非其代表的整數值。
type 即將傳送的 key event 類型。可以使用的值為 DOWNUPDOWN_AND_UP

void reboot(string bootloadType)

使用 bootloadType 指定的系統啟動載入程式,重新啟動這部裝置。

引數
into 用於重新啟動的系統啟動載入程式類型。可以使用的值有「bootboot」、「recovery」或「None」。

void removePackage(string package)

將這部裝置中指定的套件與其資料和快取一併刪除。

引數
package 這部裝置上 .apk 檔案的 Android 套件名稱。

object shell(string) cmd)

本裝置將執行 adb 殼層指令,並回傳結果 (如果有的話)。

引數
cmd 將在 adb 殼層中執行的指令。Android Debug Bridge 主題會說明這些指令的形式。
回傳
  • 指令執行的結果 (如果有的話)。回傳結果的格式會由指令決定。

void startActivity(string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, iterable flags)

如需在這部裝置上啟用活動,請傳送以既有引數建構的「意圖」。

引數
uri 如需瞭解「意圖」的 URI。請參閱 Intent.setData()
action 如需瞭解「意圖」的動作,請參閱 Intent.setAction()
data 如需瞭解「意圖」的資料 URI,請參閱 Intent.setData()
MIME 類型 如需瞭解「意圖」的 MIME 類型,請參閱 Intent.setType()
categories 一種可疊代資料結構,其中包含定義「意圖」類別的字串 (請參閱 Intent.addCategory())。
extras 「意圖」的額外資料字典,如需範例,請參閱 Intent.putExtra()

每個字典項目的鍵值應為字串。項目的鍵值可以是任何簡易資料或任何一種結構化資料。

component 「意圖」的元件 (請參閱 ComponentName)。這個引數會將「意圖」導向特定 Android 套件中的特定類別。
flag 迭代資料架構,包含「意圖」處理方式的控制標記 (請參閱 Intent.setFlags())。

MonkeyImage takeSnapshot()

本語法會將擷取裝置整個螢幕緩衝區,並得到包含當前螢幕畫面的物件。

回傳

void touch(integer x, integer y, string type)

本語法會將類型指定的觸控事件傳送至 x 和 y 在螢幕上的位置。

引數
x 觸控在實際裝置像素的水平位置,以裝置螢幕當前方向為準,從螢幕左側開始計算定位。
y 觸控在實際裝置像素的垂直位置,以裝置螢幕當前方向為準,從螢幕頂端開始計算定位。
type 即將傳送的 key event 類型。可以使用的值為 DOWNUPDOWN_AND_UP

void type(string message)

使用本語法會將把訊息中的字元以鍵盤輸入的方式傳送至這部裝置。相當於使用 key event 類型 DOWN_AND_UP 呼叫 message 每個按鍵碼的 press()

引數
message 字串,包含即將傳送的字元。

void wake()

本語法將喚醒這部裝置的螢幕畫面。


附錄

表 1 使用 getProperty()getSystemProperty() 的屬性變數名稱。

屬性群組 屬性 說明 附註
build board 裝置主機系統的代碼名稱 查看 Build
brand 自訂作業系統的電信業者或供應商。
device 裝置設計名稱。
fingerprint 當前執行版本的 ID。
host
ID 變更清單的編號或標籤。
model 使用者看得到的裝置名稱。
product 產品完整名稱。
tags 用於說明版本的標記,以逗號作為分隔,例如「未簽署」和「偵錯」。
type 用於說明版本類型,例如「user」或「eng」。
user
CPU_ABI 原生程式碼指示集的名稱,格式兼用 CPU 類型以及 ABI 慣例。
manufacturer 產品/硬體製造商。
version.incremental 版本控制系統所使用的內部程式碼,用來指明軟體的版本。
version.release 使用者看到的軟體版本名稱。
version.sdk 使用者看到的 SDK 版本,與該作業系統版本相關。
version.codename 目前的開發代碼名稱,如已推出此版本的軟體,則為「REL」。
display width 裝置的螢幕寬度 (單位為像素)。 詳情請參閱 DisplayMetrics
height 裝置的螢幕高度 (單位為像素)。
density 螢幕的邏輯密度。這項因素將影響如何調整 DIP (密度獨立像素),以符合裝置螢幕的解析度。調整後,1 DIP 等同於 160 像素/英寸螢幕中的 1 個像素。例如,在 160 dpi 的螢幕上,密度 = 1.0,而 120 dpi 的螢幕,其密度 = 0.75。

此數值不會完全符合實際螢幕大小,但會隨著螢幕 DPI 的大幅變動進行調整。詳情請參閱 density

am.current package 當前執行套件的 Android 套件名稱。 am.current 鍵會傳回目前執行「活動」的資訊。
action 當前活動的動作。與套件資訊清單中 action 元素的 name 屬性有相同格式。
comp.class 目前啟用「活動」的元件類別名稱。詳情請參閱 comp.package
comp.package 目前啟用「活動」的元件套件名稱。元件將由套件名稱與其包含的類別名稱來指定。
data 啟用當前「活動」之「意圖」所含的資料 (如果有的話)。
categories 啟用當前「活動」之「意圖」所指定的類別。
clock realtime 重新啟動裝置後經過的毫秒數,包括休眠時間。 詳情請參閱 SystemClock
uptime 重新啟動裝置後經過的毫秒數,包括休眠時間
millis 當前時間,以 UNIX Epoch 紀元時間為始 (單位為毫秒)。