HamronyOS 自動化測試框架使用指南

概述

為支撐 HarmonyOS 作業系統的自動化測試活動開展，我們提供了支援 JS/TS 語言的單元及 UI 測試框架，支援開發者針對應用介面進行單元測試，並且可基於 UI 操作進行 UI 自動化指令碼的編寫。

本指南重點介紹自動化測試框架的主要功能，同時介紹編寫單元/UI 自動化測試指令碼的方法以及執行過程。

簡介

HarmonyOS 自動化測試框架 arkxtest，作為 HarmonyOS 工具集的重要組成部分，提供了 HarmonyOS 自動化指令碼編寫和執行的基礎能力。編寫方面提供了一系列支援測試指令碼編寫的 API，包括了基礎流程 API、斷言 API 以及 UI 操作相關的 API，執行方面提供了識別測試指令碼、排程執行測試指令碼以及彙總測試指令碼執行結果的能力。

實現原理

框架重要分為兩大部分：單元測試框架和 UI 測試框架。

●  單元測試框架

單元測試框架是測試框架的基礎底座，提供了最基本的用例識別、排程、執行及結果彙總的能力。主要功能如下圖所示：

單元測試指令碼的基礎執行流程如下圖所示，依賴 aa test 命令作為執行入口，該命令可具體參考。

●  UI 測試框架

UI 測試框架主要對外提供了 UiTest API 供開發人員在對應測試場景呼叫，而其指令碼的執行基礎還是上面提到的單元測試框架。

UI 測試框架的主要功能如下圖所示：

約束與限制

●  UI 測試框架的能力在 HarmonyOS 3.0 release 版本之後方可使用，歷史版本不支援使用。

●  單元測試框架的部分能力與其版本有關，具體能力與版本匹配資訊可見程式碼倉中的 。

環境準備

環境要求

自動化指令碼的編寫主要基於 DevEco Studio，並建議使用 3.1.0.400 之後的版本進行指令碼編寫。

指令碼執行需要 PC 連線 HarmonyOS 裝置，如 JAD 等。

搭建環境

DevEco Studio 可參考其官網介紹進行 下載 ，並進行相關的配置動作。

新建測試指令碼

1.  在 DevEco Studio 中新建應用開發工程，其中 ohos 目錄即為測試指令碼所在的目錄。

2.  在工程目錄下開啟待測試模組下的 ets 檔案，將游標置於程式碼中任意位置，單擊 右鍵 > Show Context Actions > Create Ohos Test 或快捷鍵 Alt+enter > Create Ohos Test 建立測試類，更多指導請參考 DevEco Studio 中 指導 。

編寫單元測試指令碼

import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } 
from 
'@ohos/hypium'

import abilityDelegatorRegistry 
from 
'@ohos.application.abilityDelegatorRegistry'




const delegator = abilityDelegatorRegistry.
getAbilityDelegator()

export 
default 
function 
abilityTest() {
  
describe(
'ActsAbilityTest', 
function () {
    
it(
'testUiExample',
0, 
async 
function (
done) {
      
console.
info(
"uitest: TestUiExample begin");
      
//start tested ability
      
await delegator.
executeShellCommand(
'aa start -b com.ohos.uitest -a MainAbility').
then(

result =>{
        
console.
info(
'Uitest, start ability finished:' + result)
      }).
catch(

err => {
        
console.
info(
'Uitest, start ability failed: ' + err)
      })
      
await 
sleep(
1000);
      
//check top display ability
      
await delegator.
getCurrentTopAbility().
then(
(
Ability)=>{
        
console.
info(
"get top ability");
        
expect(
Ability.
context.
abilityInfo.
name).
assertEqual(
'MainAbility');
      })
      
done();
    })



    
function 
sleep(
time) {
      
return 
new 
Promise(
(
resolve) => 
setTimeout(resolve, time));
    }
  })
}

單元測試指令碼需要包含如下基本元素：

1、依賴導包，以便使用依賴的測試介面。

2、測試程式碼編寫，主要編寫測試程式碼的相關邏輯，如介面呼叫等。

3、斷言介面呼叫，設定測試程式碼中的檢查點，如無檢查點，則不可認為一個完整的測試指令碼。

編寫 UI 測試指令碼

UI 測試指令碼是在單元測試框架的基礎上編寫，主要就是增加了 UI 測試框架提供的介面呼叫，實現對應的測試邏輯。

下面的示例程式碼是在上面的測試指令碼基礎上增量編寫，首先需要增加依賴導包，如下示例程式碼所示：

import {
Driver,
ON,
Component,
MatchPattern} 
from 
'@ohos.UiTest'

然後是具體測試程式碼編寫，場景較為簡單，就是在啟動的應用頁面上進行點選操作，然後增加檢查點檢查用例。

