diff --git a/zh-cn/application-dev/ability/Readme-CN.md b/zh-cn/application-dev/ability/Readme-CN.md index f3b879e4b906488fff13331e10d006dcd98f0a51..c72f9c18af7f90498f5eac50aff092c06fa8ceeb 100644 --- a/zh-cn/application-dev/ability/Readme-CN.md +++ b/zh-cn/application-dev/ability/Readme-CN.md @@ -7,12 +7,10 @@ - [DataAbility开发指导](fa-dataability.md) - [FormAbility开发指导](fa-formability.md) - Stage模型 - - [Stage模型综述](stage-brief.md) - - [Ability开发指导](stage-ability.md) - [ServiceExtensionAbility开发指导](stage-serviceextension.md) - - [FormExtensionAbility开发指导](stage-formextension.md) - [应用迁移开发指导](stage-ability-continuation.md) - [Call调用开发指导](stage-call.md) - 其他 - [WantAgent使用指导](wantagent.md) - - [Ability助手使用指导](ability-assistant-guidelines.md) \ No newline at end of file + - [Ability助手使用指导](ability-assistant-guidelines.md) + - [测试框架使用指导](ability-delegator.md) \ No newline at end of file diff --git a/zh-cn/application-dev/ability/ability-delegator.md b/zh-cn/application-dev/ability/ability-delegator.md new file mode 100755 index 0000000000000000000000000000000000000000..891e6642e5015a6a860d0f1b566003b9cfe4fbfe --- /dev/null +++ b/zh-cn/application-dev/ability/ability-delegator.md @@ -0,0 +1,129 @@ +# 测试框架使用指导 + +Delegator测试框架是OpenHarmony提供的一套开发者应用自测试框架,旨在为开发者提供针对应用的自测试环境。开发者可以通过delegator类启动对应Ability,并通过Delegator类提供的能力对Ability进行生命周期切换和监听,同时支持shellCMD输入和测试结果打印显示等功能。 + +## 测试框架启动 + +测试框架启动有两种方式,方式一:通过aa test命令启动,方式二:通过IDE启动。 +### aa test启动 + +开发者可通过 aa test 命令启动启动测试框架,开发者可以自行指定使用的runner以及runner所在hap包的package name/module name,具体命令示例如下: + +**FA模型:** + +```javascript +aa test -p com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 +``` + +**Stage模型:** +```javascript +aa test -m com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 +``` +| 参数 | 是否必选 | 参数说明 | +| --------------- | -------- | ------------------------------------------------------------ | +| -p | 是 | TestRunner所在hap包的package name,FA模型使用。 | +| -m | 是 | TestRunner所在hap包的module name,stage模型使用。 | +| -s unittest | 是 | 启用的TestRunner名称,TestRunner名称和文件名需要保持一致。 | +| -w | 否 | 测试用例超时时间,如果未指定,测试框架会一直等待测试代码调用finishTest才退出。 | +| -s | 否 | 支持以key-value的方式输入任何参数,输入的参数可通过AbilityDelegatorArgs.parameters以key-value的方式获取。 | + +### IDE启动 + +IDE文档中介绍,待IDE文档上库补充链接。 + +## TestRunner介绍 + +TestRunner是测试框架测试流程入口类,当测试流程启动时,系统会调用TestRunner内相关接口,开发者需要派生该类,并重写onPrepare、onRun方法。IDE在创建应用模板时会初始化一个默认TestRunner,并在onRun方法启动默认的TestAbility。开发者也可以修改TestAbility测试代码内容,也可以修改默认的TestRunner内onPrepare、onRun方法,自行实现测试代码。具体详细内容请参考TestRunnerAPI接口说明[TestRunner](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-testRunner.md)。 + +## AbilityMonitor介绍 + +AbilityMonitor是测试框架提供用来绑定并监听Ability类,开发者可以使用AbilityMonitor绑定Ability,并将AbilityMonitor添加到监听列表。绑定后Ability的创建、生命周期变化等会触发AbilityMonitor内相关回调函数,开发者可以在对应回调函数内进行测试验证。具体详细内容请参考AbilityMonitor API接口说明[AbilityMonitor](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-application-abilityMonitor.md)。 + +**示例** + +```javascript +import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' + +function onAbilityCreateCallback() { + console.info("onAbilityCreateCallback"); +} + +var monitor = { + abilityName: "abilityname", + onAbilityCreate: onAbilityCreateCallback +} + +var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.addAbilityMonitor(monitor).then((void) => { + console.info("addAbilityMonitor promise"); +}); +``` + +## AbilityDelegator介绍 + +AbilityDelegator是测试框架主要功能类,提供了启动Ability、获取Ability示例、调度Ability生命周期、对Ability生命周期进行监听、打印测试结果等功能。 + +**导入模块** + +```javascript +import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' +``` + +```javascript +var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator() +``` + +### 启动Ability并监听Ability状态变化 + +配合AbilityMonitor使用,可以实现对Ability启动、Ability实例获取、监听状态变化功能。 + +**示例:** + +```javascript +var abilityDelegator; +var ability; +var timeout = 100; + +function onAbilityCreateCallback() { + console.info("onAbilityCreateCallback"); +} + +var monitor = { + abilityName: "abilityname", + onAbilityCreate: onAbilityCreateCallback +} + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.waitAbilityMonitor(monitor, timeout, (err, data) => { + ability = data; + console.info("waitAbilityMonitor callback"); +}); + +var want = { + bundleName: "bundleName", + abilityName: "abilityName" +}; + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.startAbility(want, (err, data) => { + console.info("startAbility callback"); +}); +``` + +### 调度Ability生命周期 + +AbilityDelegator提供对Ability生命周期进行显示调度,支持Foreground、Background,配合AbilityMonitor中对Ability生命周期监听方法,可以完整的测试Ability生命周期变化。具体详细内容请参考AbilityDelegator API接口说明[AbilityDelegator](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-application-abilityDelegator.md#abilitydelegator)。 + +### 执行shellCMD命令 + +AbilityDelegator提供执行shellCMD命令功能,开发者可以在测试代码中执行shell命令,该功能仅在测试环境中生效,非测试环境该接口调用无效果。 +**示例:** + +```javascript + var abilityDelegator; + var cmd = "cmd"; + abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); + abilityDelegator.executeShellCommand(cmd, (err,data) => { + console.info("executeShellCommand callback"); + }); +``` \ No newline at end of file diff --git a/zh-cn/application-dev/ability/fa-pageability.md b/zh-cn/application-dev/ability/fa-pageability.md index be05ac164e0c7d39c4f409b122fe5178f07f1a94..47db1b8792b47b81abf0e492529c9d3f337ceea4 100644 --- a/zh-cn/application-dev/ability/fa-pageability.md +++ b/zh-cn/application-dev/ability/fa-pageability.md @@ -186,4 +186,10 @@ var promise = await featureAbility.startAbility({ }, } ); -``` \ No newline at end of file +``` +## 开发实例 +针对pageAbility开发,有以下示例工程可供参考: + +- [DMS](https://gitee.com/openharmony/app_samples/tree/master/ability/DMS) + +在本示例中完整展示了启动本地Ability、启动远程Ability的使用方法。 \ No newline at end of file