!19465 自动化测试框架内容优化

Merge pull request !19465 from ningning/master

zh-cn/application-dev/application-test/arkxtest-guidelines.md

@@ -3,42 +3,38 @@
 
 ## 概述
 
-为支撑OpenHarmony操作系统的自动化测试活动开展，我们提供了支持JS/TS语言的单元及UI测试框架，支持开发者针对应用接口或系统接口进行单元测试，并且可基于UI操作进行UI自动化脚本的编写。
+OpenHarmony的自动化测试框架arkxtest，作为工具集的重要组成部分，支持JS/TS语言的单元测试框架(JsUnit)及UI测试框架(UiTest)。<br>JsUnit提供单元测试用例执行能力，提供用例编写基础接口，生成对应报告，用于测试系统或应用接口。<br>UiTest通过简洁易用的API提供查找和操作界面控件能力，支持用户开发基于界面操作的自动化测试脚本。本指南介绍了测试框架的主要功能、实现原理、环境准备，以及测试脚本编写和执行等内容。
 
-本指南重点介绍自动化测试框架的主要功能，同时介绍编写单元/UI自动化测试脚本的方法以及执行过程。
 
+## 实现原理
 
-### 简介
+测试框架分为单元测试框架和UI测试框架。<br>单元测试框架是测试框架的基础底座，提供了最基本的用例识别、调度、执行及结果汇总的能力。<br>UI测试框架主要对外提供了UiTest API供开发人员在对应测试场景调用，而其脚本的运行基础仍是单元测试框架。
 
-OpenHarmony自动化测试框架arkxtest，作为OpenHarmony工具集的重要组成部分，提供了OpenHarmony自动化脚本编写和运行的基础能力。编写方面提供了一系列支持测试脚本编写的API，包括了基础流程API、断言API以及UI操作相关的API，运行方面提供了识别测试脚本、调度执行测试脚本以及汇总测试脚本执行结果的能力。
+### 单元测试框架
 
-
-### 实现原理
-
-框架重要分为两大部分：单元测试框架和UI测试框架。
-
-- 单元测试框架
-
-  单元测试框架是测试框架的基础底座，提供了最基本的用例识别、调度、执行及结果汇总的能力。主要功能如下图所示：
+  图1.单元测试框架主要功能
 
   ![](figures/UnitTest.PNG)
 
-  单元测试脚本的基础运行流程如下图所示，依赖aa test命令作为执行入口。
-  
+  图2.脚本基础流程运行图
+ 
   ![](figures/TestFlow.PNG)
 
