openharmony/arkXtest
1
0
Fork 0
mirror of https://github.com/openharmony/arkXtest.git synced 2026-07-19 12:11:44 -04:00
Code Issues Packages Projects Releases Wiki Activity

!233 优化readme资料问题

Browse Source 
Merge pull request !233 from ry/master
This commit is contained in:
openharmony_ci
2022-08-26 04:58:44 +00:00
committed by Gitee
parent 08fbbe9bf1 550d71e5ee
commit 821965285c
1 changed files with 106 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README_zh.md
+106 -106
View File
@@ -1,4 +1,4 @@
# OpenHarmony自动化测试框架使用介绍
# 自动化测试框架使用介绍
## 简介
OpenHarmony自动化测试框架代码部件仓arkXtest，包含单元测试框架(JsUnit)和Ui测试框架(UiTest)。
@@ -21,9 +21,9 @@ arkXtest
| No. | 特性 | 功能说明 |
| ---- | -------- | ------------------------------------------------------------ |
| 1 | 基础流程 | 支持编写及执行基础用例 |
| 2 | 断言库 | 判断用例实际期望值与预期值是否相符 |
| 3 | Mock能力 | 支持函数级mock能力，对定义的函数进行mock后修改函数的行为，使其返回指定的值或者执行某种动作 |
| 1 | 基础流程 | 支持编写及执行基础用例。 |
| 2 | 断言库 | 判断用例实际期望值与预期值是否相符。 |
| 3 | Mock能力 | 支持函数级mock能力，对定义的函数进行mock后修改函数的行为，使其返回指定的值或者执行某种动作。 |
### 使用说明
@@ -33,13 +33,13 @@ arkXtest
| No. | API | 功能说明 |
| ---- | ---------- | ------------------------------------------------------------ |
| 1 | describe | 定义一个测试套，支持两个参数：测试套名称和测试套函数 |
| 2 | beforeAll | 在测试套内定义一个预置条件，在所有测试用例开始前执行且仅执行一次，支持一个参数：预置动作函数 |
| 3 | beforeEach | 在测试套内定义一个单元预置条件，在每条测试用例开始前执行，执行次数与it定义的测试用例数一致，支持一个参数：预置动作函数 |
| 4 | afterEach | 在测试套内定义一个单元清理条件，在每条测试用例结束后执行，执行次数与it定义的测试用例数一致，支持一个参数：清理动作函数 |
| 5 | afterAll | 在测试套内定义一个清理条件，在所有测试用例结束后执行且仅执行一次，支持一个参数：清理动作函数 |
| 6 | it | 定义一条测试用例，支持三个参数：用例名称，过滤参数和用例函数 |
| 7 | expect | 支持bool类型判断等多种断言方法 |
| 1 | describe | 定义一个测试套，支持两个参数：测试套名称和测试套函数。 |
| 2 | beforeAll | 在测试套内定义一个预置条件，在所有测试用例开始前执行且仅执行一次，支持一个参数：预置动作函数。 |
| 3 | beforeEach | 在测试套内定义一个单元预置条件，在每条测试用例开始前执行，执行次数与it定义的测试用例数一致，支持一个参数：预置动作函数。 |
| 4 | afterEach | 在测试套内定义一个单元清理条件，在每条测试用例结束后执行，执行次数与it定义的测试用例数一致，支持一个参数：清理动作函数。 |
| 5 | afterAll | 在测试套内定义一个清理条件，在所有测试用例结束后执行且仅执行一次，支持一个参数：清理动作函数。 |
| 6 | it | 定义一条测试用例，支持三个参数：用例名称，过滤参数和用例函数。 |
| 7 | expect | 支持bool类型判断等多种断言方法。 |
示例代码：
@@ -79,18 +79,18 @@ export default async function abilityTest() {
| No. | API | 功能说明 |
| :--- | :--------------- | ------------------------------------------------------------ |
| 1 | assertClose | 检验actualvalue和expectvalue(0)的接近程度是否是expectValue(1) |
| 2 | assertContain | 检验actualvalue中是否包含expectvalue |
| 3 | assertEqual | 检验actualvalue是否等于expectvalue[0] |
| 4 | assertFail | 抛出一个错误 |
| 5 | assertFalse | 检验actualvalue是否是false |
| 6 | assertTrue | 检验actualvalue是否是true |
| 7 | assertInstanceOf | 检验actualvalue是否是expectvalue类型 |
| 8 | assertLarger | 检验actualvalue是否大于expectvalue |
| 9 | assertLess | 检验actualvalue是否小于expectvalue |
| 10 | assertNull | 检验actualvalue是否是null |
| 11 | assertThrowError | 检验actualvalue抛出Error内容是否是expectValue |
| 12 | assertUndefined | 检验actualvalue是否是undefined |
| 1 | assertClose | 检验actualvalue和expectvalue(0)的接近程度是否是expectValue(1)。 |
| 2 | assertContain | 检验actualvalue中是否包含expectvalue。 |
| 3 | assertEqual | 检验actualvalue是否等于expectvalue[0]。 |
| 4 | assertFail | 抛出一个错误。 |
| 5 | assertFalse | 检验actualvalue是否是false。 |
| 6 | assertTrue | 检验actualvalue是否是true。 |
| 7 | assertInstanceOf | 检验actualvalue是否是expectvalue类型。 |
| 8 | assertLarger | 检验actualvalue是否大于expectvalue。 |
| 9 | assertLess | 检验actualvalue是否小于expectvalue。 |
| 10 | assertNull | 检验actualvalue是否是null。 |
| 11 | assertThrowError | 检验actualvalue抛出Error内容是否是expectValue。 |
| 12 | assertUndefined | 检验actualvalue是否是undefined。 |
示例代码：
@@ -131,24 +131,24 @@ export default async function abilityTest() {
| No. | API | 功能说明 |
| --- | --- | --- |
| 1 | mockFunc( f：founction )：founction() | 对定义的方法进行mock后修改方法的行为,返回一个被修改后的方法 |
| 2 | when(mockedfunc：function) | 对传入后方法做检查，检查是否被mock并标记过，返回的是一个方法声明 |
| 3 |afterReturn(x：value) | 设定预期返回一个自定义的值value，比如某个字符串 |
| 4 | afterReturnNothing() | 设定预期没有返回值，即 undefine |
| 5 | afterAction(x：action) | 设定预期返回一个函数执行的操作 |
| 6 | afterThrow(x：msg) | 设定预期抛出异常，并指定异常msg |
| 7 | clear() | 用例执行完毕后，进行数据mocker对象的清理 |
| 8 | any | 设定用户传任何类型参数（undefine和null除外），执行的结果都是预期的值 |
| 9 | anyString | 设定用户传任何字符串参数，执行的结果都是预期的值 |
| 10 | anyBoolean | 设定用户传任何boolean类型参数，执行的结果都是预期的值 |
| 11 | anyFounction | 设定用户传任何function类型参数，执行的结果都是预期的值 |
| 12 | anyNumber | 设定用户传任何数字类型参数，执行的结果都是预期的值 |
| 13 | anyObj | 设定用户传任何对象类型参数，执行的结果都是预期的值 |
| 14 | matchRegexs(Regex) | 设定用户传任何正则表达式类型参数Regex，执行的结果都是预期的值 |
| 1 | mockFunc( f：founction )：founction() | 对定义的方法进行mock后修改方法的行为,返回一个被修改后的方法。 |
| 2 | when(mockedfunc：function) | 对传入后方法做检查，检查是否被mock并标记过，返回的是一个方法声明。 |
| 3 |afterReturn(x：value) | 设定预期返回一个自定义的值value，比如某个字符串。 |
| 4 | afterReturnNothing() | 设定预期没有返回值，即 undefine。 |
| 5 | afterAction(x：action) | 设定预期返回一个函数执行的操作。 |
| 6 | afterThrow(x：msg) | 设定预期抛出异常，并指定异常msg。 |
| 7 | clear() | 用例执行完毕后，进行数据mocker对象的清理。 |
| 8 | any | 设定用户传任何类型参数（undefine和null除外），执行的结果都是预期的值。 |
| 9 | anyString | 设定用户传任何字符串参数，执行的结果都是预期的值。 |
| 10 | anyBoolean | 设定用户传任何boolean类型参数，执行的结果都是预期的值。 |
| 11 | anyFounction | 设定用户传任何function类型参数，执行的结果都是预期的值。 |
| 12 | anyNumber | 设定用户传任何数字类型参数，执行的结果都是预期的值。 |
| 13 | anyObj | 设定用户传任何对象类型参数，执行的结果都是预期的值。 |
| 14 | matchRegexs(Regex) | 设定用户传任何正则表达式类型参数Regex，执行的结果都是预期的值。 |
- **使用示例：**
用户可以通过一下方式进行引入mock模块进行测试用例编写：
用户可以通过以下方式进行引入mock模块进行测试用例编写：
```javascript
//必须引入的mock能力模块api: MockKit, when
@@ -198,7 +198,7 @@ export default function ActsAbilityTest() {
});
}
```
- **特别注意：**
- **须知：**
`when(mockfunc)('test').afterReturn('1');`
这句代码中的`('test')`是mock后的函数需要传递的匹配参数，目前支持一个参数
`afterReturn('1')`是用户需要预期返回的结果。
@@ -253,9 +253,8 @@ export default function ActsAbilityTest() {
**示例3： 设定参数类型为any ，即接受任何参数（undefine和null除外）的使用**
```javascript
//注意需要引入ArgumentMatchers类，即参数匹配器，例如：ArgumentMatchers.any
```
须知：需要引入ArgumentMatchers类，即参数匹配器，例如：ArgumentMatchers.any
```javascript
import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
@@ -304,7 +303,8 @@ export default function ActsAbilityTest() {
}
```
**示例4： 设定参数类型为anyString,anyBoolean等 的使用**
**示例4： 设定参数类型为anyString,anyBoolean等的使用**
```javascript
import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
@@ -664,14 +664,14 @@ export default function ActsAbilityTest() {
##### 约束限制
单元测试框架数据驱动能力从[hypium 1.0.2版本](https://repo.harmonyos.com/#/cn/application/atomService/@ohos%2Fhypium)开始支持
单元测试框架数据驱动能力从[hypium 1.0.2版本](https://repo.harmonyos.com/#/cn/application/atomService/@ohos%2Fhypium)开始支持。
- 参数传递 : 为指定测试套、测试用例传递参数
- 压力测试 : 为指定测试套、测试用例的执行次数
- 参数传递 : 为指定测试套、测试用例传递参数。
- 压力测试 : 为指定测试套、测试用例的执行次数。
数据驱动可以根据配置参数来驱动测试用例的执行次数和每一次传入的参数，使用时依赖data.json配置文件，文件内容如下：
建议 : data.json与测试用例*.test.js|ets文件同目录
>说明 : data.json与测试用例*.test.js|ets文件同目录
```json
{
@@ -702,14 +702,14 @@ export default function ActsAbilityTest() {
配置参数说明：
| | 配置项名称 | 功能 |
| :--- | :--------- | :---------------------------------------- |
| 1 | "suite" | 测试套配置 (必填) |
| 2 | "items" | 测试用例配置 (必填) |
| 3 | "describe" | 测试套名称 (必填) |
| 4 | "it" | 测试用例名称 (必填) |
| 5 | "params" | 测试套 / 测试用例 可传入使用的参数 (可选) |
| 6 | "stress" | 测试套 / 测试用例 指定执行次数 (可选) |
| | 配置项名称 | 功能 | 必填 |
| :--- | :--------- | :------------------------------------ | ---- |
| 1 | "suite" | 测试套配置 。 | 是 |
| 2 | "items" | 测试用例配置 。 | 是 |
| 3 | "describe" | 测试套名称 。 | 是 |
| 4 | "it" | 测试用例名称 。 | 是 |
| 5 | "params" | 测试套 / 测试用例 可传入使用的参数 。 | 否 |
| 6 | "stress" | 测试套 / 测试用例 指定执行次数 。 | 否 |
示例代码：
@@ -753,10 +753,10 @@ export default function abilityTest() {
| No. | 特性 | 功能说明 |
| ---- | ----------- | ------------------------------------------------------------ |
| 1 | UiDriver | Ui测试的入口，提供查找控件，检查控件存在性以及注入按键能力 |
| 2 | By | 用于描述目标控件特征(文本、id、类型等)，`UiDriver`根据`By`描述的控件特征信息来查找控件 |
| 3 | UiComponent | UiDriver查找返回的控件对象，提供查询控件属性，滑动查找等触控和检视能力 |
| 4 | UiWindow | UiDriver查找返回的窗口对象，提供获取窗口属性、操作窗口的能力 |
| 1 | UiDriver | Ui测试的入口，提供查找控件，检查控件存在性以及注入按键能力。 |
| 2 | By | 用于描述目标控件特征(文本、id、类型等)，`UiDriver`根据`By`描述的控件特征信息来查找控件。 |
| 3 | UiComponent | UiDriver查找返回的控件对象，提供查询控件属性，滑动查找等触控和检视能力。 |
| 4 | UiWindow | UiDriver查找返回的窗口对象，提供获取窗口属性、操作窗口的能力。 |
**使用者在测试脚本通过如下方式引入使用：**
@@ -764,7 +764,7 @@ export default function abilityTest() {
import {UiDriver,BY,UiComponent,Uiwindow,MatchPattern} from '@ohos.uitest'
```
> 注意事项
> 须知
> 1. `By`类提供的接口全部是同步接口，使用者可以使用`builder`模式链式调用其接口构造控件筛选条件。
> 2. `UiDrivier`和`UiComponent`类提供的接口全部是异步接口(`Promise`形式)，**需使用`await`语法**。
> 3. Ui测试用例均需使用**异步**语法编写用例，需遵循单元测试框架异步用例编写规范。
@@ -798,17 +798,17 @@ export default async function abilityTest() {
`UiDriver`类作为UiTest测试框架的总入口，提供查找控件，注入按键，单击坐标，滑动控件，手势操作，截图等能力。
| No. | API | 功能描述 |
| ---- | ------------------------------------------------------------ | ---------------------- |
| 1 | create():Promise<UiDriver> | 静态方法，构造UiDriver |
| 2 | findComponent(b:By):Promise<UiComponent> | 查找匹配控件 |
| 3 | pressBack():Promise<void> | 单击BACK键 |
| 4 | click(x:number, y:number):Promise<void> | 基于坐标点的单击 |
| 5 | swipe(x1:number, y1:number, x2:number, y2:number):Promise<void> | 基于坐标点的滑动 |
| 6 | assertComponentExist(b:By):Promise<void> | 断言匹配的控件存在 |
| 7 | delayMs(t:number):Promise<void> | 延时 |
| 8 | screenCap(s:path):Promise<void> | 截屏 |
| 9 | findWindow(filter: WindowFilter): Promise<UiWindow> | 查找匹配窗口 |
| No. | API | 功能描述 |
| ---- | ------------------------------------------------------------ | ------------------------ |
| 1 | create():Promise<UiDriver> | 静态方法，构造UiDriver。 |
| 2 | findComponent(b:By):Promise<UiComponent> | 查找匹配控件。 |
| 3 | pressBack():Promise<void> | 单击BACK键。 |
| 4 | click(x:number, y:number):Promise<void> | 基于坐标点的单击。 |
| 5 | swipe(x1:number, y1:number, x2:number, y2:number):Promise<void> | 基于坐标点的滑动。 |
| 6 | assertComponentExist(b:By):Promise<void> | 断言匹配的控件存在。 |
| 7 | delayMs(t:number):Promise<void> | 延时。 |
| 8 | screenCap(s:path):Promise<void> | 截屏。 |
| 9 | findWindow(filter: WindowFilter): Promise<UiWindow> | 查找匹配窗口。 |
其中assertComponentExist接口是断言API，用于断言当前界面存在目标控件；如果控件不存在，该API将抛出JS异常，使当前测试用例失败。
@@ -841,18 +841,18 @@ Ui测试框架通过`By`类提供了丰富的控件特征描述API，用来匹
- 控件属性支持多种匹配模式(等于，包含，`STARTS_WITH`，`ENDS_WITH`)。
- 支持相对定位控件，可通过`isBefore`和`isAfter`等API限定邻近控件特征进行辅助定位。
| No. | API | 功能描述 |
| ---- | ---------------------------------- | ---------------------------------------------- |
| 1 | id(i:number):By | 指定控件id |
| 2 | text(t:string, p?:MatchPattern):By | 指定控件文本，可指定匹配模式 |
| 3 | type(t:string)):By | 指定控件类型 |
| 4 | enabled(e:bool):By | 指定控件使能状态 |
| 5 | clickable(c:bool):By | 指定控件可单击状态 |
| 6 | focused(f:bool):By | 指定控件获焦状态 |
| 7 | scrollable(s:bool):By | 指定控件可滑动状态 |
| 8 | selected(s:bool):By | 指定控件选中状态 |
| 9 | isBefore(b:By):By | **相对定位**，限定目标控件位于指定特征控件之前 |
| 10 | isAfter(b:By):By | **相对定位**，限定目标控件位于指定特征控件之后 |
| No. | API | 功能描述 |
| ---- | ---------------------------------- | ------------------------------------------------ |
| 1 | id(i:number):By | 指定控件id。 |
| 2 | text(t:string, p?:MatchPattern):By | 指定控件文本，可指定匹配模式。 |
| 3 | type(t:string)):By | 指定控件类型。 |
| 4 | enabled(e:bool):By | 指定控件使能状态。 |
| 5 | clickable(c:bool):By | 指定控件可单击状态。 |
| 6 | focused(f:bool):By | 指定控件获焦状态。 |
| 7 | scrollable(s:bool):By | 指定控件可滑动状态。 |
| 8 | selected(s:bool):By | 指定控件选中状态。 |
| 9 | isBefore(b:By):By | **相对定位**，限定目标控件位于指定特征控件之前。 |
| 10 | isAfter(b:By):By | **相对定位**，限定目标控件位于指定特征控件之后。 |
其中，`text`属性支持{`MatchPattern.EQUALS`，`MatchPattern.CONTAINS`，`MatchPattern.STARTS_WITH`，`MatchPattern.ENDS_WITH`}四种匹配模式，缺省使用`MatchPattern.EQUALS`模式。
@@ -900,15 +900,15 @@ let switch = await driver.findComponent(BY.id(Id_switch).isAfter(BY.text("Item3_
`UiComponent`包含的常用API：
| No. | API | 功能描述 |
| ---- | --------------------------------- | -------------------------------------------- |
| 1 | click():Promise<void> | 单击该控件 |
| 2 | inputText(t:string):Promise<void> | 向控件中输入文本(适用于文本框控件) |
| 3 | scrollSearch(s:By):Promise<bool> | 在该控件上滑动查找目标控件(适用于List等控件) |
| 4 | getText():Promise<string> | 获取控件text |
| 5 | getId():Promise<number> | 获取控件id |
| 6 | getType():Promise<string> | 获取控件类型 |
| 7 | isEnabled():Promise<bool> | 获取控件使能状态 |
| No. | API | 功能描述 |
| ---- | --------------------------------- | ---------------------------------------------- |
| 1 | click():Promise<void> | 单击该控件。 |
| 2 | inputText(t:string):Promise<void> | 向控件中输入文本(适用于文本框控件)。 |
| 3 | scrollSearch(s:By):Promise<bool> | 在该控件上滑动查找目标控件(适用于List等控件)。 |
| 4 | getText():Promise<string> | 获取控件text。 |
| 5 | getId():Promise<number> | 获取控件id。 |
| 6 | getType():Promise<string> | 获取控件类型。 |
| 7 | isEnabled():Promise<bool> | 获取控件使能状态。 |
`UiComponent`完整的API列表请参考[API文档](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.uitest.d.ts)及[示例文档说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-uitest.md#uicomponent)。
@@ -946,15 +946,15 @@ await editText.inputText("user_name")
`UiWindow`包含的常用API：
| No. | API | 功能描述 |
| ---- | ------------------------------------------------------------ | ------------------------------------------------ |
| 1 | getBundleName(): Promise<string> | 获取窗口所属应用包名 |
| 2 | getTitle(): Promise<string> | 获取窗口标题信息 |
| 3 | focus(): Promise<bool> | 使得当前窗口获取焦点 |
| 4 | moveTo(x: number, y: number): Promise<bool>; | 将当前窗口移动到指定位置（适用于支持移动的窗口） |
| 5 | resize(wide: number, height: number, direction: ResizeDirection): Promise<bool> | 调整窗口大小（适用于支持调整大小的窗口） |
| 6 | split(): Promise<bool> | 将窗口模式切换为分屏模式(适用于支持分屏的窗口) |
| 7 | close(): Promise<bool> | 关闭当前窗口 |
| No. | API | 功能描述 |
| ---- | ------------------------------------------------------------ | -------------------------------------------------- |
| 1 | getBundleName(): Promise<string> | 获取窗口所属应用包名。 |
| 2 | getTitle(): Promise<string> | 获取窗口标题信息。 |
| 3 | focus(): Promise<bool> | 使得当前窗口获取焦点。 |
| 4 | moveTo(x: number, y: number): Promise<bool>; | 将当前窗口移动到指定位置（适用于支持移动的窗口）。 |
| 5 | resize(wide: number, height: number, direction: ResizeDirection): Promise<bool> | 调整窗口大小（适用于支持调整大小的窗口）。 |
| 6 | split(): Promise<bool> | 将窗口模式切换为分屏模式(适用于支持分屏的窗口)。 |
| 7 | close(): Promise<bool> | 关闭当前窗口。 |
`UiWindow`完整的API列表请参考[API文档](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.uitest.d.ts)及[示例文档说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-uitest.md#uiwindow9)。
@@ -982,15 +982,15 @@ await window.close()
### 使用方式
开发者可以下载Deveco Studio创建测试工程后，在其中调用框架提供接口进行相关测试操作，测试工程创建及测试脚本执行使用指南请参见[IDE指导文档](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453)。
> UI测试框架使能需要执行如下命令。
UI测试框架使能需要执行如下命令。
>```shell
> hdc_std shell param set persist.ace.testmode.enabled 1
>```
### UI测试框架自构建方式
> Ui测试框架在OpenHarmony-3.1-Release版本中未随版本编译，需手动处理，具体指导请[参考](https://gitee.com/openharmony/arkXtest/blob/OpenHarmony-3.1-Release/README_zh.md#%E6%8E%A8%E9%80%81ui%E6%B5%8B%E8%AF%95%E6%A1%86%E6%9E%B6%E8%87%B3%E8%AE%BE%E5%A4%87)。
> Ui测试框架在OpenHarmony-3.1-Release版本中未随版本编译，需手动处理，请参考[3.1-Release版本使用指导](https://gitee.com/openharmony/arkXtest/blob/OpenHarmony-3.1-Release/README_zh.md#%E6%8E%A8%E9%80%81ui%E6%B5%8B%E8%AF%95%E6%A1%86%E6%9E%B6%E8%87%B3%E8%AE%BE%E5%A4%87)。
开发者如需自行编译Ui测试框架代码验证子修改内容，编译命令和推送位置请参考本章节内容。
开发者如需自行编译Ui测试框架代码验证子修改内容，构建命令和推送位置请参考本章节内容。
#### 构建命令
@@ -1009,6 +1009,6 @@ hdc_std shell chmod +x /system/bin/uitest
### 版本信息
| 版本号 | 功能说明 |
| :-----: | :----------------------------------------------------------: |
| 版本号 | 功能说明 |
| :------ | :----------------------------------------------------------- |
| 3.2.2.1 | 1、增加抛滑、获取/设置屏幕方向接口<br />2、窗口处理逻辑增加不支持场景处理逻辑 |