Appium 客戶端類庫

Appium 支持如下語言的客戶端類庫：

語言

Ruby

Python

Java

JavaScript

PHP

C#

Objective-C

鎖定注意，一些方法相似 endTestCoverage() 目前並不能徹底支持。當這個問題被解決後，覆蓋率支持纔會被添加。若是你仍然想使用這些方法，請參考 GitHub 上關於 bindings 的文檔。

鎖定屏幕。

# ruby lock 5

# python driver.lock(5)

// java driver.lockScreen(3);

// javascript driver.lock(3)

// php $this->lock(3);

// c# driver.LockDevice(3);

// objective c [driver lockDeviceScreen:3];

將應用切換至後臺

將當前的應用切換到後臺，而後可讓其在指定時間內回到前臺，或者讓它一直留在後臺。

傳遞給這個方法的參數有兩種類型：

1. 一個整型（秒）：表示後臺狀態維持多久。-1 表示持續置於後臺。這種風格的參數已經被廢棄。
2. 一個看起來像 {"timeout": secs} 的對象。裏面的 secs 是含義和第一個類型同樣的整型數字（即表示置於後臺多少秒），或者爲 null （表示持續置於後臺）。

# ruby background_app 5 # 置於後臺，持續5秒 background_app -1 # 持續置於後臺

# python driver.background_app(5) # 置於後臺，持續5秒 driver.background_app(-1) # 持續置於後臺 driver.background_app({'timeout': None}) # 持續置於後臺

// java driver.runAppInBackground(5); // 置於後臺，持續5秒 driver.runAppInBackground(-1); // 持續置於後臺

// javascript driver.backgroundApp(5); // 置於後臺，持續5秒 driver.backgroundApp(-1); // 持續置於後臺 driver.backgroundApp({timeout: null}); // 持續置於後臺

// php $this->backgroundApp(5); $this->backgroundApp(-1);

// c# driver.BackgroundApp(5); driver.BackgroundApp(-1);

// objective c [driver runAppInBackground:3]; [driver runAppInBackground:-1];

收起鍵盤

收起鍵盤。 注意: 在 iOS，這輔助功能並不能保證必定有效。由於沒有用於隱藏鍵盤的自動化鉤子方法（譯者注：能夠理解爲 iOS 沒有提供隱藏鍵盤的 API），並且應用是容許用戶去使用各類策略去收起鍵盤的，不管是點擊鍵盤之外的區域，仍是向下滑動諸如此類...相比於使用該方法，咱們更加鼓勵你去思考 用戶 在應用中是如何收起鍵盤（如滑動，點擊一個固定的座標，等等...），並讓 Appium 去執行這些方法，而不是調用這個 API 。話雖如此，但這裏默認的行爲仍是可能幫助到你的。

# ruby hide_keyboard

# python driver.hide_keyboard()

// java driver.hideKeyboard();

// javascript driver.hideKeyboard()

// php $this->hideKeyboard(); $this->hideKeyboard(array('strategy' => 'pressKey', 'key' => 'Done'));

// c# driver.HideKeyboard("Done");

// objective c [driver hideKeyboard];

啓動 Activity

在當前 app 打開一個 activity，或者新打開一個應用並啓動一個 acticity， 僅支持 Android。

// java driver.startActivity("appPackage","com.example.android.apis", null, null);

// javascript driver.startActivity({appPackage: 'com.example.android.apis', appActivity: '.Foo'}, cb);

# python driver.start_activity('com.example.android.apis', '.Foo')

# ruby start_activity app_package: 'io.appium.android.apis', app_activity: '.accessibility.AccessibilityNodeProviderActivity'

// c# driver.StartActivity("com.example.android.apis", ".Foo");

// php $this->startActivity(array("appPackage" => "com.example.android.apis",  "appActivity" => ".Foo"));

// objective c [driver startActivity:@"com.example.android.apis" package:@".Foo"];

打開通知欄

打開通知欄，僅支持 Android。

// java driver.openNotifications();

// javascript driver.openNotifications(cb);

# python driver.open_notifications()

# ruby open_notifications

// c# driver.OpenNotifications();

// php $this->openNotifications();

// objective c [driver openNotifications];

應用是否已安裝

檢測應用是否已被安裝。

# ruby is_installed? "com.example.android.apis"

# python driver.is_app_installed('com.example.android.apis')

// java driver.isAppInstalled("com.example.android.apis")

// javascript driver.isAppInstalled("com.example.android.apis") .then(function (isAppInstalled) { /*...*/ })

