Android APP 自動化測試 [v1.0]
===
目錄
==
[TOC]

## 各家自動化套件與框架比較

## 工具介紹

### 1. Python
一種可讀性高的程式語言，至少有一個 main.py 就可以執行了

import foo

def foo_function(args): 
    print(args)
    return 'foo'

if __name__ == “__main__”:
    print(foo_funcion('a'))

印出來的結果會是

a
foo

### 2. UIAutomator2

> UIAutomator 是 Google 提供的用來做 Android 自動化測試的一個Java庫。可以對 APP 內的任意一個元件，並對其進行任意操作，但有兩個缺點：1. 測試腳本只能使用Java語言 2. 測試腳本必須每次被上傳到設備上運行。

[openatx](https://github.com/openatx) 基於 [UIAutomator](https://developer.android.com/training/testing/ui-automator) 發展出可用 Python 的 [UIAutomator2](https://github.com/openatx/uiautomator2)，並開發了其他新功能
1. 加入了 [openstf/minicap](https://github.com/openstf/minicap) 達到實時屏幕投頻，以及實時截圖
2. 加入了 [openstf/minitouch](https://github.com/openstf/minitouch) 達到精確實時控制設備

### 3. WEditor
可以實時檢視 Android 內的元件與元素的工具，這個將會是在撰寫測試案例時非常好用的工具


### 4. Atx-server (For Android)

## 環境設置
1. Python >= v3.5.0
[下載並安裝](https://www.python.org/downloads/)

2. 安裝 Android Studio
[下載並安裝](https://developer.android.com/studio)

3. 安裝 pip 函式庫
建立一個 requirement.txt

    PyYAML
    weditor
    uiautomator2
    google-api-python-client
    google-auth
    google-auth-httplib2
    google-auth-oauthlib
    gspread

使用 cmd 輸入

    pip instal requirement.txt

4. 電腦透過線連結手機後，輸入指令安裝 ATX-agent
1. 先 [連結手機](#WEditor) 再透過 cmd/terminals 安裝 ATX-agents
`python -m uiautomator2 init`

# 工具使用方式
## Android 手機開啟開發者模式
參考: https://www.samsung.com/tw/support/mobile-devices/how-to-open-close-developer-options/

### 必要操作
1. 打開 USB 偵錯模式
2. 關閉動畫
將視窗動畫比例、專場動畫比例、動畫影片長度比例設為關閉

## 用 WEditor 索取元件信息

1. 確定已經下載 WEditor, 下載的方式 [環境設置 > 3.安裝 pip 函式庫](#環境設置)
2. 打開 cmd/Terminal 輸入指令 `python -m weditor`
3. 網頁將自動打開，如下圖


4. 在手機的 設定 > WiFi > 點擊 Wifi 名字索取 IP, 並取代指令內的 $IP 打開 cmd/Terminal 輸入指令，手機將完成連結

adb connect $IP:5555

> 記得在手機上點擊確認連結

如果想要斷開連結

adb kill-server

5. 索取元件信息的方式

1. 手機 APP 畫面實時/靜態模式
2. 更新元件信息，為了確保畫面上的元件是最新的資料，可以多點擊 Dump Heriachy
3. 索取元件信息，用滑鼠在畫面上點擊元件, 點擊元件後畫面上的元件信息會更新


4. xpath (只能獨立使用):
xpath `//*[@resource-id="tw.com.youbike.plus:id/map_position"]`

5. 多種組合精準定位:
可以使用多個 Prop 和 Value 進行組合

`resourceId: tw.com.youbike.plus:id/map_position`
`className: android.widget.ImageButton`
`clickable: true`

或者其他像是

`text: 會員登入`

## Check Sheet 產生器
### 前置步驟
#### A. 申請 Google API (程式只要一個就足夠了)
1. 打開 https://console.developers.google.com
2. 選擇建立新專案

3. 建立憑證

4. 建立完成將自動下載

5. 點擊啟用 [Google Drive API](https://console.developers.google.com/apis/library/drive.googleapis.com?q=Drive) & [Google Sheet API](https://console.developers.google.com/apis/library/sheets.googleapis.com?q=sheet)

6. 打開剛剛自動下載的 json 檔案，將 `client_email` 的 email 複製

7. 打開 Google Drive 將放置 Google Sheet 的文件夾共享給 **第6步** 複製的 email

8. 將 json 重新命名為 cred.json 並將檔案放置到 credentials/ 裡面

#### B. 程式設定檔
將以下範例資料 config.yaml 改寫

Project: "Any Text"                # 任意名字
SpreadSheet: "Spread Sheet Name"   # Google Sheet 的檔名
WorkSheet:                         # Google Sheet 裡工作表的名稱
  - 01
  - 02
  - 03

#### C. Google Sheet 產生 CS 的工作表使用規則
需要建立三個工作表， 例如測試工作表名稱為 XX，參數與模板名字必須命名為 (XX PARAMS & XX TMP)
1. 建立 01: 放置之後生成的結果
2. 建立 01 PARAMS: 用於放置參數的 Key 與 Value
3. 建立 01 TMP: 放置一個完整步驟的 TestCase 模板
a. 模板必須依照規範來製作, 請參考後續內容
4. 參數必須為大寫、前後各加上 $ 符號 `$PARAMETER$`

## Google Sheet 製作與產生 Test Case

[Google Sheet testcase 範例](https://docs.google.com/spreadsheets/d/1hIUxVOjCl5KGR9y7MjWyWMvAuU4bJYuEZ5h9q05h22o/edit#gid=1995617163)

### 欄位介紹
一共有 16 個欄位, 可以分成 4 個部分來詳細說明, 建議搭配 test case 查看


test_case_id:         測試案例 id
step_id:              步驟計數
info:                 測試內容或目標
pre:                  前置動作
selector_key          元件內的 Prop
selector_value        元件內的 Value
child_by_text_key     元件內的 Prop (進階)
child_by_text_value   元件內的 Value (進階)
child_key             元件內的 Prop (進階)
child_value           元件內的 Value (進階)
action_key            動作名稱(檢查元件存在，輸入文字，清除文字)
action_value          數據( True | False | Value )
error_message         當程式出錯時將紀錄在報告內
sleep                 暫停（秒)
parameter_key         參數名字
parameter_value       參數內容

#### 1. 測試案例資訊
<!--  -->

| 欄位 | 需求 | 定義 | 內容 | 備註 |
| ----- | ----- | ---- | ----| --- |
| test_case_id | 必 | 測試名字 | 文字 | 一項測試案例只寫第一行
| step_id | 必 | 步驟 | 文字 | 一個步驟也只需要寫一行
| info | 必 | 動作的解說 | 文字 |
| pre | 選 | 測試開始之前將執行的程式 | 程式名稱 | 需預先撰寫程式才能執行

#### 2. 尋找 APP 元件
<!--  -->

| 欄位 | 需求 | 定義 | 內容 | 備註 |
| ----- | ----- | ---- | ----| --- |
| selector_key | 必 | 元件的元素 | 文字 | 可以超過一項
| selector_value | 必 | 元件的元素 | 文字 | 可以超過一項
| child_by_text_key | 選 | 元件的元素 | 文字 | 進階版
| child_by_text_value | 選 | 元件的元素 | 文字 | 進階版
| child_key | 選 | 元件的元素 | 文字 | 進階版
| child_value | 選 | 元件的元素 | 文字 | 進階版

#### 3. 動作
<!--  -->

| 欄位 | 需求 | 定義 | 內容 | 備註 |
| ----- | ----- | ---- | ----| --- |
| action_key | 必 | 對於元素的動作 | 文字 | 可以超過一項動作，由上至下需按照動作順序
| action_value | 必 | 對於元素的動作 | 文字 | True, False, Value

#### 4. 其他
<!--  -->

| 欄位 | 需求 | 定義 | 內容 | 備註 |
| ----- | ----- | ---- | ----| --- |
| error_message | 必 | 出現錯誤的時候將顯示，以方便追蹤 | 文字 |
| sleep | 選 | 停頓，讓資料加載或等 UI 執行完成 | 文字 | 以秒為單位
| parameter_key & parameter_value | 選 | 若 Google Sheet 測試案例中有出現與 parameter_key 相同的字, 將會在生成程式案例的時候覆蓋為 parameter_value | 文字 |

### 動作解析
將對以下的測試案例 (登入失敗測試) 解析，一共有 7 個步驟


#### 測試案例
<!--  -->

a. 定義 test_case_id，一項測試只需要寫一次就好
b. 定義 step_id，同一個元件也只需要寫一次就好
c. 填寫 info 內容為 "點選左上角功能展開功能選單"
d. 使用 WEditor 找出元件的元素 —— description 向上瀏覽
e. 定義元素需要執行的 action —— click


<!-- #### 2. 填寫測試案例

a. 定義 step_id，也只需要寫一次就好
b. 填寫 info 內容為 "手機號碼輸入提示" -->
<!-- c. 使用 WEditor 找出元件的元素 —— xpath (因為其他元素都沒有辦法找到特定的元件，只好使用 xpath) -->

# 功能清單
1. Selector
a. text
b. description
c. className
d. packageName
e. resourceId
f. xpath (只能獨立使用)

2. Action
a. click 將判斷元件是否存在，再點擊
b. exists 判斷元件是否存在
c. send_keys 輸入文字到輸入框，輸入前最好有一個點擊輸入框的步驟
c. check_text 檢查內部的文字與預期做比較
d. clear 清除輸入框內的文字

### CSV To Json [棄用]
*<details><summary>隱藏中點擊開啟</summary>*
<p>

1. 在 Google Sheet 點擊左上方檔案 > 下載格式 > CSV

2. 把 csv 都放到程式資料夾 csv/ 裡面
3. 執行程式 main.py 將全部把 csv 轉換成 json

</p>
</details>

## 程式解說
> 搭配相關流程圖將更加清除

[流程圖](https://drive.google.com/file/d/1D5zUvmwW_k3sOx_h15ThHj2NXrPrrVAA/view?usp=sharing)

## 相關流程圖

[CS Generator & UnitTest Generator 流程圖](https://drive.google.com/file/d/1D5zUvmwW_k3sOx_h15ThHj2NXrPrrVAA/view?usp=sharing)