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| -p | Optimization mode. This parameter is optional. This command can be customized.       |
51
52  **Return value**
53
54  Returns "start ability successfully." if the ability is started; returns "error: failed to start ability." and the corresponding error information otherwise.
55
56  **Method**
57
58
59  ```bash
60  # Display the ability started.
61  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>] [-p <perf-cmd>]
62
63  # Implicitly start an ability. If none of the parameters in the command is set, the startup fails.
64  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>] [-p <perf-cmd>]
65  ```
66
67  **Example**
68
69The following uses the implicit startup of an ability as an example.
70  > **NOTE**
71  >
72  > 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).
73
74
75  - Configure **uris** for the target ability in the **module.json5** file.
76
77      ```json
78      {
79        "name": "TargetAbility",
80        ......
81        "exported": true,
82        "skills": [
83          {
84            "actions":[
85              "ohos.want.action.viewData"
86            ],
87            "uris":[
88              {
89                "scheme": "myscheme",
90                "host": "www.test.com",
91                "port": "8080",
92                "path": "path",
93              }
94            ]
95          }
96        ]
97      }
98      ```
99
100
101  - Implicitly start the ability.
102
103    - Run the **-U** command to start an application page.
104
105        ```bash
106        aa start -U myscheme://www.test.com:8080/path
107        ```
108
109    - If parameters need to be carried, run the following command:
110
111        ```bash
112        aa start -U myscheme://www.test.com:8080/path --pi paramNumber 1 --pb paramBoolean true --ps paramString teststring  --psn paramNullString
113        ```
114
115      The following is an example for the UIAbility to obtain input parameters:
116
117        ```ts
118        import UIAbility from '@ohos.app.ability.UIAbility';
119        import hilog from '@ohos.hilog';
120        import Want from '@ohos.app.ability.Want';
121
122        export default class TargetAbility extends UIAbility {
123          onCreate(want:Want, launchParam) {
124            hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
125            let paramNumber = want.parameters.paramNumber
126            let paramBoolean = want.parameters.paramBoolean
127            let paramString = want.parameters.paramString
128            let paramNullString = want.parameters.paramNullString
129          }
130        }
131        ```
132
133    - Run the **-A -U** command to start the browser and redirect to a specified page.
134
135      The following uses **https://www.example.com** as an example. Replace it with the actual URL.
136
137        ```bash
138        aa start -A ohos.want.action.viewData -U https://www.example.com
139        ```
140
141
142## stop-service
143  Stops a ServiceAbility.
144
145| Name| Description|
146| -------- | -------- |
147| -h/--help | Help information.|
148| -d | Device ID. This parameter is optional.|
149| -a | Ability name. This parameter is mandatory.|
150| -b | Bundle name. This parameter is mandatory.|
151| -m | Module name. This parameter is optional.|
152
153  **Return value**
154
155  Returns "stop service ability successfully." if the ServiceAbility is stopped; returns "error: failed to stop service ability." otherwise.
156
157  **Method**
158
159
160  ```bash
161  aa stop-service [-d <deviceId>] -a <abilityName> -b <bundleName> [-m <moduleName>]
162  ```
163
164## dump<sup>(deprecated)</sup>
165  > **NOTE**
166  >
167  > 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.
168
169  Prints information about an application component.
170| Name| Level-2 Parameter| Description|
171| -------- | -------- | -------- |
172| -h/--help | - | Help information.|
173| -a/--all | - | Application component information in all missions.|
174| -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.|
175| -e/--extension | elementName | Extended component information.|
176| -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**.|
177| -d/--data | - | DataAbility information.|
178| -i/--ability | AbilityRecord ID | Detailed information about an application component.|
179| -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**.|
180| -p/--pending | - | Pending Want information. This parameter must be used together with other parameters. Example command: **aa dump -a -p**.|
181| -r/--process | - | Process information. This parameter must be used together with other parameters. Example command: **aa dump -a -r**.|
182
183  **Method**
184
185
186  ```bash
187  aa dump -a
188  ```
189
190  ![aa-dump-a](figures/aa-dump-a.png)
191
192
193  ```bash
194  aa dump -l
195  ```
196
197  ![aa-dump-l](figures/aa-dump-l.png)
198
199
200  ```bash
201  aa dump -i 12
202  ```
203
204  ![aa-dump-i](figures/aa-dump-i.png)
205
206## force-stop
207  Forcibly stops a process based on the bundle name.
208
209  **Return value**
210
211  Returns "force stop process successfully." if the process is forcibly stopped; returns "error: failed to force stop process." otherwise.
212
213  **Method**
214
215
216  ```bash
217  aa force-stop <bundleName>
218  ```
219
220## test
221
222  Starts the test framework based on the carried parameters.
223
224  > **NOTE**
225  >
226  > For details about parameters such as **class**, **level**, **size**, and **testType**, see <!--RP2-->[Keywords in the aa test Commands](../application-test/arkxtest-guidelines.md)<!--RP2End-->.
227
228| Name| Description|
229| -------- | -------- |
230| -h/--help | Help information.|
231| -b | Bundle name. This parameter is mandatory.|
232| -s unittest | Test runner. This parameter is mandatory.|
233| -p | Package name of the test runner. This parameter is optional.<br>**NOTE**: This parameter can be used only in the FA model.|
234| -m | Module name of the test runner. This parameter is optional.<br>**NOTE**: This parameter can be used only in the stage model.|
235| -s class | Test suite or test case to be executed. This parameter is optional.|
236| -s level | Level of the test case to be executed. This parameter is optional.|
237| -s size | Size of the test case to be executed. This parameter is optional.|
238| -s testType | Type of the test case to be executed. This parameter is optional.|
239| -s timeout | Timeout interval for executing the test case, in ms. The default value is 5000. This parameter is optional.|
240| -s \<any-key> | Any key-value pair. This parameter is optional.|
241| -w | Test running time, in ms. This parameter is optional.|
242| -D | Debugging mode. This parameter is optional.|
243
244  **Return value**
245
246  Returns "user test started." if the test framework is started; returns "error: failed to start user test." and the corresponding error information otherwise.
247
248  **Method**
249
250  ```bash
251  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>
252  ```
253
254## attach
255  Attaches an application to enable it to enter the debugging mode.
256
257| Name| Description             |
258| -------- |-------------------|
259| -h/--help | Help information.            |
260| -b | Bundle name. This parameter is mandatory. |
261
262
263  **Return value**
264
265  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.
266
267  **Method**
268
269
270  ```bash
271  aa attach -b <bundleName>
272  ```
273
274## detach
275  Detaches an application to enable it to exit the debugging mode.
276
277| Name| Description             |
278| -------- |-------------------|
279| -h/--help | Help information.            |
280| -b | Bundle name. This parameter is mandatory. |
281
282
283  **Return value**
284
285  Returns "detach 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.
286
287  **Method**
288
289
290  ```bash
291  aa detach -b <bundleName>
292  ```
293
294## appdebug
295  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.
296
297| Name| Level-2 Parameter| Description|
298| -------- | -------- | -------- |
299| -h/--help | - | Help information.|
300| -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.|
301| -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**.|
302| -c/--cancel | - | Used to cancel the waiting-for-debugging state.|
303| -g/--get | - | Used to obtain the bundle name and persistence flag of an application in the waiting-for-debugging state.|
304
305  **Return value**
306
307  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.
308
309  **Method**
310
311  ```bash
312  # Display the help information.
313  aa appdebug -h
314
315  # Set the waiting-for-debugging state for an application.
316  aa appdebug -b <bundleName> [-p]
317
318  # Cancel the waiting-for-debugging state.
319  aa appdebug -c
320
321  # Obtain the bundle name and persistence flag of an application in the waiting-for-debugging state.
322  aa appdebug -g
323  # Example of the obtained information: bundle name: com.example.publishsystem, persist: false
324  ```
325
326## process
327  Debugs or optimizes an application. In DevEco Studio, this command is used to integrate debugging and optimization tools.
328
329| Name| Description|
330| -------- | -------- |
331| -h/--help | Help information.|
332| -b | Bundle name. This parameter is mandatory.|
333| -a | Ability name. This parameter is mandatory.|
334| -m | Module name. This parameter is optional.|
335| -p | Optimization mode. This parameter is optional. Either this parameter or **-D** must be specified. This command can be customized.|
336| -D | Debugging mode. This parameter is optional. Either this parameter or **-p** must be specified. This command can be customized.|
337| -S | Used to enter the application sandbox. This parameter is optional.|
338
339  **Return value**
340
341  Returns "start native process successfully." if this command is executed successfully; returns "start native process successfully." if this command fails to be executed; returns "start native process successfully." and prints the help information if the specified parameter is invalid.
342
343  **Method**
344
345  ```bash
346  # Display the help information.
347  aa process -h
348
349  # Debug an application.
350  aa process -b <bundleName> -a <abilityName> [-m <moduleName>] [-D <debug-cmd>] [-S]
351
352  # Optimize an application.
353  aa process -b <bundleName> -a <abilityName> [-m <moduleName>] [-p <perf-cmd>] [-S]
354  ```
355