// php $this->isAppInstalled('com.example.android.apis');

// c# driver.IsAppInstalled("com.example.android.apis-");

// objective c [driver isAppInstalled:@"com.example.android.apis-"];

安裝應用

在設備上安裝應用。

# ruby install 'path/to/my.apk'

# python driver.install_app('path/to/my.apk')

// java driver.installApp("path/to/my.apk")

// javascript driver.installApp("path/to/my.apk")

// php $this->installApp('path/to/my.apk');

// c# driver.InstallApp("path/to/my.apk");

// objective c [driver installAppAtPath:@"path/to/my.apk"];

卸載應用

卸載設備上的應用。

# ruby remove 'com.example.android.apis'

# python driver.remove_app('com.example.android.apis')

// java driver.removeApp("com.example.android.apis")

// javascript driver.removeApp("com.example.android.apis")

// php $this->removeApp('com.example.android.apis');

// c# driver.RemoveApp("com.example.android.apis");

// objective c [driver removeApp:@"com.example.android.apis"];

搖一搖

模擬搖晃設備的操做。

# ruby shake

# python driver.shake()

// java driver.shake()

// javascript driver.shake()

// php $this->shake();

// c# driver.ShakeDevice();

// objective c [driver shakeDevice];

關閉應用

關閉應用。

# ruby close_app

# python driver.close_app();

// java driver.closeApp()

// javascript driver.closeApp()

// php $this->closeApp();

// c# driver.CloseApp();

// objective c [driver closeApp];

啓動（Launch）

爲 desired capabilities 啓動一個 session。請注意只有設置了 autoLaunch=false 關鍵字時纔會生效。這不是爲了隨意啓動一個應用或 activities ——若是你想這麼作，請使用 start_activity 這個 desired capability 的參數。這個方法的使用場景是在你設置了 autoLaunch=false 後，用來繼續執行初始化（"launch"）流程的。（譯者注：舉個例子，國產系統常常會在應用安裝時彈出提示窗阻礙安裝，此時能夠經過 autoLaunch=false 來讓應用安裝後先執行你的腳原本關掉彈窗，而後再用這個函數來繼續啓動應用。）

# ruby launch_app

# python driver.launch_app()

// java driver.launchApp()

// javascript driver.launchApp()

// php $this->launchApp();

// c# driver.LaunchApp();

// objective c [driver launchApp];

重置

重置應用。（譯者注：相似於清除緩存）

# ruby driver.reset

# python driver.reset()

// java driver.resetApp()

// javascript driver.resetApp()

// php $this->reset();

// c# driver.ResetApp();

// objective c [driver resetApp];

可用的上下文（Contexts）

列出全部可用的上下文（contexts）。

# ruby context_array = available_contexts

# python driver.contexts

// java driver.getContextHandles()

// javascript driver.contexts().then(function (contexts) { /*...*/ })

// php $this->contexts();

// c# driver.GetContexts()

// objective c NSArray *contexts = driver.allContexts;

當前上下文（context）

列出當前的上下文（context）。

# ruby context = current_context

# python driver.current_context

// java driver.getContext()

// javascript driver.currentContext().then(function (context) { /*...*/ })

// php $this->context();

// c# driver.GetContext()

// objective c NSString *context = driver.context;

切換至默認的上下文（context）

切換回默認的上下文（context）。（譯者注：通常就是原生上下文 「NATIVE_APP」）

# ruby switch_to_default_context

# python driver.switch_to.context(None)

// java driver.context();

// javascript driver.context()

// php $this->context(NULL);

// c# driver.SetContext();

// objective c [driver setContext:nil];

應用的字符串

得到應用的字符串。（譯者注：這裏實際指的是返回應用的多語言文本，即每一個 string 變量及在指定語言上的顯示內容。例如 {"action_forgot_password":"Forgot your password?"} 。在 android 上對應的是項目中的 strings.xml 多語言配置文件）

# ruby app_strings

# python driver.app_strings

// java driver.getAppStrings();

// javascript driver.getAppStrings().then(function (appStrings) { /*...*/ })

// php $this->appStrings(); $this->appStrings('ru');

// c# driver.GetAppStrings();

// objective c [driver appStrings]; [driver appStringsForLanguage:"@ru"];

按鍵事件

給設備發送按鍵事件。

# ruby key_event 176

# python driver.keyevent(176)

// java driver.sendKeyEvent(AndroidKeyCode.HOME);

// javascript driver.deviceKeyEvent(wd.SPECIAL_KEYS.Home)

// php $this->keyEvent('176');

