diff --git a/en/application-dev/ability/ability-delegator.md b/en/application-dev/ability/ability-delegator.md index cbf823bacad7b9781d90c8a86224893740444f35..4e27041093bc2b9d1e3a2966f7a5f20b0f51b94c 100644 --- a/en/application-dev/ability/ability-delegator.md +++ b/en/application-dev/ability/ability-delegator.md @@ -1,60 +1,71 @@ # Test Framework Usage ## Overview -The delegator test framework provides a self-test framework (environment) for OpenHarmony applications. Using this framework, you can start an ability, schedule its lifecycle, listen for its state changes, run a shell command, and print the test result. +The delegator test framework provides a self-test environment for OpenHarmony applications. Using this framework, you can start an ability, schedule its lifecycle, listen for its state changes, run a shell command, and print the test result. ## Constraints -The APIs provided by the test framework can be used only in the test HAP. They take effect only after the test framework is started by running the **aa test** command or using the Integrated Development Environment (IDE). +The APIs provided by the test framework can be used only in the test HAP. They take effect only after the test framework is started. ## Starting the Test Framework -The test framework can be started using either of the following methods: +The test framework can be started in either of the following ways: -- Method 1: Run the **aa test** command. +- Method 1: Run the aa test command. - Method 2: Use the IDE. ### Running aa test -You can run the **aa test** command to start the test framework. You can specify the **TestRunner** to be used and the package name or module name of the HAP where the **TestRunner** is located. +To start the test framework, specify the **TestRunner** and the package name or module name of the HAP where the **TestRunner** is located. An example command in the FA model is as follows: ```javascript -aa test -p com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 +aa test -b BundleName -p com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 ``` An example command in the stage model is as follows: ```javascript -aa test -m com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 +aa test -b BundleName -m com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 ``` | Parameter | Mandatory| Description | | --------------- | -------- | ------------------------------------------------------------ | +| -b | Yes | Bundle name of the HAP where the **TestRunner** is located. | | -p | Yes | Package name of the HAP where the **TestRunner** is located. This parameter is used by the FA model. | | -m | Yes | Module name of the HAP where the **TestRunner** is located. This parameter is used by the stage model. | | -s unittest | Yes | Name of the **TestRunner** to be used. The TestRunner name must be the same as the file name. | -| -w | No | Timeout interval of a test case, in seconds. If this parameter is not specified, the test framework exits only after **finishTest** is invoked.| -| -s | No | It can be any parameter in the key-value format. The entered parameters can be obtained in key-value mode through **AbilityDelegatorArgs.parameters**. For example, in **-s classname myTest**, **classname** is the key and **myTest** is the value.| +| -w | No | Timeout interval of a test case, in seconds. If this parameter is not specified or is set to a value less than or equal to **0**, the test framework exits only after **finishTest** is invoked.| +| -s \\ | No | **-s** can be followed by any key-value pair obtained through **AbilityDelegatorArgs.parameters**. For example, in **-s classname myTest**, **-s classname** is the key and **myTest** is the value.| +| -D | No | Debug mode for starting the tested application. | +| -h | No | Help information. | ### Using the IDE -For details about how to start the IDE, see [IDE Guide](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453#section1034420367508). +For details about how to use the IDE to start the test framework, see [IDE Guide](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453#section1034420367508). ## Introduction to TestRunner **TestRunner** is the entry class of the test framework test process. When the test process is started, the system calls related APIs in **TestRunner**. You need to inherit this class and override the **onPrepare** and **onRun** APIs. When creating an application template, the IDE initializes the default **TestRunner** and starts the default **TestAbility** in the **onRun** API. You can modify the test code of **TestAbility** or override **onPrepare** and **onRun** in **TestRunner** to implement your own test code. For details, see [TestRunner](../reference/apis/js-apis-testRunner.md). +## Introduction to AbilityDelegatorRegistry + +**AbilityDelegatorRegistry** is the **AbilityDelegator** repository class provided by the test framework. You can use **AbilityDelegatorRegistry** to obtain an **AbilityDelegator** instance and the input and generated parameters **AbilityDelegatorArgs** during the test. You can use **AbilityDelegator** to invoke the function set provided by the test framework for testing and verification. For details, see [AbilityDelegatorRegistry](../reference/apis/js-apis-abilityDelegatorRegistry.md). + +## Introduction to AbilityDelegatorArgs + +**AbilityDelegatorArgs** is a test parameter class provided by the test framework. You can use **AbilityDelegatorArgs** to obtain the parameters passed and generated during the test. For details, see [AbilityDelegatorArgs](../reference/apis/js-apis-application-abilityDelegatorArgs.md). + ## Introduction to AbilityMonitor -**AbilityMonitor** is provided by the test framework for binding to and listening for abilities. You can use **AbilityMonitor** to bind to an **Ability** instance and add **AbilityMonitor** to the listening list. After an ability is bound, the creation and lifecycle changes of the ability will trigger the related callback in **AbilityMonitor**. You can test and verify the ability in these callbacks. For details, see [AbilityMonitor](../reference/apis/js-apis-application-abilityMonitor.md). +**AbilityMonitor** is provided by the test framework for binding to and listening for abilities. You can use **AbilityMonitor** to bind to an **Ability** instance and add **AbilityMonitor** to the listening list. When **AbilityMonitor** is bound to an ability, the creation and lifecycle changes of the ability will trigger the related callback in **AbilityMonitor**. You can test and verify the ability in these callbacks. For details, see [AbilityMonitor](../reference/apis/js-apis-application-abilityMonitor.md). **Example** ```javascript import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' -function onAbilityCreateCallback() { +function onAbilityCreateCallback(data) { console.info("onAbilityCreateCallback"); } @@ -64,7 +75,7 @@ var monitor = { } var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); -abilityDelegator.addAbilityMonitor(monitor).then((void) => { +abilityDelegator.addAbilityMonitor(monitor).then(() => { console.info("addAbilityMonitor promise"); }); ``` @@ -94,7 +105,7 @@ var abilityDelegator; var ability; var timeout = 100; -function onAbilityCreateCallback() { +function onAbilityCreateCallback(data) { console.info("onAbilityCreateCallback"); } @@ -113,8 +124,6 @@ var want = { bundleName: "bundleName", abilityName: "abilityName" }; - -abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); abilityDelegator.startAbility(want, (err, data) => { console.info("startAbility callback"); }); @@ -126,14 +135,44 @@ abilityDelegator.startAbility(want, (err, data) => { ### Running a Shell Command -**AbilityDelegator** provides APIs to run shell commands. You can run a shell command in the test code. This feature takes effect only in the test environment. +**AbilityDelegator** provides APIs to run shell commands in the test environment. **Example** ```javascript - var abilityDelegator; - var cmd = "cmd"; - abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); - abilityDelegator.executeShellCommand(cmd, (err,data) => { +var abilityDelegator; +var cmd = "cmd"; +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.executeShellCommand(cmd, (err, data) => { console.info("executeShellCommand callback"); - }); +}); +``` + +### Printing Log Information + +**AbilityDelegator** provides APIs for printing log information. You can call any API in the test code to print process logs to the unit test console. +**Example** + +```javascript +var abilityDelegator; +var msg = "msg"; + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.print(msg, (err) => { + console.info("print callback"); +}); +``` + +### Finishing the Test and Printing Log Information + +**AbilityDelegator** provides the APIs for actively finishing the test. You can call any API in test code to finish the test and print logs to the unit test console. +**Example** + +```javascript +var abilityDelegator; +var msg = "msg"; + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.finishTest(msg, 0, (err) => { + console.info("finishTest callback"); +}); ```