1# Test Framework Usage 2 3## Overview 4The 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. 5 6## Constraints 7 8The APIs provided by the test framework can be used only in the test HAP. They take effect only after the test framework is started. 9 10 11## Starting the Test Framework 12 13The test framework can be started in either of the following ways: 14 15- Method 1: Run the `aa test` command. 16- Method 2: Use DevEco Studio. 17 18### Running aa test 19 20To start the test framework, specify the **TestRunner** and the package name or module name of the HAP where the **TestRunner** is located. 21 22An example command in the FA model is as follows: 23 24```javascript 25aa test -b BundleName -p com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 26``` 27 28An example command in the stage model is as follows: 29```javascript 30aa test -b BundleName -m com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20 31``` 32| Parameter | Mandatory| Description | 33| --------------- | -------- | ------------------------------------------------------------ | 34| -b | Yes | Bundle name of the HAP where the **TestRunner** is located. | 35| -p | Yes | Package name of the HAP where the **TestRunner** is located. This parameter is used by the FA model. | 36| -m | Yes | Module name of the HAP where the **TestRunner** is located. This parameter is used by the stage model. | 37| -s unittest | Yes | Name of the **TestRunner** to be used. The TestRunner name must be the same as the file name. | 38| -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.| 39| -s \<key>\<value> | 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.| 40| -D | No | Debug mode for starting the tested application.| 41| -h | No | Help information.| 42 43### Using DevEco Studio 44 45For details about how to use DevEco Studio to start the test framework, see [OpenHarmony Test Framework](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453#section1034420367508). 46 47## Introduction to TestRunner 48 49**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, DevEco Studio 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-application-testRunner.md). 50 51## Introduction to AbilityDelegatorRegistry 52 53**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-application-abilityDelegatorRegistry.md). 54 55## Introduction to AbilityDelegatorArgs 56 57**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-inner-application-abilityDelegatorArgs.md). 58 59## Introduction to AbilityMonitor 60 61**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). 62 63**Example** 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## Introduction to AbilityDelegator 84 85**AbilityDelegator** is a main function class of the test framework. It provides the functions of starting an ability, obtaining an **Ability** instance, scheduling the ability lifecycle, listening for the ability state, and printing test results. 86 87**Modules to Import** 88 89```javascript 90import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' 91``` 92 93```javascript 94var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator() 95``` 96 97### Starting an Ability and Listening for the Ability State 98 99Use **AbilityDelegator** and **AbilityMonitor** to start an ability, obtain an **Ability** instance, and listen for the ability state. 100 101**Example** 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### Scheduling the Ability Lifecycle 133 134**AbilityDelegator** provides APIs to display and schedule the ability lifecycle and supports the foreground and background. It works with **AbilityMonitor** to listen for the ability lifecycle. For details, see [AbilityDelegator](../reference/apis/js-apis-inner-application-abilityDelegator.md). 135 136### Running a Shell Command 137 138**AbilityDelegator** provides APIs to run shell commands in the test environment. 139 140**Example** 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### Printing Log Information 152 153**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. 154 155**Example** 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### Finishing the Test and Printing Log Information 168 169**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. 170 171**Example** 172 173```javascript 174var abilityDelegator; 175var msg = "msg"; 176 177abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 178abilityDelegator.finishTest(msg, 0, (err) => { 179 console.info("finishTest callback"); 180}); 181``` 182