// c# driver.KeyEvent("176");

// objective c NSError *err; [driver triggerKeyEvent:176 metastate:0 error:&err];

當前 Activity

獲取當前的 Acticity。僅支持 Android。

# ruby current_activity

# python driver.current_activity

// java driver.currentActivity();

// javascript driver.getCurrentActivity().then(function (activity) { /*...*/ })

// php $this->currentActivity();

// c# driver.GetCurrentActivity();

// objective c NSError *err; [driver currentActivity];

當前包名（package）

獲取當前包名（package）。僅支持 Android 。

# ruby current_package

# python driver.current_package

// java driver.getCurrentPackage();

// javascript driver.getCurrentPackage().then(function (package) { /*...*/ })

// php $this->currentPackage();

// c# driver.GetCurrentPackage();

點擊操做 / 多點觸控操做

用於生成點擊操做的 API。這部分文檔的內容將會很快被補充進來。

# ruby touch_action = Appium::TouchAction.new element = find_element :accessibility_id, 'Buttons, Various uses of UIButton' touch_action.press(element: element, x: 10, y: 10).perform

# python action = TouchAction(driver) action.press(element=el, x=10, y=10).release().perform()

// java TouchAction action = new TouchAction(driver) .press(mapview, 10, 10) .release(). perform();

// javascript var action = new wd.TouchAction(driver); action .tap({el: el, x: 10, y: 10}) .release(); return action.perform(); // returns a promise

// php $action = $this->initiateTouchAction();  ->press(array('element' => $el))  ->release()  ->perform();  $action1 = $this->initiateTouchAction(); $action1->press(array('element' => $els[0]))  ->moveTo(array('x' => 10, 'y' => 0))  ->moveTo(array('x' => 10, 'y' => -75))  ->moveTo(array('x' => 10, 'y' => -600))  ->release();  $action2 = $this->initiateTouchAction(); $action2->press(array('element' => $els[1]))  ->moveTo(array('x' => 10, 'y' => 10))  ->moveTo(array('x' => 10, 'y' => -300))  ->moveTo(array('x' => 10, 'y' => -600))  ->release();  $multiAction = $this->initiateMultiAction(); $multiAction->add($action1); $multiAction->add($action2); $multiAction->perform();

// c# ITouchAction action = new TouchAction(driver); action.Press(el, 10, 10).Release(); action.Perform ();

滑動屏幕

模擬用戶滑動屏幕的操做。

# ruby swipe start_x: 75, start_y: 500, end_x: 75, end_y: 0, duration: 0.8

# python driver.swipe(start_x=75, start_y=500, end_x=75, end_y=0, duration=800)

// java driver.swipe(75, 500, 75, 0, 0.8)

// javascript function swipe(opts) { var action = new wd.TouchAction(this); action .press({x: opts.startX, y: opts.startY}) .wait(opts.duration) .moveTo({x: opts.endX, y: opts.endY}) .release(); return action.perform(); } wd.addPromiseChainMethod('swipe', swipe); // ... return driver.swipe({ startX: 75, startY: 500, endX: 75, endY: 0, duration: 800 });

// php $this->swipe(75, 500, 75, 0, 800);

// c# todo: c#

捏（Pinch）手勢

在屏幕上使用捏（Pinch）手勢。

# ruby pinch 75

# python driver.pinch(element=el)

// java driver.pinch(element);

// javascript function pinch(el) { return Q.all([ el.getSize(), el.getLocation(), ]).then(function(res) { var size = res[0]; var loc = res[1]; var center = { x: loc.x + size.width / 2, y: loc.y + size.height / 2 }; var a1 = new wd.TouchAction(this); a1.press({el: el, x: center.x, y:center.y - 100}).moveTo({el: el}).release(); var a2 = new wd.TouchAction(this); a2.press({el: el, x: center.x, y: center.y + 100}).moveTo({el: el}).release(); var m = new wd.MultiAction(this); m.add(a1, a2); return m.perform(); }.bind(this)); }; wd.addPromiseChainMethod('pinch', pinch); wd.addElementPromiseChainMethod('pinch', function() { return this.browser.pinch(this); }); // ... return driver.pinch(el); // ... return el.pinch();

$this->pinch($el);

// c# driver.Pinch(25, 25)

放大屏幕（Zoom）

在屏幕上使用放大手勢。

# ruby zoom 200

# python driver.zoom(element=el)

// java driver.zoom(element);

