1# 测试框架使用指导 2 3## 概述 4Delegator测试框架是OpenHarmony提供的一套开发者应用自测试框架，旨在为开发者提供针对应用的自测试环境。开发者可以通过Delegator类启动对应Ability，并通过Delegator类提供的能力对Ability进行生命周期切换和监听，同时支持shellCMD输入和测试结果打印显示等功能。 5 6## 约束与限制 7 8测试框架相关接口只能在测试hap包中使用，只有通过`aa test`命令或者DevEco Studio启动测试环境后相关接口才能生效。 9 10 11## 测试框架启动 12 13测试框架启动有两种方式： 14 15- 方式一：通过`aa test`命令启动。 16- 方式二：通过DevEco Studio启动。 17 18### aa test启动 19 20开发者可通过 `aa test` 命令启动测试框架，开发者可以自行指定使用的TestRunner以及TestRunner所在hap包的package name或module name，具体命令示例如下: 21 22**FA模型：** 23 24```javascript 25aa test -b BundleName -p com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 26``` 27 28**Stage模型：** 29```javascript 30aa test -b BundleName -m com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 31``` 32| 参数 | 是否必选 | 参数说明 | 33| --------------- | -------- | ------------------------------------------------------------ | 34| -b | 是 | TestRunner所在hap包的bundle name。 | 35| -p | 是 | TestRunner所在hap包的package name，FA模型使用。 | 36| -m | 是 | TestRunner所在hap包的module name，Stage模型使用。 | 37| -s unittest | 是 | 启用的TestRunner名称，TestRunner名称和文件名需要保持一致。 | 38| -w | 否 | 测试用例超时时间，单位为秒，如果未指定或指定小于等于0的整数，测试框架会一直等待测试代码调用finishTest才退出。 | 39| -s \<key>\<value> | 否 | 支持以key-value的方式输入任何参数，输入的参数可通过AbilityDelegatorArgs.parameters以key-value的方式获取。示例：-s classname myTest，key为"-s classname"，value为"myTest"。 | 40| -D | 否 | 以Debug模式启动被测试应用。 | 41| -h | 否 | 输出帮助信息。 | 42 43### DevEco Studio启动 44 45DevEco Studio启动相关介绍见 [OpenHarmony测试框架](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453#section1034420367508)。 46 47## TestRunner介绍 48 49TestRunner是测试框架测试流程入口类。当测试流程启动时，系统会调用TestRunner内相关接口，开发者需要派生该类，并重写onPrepare、onRun方法。DevEco Studio在创建应用模板时会初始化一个默认TestRunner，并在onRun方法启动默认的TestAbility。开发者也可以修改TestAbility测试代码内容，也可以修改默认的TestRunner内onPrepare、onRun方法，自行实现测试代码。具体详细内容请参考TestRunnerAPI接口说明[TestRunner](../reference/apis/js-apis-application-testRunner.md)。 50 51## AbilityDelegatorRegistry介绍 52 53AbilityDelegatorRegistry是测试框架提供的AbilityDelegator仓库类。开发者可以使用AbilityDelegatorRegistry获取AbilityDelegator实例以及执行此次测试时传入和生成的相关参数AbilityDelegatorArgs。开发者可以使用AbilityDelegator调用测试框架提供的函数集进行测试验证。具体详细内容请参考AbilityDelegatorRegistry API接口说明[AbilityDelegatorRegistry](../reference/apis/js-apis-application-abilityDelegatorRegistry.md)。 54 55## AbilityDelegatorArgs介绍 56 57AbilityDelegatorArgs是测试框架提供的测试参数类。开发者可以使用AbilityDelegatorArgs获取执行此次测试时传入和生成的相关参数。具体详细内容请参考AbilityDelegatorArgs API接口说明[AbilityDelegatorArgs](../reference/apis/js-apis-inner-application-abilityDelegatorArgs.md)。 58 59## AbilityMonitor介绍 60 61AbilityMonitor是测试框架提供用来绑定并监听Ability类。开发者可以使用AbilityMonitor绑定Ability，并将AbilityMonitor添加到监听列表。绑定后Ability的创建、生命周期变化等会触发AbilityMonitor内相关回调函数，开发者可以在对应回调函数内进行测试验证。具体详细内容请参考AbilityMonitor API接口说明[AbilityMonitor](../reference/apis/js-apis-inner-application-abilityMonitor.md)。 62 63**示例** 64 65```javascript 66import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' 67 68function onAbilityCreateCallback(data) { 69 console.info("onAbilityCreateCallback"); 70} 71 72var monitor = { 73 abilityName: "abilityname", 74 onAbilityCreate: onAbilityCreateCallback 75} 76 77var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 78abilityDelegator.addAbilityMonitor(monitor).then(() => { 79 console.info("addAbilityMonitor promise"); 80}); 81``` 82 83## AbilityDelegator介绍 84 85AbilityDelegator是测试框架主要功能类，提供了启动Ability、获取Ability示例、调度Ability生命周期、对Ability生命周期进行监听、打印测试结果等功能。 86 87**导入模块** 88 89```javascript 90import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' 91``` 92 93```javascript 94var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator() 95``` 96 97### 启动Ability并监听Ability状态变化 98 99配合AbilityMonitor使用，可以实现对Ability启动、Ability实例获取、监听状态变化功能。 100 101**示例：** 102 103```javascript 104var abilityDelegator; 105var ability; 106var timeout = 100; 107 108function onAbilityCreateCallback(data) { 109 console.info("onAbilityCreateCallback"); 110} 111 112var monitor = { 113 abilityName: "abilityname", 114 onAbilityCreate: onAbilityCreateCallback 115} 116 117abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 118abilityDelegator.waitAbilityMonitor(monitor, timeout, (err, data) => { 119 ability = data; 120 console.info("waitAbilityMonitor callback"); 121}); 122 123var want = { 124 bundleName: "bundleName", 125 abilityName: "abilityName" 126}; 127abilityDelegator.startAbility(want, (err, data) => { 128 console.info("startAbility callback"); 129}); 130``` 131 132### 调度Ability生命周期 133 134AbilityDelegator提供对Ability生命周期进行显示调度的能力，支持Foreground、Background，配合AbilityMonitor中对Ability生命周期监听方法，可以完整的测试Ability生命周期变化。具体详细内容请参考AbilityDelegator API接口说明[AbilityDelegator](../reference/apis/js-apis-inner-application-abilityDelegator.md)。 135 136### 执行shellCMD命令 137 138AbilityDelegator提供执行shellCMD命令功能，开发者可以在测试代码中执行shell命令，该功能仅在测试环境中生效，非测试环境该接口调用无效果。 139 140**示例：** 141 142```javascript 143var abilityDelegator; 144var cmd = "cmd"; 145abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 146abilityDelegator.executeShellCommand(cmd, (err, data) => { 147 console.info("executeShellCommand callback"); 148}); 149``` 150 151### 打印日志信息 152 153AbilityDelegator提供打印日志信息功能，开发者可以在测试代码中输出过程日志信息到终端控制台。 154 155**示例：** 156 157```javascript 158var abilityDelegator; 159var msg = "msg"; 160 161abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 162abilityDelegator.print(msg, (err) => { 163 console.info("print callback"); 164}); 165``` 166 167### 结束测试并打印日志信息 168 169AbilityDelegator提供主动结束测试的功能，开发者可以在测试代码中主动结束测试过程并输出日志码及信息到终端控制台。 170 171**示例：** 172 173```javascript 174var abilityDelegator; 175var msg = "msg"; 176 177abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 178abilityDelegator.finishTest(msg, 0, (err) => { 179 console.info("finishTest callback"); 180}); 181```