1# OpenHarmony自动化测试框架使用介绍 2 3## 简介 4 OpenHarmony自动化测试框架代码部件仓arkXtest，包含单元测试框架(JsUnit)和Ui测试框架(UiTest)。 5 6 单元测试框架(JsUnit)提供单元测试用例执行能力，提供用例编写基础接口，生成对应报告，用于测试系统或应用接口。 7 8 Ui测试框架(UiTest)通过简洁易用的API提供查找和操作界面控件能力，支持用户开发基于界面操作的自动化测试脚本。 9 10## 目录 11 12``` 13arkXtest 14 |-----jsunit 单元测试框架 15 |-----uitest Ui测试框架 16``` 17## 约束限制 18本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 19 20## 单元测试框架功能特性 21 22| No. | 特性 | 功能说明 | 23| ---- | -------- | ---------------------------------- | 24| 1 | 基础流程 | 支持编写及执行基础用例 | 25| 2 | 断言库 | 判断用例实际期望值与预期值是否相符 | 26 27### 使用说明 28 29#### 基础流程 30 31测试用例采用业内通用语法，describe代表一个测试套， it代表一条用例。 32 33| No. | API | 功能说明 | 34| ---- | ---------- | ------------------------------------------------------------ | 35| 1 | describe | 定义一个测试套，支持两个参数：测试套名称和测试套函数 | 36| 2 | beforeAll | 在测试套内定义一个预置条件，在所有测试用例开始前执行且仅执行一次，支持一个参数：预置动作函数 | 37| 3 | beforeEach | 在测试套内定义一个单元预置条件，在每条测试用例开始前执行，执行次数与it定义的测试用例数一致，支持一个参数：预置动作函数 | 38| 4 | afterEach | 在测试套内定义一个单元清理条件，在每条测试用例结束后执行，执行次数与it定义的测试用例数一致，支持一个参数：清理动作函数 | 39| 5 | afterAll | 在测试套内定义一个清理条件，在所有测试用例结束后执行且仅执行一次，支持一个参数：清理动作函数 | 40| 6 | it | 定义一条测试用例，支持三个参数：用例名称，过滤参数和用例函数 | 41| 7 | expect | 支持bool类型判断等多种断言方法 | 42 43示例代码： 44 45```javascript 46import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from 'hypium/index' 47import demo from '@ohos.bundle' 48 49export default async function abilityTest() { 50 describe('ActsAbilityTest', function () { 51 it('String_assertContain_success', 0, function () { 52 let a = 'abc' 53 let b = 'b' 54 expect(a).assertContain(b) 55 expect(a).assertEqual(a) 56 }) 57 it('getBundleInfo_0100', 0, async function () { 58 const NAME1 = "com.example.MyApplicationStage" 59 await demo.getBundleInfo(NAME1, 60 demo.BundleFlag.GET_BUNDLE_WITH_ABILITIES | demo.BundleFlag.GET_BUNDLE_WITH_REQUESTED_PERMISSION) 61 .then((value) => { 62 console.info(value.appId) 63 }) 64 .catch((err) => { 65 console.info(err.code) 66 }) 67 }) 68 }) 69} 70``` 71 72 73 74#### 断言库 75 76断言功能列表： 77 78 79| No. | API | 功能说明 | 80| :--- | :--------------- | ------------------------------------------------------------ | 81| 1 | assertClose | 检验actualvalue和expectvalue(0)的接近程度是否是expectValue(1) | 82| 2 | assertContain | 检验actualvalue中是否包含expectvalue | 83| 3 | assertEqual | 检验actualvalue是否等于expectvalue[0] | 84| 4 | assertFail | 抛出一个错误 | 85| 5 | assertFalse | 检验actualvalue是否是false | 86| 6 | assertTrue | 检验actualvalue是否是true | 87| 7 | assertInstanceOf | 检验actualvalue是否是expectvalue类型 | 88| 8 | assertLarger | 检验actualvalue是否大于expectvalue | 89| 9 | assertLess | 检验actualvalue是否小于expectvalue | 90| 10 | assertNull | 检验actualvalue是否是null | 91| 11 | assertThrowError | 检验actualvalue抛出Error内容是否是expectValue | 92| 12 | assertUndefined | 检验actualvalue是否是undefined | 93 94示例代码： 95 96```javascript 97import { describe, it, expect } from 'hypium/index' 98export default async function abilityTest() { 99 describe('assertClose', function () { 100 it('assertBeClose success', 0, function () { 101 let a = 100 102 let b = 0.1 103 expect(a).assertClose(99, b) 104 }) 105 it('assertBeClose fail', 0, function () { 106 let a = 100 107 let b = 0.1 108 expect(a).assertClose(1, b) 109 }) 110 it('assertBeClose fail', 0, function () { 111 let a = 100 112 let b = 0.1 113 expect(a).assertClose(null, b) 114 }) 115 it('assertBeClose fail', 0, function () { 116 expect(null).assertClose(null, 0) 117 }) 118 }) 119} 120``` 121### 使用方式 122 123 单元测试框架以npm包（hypium）形式发布至官网([https://www.npmjs.com/](https://www.npmjs.com/))，集成至sdk，开发者可以下载Deveco Studio使用，测试工程创建及测试脚本执行使用指南请参见[IDE指导文档](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453)。 124 125## Ui测试框架功能特性 126 127| No. | 特性 | 功能说明 | 128| ---- | ----------- | ------------------------------------------------------------ | 129| 1 | UiDriver | Ui测试的入口，提供查找控件，检查控件存在性以及注入按键能力 | 130| 2 | By | 用于描述目标控件特征(文本、id、类型等)，`UiDriver`根据`By`描述的控件特征信息来查找控件 | 131| 3 | UiComponent | UiDriver查找返回的控件对象，提供查询控件属性，滑动查找等触控和检视能力 | 132 133**使用者在测试脚本通过如下方式引入使用：** 134 135```typescript 136import {UiDriver,BY,UiComponent,MatchPattern} from '@ohos.uitest' 137``` 138 139> 注意事项 140> 1. `By`类提供的接口全部是同步接口，使用者可以使用`builder`模式链式调用其接口构造控件筛选条件。 141> 2. `UiDrivier`和`UiComponent`类提供的接口全部是异步接口(`Promise`形式)，**需使用`await`语法**。 142> 3. Ui测试用例均需使用**异步**语法编写用例，需遵循单元测试框架异步用例编写规范。 143 144 145 146在测试用例文件中import `By/UiDriver/UiComponent`类，然后调用API接口编写测试用例。 147 148```javascript 149import {describe, beforeAll, beforeEach, afterEach, afterAll, it, expect} from 'hypium/index' 150import {BY, UiDriver, UiComponent, MatchPattern} from '@ohos.uitest' 151 152export default async function abilityTest() { 153 describe('uiTestDemo', function() { 154 it('uitest_demo0', 0, async function() { 155 // create UiDriver 156 let driver = await UiDriver.create() 157 // find component by text 158 let button = await driver.findComponent(BY.text('hello').enabled(true)) 159 // click component 160 await button.click() 161 // get and assert component text 162 let content = await button.getText() 163 expect(content).assertEquals('clicked!') 164 }) 165 }) 166} 167``` 168 169### UiDriver使用说明 170 171`UiDriver`类作为UiTest测试框架的总入口，提供查找控件，注入按键，单击坐标，滑动控件，手势操作，截图等能力。 172 173| No. | API | 功能描述 | 174| ---- | ------------------------------------------------------------ | ---------------------- | 175| 1 | create():Promise<UiDriver> | 静态方法，构造UiDriver | 176| 2 | findComponent(b:By):Promise<UiComponent> | 查找匹配控件 | 177| 3 | pressBack():Promise<void> | 单击BACK键 | 178| 4 | click(x:number, y:number):Promise<void> | 基于坐标点的单击 | 179| 5 | swipe(x1:number, y1:number, x2:number, y2:number):Promise<void> | 基于坐标点的滑动 | 180| 6 | assertComponentExist(b:By):Promise<void> | 断言匹配的控件存在 | 181| 7 | delayMs(t:number):Promise<void> | 延时 | 182| 8 | screenCap(s:path):Promise<void> | 截屏 | 183 184其中assertComponentExist接口是断言API，用于断言当前界面存在目标控件；如果控件不存在，该API将抛出JS异常，使当前测试用例失败。 185 186```javascript 187import {BY,UiDriver,UiComponent} from '@ohos.uitest' 188 189export default async function abilityTest() { 190 describe('UiTestDemo', function() { 191 it('Uitest_demo0', 0, async function(done) { 192 try{ 193 // create UiDriver 194 let driver = await UiDriver.create() 195 // assert text 'hello' exists on current Ui 196 await assertComponentExist(BY.text('hello')) 197 } finally { 198 done() 199 } 200 }) 201 }) 202} 203``` 204 205### By使用说明 206 207Ui测试框架通过`By`类提供了丰富的控件特征描述API，用来匹配查找要操作或检视的目标控件。`By`提供的API能力具有以下特点： 208 209- 支持匹配单属性和匹配多属性组合，例如同时指定目标控件text和id。 210- 控件属性支持多种匹配模式(等于，包含，`STARTS_WITH`，`ENDS_WITH`)。 211- 支持相对定位控件，可通过`isBefore`和`isAfter`等API限定邻近控件特征进行辅助定位。 212 213| No. | API | 功能描述 | 214| ---- | ---------------------------------- | ---------------------------------------------- | 215| 1 | id(i:number):By | 指定控件id | 216| 2 | text(t:string, p?:MatchPattern):By | 指定控件文本，可指定匹配模式 | 217| 3 | type(t:string)):By | 指定控件类型 | 218| 4 | enabled(e:bool):By | 指定控件使能状态 | 219| 5 | clickable(c:bool):By | 指定控件可单击状态 | 220| 6 | focused(f:bool):By | 指定控件获焦状态 | 221| 7 | scrollable(s:bool):By | 指定控件可滑动状态 | 222| 8 | selected(s:bool):By | 指定控件选中状态 | 223| 9 | isBefore(b:By):By | **相对定位**，限定目标控件位于指定特征控件之前 | 224| 10 | isAfter(b:By):By | **相对定位**，限定目标控件位于指定特征控件之后 | 225 226其中，`text`属性支持{`MatchPattern.EQUALS`，`MatchPattern.CONTAINS`，`MatchPattern.STARTS_WITH`，`MatchPattern.ENDS_WITH`}四种匹配模式，缺省使用`MatchPattern.EQUALS`模式。 227 228#### 控件绝对定位 229 230**示例代码1**：查找id是`Id_button`的控件。 231 232```javascript 233let button = await driver.findComponent(BY.id(Id_button)) 234``` 235 236 **示例代码2**：查找id是`Id_button`并且状态是`enabled`的控件，适用于无法通过单一属性定位的场景。 237 238```javascript 239let button = await driver.findComponent(BY.id(Id_button).enabled(true)) 240``` 241 242通过`By.id(x).enabled(y)`来指定目标控件的多个属性。 243 244**示例代码3**：查找文本中包含`hello`的控件，适用于不能完全确定控件属性取值的场景。 245 246```javascript 247let txt = await driver.findComponent(BY.text("hello", MatchPattern.CONTAINS)) 248``` 249 250通过向`By.text()`方法传入第二个参数`MatchPattern.CONTAINS`来指定文本匹配规则；默认规则是`MatchPattern.EQUALS`，即目标控件text属性必须严格等于给定值。 251 252#### 控件相对定位 253 254**示例代码1**：查找位于文本控件`Item3_3`后面的，id是`ResourceTable.Id_switch`的Switch控件。 255 256```javascript 257let switch = await driver.findComponent(BY.id(Id_switch).isAfter(BY.text("Item3_3"))) 258``` 259 260通过`By.isAfter`方法，指定位于目标控件前面的特征控件属性，通过该特征控件进行相对定位。一般地，特征控件是某个具有全局唯一特征的控件(例如具有唯一的id或者唯一的text)。 261 262 263类似的，可以使用`By.isBefore`控件指定位于目标控件后面的特征控件属性，实现相对定位。 264 265### UiComponent使用说明 266 267`UiComponent`类代表了Ui界面上的一个控件，一般是通过`UiDriver.findComponent(by)`方法查找到的。通过该类的实例，用户可以获取控件属性，单击控件，滑动查找，注入文本等操作。 268 269`UiComponent`包含的常用API： 270 271| No. | API | 功能描述 | 272| ---- | --------------------------------- | -------------------------------------------- | 273| 1 | click():Promise<void> | 单击该控件 | 274| 2 | inputText(t:string):Promise<void> | 向控件中输入文本(适用于文本框控件) | 275| 3 | scrollSearch(s:By):Promise<bool> | 在该控件上滑动查找目标控件(适用于List等控件) | 276| 4 | getText():Promise<string> | 获取控件text | 277| 5 | getId():Promise<number> | 获取控件id | 278| 6 | getType():Promise<string> | 获取控件类型 | 279| 7 | isEnabled():Promise<bool> | 获取控件使能状态 | 280 281`UiComponent`完整的API列表请参考其API文档。 282 283**示例代码1**：单击控件。 284 285```javascript 286let button = await driver.findComponent(BY.id(Id_button)) 287await button.click() 288``` 289 290**示例代码2**：通过get接口获取控件属性后，可以使用单元测试框架提供的assert*接口做断言检查。 291 292```javascript 293let component = await driver.findComponent(BY.id(Id_title)) 294expect(component !== null).assertTrue() 295``` 296 297**示例代码3**：在List控件中滑动查找text是`Item3_3`的子控件。 298 299```javascript 300let list = await driver.findComponent(BY.id(Id_list)) 301let found = await list.scrollSearch(BY.text("Item3_3")) 302expect(found).assertTrue() 303``` 304 305**示例代码4**：向输入框控件中输入文本。 306 307```javascript 308let editText = await driver.findComponent(BY.type('InputText')) 309await editText.inputText("user_name") 310``` 311### 使用方式 312 313 开发者可以下载Deveco Studio创建测试工程后，在其中调用框架提供接口进行相关测试操作，测试工程创建及测试脚本执行使用指南请参见[IDE指导文档](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453)。 314 315### 推送Ui测试框架至设备 316 317> Ui测试框架3.1Release版本暂不随版本编译，使用时需自行编译后推送至OpenHarmony设备。后续随版本编译后，直接使用版本即可。 318 319#### 下载代码 320 321在工程test目录下执行如下命令下载测试框架仓代码。 322 323```shell 324git clone https://gitee.com/openharmony/arkXtest.git -b OpenHarmony-3.1-Release 325``` 326#### 编译脚本修改 327 328修改build仓中subsystem_config.json文件，增加如下字段。 329 330```shell 331"arkXtest": { 332 "path": "test/arkXtest", 333 "name": "arkXtest" 334 }, 335``` 336修改productdefine_common仓中 rk3568.json文件，增加如下字段。 337```shell 338"arkXtest:arkXtest":{}, 339``` 340#### 构建方式 341 342```shell 343./build.sh --product-name rk3568 --build-target uitestkit 344``` 345#### 推送方式 346 347```shell 348hdc_std target mount 349hdc_std shell mount -o rw,remount / 350hdc_std file send uitest /system/bin/uitest 351hdc_std file send libuitest.z.so /system/lib/module/libuitest.z.so 352hdc_std shell chmod +x /system/bin/uitest 353``` 354