// javascript function zoom(el) { return Q.all([ this.getWindowSize(), this.getLocation(el), ]).then(function(res) { var size = res[0]; var loc = res[1]; var center = { x: loc.x + size.width / 2, y: loc.y + size.height / 2 }; var a1 = new wd.TouchAction(this); a1.press({el: el}).moveTo({el: el, x: center.x, y: center.y - 100}).release(); var a2 = new wd.TouchAction(this); a2.press({el: el}).moveTo({el: el, x: center.x, y: center.y + 100}).release(); var m = new wd.MultiAction(this); m.add(a1, a2); return m.perform(); }.bind(this)); }; wd.addPromiseChainMethod('zoom', zoom); wd.addElementPromiseChainMethod('zoom', function() { return this.browser.zoom(this); }); // ... return driver.zoom(el); // ... return el.zoom();

// php $this->zoom($el);

// c# driver.Zoom(100, 200);

滾動到

滾動到指定的元素。

# ruby element = find_element :accessibility_id, "Element ID" execute_script "mobile: scroll", direction: "down", element: element.ref

# python driver.execute_script("mobile: scroll", {"direction": "down", "element": element.id})

// java JavascriptExecutor js = (JavascriptExecutor) driver; HashMap<String, String> scrollObject = new HashMap<String, String>(); scrollObject.put("direction", "down"); scrollObject.put("element", ((RemoteWebElement) element).getId()); js.executeScript("mobile: scroll", scrollObject);

// javascript return driver.elementByAccessibilityId().then(function (el) { driver.execute("mobile: scroll", [{direction: "down", element: el.value}]); });

// php $els = $this->elements($this->using('class name')->value('android.widget.TextView')); $this->scroll($els[count($els) - 1], $els[0]);

// c# Dictionary<string, string> scrollObject = new Dictionary<string, string>(); scrollObject.Add("direction", "down"); scrollObject.Add("element", <element_id>); ((IJavaScriptExecutor)driver).ExecuteScript("mobile: scroll", scrollObject));

拉取（pull）文件

從設備上拉取文件。

# ruby pull_file 'Library/AddressBook/AddressBook.sqlitedb'

# python driver.pull_file('Library/AddressBook/AddressBook.sqlitedb')

// java driver.pullFile("Library/AddressBook/AddressBook.sqlitedb");

// javascript driver.pullFile("Library/AddressBook/AddressBook.sqlitedb") .then(function (base64File) { /*...*/ })

// php $this->pullFile('Library/AddressBook/AddressBook.sqlitedb');

// c# driver.PullFile("Library/AddressBook/AddressBook.sqlitedb");

推送（push）文件

推送文件到設備。

# ruby data = "some data for the file" path = "/data/local/tmp/file.txt" push_file path, data

# python data = "some data for the file" path = "/data/local/tmp/file.txt" driver.push_file(path, data.encode('base64'))

// java byte[] data = Base64.encodeBase64("some data for the file".getBytes()); String path = "/data/local/tmp/file.txt"; driver.pushFile(path, data)

// javascript driver.pushFile(path, data)

// php $path = 'data/local/tmp/test_push_file.txt'; $data = 'This is the contents of the file to push to the device.'; $this->pushFile($path, base64_encode($data));

// c# driver.PushFile("/data/local/tmp/file.txt", "some data for the file");

設置

在這你會找到關於獲取或設置 appium 服務器設置的示例代碼。若是想了解工做原理，以及支持哪些設置，請查看設置文檔

# ruby current_settings = get_settings update_settings someSetting: true

# python current_settings = driver.get_settings() driver.update_settings({"someSetting": true})

// java JsonObject settings = driver.getSettings() // java 客戶端不支持設置任意的設置項，只能設置 appium 當前支持的部分。 // 因此對於 `ignoreUnimportantViews`（譯者注：忽略不重要的視圖，即 android uiautomator 上的壓縮後 xml ）這個設置項，對應存在下面這個設置方法： driver.ignoreUnimportantViews(true);

// javascript var settings = driver.settings(); browser.updateSettings({'someSetting': true});

// php $settings = $this->getSettings(); $this->updateSettings(array('cyberdelia' => "open"));

// c# Dictionary<String, Object>settings = driver.GetSettings(); // .net 客戶端不支持設置任意的設置項，只能設置 appium 當前支持的部分。 // 因此對於 `ignoreUnimportantViews`（譯者注：忽略不重要的視圖，即 android uiautomator 上的壓縮後 xml ）這個設置項，對應存在下面這個設置方法： driver.IgnoreUnimportantViews(true);

Appium 桌面應用

Appium 的桌面應用支持 OS X, Windows 及 Linux.