1# Ability Assistant 2 3 4Ability Assistant (AA) is a tool used to start applications and test cases. It provides basic application debugging and testing capabilities, for example, starting application components, forcibly stopping processes, and printing application component information. 5 6> **NOTE** 7> 8> Before using this tool, you must obtain the <!--Del-->[<!--DelEnd-->hdc tool<!--Del-->](../../device-dev/subsystems/subsys-toolchain-hdc-guide.md)<!--DelEnd--> and run the hdc shell command. 9 10 11## help 12 Displays help information for the Ability Assistant. 13 14 **Return value** 15 16 Returns the help information. 17 18 **Method** 19 20 21 ```bash 22 aa help 23 ``` 24 25 26## start 27 Starts an application component. The target component can be the PageAbility and ServiceAbility components of the FA model or the UIAbility and ServiceExtensionAbility components of the Stage model. The **exported** tag in the configuration file of the target component cannot be set to **false**. 28 29 | Name| Description | 30 | -------- |-------------------| 31 | -h/--help | Help information. | 32 | -d | Device ID. This parameter is optional. | 33 | -a | Ability name. This parameter is optional.| 34 | -b | Bundle name. This parameter is optional. | 35 | -m | Module name. This parameter is optional. | 36 | -U | URI. This parameter is optional. | 37 | -A | Action. This parameter is optional. | 38 | -e | Entity. This parameter is optional. | 39 | -t | Type. This parameter is optional. | 40 | -S | Whether to enter the application sandbox during debugging. This parameter is optional. If this parameter is carried, the application sandbox is entered. Otherwise, the application sandbox is not entered.| 41 | --pi | Key-value pair of the integer type. This parameter is optional. | 42 | --pb | Key-value pair of the Boolean type. This parameter is optional. | 43 | --ps | Key-value pair of the string type. This parameter is optional. | 44 | --psn | Keyword of an empty string. This parameter is optional. | 45 | --wl | Left margin of the window, in px. This parameter is optional.<br>**Constraints**:<br>This field is valid only when the 2-in-1 device is in developer mode and the application to start uses a debug signature.| 46 | --wt | Top margin of the window, in px. This parameter is optional.<br>**Constraints**:<br>This field is valid only when the 2-in-1 device is in developer mode and the application to start uses a debug signature.| 47 | --wh | Window height, in px. This parameter is optional.<br>**Constraints**:<br>This field is valid only when the 2-in-1 device is in developer mode and the application to start uses a debug signature.| 48 | --ww | Window width, in px. This parameter is optional.<br>**Constraints**:<br>This field is valid only when the 2-in-1 device is in developer mode and the application to start uses a debug signature.| 49 | -D | Debugging mode. This parameter is optional. | 50 51 **Return value** 52 53 Returns "start ability successfully." if the ability is started; returns "error: failed to start ability." and the corresponding error information otherwise. 54 55 **Method** 56 57 58 ```bash 59 # Display the ability started. 60 aa start [-d <deviceId>] [-a <abilityName> -b <bundleName>] [-m <moduleName>] [-D] [-S] [--pi <key> <integer-value>] [--pb <key> <bool-value: true/false/t/f, case insensitive] [--ps <key> <value>] [--psn <key>] [--wl <windowLeft>] [--wt <windowTop>] [--wh <windowHeight>] [--ww <windowWidth>] 61 62 # Implicitly start an ability. If none of the parameters in the command is set, the startup fails. 63 aa start [-d <deviceId>] [-U <URI>] [-t <type>] [-A <action>] [-e <entity>] [-D] [--pi <key> <integer-value>] [--pb <key> <bool-value: true/false/t/f, case insensitive] [--ps <key> <value>] [--psn <key>] [--wl <windowLeft>] [--wt <windowTop>] [--wh <windowHeight>] [--ww <windowWidth>] 64 ``` 65 66 **Example** 67 68The following uses the implicit startup of an ability as an example. 69 > **NOTE** 70 > 71 > This example describes only the usage of some fields. For details about ability matching rules, see [Matching Rules of Explicit Want and Implicit Want](../application-models/explicit-implicit-want-mappings.md). 72 73 741. Configure **uris** for the target ability in the **module.json5** file. 75 76 ```json 77 { 78 "name": "TargetAbility", 79 ...... 80 "exported": true, 81 "skills": [ 82 { 83 "actions":[ 84 "ohos.want.action.viewData" 85 ], 86 "uris":[ 87 { 88 "scheme": "myscheme", 89 "host": "www.test.com", 90 "port": "8080", 91 "path": "path", 92 } 93 ] 94 } 95 ] 96 } 97 ``` 98 99 1002. Implicitly start the ability. 101 102 - Run the **-U** command to start an application page. 103 104 ```bash 105 aa start -U myscheme://www.test.com:8080/path 106 ``` 107 108 - If parameters need to be carried, run the following command: 109 110 ```bash 111 aa start -U myscheme://www.test.com:8080/path --pi paramNumber 1 --pb paramBoolean true --ps paramString teststring --psn paramNullString 112 ``` 113 114 The following is an example for the UIAbility to obtain input parameters: 115 116 ```ts 117 import UIAbility from '@ohos.app.ability.UIAbility'; 118 import hilog from '@ohos.hilog'; 119 import Want from '@ohos.app.ability.Want'; 120 121 export default class TargetAbility extends UIAbility { 122 onCreate(want:Want, launchParam) { 123 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 124 let paramNumber = want.parameters.paramNumber 125 let paramBoolean = want.parameters.paramBoolean 126 let paramString = want.parameters.paramString 127 let paramNullString = want.parameters.paramNullString 128 } 129 } 130 ``` 131 132 - Run the **-A -U** command to start the browser and redirect to a specified page. 133 134 The following uses **https://www.example.com** as an example. Replace it with the actual URL. 135 136 ```bash 137 aa start -A ohos.want.action.viewData -U https://www.example.com 138 ``` 139 140 141## stop-service 142 Stops a ServiceAbility. 143 144 | Name| Description| 145 | -------- | -------- | 146 | -h/--help | Help information.| 147 | -d | Device ID. This parameter is optional.| 148 | -a | Ability name. This parameter is mandatory.| 149 | -b | Bundle name. This parameter is mandatory.| 150 | -m | Module name. This parameter is optional.| 151 152 **Return value** 153 154 Returns "stop service ability successfully." if the ServiceAbility is stopped; returns "error: failed to stop service ability." otherwise. 155 156 **Method** 157 158 159 ```bash 160 aa stop-service [-d <deviceId>] -a <abilityName> -b <bundleName> [-m <moduleName>] 161 ``` 162 163## dump<sup>(deprecated)</sup> 164 > **NOTE** 165 > 166 > This command is supported since API version 7 and deprecated since API version 9. You are advised to use **[hidumper](../dfx/hidumper.md) -s AbilityManagerService** instead. 167 168 Prints information about an application component. 169 | Name| Level-2 Parameter| Description| 170 | -------- | -------- | -------- | 171 | -h/--help | - | Help information.| 172 | -a/--all | - | Application component information in all missions.| 173| -l/--mission-list | type (All logs are printed if this parameter is left unspecified.)| For better management, the service side maintains four types of MissionLists, as described below:<br>- **NORMAL**: MissionList that is started normally. For example, if A starts B and C, the corresponding MissionList is A->B->C.<br>- **DEFAULT_STANDARD**: If a MissionList is damaged, missions with the launch type set to **multiton** are removed to this MissionList. The Missions in it are not associated with each other.<br>- **DEFAULT_SINGLE**: If a MissionList is damaged, missions with the launch type set to **singleton** are removed to this MissionList. The Missions in it are not associated with each other.<br>- **LAUNCHER**: MissionList for launcher abilities.| 174 | -e/--extension | elementName | Extended component information.| 175 | -u/--userId | UserId | Mission stack information of a specified user ID. This parameter must be used together with other parameters. Example commands: **aa dump -a -u 100** and **aa dump -d -u 100**.| 176 | -d/--data | - | DataAbility information.| 177 | -i/--ability | AbilityRecord ID | Detailed information about an application component.| 178 | -c/--client | - | Detailed information about an application component. This parameter must be used together with other parameters. Example commands: **aa dump -a -c** and **aa dump -i 21 -c**.| 179 | -p/--pending | - | Pending Want information. This parameter must be used together with other parameters. Example command: **aa dump -a -p**.| 180 | -r/--process | - | Process information. This parameter must be used together with other parameters. Example command: **aa dump -a -r**.| 181 182 **Method** 183 184 185 ```bash 186 aa dump -a 187 ``` 188 189  190 191 192 ```bash 193 aa dump -l 194 ``` 195 196  197 198 199 ```bash 200 aa dump -i 12 201 ``` 202 203  204 205## force-stop 206 Forcibly stops a process based on the bundle name. 207 208 **Return value** 209 210 Returns "force stop process successfully." if the process is forcibly stopped; returns "error: failed to force stop process." otherwise. 211 212 **Method** 213 214 215 ```bash 216 aa force-stop <bundleName> 217 ``` 218 219## test 220 221 Starts the test framework based on the carried parameters. 222 223 > **NOTE** 224 > 225 > For details about parameters such as **class**, **level**, **size**, and **testType**, see [Keywords in the aa test Commands](../application-test/arkxtest-guidelines.md#in-the-cli). 226 227 | Name| Description| 228 | -------- | -------- | 229 | -h/--help | Help information.| 230 | -b | Bundle name. This parameter is mandatory.| 231 | -s unittest | Test runner. This parameter is mandatory.| 232 | -p | Package name of the test runner. This parameter is optional.<br>**NOTE**: This parameter can be used only in the FA model.| 233 | -m | Module name of the test runner. This parameter is optional.<br>**NOTE**: This parameter can be used only in the stage model.| 234 | -s class | Test suite or test case to be executed. This parameter is optional.| 235 | -s level | Level of the test case to be executed. This parameter is optional.| 236 | -s size | Size of the test case to be executed. This parameter is optional.| 237 | -s testType | Type of the test case to be executed. This parameter is optional.| 238 | -s timeout | Timeout interval for executing the test case, in ms. The default value is 5000. This parameter is optional.| 239 | -s \<any-key> | Any key-value pair. This parameter is optional.| 240 | -w | Test running time, in ms. This parameter is optional.| 241 | -D | Debugging mode. This parameter is optional.| 242 243 **Return value** 244 245 Returns "user test started." if the test framework is started; returns "error: failed to start user test." and the corresponding error information otherwise. 246 247 **Method** 248 249 ```bash 250 aa test -b <bundleName> [-m <module-name>] [-p <package-name>] [-s class <test-class>] [-s level <test-level>] [-s size <test-size>] [-s testType <test-testType>] [-s timeout <test-timeout>] [-s <any-key> <any-value>] [-w <wait-time>] -s unittest <testRunner> 251 ``` 252 253## attach 254 Attaches an application to enable it to enter the debugging mode. 255 256 | Name| Description | 257 | -------- |-------------------| 258 | -h/--help | Help information. | 259 | -b | Bundle name. This parameter is mandatory. | 260 261 262 **Return value** 263 264 Returns "attach app debug successfully." if the application enters the debugging mode; returns "fail: unknown option." and prints the help information if the specified parameter is invalid. 265 266 **Method** 267 268 269 ```bash 270 aa attach -b <bundleName> 271 ``` 272 273## detach 274 Detaches an application to enable it to exit the debugging mode. 275 276 | Name| Description | 277 | -------- |-------------------| 278 | -h/--help | Help information. | 279 | -b | Bundle name. This parameter is mandatory. | 280 281 282 **Return value** 283 284 Returns "attach app debug successfully." if the application exits the debugging mode; returns "fail: unknown option." and prints the help information if the specified parameter is invalid. 285 286 **Method** 287 288 289 ```bash 290 aa detach -b <bundleName> 291 ``` 292 293## appdebug 294 Sets or cancels the waiting-for-debugging state of an application, and obtains the bundle name and persistence flag of an application in the waiting-for-debugging state. The waiting-for-debugging state takes effect only for debugging applications. The setting command of **appdebug** takes effect only for a single application. Once the command is executed repeatedly, the bundle name and persistence flag are replaced with the latest settings. 295 296 | Name| Level-2 Parameter| Description| 297 | -------- | -------- | -------- | 298 | -h/--help | - | Help information.| 299 | -b/--bundlename | bundleName | Bundle name for which the waiting-for-debugging state is set. The system does not verify the validity of the bundle name.| 300 | -p/--persist | - | Persistence flag. This parameter is optional. If this parameter is carried, the application is set to the waiting-for-debugging state persistently. That is, the setting takes effect regardless of whether the device is restarted or the application is reinstalled. If this parameter is not carried, the state takes effect only before the device is restarted. This parameter must be used together with the **-b** parameter. Example command: **aa appdebug -b \<bundleName> -p**.| 301 | -c/--cancel | - | Used to cancel the waiting-for-debugging state.| 302 | -g/--get | - | Used to obtain the bundle name and persistence flag of an application in the waiting-for-debugging state.| 303 304 **Return value** 305 306 Returns "app debug successfully." if the operation is successful; returns "error: not developer mode." if the operation fails because the application is not in developer mode; returns "error: failed to app debug." if the operation fails due to other reasons. 307 308 **Method** 309 310 ```bash 311 # Display the help information. 312 aa appdebug -h 313 314 # Set the waiting-for-debugging state for an application. 315 aa appdebug -b <bundleName> [-p] 316 317 # Cancel the waiting-for-debugging state. 318 aa appdebug -c 319 320 # Obtain the bundle name and persistence flag of an application in the waiting-for-debugging state. 321 aa appdebug -g 322 # Example of the obtained information: bundle name: com.example.publishsystem, persist: false 323 ``` 324
