入門指南 · Appium 官方文檔

## 新手入門本文將會帶你了解并運行一個簡單的appium案例以及向你介紹一些關于appium的基本概念。想要了解更多關于appium的詳細信息，請查看[相關介紹](../about-appium/intro.md)。 ### 安裝appium Appium可以通過以下兩種方式進行安裝：使用[NPM](https://npmjs.com)命令或者是下載[appium客戶端](https://github.com/appium/appium-desktop) ，一種基于桌面圖形化的方式來啟動appium服務。 #### 使用NPM命令進行appium安裝如果你想使用`npm install`命令安裝appium，或者是改造appium，或者提交代碼為appium做貢獻，你都需要安裝[Node.js和NPM](http://nodejs.org)（使用[nvm](https://github.com/creationix/nvm),[n](https://github.com/visionmedia/n)命令，或者是`brew install node`命令來安裝node.js。請確認你沒有使用`sudo`命令進行Node或者Appium的安裝，否則運行時會出現問題）盡管Appium支持Node10及以上版本，我們仍然推薦使用最新穩定版。 Appium的安裝直接使用如下命令即可： ``` npm install -g appium ``` #### 通過下載桌面應用的方式來進行Appium的安裝可直接從[版本發行頁面](https://github.com/appium/appium-desktop/releases)點擊下載最新版的Appium桌面版。 ### 指定系統的 driver安裝你可能想要用Appium來進行不同應用的自動化操作，例如iOS應用或者是Android應用，Appium driver 提供了對于不同平臺的自動化操作。下面列舉的driver類型可以使你在不同的平臺都能使用自動化技術，并且每種driver都有他們特定的安裝要求。對于某個平臺來說，driver的安裝要求與在該平臺上進行app開發所需的環境要求大多一致。例如，如果你想使用任意一種Android driver來進行Android應用的自動化操作，那么你所使用的的系統中應該配置好Android SDK. 在某些情況下，對于你想進行自動化操作的平臺，請確認你查看過對應driver的文檔，以便能正確進行安裝： - [XCUITest driver](../drivers/ios-xcuitest.md) (iOS和tvOS應用使用) - [Espresso driver](../drivers/android-espresso.md) (Android應用使用) - [UiAutomator2 driver](../drivers/android-uiautomator2.md) (Android應用使用) - [Windows driver](../drivers/windows.md) (Windows操作系統桌面應用使用) - [Mac driver](../drivers/mac.md) (Mac操作系統桌面應用使用) ### 驗證安裝你可以使用`appium-doctor`命令來確認安裝Appium所需的依賴是否都已滿足要求。使用`npm install -g appium-doctor`命令來進行上述命令的安裝，安裝完成后，運行`appium-doctor`命令確認Appium所需的依賴都已正確安裝，該命令還支持與`--ios`或者 `--android`選項一起搭配使用。 ### Appium 客戶端當上述所需條件都已滿足，Appium 其實是一個HTTP服務器而已。它需要與客戶端進行連接，并由客戶端發出指令告訴它應該開啟哪種會話，還有一旦會話啟動成功后該進行哪些自動化操作。這就意味著你永遠不能只單獨使用Appium本身，你需要將它與某一個客戶端一起搭配使用（或者，如果你具有探索精神，可以使用cURL的方式進行嘗試）幸運的是，Appium與[Selenium](http://www.seleniumhq.org/)使用同一種協議，稱為WebDriver協議。也許在你使用的系統中已經安裝了多個客戶端，但你只需要搭配任意一種標準Selenium客戶端便足夠運行Appium進行多種操作，特別是當你使用Appium來進行移動平臺上的瀏覽器測試的時候。盡管如此，正如移動端可以進行的某些操作不能在瀏覽器端進行，有些操作也是Appium可以但是Selenium卻不行。因此，為了彌補這些不足，我們在傳統Selenium客戶端已有功能的基礎上進行了相應的擴展，提供了一系列支持不同編程語言的Appium客戶端。你可通過查看[Appium客戶端列表](../about-appium/appium-clients.md)頁面，點擊相應的鏈接進行下載。在進行下一步之前，請確認你已經根據自己使用的語言類型下載好了對應的客戶端并準備好一切所需條件 ### 啟動Appium 現在我們可以打開Appium服務端，通過使用下面的命令行進行Appium的啟動（假設NPM命令已經安裝成功）： ``` appium ``` 或者是點擊Appium客戶端頁面上比較顯眼的啟動按鈕。 Appium啟動成功后將會向你展示一段簡短的歡迎消息，其中包含了你目前所使用的Appium版本號和正在監聽的端口號（默認使用`4723`）。該監聽端口信息很重要，因為你需要確認測試客戶端能通過該端口號順利連接上Appium。如果你想要修改默認端口號，你可以在啟動Appium時通過使用`-p`選項進行端口的設置（請確認已經查看過完整的[服務端參數列表](../writing-running-appium/server-args.md)文檔） ### 運行你的第一個測試用例在該部分，我們將會運行一個簡單的“Hello World”Android測試用例。之所以選擇Android是因為它在所有平臺上都能運行。同時，我們將使用[UiAutomator2 driver](../drivers/android-uiautomator2.md)，所以請確保你已經通讀過相關文檔并且系統已經具備所需的環境。本次將使用JavaScript作為開發語言，以便于不需要再使用到其他的依賴組件。（有可能你最終想進行自動化測試的平臺并非Android，使用的編程語言也并非JavaScript。對于這種情況，可以查看[代碼示例](https://github.com/appium/appium/tree/master/sample-code)文檔, 其中包含了不同編程語言及運行平臺的代碼示例。）） #### 前提條件 - 我們假設你已經配置好并能成功運行Android8.0模擬器（在低版本上運行該示例時，修改對應的版本號即可） - 我們假設你已經將所需的[測試APK](https://github.com/appium/appium/raw/master/sample-code/apps/ApiDemos-debug.apk)下載到本地系統 #### 配置 Appium 客戶端在本次示例中，我們將使用[Webdriver.io](http://webdriver.io)作為我們的Appium客戶端。首先為該示例代碼創建一個目錄，然后運行下面的命令： ``` npm init -y ``` 一旦項目初始化成功，則接下來就可以使用下面的命令進行`webdriverio`的安裝： ``` npm install webdriverio ``` #### 初始化會話現在我們可以創建一個名為`index.js`的測試文件，并且進行客戶端的初始化： ```js // javascript const wdio = require("webdriverio"); ``` 接下來我們需要做的是啟動一個Appium會話。通過定義一系列的服務選項和參數配置，并使用`wdio.remote()`方法來進行調用。這里所講的參數配置其實僅僅是一些在會話初始化之后，發送至Appium服務端，告訴Appium我們想要進行哪些自動化操作的鍵值對。對于任意Appium driver來說，至少應該包含以下這幾個配置： - `platformName`: 需要進行自動化操作的平臺名稱 - `platformVersion`: 需要進行自動化操作的平臺版本 - `deviceName`: 需要進行自動化的設備 - `app`: 需要進行自動化的APP路徑 (與之相反，在進行瀏覽器自動化操作的時候需要使用`browserName`設置項) - `automationName`: 需要使用的驅動名稱更多關于配置項和Appium中可用的配置項列表信息，可查看[參數配置文檔](../writing-running-appium/caps.md). 下面所示測試文件中的代碼向我們展示了怎樣進行會話的開啟： ```js // javascript const opts = { path: '/wd/hub', port: 4723, capabilities: { platformName: "Android", platformVersion: "8", deviceName: "Android Emulator", app: "/path/to/the/downloaded/ApiDemos.apk", appPackage: "io.appium.android.apis", appActivity: ".view.TextFields", automationName: "UiAutomator2" } }; async function main () { const client = await wdio.remote(opts); await client.deleteSession(); } main(); ``` #### 運行測試命令上一個步驟中我們已經將Appium的端口進行了設置，也根據自己的需求進行了參數配置（但是不要忘記將代碼中的APK路徑更換為自己系統中的實際路徑）并且使用`webdriverio`將上述配置進行了注冊，現在我們已經創建好了能與Appium服務器進行連接的客戶端對象。至此，我們可以繼續后續的啟動會話，執行一些測試命令和關閉會話等操作。在本次測試中，我們將會執行一個簡單的文本框輸入操作并檢查輸入的文本是否正確。 ```js // javascript const field = await client.$("android.widget.EditText"); await field.setValue("Hello World!"); const value = await field.getText(); assert.equal(value, "Hello World!"); ``` 當我們創建好了會話并且登錄了應用后，接下來需要做的就是利用Appium在應用的層次結構中找到所需的元素并進行輸入操作。然后查詢該元素并獲取其文本內容，獲取到的內容應該與斷言中的期望值一致。將上述所有代碼整合在一起，完整的文件內容如下所示： ```js // javascript const wdio = require("webdriverio"); const assert = require("assert"); const opts = { path: '/wd/hub', port: 4723, capabilities: { platformName: "Android", platformVersion: "8", deviceName: "Android Emulator", app: "/path/to/the/downloaded/ApiDemos.apk", appPackage: "io.appium.android.apis", appActivity: ".view.TextFields", automationName: "UiAutomator2" } }; async function main () { const client = await wdio.remote(opts); const field = await client.$("android.widget.EditText"); await field.setValue("Hello World!"); const value = await field.getText(); assert.equal(value,"Hello World!"); await client.deleteSession(); } main(); ``` 你可以嘗試自己運行這個示例。只需要將上述代碼保存并且使用下面的命令執行即可。 `node`: ``` node index.js ``` 如果一切順利，你將會看到Appium開始產生日志，最終屏幕上會彈出應用并且開始進行操作仿佛有一個無形的用戶在進行點擊 ### 接下來的內容上述內容中我們只是接觸到了一些Appium的皮毛。查看下面所示文檔更好的幫助你進行Appium的使用 - [命令相關](https://appium.io../commands/status/) - 學習可用的命令，如何將它們與特定的客戶端進行使用等... - [代碼示范目錄](https://github.com/appium/appium/tree/master/sample-code) 可查看多種代碼示例 - [Appium論壇](https://discuss.appium.io) - 這是一個可以更好的幫助你進行入門學習，或者是當你遇到困難時可以尋求幫助的Appium社區論壇 - [問題追蹤](https://github.com/appium/appium/issues) - 如果你認為自己發現了問題，可通過此方式讓Appium維護者知曉