-- UI测试框架
+> **说明：**
+>
+> 单元测试框架中的函数具体含义请参考[函数定义](https://gitee.com/openharmony/testfwk_arkxtest/blob/master/README_zh.md#%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E)。
 
-  UI测试框架主要对外提供了[UiTest API](../reference/apis/js-apis-uitest.md)供开发人员在对应测试场景调用，而其脚本的运行基础还是上面提到的单元测试框架。
+### UI测试框架
 
-  UI测试框架的主要功能如下图所示：
+  图3.UI测试框架主要功能
 
   ![](figures/Uitest.PNG)
 
 
-### 约束与限制
+## 约束与限制
 
 - UI测试框架的能力在OpenHarmony 3.1 release版本之后方可使用，历史版本不支持使用。
+
 - 单元测试框架的部分能力与其版本有关，具体能力与版本匹配信息可见代码仓中的[文档介绍](https://gitee.com/openharmony/testfwk_arkxtest/blob/master/README_zh.md)。
 
 
@@ -62,6 +58,18 @@ DevEco Studio可参考其官网介绍进行[下载](https://developer.harmonyos.
 
 ## 编写单元测试脚本
 
+本章节主要描述单元测试框架支持能力，以及能力的使用方法。
+
+在单元测试框架，测试脚本需要包含如下基本元素:
+
+1、依赖导包，以便使用依赖的测试接口。
+
+2、测试代码编写，主要编写测试代码的相关逻辑，如接口调用等。
+
+3、断言接口调用，设置测试代码中的检查点，如无检查点，则不可认为一个完整的测试脚本。
+
+如下示例代码实现的场景是：启动测试页面，检查设备当前显示的页面是否为预期页面。
+
 ```TS
 import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium';
 import abilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry';
@@ -93,25 +101,17 @@ export default function abilityTest() {
 }
 ```
 
-单元测试脚本需要包含如下基本元素：
-
-1、依赖导包，以便使用依赖的测试接口。
-
-2、测试代码编写，主要编写测试代码的相关逻辑，如接口调用等。
-
-3、断言接口调用，设置测试代码中的检查点，如无检查点，则不可认为一个完整的测试脚本。
-
 ## 编写UI测试脚本
 
-UI测试脚本是在单元测试框架的基础上编写，主要就是增加了UI测试框架提供的接口调用，实现对应的测试逻辑。
+本章节主要介绍UI测试框架支持能力，以及对应能力API的使用方法。<br>UI测试基于单元测试，UI测试脚本在单元测试脚本上增加了对UiTest接口（提供链接）调用，进而完成对应的测试活动。<br>如下的示例代码是在上面的单元测试脚本基础上增量编写，实现的是在启动的应用页面上进行点击操作，然后检测当前页面变化是否为预期变化。
 
-下面的示例代码是在上面的测试脚本基础上增量编写，首先需要增加依赖导包，如下示例代码所示：
+1.增加依赖导包。
 
 ```js
 import {Driver,ON,Component,MatchPattern} from '@ohos.uitest'
 ```
 
-然后是具体测试代码编写，场景较为简单，就是在启动的应用页面上进行点击操作，然后增加检查点检查用例。
+2.编写具体测试代码。
 
 ```js
 export default function abilityTest() {
@@ -158,11 +158,11 @@ export default function abilityTest() {
 
 通过点击按钮执行，当前支持以下执行方式：
 
-1、测试包级别执行即执行测试包内的全部用例。
+1、测试包级别执行，即执行测试包内的全部用例。
 
-2、测试套级别执行即执行describe方法中定义的全部测试用例。
+2、测试套级别执行，即执行describe方法中定义的全部测试用例。
 
-3、测试方法级别执行即执行指定it方法也就是单条测试用例。
+3、测试方法级别执行，即执行指定it方法也就是单条测试用例。
 
 ![](figures/Execute.PNG)
 
@@ -172,9 +172,17 @@ export default function abilityTest() {
 
 ![](figures/TestResult.PNG)
 
+**查看测试用例覆盖率**
+
+执行完测试用例后可以查看测试用例覆盖率，具体操作请参考[OpenHarmony Test代码覆盖率统计](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/harmonyos_jnit_jsunit-0000001092459608-V3?catalogVersion=V3#section1989615417457)
+
 ### CMD执行
 
-通过在cmd窗口中输入aa命令执行触发用例执行，并通过设置执行参数触发不同功能。
+将应用测试包安装到测试设备上，在cmd窗口中执行aa命令，完成对用例测试。
+
+> **说明：**
+>
+> 使用cmd的方式，需要配置好hdc相关的环境变量。
 
 **aa test命令执行配置参数**
 
@@ -201,74 +209,72 @@ export default function abilityTest() {
 | size         | 指定要执行用例的用例规模                                    | small，medium，large                                         | -s size small        
 | stress       | 指定要执行用例的执行次数                                    |  正整数                                         | -s stress 1000                            |
 
-**通过在cmd窗口直接执行命令。**
-
-> 使用cmd的方式，需要配置好hdc相关的环境变量
+**cmd窗口执行test命令**
 
 - 打开cmd窗口
 - 执行 aa test 命令
 
-**示例代码1**：执行所有测试用例。
+示例代码1：执行所有测试用例。
 
 ```shell  
  hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner
 ```
 
-**示例代码2**：执行指定的describe测试套用例，指定多个需用逗号隔开。
+示例代码2：执行指定的describe测试套用例，指定多个需用逗号隔开。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner -s class s1,s2
 ```
 
-**示例代码3**：执行指定测试套中指定的用例，指定多个需用逗号隔开。
+示例代码3：执行指定测试套中指定的用例，指定多个需用逗号隔开。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner -s class testStop#stop_1,testStop1#stop_0
 ```
 
-**示例代码4**：执行指定除配置以外的所有的用例，设置不执行多个测试套需用逗号隔开。
+示例代码4：执行指定除配置以外的所有的用例，设置不执行多个测试套需用逗号隔开。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner -s notClass testStop
 ```
 
-**示例代码5**：执行指定it名称的所有用例，指定多个需用逗号隔开。
+示例代码5：执行指定it名称的所有用例，指定多个需用逗号隔开。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner -s itName stop_0
 ```
 
-**示例代码6**：用例执行超时时长配置。
+示例代码6：用例执行超时时长配置。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner  -s timeout 15000
 ```
 
-**示例代码7**：用例以breakOnError模式执行用例。
+示例代码7：用例以breakOnError模式执行用例。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner   -s breakOnError true
 ```
 
-**示例代码8**：执行测试类型匹配的测试用例。
+示例代码8：执行测试类型匹配的测试用例。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner   -s testType function
 ```
 
-**示例代码9**：执行测试级别匹配的测试用例。
+示例代码9：执行测试级别匹配的测试用例。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner   -s level 0
 ```
 
-**示例代码10**：执行测试规模匹配的测试用例。
+示例代码10：执行测试规模匹配的测试用例。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner   -s size small
 ```
 
-**示例代码11**：执行测试用例指定次数。
+示例代码11：执行测试用例指定次数。
 
 ```shell  
   hdc shell aa test -b xxx -p xxx -s unittest OpenHarmonyTestRunner   -s stress 1000
@@ -299,14 +305,14 @@ OHOS_REPORT_STATUS: consuming=4
 
 | 日志输出字段               | 日志输出字段含义       |
 | -------           | -------------------------|
-| OHOS_REPORT_SUM    | 当前测试套用例总数 |
-| OHOS_REPORT_STATUS: class | 当前执行用例测试套名称|
-| OHOS_REPORT_STATUS: id | 用例执行语言,默认JS  |
-| OHOS_REPORT_STATUS: numtests | 测试包中测试用例总数 |
-| OHOS_REPORT_STATUS: stream | 当前用例发生错误时，记录错误信息 |
-| OHOS_REPORT_STATUS: test| 当前用例执行的it name |
-| OHOS_REPORT_STATUS_CODE | 当前用例执行结果状态 0 (pass) 1(error) 2(fail) |
-| OHOS_REPORT_STATUS: consuming | 当前用例执行消耗的时长 |
+| OHOS_REPORT_SUM    | 当前测试套用例总数。 |
+| OHOS_REPORT_STATUS: class | 当前执行用例测试套名称。|
+| OHOS_REPORT_STATUS: id | 用例执行语言,默认JS。  |
+| OHOS_REPORT_STATUS: numtests | 测试包中测试用例总数 。|
+| OHOS_REPORT_STATUS: stream | 当前用例发生错误时，记录错误信息。 |
+| OHOS_REPORT_STATUS: test| 当前用例执行的it name。 |
+| OHOS_REPORT_STATUS_CODE | 当前用例执行结果状态。0表示通过，1表示错误，2表示失败。|
+| OHOS_REPORT_STATUS: consuming | 当前用例执行消耗的时长（ms）。 |
 
 - cmd执行完成后,会打印如下相关日志信息。
 
@@ -320,14 +326,70 @@ OHOS_REPORT_STATUS: taskconsuming=16029
 ```
 | 日志输出字段               | 日志输出字段含义           |
 | ------------------| -------------------------|
-| run    | 当前测试包用例总数 |
-| Failure | 当前测试失败用例个数 |
-| Error | 当前执行用例发生错误用例个数  |
-| Pass | 当前执行用例通过用例个数 |
-| Ignore | 当前未执行用例个数 |
-| taskconsuming| 执行当前测试用例总耗时 |
+| run    | 当前测试包用例总数。 |
+| Failure | 当前测试失败用例个数。 |
+| Error | 当前执行用例发生错误用例个数。  |
+| Pass | 当前执行用例通过用例个数 。|
+| Ignore | 当前未执行用例个数。 |
+| taskconsuming| 执行当前测试用例总耗时（ms）。 |
+
+> 当处于breakOnError模式，用例发生错误时,注意查看Ignore以及中断说明。
+
+## 相关实例
+
+### 单元测试脚本实例
+
+#### 单元测试断言功能使用实例
+介绍单元测试框架中支持的断言能力如何使用，具体代码请查看[断言能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/jsunit/entry/src/ohosTest/ets/test/assertExampleTest/assertExample.test.ets)
+
+#### 单元测试测试套定义使用实例
+介绍单元测试框架测试套嵌如何定义，包括嵌套定义能力，具体代码请参考[测试套嵌套示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/jsunit/entry/src/ohosTest/ets/test/coverExampleTest/coverExample.test.ets)
+
+#### 单元测试测试应用自定义函数使用实例
+介绍针对应用内自定义函数如何使用框架能力进行测试，具体代码请参考[应用自定义函数测试示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/jsunit/entry/src/ohosTest/ets/test/customExampleTest/customExample.test.ets)
+
+#### 单元测试数据驱动能力使用实例
+介绍测试框架数据驱动能力、脚本重复执行配置功能，具体代码请参考[数据驱动能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/jsunit/entry/src/ohosTest/ets/test/paramExampleTest/paramExample.test.ets)
+
+### UI测试脚本实例（控件类）
+
+#### 查找指定控件能力实例
+介绍通过设置控件属性作为查找条件，在应用界面上查找组件对象，具体代码请参考[控件查找示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/findCommentExampleTest/Component/findCommentExample.test.ets)
+
+#### 模拟点击操作事件能力实例
+介绍模拟用户在应用界面上进行点击，长按，双击等事件,具体代码请参考[点击事件示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/ui/clickEvent.test.ets)
 
-> 当处于breakOnError模式，用例发生错误时,注意查看Ignore以及中断说明
+#### 模拟鼠标操作能力实例
+介绍模拟鼠标左击、右击、滑轮事件,具体代码请参考[鼠标操作事件示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/ui/MouseEvent.test.ets)
+
+#### 模拟文本输入能力实例
+介绍模拟输入中文、英文文本内容，使用前提是针对可以输入文本的组件类似文本框等组件进行操作，具体代码请参考[文本输入能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/ui/InputEvent.test.ets)
+
+#### 截图能力实例
+介绍屏幕截图功能，包括指定区域截图能力，具体代码请参考[截图能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/ui/ScreenCapEvent.test.ets)
+
+#### 模拟快滑操作能力实例
+介绍模拟快滑操作能力，即在可滑动页面上进行滑动，滑动后手指离开屏幕，具体代码请参考[模拟快滑操作能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/ui/FlingEvent.test.ets)
+
+#### 模拟慢滑操作能力实例
+介绍模拟慢滑操作能力，即在可滑动页面上进行滑动，滑动后手指仍停留在屏幕，具体代码请参考[模拟慢滑操作能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/ui/SwipeEvent.test.ets)
+
+#### 模拟缩放操作能力实例
+介绍模拟缩放能力，即在支持放大缩小的图片上，模拟双指缩放操作的能力，具体代码请参考[模拟缩放操作能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/ui/PinchEvent.test.ets)
+
+#### 模拟滚动到组件顶端或底端能力实例
+介绍模拟针对滑动类组件，可以模拟操作直接滚动到组件顶端或底端，具体代码请参考[模拟滚动到组件顶端或底端示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/ui/ScrollerEvent.test.ets)
+
+### UI测试脚本实例（窗口类）
+
+#### 查找指定窗口能力实例
+介绍通过应用报名查找应用窗口，具体代码请参考[查找指定窗口能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/findCommentExampleTest/window/findWindowExample.test.ets)
+
+#### 模拟窗口移动能力实例
+介绍模拟移动窗口到指定位置能力，具体代码请参考[模拟窗口移动示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/window/MoveToEvent.test.ets)
+
+#### 模拟调整窗口大小能力实例
+介绍模拟调整窗口大小能力，并可指定调整的具体方向，具体代码请参考[模拟调整窗口大小能力示例](https://gitee.com/openharmony/applications_app_samples/blob/master/code/Project/Test/uitest/entry/src/ohosTest/ets/test/operationExampleTest/window/ReSizeWindow.test.ets)
 
 ## 常见问题
 
@@ -422,7 +484,7 @@ UI测试用例执行失败，查看hilog日志发现日志中有“uitest-api do
 
 **3、失败日志有“does not exist on current UI! Check if the UI has changed after you got the widget object”错误信息**
 
-**问题描述**
+**问题描述** 
 
 UI测试用例执行失败，查看hilog日志发现日志中有“does not exist on current UI! Check if the UI has changed after you got the widget object”错误信息。