export 
default 
function 
abilityTest() {
  
describe(
'ActsAbilityTest', 
function () {
    
it(
'testUiExample',
0, 
async 
function (
done) {
      
console.
info(
"uitest: TestUiExample begin");
      
//start tested ability
      
await delegator.
executeShellCommand(
'aa start -b com.ohos.uitest -a MainAbility').
then(

result =>{
        
console.
info(
'Uitest, start ability finished:' + result)
      }).
catch(

err => {
        
console.
info(
'Uitest, start ability failed: ' + err)
      })
      
await 
sleep(
1000);
      
//check top display ability
      
await delegator.
getCurrentTopAbility().
then(
(
Ability)=>{
        
console.
info(
"get top ability");
        
expect(
Ability.
context.
abilityInfo.
name).
assertEqual(
'MainAbility');
      })
      
//ui test code
      
//init driver
      
var driver = 
await 
Driver.
create();
      
await driver.
delayMs(
1000);
      
//find button by text 'Next'
      
var button = 
await driver.
findComponent(
ON.
text(
'Next'));
      
//click button
      
await button.
click();
      
await driver.
delayMs(
1000);
      
//check text
      
await driver.
assertComponentExist(
ON.
text(
'after click'));
      
await driver.
pressBack();
      
done();
    })



    
function 
sleep(
time) {
      
return 
new 
Promise(
(
resolve) => 
setTimeout(resolve, time));
    }
  })
}

說明

只支援應用內使用。暫不支援應用外的場景實現自動化，例如與許可權彈窗和 SystemUi 上的控制元件進行互動。

執行測試指令碼

執行測試指令碼可以直接在 DevEco Studio 中透過點選按鈕執行，當前支援以下執行方式：

1、測試包級別執行即執行測試包內的全部用例。

2、測試套級別執行即執行 describe 方法中定義的全部測試用例。

3、測試方法級別執行即執行指定 it 方法也就是單條測試用例。

檢視測試結果

測試執行完畢後可直接在 DevEco Studio 中檢視測試結果，如下圖示例所示：

常見問題

單元測試用例常見問題

1、用例中增加的列印日誌在用例結果之後才列印

問題描述

用例中增加的日誌列印資訊，沒有在用例執行過程中出現，而是在用例執行結束之後才出現。

可能原因

此類情況只會存在於用例中有呼叫非同步介面的情況，原則上用例中所有的日誌資訊均在用例執行結束之前列印。

解決方法

當被呼叫的非同步介面多於一個時，建議將介面呼叫封裝成 Promise 方式呼叫。

2、執行用例時報 error：fail to start ability

問題描述

執行測試用例時候，用例執行失敗，控制檯返回錯誤：fail to start ability。

可能原因

測試包打包過程中出現問題，未將測試框架依賴檔案打包在測試包中。

解決方法

檢查測試包中是否包含 TestRunner.abc 檔案，如沒有則重新編譯打包後再次執行測試。

3、執行用例時報用例超時錯誤

問題描述

用例執行結束，控制檯提示 execute time XXms 錯誤，即用例執行超時

可能原因

1.用例執行非同步介面，但執行過程中沒有執行到 done 函式，導致用例執行一直沒有結束，直到超時結束。

2.用例呼叫函式耗時過長，超過用例執行設定的超時時間。

解決方法

1.檢查用例程式碼邏輯，確保即使斷言失敗場景認可走到 done 函式，保證用例執行結束。

2.可在 IDE 中 Run/Debug Configurations 中修改用例執行超時配置引數，避免用例執行超時。

UI 測試用例常見問題

1、失敗日誌有“Get windows failed/GetRootByWindow failed”錯誤資訊

問題描述

UI 測試用例執行失敗，檢視 hilog 日誌發現日誌中有“Get windows failed/GetRootByWindow failed”錯誤資訊。

可能原因

系統 ArkUI 開關未開啟，導致被測試介面控制元件樹資訊未生成。

解決方法

執行如下命令，並重啟裝置再次執行用例。

hdc shell param 
set persist.ace.testmode.enabled 
1

2、失敗日誌有“uitest-api dose not allow calling concurrently”錯誤資訊

問題描述

UI 測試用例執行失敗，檢視 hilog 日誌發現日誌中有“uitest-api dose not allow calling concurrently”錯誤資訊。

可能原因

1.用例中 UI 測試框架提供非同步介面沒有增加 await 語法糖呼叫。

2.多程式執行 UI 測試用例，導致拉起多個 UITest 程式，框架不支援多程式呼叫。

解決方法

1.檢查用例實現，非同步介面增加 await 語法糖呼叫。

2.避免多程式執行 UI 測試用例。

3、失敗日誌有“dose not exist on current UI! Check if the UI has changed after you got the widget object”錯誤資訊

問題描述

UI 測試用例執行失敗，檢視 hilog 日誌發現日誌中有“dose not exist on current UI! Check if the UI has changed after you got the widget object”錯誤資訊。

可能原因

在用例中程式碼查詢到目標控制元件後，裝置介面發生了變化，導致查詢到的控制元件丟失，無法進行下一步的模擬操作。

解決方法

重新執行 UI 測試用例。