1# 自动化测试框架使用指南 2 3 4## 概述 5 6为支撑OpenHarmony操作系统的自动化测试活动开展，我们提供了支持JS/TS语言的单元及UI测试框架，支持开发者针对应用接口或系统接口进行单元测试，并且可基于UI操作进行UI自动化脚本的编写。 7 8本指南重点介绍自动化测试框架的主要功能，同时介绍编写单元/UI自动化测试脚本的方法以及执行过程。 9 10 11### 简介 12 13OpenHarmony自动化测试框架arkxtest，作为OpenHarmony工具集的重要组成部分，提供了OpenHarmony自动化脚本编写和运行的基础能力。编写方面提供了一系列支持测试脚本编写的API，包括了基础流程API、断言API以及UI操作相关的API，运行方面提供了识别测试脚本、调度执行测试脚本以及汇总测试脚本执行结果的能力。 14 15 16### 实现原理 17 18框架重要分为两大部分：单元测试框架和UI测试框架。 19 20- 单元测试框架 21 22 单元测试框架是测试框架的基础底座，提供了最基本的用例识别、调度、执行及结果汇总的能力。主要功能如下图所示： 23 24  25 26 单元测试脚本的基础运行流程如下图所示，依赖aa test命令作为执行入口，该命令可具体参考。 27 28  29 30- UI测试框架 31 32 UI测试框架主要对外提供了[UiTest API](../reference/apis/js-apis-uitest.md)供开发人员在对应测试场景调用，而其脚本的运行基础还是上面提到的单元测试框架。 33 34 UI测试框架的主要功能如下图所示： 35 36  37 38 39### 约束与限制 40 41- UI测试框架的能力在OpenHarmony 3.1 release版本之后方可使用，历史版本不支持使用。 42- 单元测试框架的部分能力与其版本有关，具体能力与版本匹配信息可见代码仓中的[文档介绍](https://gitee.com/openharmony/testfwk_arkxtest/blob/master/README_zh.md)。 43 44 45## 环境准备 46 47### 环境要求 48 49OpenHarmony自动化脚本的编写主要基于DevEco Studio，并建议使用3.0之后的版本进行脚本编写。 50 51脚本执行需要PC连接OpenHarmony设备，如RK3568开发板等。 52 53### 搭建环境 54 55DevEco Studio可参考其官网介绍进行[下载](https://developer.harmonyos.com/cn/develop/deveco-studio#download)，并进行相关的配置动作。 56 57 58## 新建测试脚本 59 601. 在DevEco Studio中新建应用开发工程，其中ohos目录即为测试脚本所在的目录。 612. 在工程目录下打开待测试模块下的ets文件，将光标置于代码中任意位置，单击**右键 > Show Context Actions** **> Create Ohos Test**或快捷键**Alt+enter** **> Create Ohos Test**创建测试类，更多指导请参考DevEco Studio中[指导](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/harmonyos_jnit_jsunit-0000001092459608-V3?catalogVersion=V3#section13366184061415)。 62 63## 编写单元测试脚本 64 65```TS 66import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium' 67import abilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' 68 69const delegator = abilityDelegatorRegistry.getAbilityDelegator() 70export default function abilityTest() { 71 describe('ActsAbilityTest', function () { 72 it('testUiExample',0, async function (done) { 73 console.info("uitest: TestUiExample begin"); 74 //start tested ability 75 await delegator.executeShellCommand('aa start -b com.ohos.uitest -a MainAbility').then(result =>{ 76 console.info('Uitest, start ability finished:' + result) 77 }).catch(err => { 78 console.info('Uitest, start ability failed: ' + err) 79 }) 80 await sleep(1000); 81 //check top display ability 82 await delegator.getCurrentTopAbility().then((Ability)=>{ 83 console.info("get top ability"); 84 expect(Ability.context.abilityInfo.name).assertEqual('MainAbility'); 85 }) 86 done(); 87 }) 88 89 function sleep(time) { 90 return new Promise((resolve) => setTimeout(resolve, time)); 91 } 92 }) 93} 94``` 95 96单元测试脚本需要包含如下基本元素： 97 981、依赖导包，以便使用依赖的测试接口。 99 1002、测试代码编写，主要编写测试代码的相关逻辑，如接口调用等。 101 1023、断言接口调用，设置测试代码中的检查点，如无检查点，则不可认为一个完整的测试脚本。 103 104## 编写UI测试脚本 105 106UI测试脚本是在单元测试框架的基础上编写，主要就是增加了UI测试框架提供的接口调用，实现对应的测试逻辑。 107 108下面的示例代码是在上面的测试脚本基础上增量编写，首先需要增加依赖导包，如下示例代码所示： 109 110```js 111import {Driver,ON,Component,MatchPattern} from '@ohos.uitest' 112``` 113 114然后是具体测试代码编写，场景较为简单，就是在启动的应用页面上进行点击操作，然后增加检查点检查用例。 115 116```js 117export default function abilityTest() { 118 describe('ActsAbilityTest', function () { 119 it('testUiExample',0, async function (done) { 120 console.info("uitest: TestUiExample begin"); 121 //start tested ability 122 await delegator.executeShellCommand('aa start -b com.ohos.uitest -a MainAbility').then(result =>{ 123 console.info('Uitest, start ability finished:' + result) 124 }).catch(err => { 125 console.info('Uitest, start ability failed: ' + err) 126 }) 127 await sleep(1000); 128 //check top display ability 129 await delegator.getCurrentTopAbility().then((Ability)=>{ 130 console.info("get top ability"); 131 expect(Ability.context.abilityInfo.name).assertEqual('MainAbility'); 132 }) 133 //ui test code 134 //init driver 135 var driver = await Driver.create(); 136 await driver.delayMs(1000); 137 //find button by text 'Next' 138 var button = await driver.findComponent(ON.text('Next')); 139 //click button 140 await button.click(); 141 await driver.delayMs(1000); 142 //check text 143 await driver.assertComponentExist(ON.text('after click')); 144 await driver.pressBack(); 145 done(); 146 }) 147 148 function sleep(time) { 149 return new Promise((resolve) => setTimeout(resolve, time)); 150 } 151 }) 152} 153``` 154 155## 执行测试脚本 156 157执行测试脚本可以直接在DevEco Studio中通过点击按钮执行，当前支持以下执行方式： 158 1591、测试包级别执行即执行测试包内的全部用例。 160 1612、测试套级别执行即执行describe方法中定义的全部测试用例。 162 1633、测试方法级别执行即执行指定it方法也就是单条测试用例。 164 165 166 167## 查看测试结果 168 169测试执行完毕后可直接在DevEco Studio中查看测试结果，如下图示例所示： 170 171 172 173## 常见问题 174 175### 单元测试用例常见问题 176 177**1、用例中增加的打印日志在用例结果之后才打印** 178 179**问题描述** 180 181用例中增加的日志打印信息，没有在用例执行过程中出现，而是在用例执行结束之后才出现。 182 183 **可能原因** 184 185此类情况只会存在于用例中有调用异步接口的情况，原则上用例中所有的日志信息均在用例执行结束之前打印。 186 187 **解决方法** 188 189当被调用的异步接口多于一个时，建议将接口调用封装成Promise方式调用。 190 191**2、执行用例时报error：fail to start ability** 192 193**问题描述** 194 195执行测试用例时候，用例执行失败，控制台返回错误：fail to start ability。 196 197**可能原因** 198 199测试包打包过程中出现问题，未将测试框架依赖文件打包在测试包中。 200 201**解决方法** 202 203检查测试包中是否包含OpenHarmonyTestRunner.abc文件，如没有则重新编译打包后再次执行测试。 204 205**3、执行用例时报用例超时错误** 206 207**问题描述** 208 209用例执行结束，控制台提示execute time XXms错误，即用例执行超时 210 211**可能原因** 212 2131.用例执行异步接口，但执行过程中没有执行到done函数，导致用例执行一直没有结束，直到超时结束。 214 2152.用例调用函数耗时过长，超过用例执行设置的超时时间。 216 217**解决方法** 218 2191.检查用例代码逻辑，确保即使断言失败场景认可走到done函数，保证用例执行结束。 220 2212.可在IDE中Run/Debug Configurations中修改用例执行超时配置参数，避免用例执行超时。 222 223### UI测试用例常见问题 224 225**1、失败日志有“Get windows failed/GetRootByWindow failed”错误信息** 226 227**问题描述** 228 229UI测试用例执行失败，查看hilog日志发现日志中有“Get windows failed/GetRootByWindow failed”错误信息。 230 231**可能原因** 232 233系统ArkUI开关未开启，导致被测试界面控件树信息未生成。 234 235**解决方法** 236 237执行如下命令，并重启设备再次执行用例。 238 239```shell 240hdc shell param set persist.ace.testmode.enabled 1 241``` 242 243**2、失败日志有“uitest-api dose not allow calling concurrently”错误信息** 244 245**问题描述** 246 247UI测试用例执行失败，查看hilog日志发现日志中有“uitest-api dose not allow calling concurrently”错误信息。 248 249**可能原因** 250 2511.用例中UI测试框架提供异步接口没有增加await语法糖调用。 252 2532.多进程执行UI测试用例，导致拉起多个UITest进程，框架不支持多进程调用。 254 255**解决方法** 256 2571.检查用例实现，异步接口增加await语法糖调用。 258 2592.避免多进程执行UI的测试用例。 260 261**3、失败日志有“dose not exist on current UI! Check if the UI has changed after you got the widget object”错误信息** 262 263**问题描述** 264 265UI测试用例执行失败，查看hilog日志发现日志中有“dose not exist on current UI! Check if the UI has changed after you got the widget object”错误信息。 266 267**可能原因** 268 269在用例中代码查找到目标控件后，设备界面发生了变化，导致查找到的控件丢失，无法进行下一步的模拟操作。 270 271**解决方法** 272 273重新执行UI测试用例。 274
