1# wukong User Guide
2
3## Introduction
4
5wukong is a built-in command line tool that implements application stability test capabilities such as random event injection, component injection, exception capture, report generation, and data traversal of abilities. This tool allows you to conduct stability tests on the system or applications by simulating user behavior. wukong provides three types of testing: random testing, special testing, and focus testing.
6
7In random testing, test inputs are generated randomly. Available features include shell startup, whole application startup, multiple injection modes, random seeds setting, run log printing, and report generation.
8
9In special testing, specific application components are tested. Available features include shell startup, sequential traversal and screenshot, sleep and wakeup test, recording and playback, run log printing, and report generation.
10
11In focus testing, specific components are injected. Available features include shell startup, device application startup, multiple injection modes, random seed setting, focus component type setting, component injection times setting, run log printing, and report generation.
12
13## Principles
14
15The following figure shows the wukong component architecture and the responsibilities of sub-modules.
16![Alternate text](figures/wukongRandomTestFlow.png)
17
18- Command line parsing: Obtain and parse parameters using commands.
19- Operating environment management: Initialize the overall operating environment of wukong using commands.
20- System API management: Check and obtain the specified mgr, and register the callback function of the Faultlogger for the controller and DFX.
21- Random event generation: Use the **random** function to generate a sequence of random numbers with the specified seed value to generate an event.
22- Event injection: Inject events of supported types to the system. This feature depends on the window, multi-mode, and security subsystems.
23- Exception capture and processing and report generation: Obtain exception information with the DFX subsystem during application running, record log, and generate reports.
24
25## Constraints
26
271. The wukong tool is built in the system since API version 9.
28
292. In API versions earlier than 9, you need to build the tool and push it to the target device. The procedure is as follows:
30
31   ```bash
32   // Build code.
33   ./build.sh --product-name rk3568 --build-target wukong
34
35   // Push code.
36   hdc shell mount -o rw,remount /
37   hdc file send wukong /
38   hdc shell chmod a+x /wukong
39   hdc shell mv /wukong /bin/
40   ```
41
423. When the PC is connected to one or more target devices, you can run test commands.
43
444. Enter the shell mode before running any command.
45
46## Functions and Commands
47
48| Command          | Description                                          |
49| -------------- | ---------------------------------------------- |
50| version | Obtains version information.                            |
51| help    | Obtains help information.                            |
52| appinfo | Queries the bundle name and the name of the corresponding mainAbility of the app that can be started.|
53| special | Runs special testing.                                  |
54| exec    | Runs random testing.                                  |
55| focus   | Runs focus testing.                                  |
56
57### Running Commands
58
59- Open the shell.
60
61  ```bash
62  #If you are testing one device, run **hdc shell**.
63  C:\Users>hdc shell
64  #
65
66  #If you are testing multiple devices, run **hdc list targets** to obtain the SNs, and then run **hdc -t** open the shell.
67  C:\Users>hdc list targets
68  15xxx424axxxx345209d94xxxx8fxx900
69  C:\Users>hdc -t 15xxx424axxxx345209d94xxxx8fxx900 shell
70  #
71  ```
72
73- Obtain the bundle name and ability name of the application.
74
75  ```bash
76  # wukong appinfo
77  BundleName:  com.ohos.adminprovisioning
78  AbilityName:  com.ohos.adminprovisioning.MainAbility
79  BundleName:  com.ohos.callui
80  AbilityName:  com.ohos.callui.MainAbility
81  ```
82- View the help information.
83
84  ```bash
85  C:\Users>hdc shell
86  # wukong --help        // wukong help menu.
87  wukong: '--help' is not a valid wukong command. See 'wukong help'.
88  usage: wukong <command> [<arguments>]
89  These are common wukong command list:
90    help                       wukong help information
91    -v/--version               wukong version
92    exec                       run random test
93    special                    run special test
94    focus                      run focus test
95    appinfo                    show all app information
96  # wukong exec -help   // Help menu for wukong random testing.
97  usage: wukong exec [<arguments>]
98  These are wukong exec arguments list:
99    -h, --help                 random test help
100    -a, --appswitch            appswitch event percent
101    -b, --bundle               the bundle name of allowlist
102    -p, --prohibit             the bundle name of blocklist
103    -d, --page                 block page list
104    -t, --touch                touch event percent
105    -c, --count                test count
106    -i, --interval             interval
107    -s, --seed                 random seed
108    -m, --mouse                mouse event percent
109    -k, --keyboard             keyboard event percent
110    -H, --hardkey              hardkey event percent
111    -S, --swap                 swap event percent
112    -T, --time                 test time
113    -C, --component            component event percent
114    -r, --rotate               rotate event percent
115    -e, --allow ability        the ability name of allowlist
116    -E, --block ability        the ability name of blocklist
117    -I, --screenshot           get screenshot(only in random input)
118  # wukong special -help    // Help menu for wukong special testing.
119  usage: wukong special [<arguments>]
120  These are wukong special arguments list:
121    -h, --help                 special test help
122    -t, --touch[x,y]           touch event
123    -c, --count                total count of test
124    -i, --interval             interval
125    -S, --swap[option]         swap event
126                                option is -s| -e| -b
127                                -s, --start: the start point of swap
128                                -e, --end: the end point of swap
129                                -b, --bilateral: swap go and back
130    -k, --spec_insomnia        power on/off event
131    -T, --time                 total time of test
132    -C, --component            component event
133    -p, --screenshot           get screenshot(only in componment input)
134    -r, --record               record user operation
135    -R, --replay               replay user operation
136    -u, --uitest               uitest dumpLayout
137  ```
138
139## Random Testing
140
141### Commands
142
143| Command           | Description                                | Mandatory| Description                                    |
144| --------------- | ------------------------------------ | ---- | ---------------------------------------- |
145| -h,--help       | Obtains the help information about the test.              | No  |  -                        |
146| -c,--count      | Sets the number of execution times. This command conflicts with the **-T** command. Select either of them.  | No  | The default value is 10, in times.                      |
147| -i,--interval   | Sets the test interval.                        | No  | The default value is 1500, in millisecond.                      |
148| -s,--seed       | Sets the random seed.                        | No  | If the same random seed is set, the same random event sequence is generated.|
149| -b,--bundle[bundlename, ......, bundlename]    | Sets the allowed bundles for the test. This command conflicts with the **-p** command.| No  | By default, all bundles on the device are allowed. Use commas (,) to separate bundle names.                |
150| -p,--prohibit[bundlename, ......, bundlename]  | Sets the blocked bundles for the test. This command conflicts with the **-b** command.| No  | By default, no bundle is blocked. Use commas (,) to separate bundle names.                      |
151| -d,--page[page, ......, page]                  | Sets the blocked pages for the test.| No | By default, the **pages/system** pages are blocked. Use commas (,) to separate page names.|
152| -a,--appswitch  | Sets the proportion of the random application startup event test.            | No  | The default value is 10%.                                 |
153| -t,--touch      | Sets the proportion of the random touch event test.           | No  | The default value is 10%.                                 |
154| -S,--swap       | Sets the proportion of the random swipe event test.            | No  | The default value is 3%.                                  |
155| -m,--mouse      | Sets the proportion of the random mouse event test.           | No  | The default value is 1%.                                  |
156| -k,--keyboard   | Sets the proportion of the random keyboard event test.        | No  | The default value is 2%.                                  |
157| -H,--hardkey    | Sets the proportion of the random hardkey test.             | No  | The default value is 2%.                                  |
158| -r,--rotate     | Sets the proportion of the random rotate event test.              | No  | The default value is 2%.                                  |
159| -C, --component | Sets the proportion of random component test.                | No  | The default value is 70%.                                 |
160| -I, --screenshot | Takes a screenshot for the component test.                | No  | - |
161| -T,--time       | Sets the total test time. This command conflicts with the **-c** command. Set either of them.| No  | The default value is 10, in minute.        |
162| -e, --allow ability   |  Sets the ability that allows testing.| No| - |
163| -E, --block ability   |  Sets the ability that blocks testing.| No| - |
164| -Y, --blockCompId     |  Sets the blocked **CompId**.| No| - |
165| -y, --blockCompType   |  Sets the blocked **CompType**.| No| - |
166| -B, --checkBWScreen   |  Enables black and white screen check.| No| - |
167| -U, -uri              |  Sets the URI of the application startup page.| No| - |
168| -x, -uriType          |  Sets the URI type of the application startup page.| No| - |
169
170### Samples
171
172- Set 100 event injections.
173
174  ```bash
175  # wukong exec -s 10 -i 1000 -a 0.28 -t 0.72 -c 100
176  ```
177
178  The parameters in the command are described as follows.
179  | Command          | Value     |Description       |
180  | -------------- | -------------- | -------------- |
181  | wukong exec | -           | Works as the main command.               |
182  | -s     | 10           | Sets the random seed. The seed value is **10**. |
183  | -i  | 1000           | Sets the application startup interval to **1000** ms.|
184  | -a  | 0.28          | Sets the proportion of the random application startup test to **28%**.   |
185  | -t  | 0.72           | Sets the proportion of the random touch test to **72%**.   |
186  | -c  | 100           | Sets the number of execution times to **100**.        |
187
188- Specify a page to perform a pressure test.
189
190  ```bash
191  > Explicit start
192  > hdc_std shell
193  # wukong exec -b bundlename -a abilityname -U uri
194
195  > Implicit start
196  > hdc_std shell
197  # wukong exec -b bundlename -U uri -x uriType
198  ```
199
200- Set the ability that allows and blocks testing.
201  ```bash
202  # wukong exec -b com.ohos.settings -e com.ohos.settings.MainAbility -E com.ohos.settings.AppInfoAbility
203  ```
204  >  **NOTE**
205  >
206  > If **-e** and **-E** are set, you must set **-b** to specify an application.
207
208## Special Testing
209
210### Commands
211
212| Command               | Description                  | Mandatory| Description               |
213| :------------------ | ---------------------- | ---- | :------------------ |
214| -h, --help          | Obtains the help information about the special testing.| No  |  -    |
215| -k, --spec_insomnia | Powers on/off the special testing.      | No  | -                   |
216| -c, --count         | Sets the number of test times.          | No  | The default value is 10, in times.         |
217| -i, --interval      | Sets the test interval.          | No  | The default value is 1500, in millisecond. |
218| -S, --swap          | Sets a swipe event for the test.              | No  | -                   |
219| -s, --start[x,y]    | Sets the coordinates of the start point of the swipe event.  | No  | The values of coordinates are positive.          |
220| -e, --end[x,y]      | Sets the coordinates of the end point of the swipe event.  | No  | The values of coordinates are positive.         |
221| -b, --bilateral     | Sets a back and forth swipe event.          | No  | By default, the back and forth swipe event is disabled.     |
222| -t, --touch[x,y]    | Sets a touch event for the test.              | No  | -                   |
223| -T, --time          | Sets the total test time.        | No  | The default value is 10, in minute.|
224| -C, --component     | Sets the sequential traversal test for components.      | No  | You need to set the name of the test application.|
225| -r, --record     | Records user operation.      | No  | You need to specify the recording file.|
226| -R, --replay    |  Replays user operation.     | No  | You need to specify the playback file.|
227| -p, --screenshot    |  Takes a screenshot for the component test.     | No  | - |
228
229### Samples
230
231```bash
232# wukong special -C [bundlename] -p
233```
234
235## Focus Testing
236
237### Commands
238
239| Command           | Description                                | Mandatory| Description                                    |
240| --------------- | ------------------------------------ | ---- | ---------------------------------------- |
241| -n,--numberfocus       | Sets the number of injections for each component.              | No  | Unit: times                |
242| -f, --focustypes       | Sets the types of component for the focus testing.              | No  | Use commas (,) to separate the types.                        |
243| -h,--help       | Obtains the help information about the test.              | No  |                          |
244| -c,--count      | Sets the number of test times. This command conflicts with the **-T** command. Set either of them.  | No  | The default value is 10, in times.                      |
245| -i,--interval   | Sets the test interval.                        | No  | The default value is 1500, in millisecond.                      |
246| -s,--seed       | Sets the random seed.                        | No  | If the same random seed is set, the same random event sequence is generated.|
247| -b,--bundle[bundlename, ......, bundlename]    | Sets the bundle name of allowlist for the test. This command conflicts with the **-p** command.| No  | By default, all applications on the device are allowed. (Use commas (,) to separate application names.)                |
248| -p,--prohibit[bundlename, ......, bundlename]  | Sets the bundle name of blocklist for the test. This command conflicts with the **-b** command.| No  | By default, no application is blocked. (Use commas (,) to separate application names.)                      |
249| -d,--page[page, ......, page]                  | Sets the list of blocked pages for the test.| No | By default, the pages/system pages are blocked. (Use commas (,) to separate page names.)|
250| -a,--appswitch  | Sets the proportion of random application startup test.            | No  | The default value is 10%.                                 |
251| -t,--touch      | Sets the proportion of the random touch event test.           | No  | The default value is 10%.                                 |
252| -S,--swap       | Sets the proportion of the random swipe event test.            | No  | The default value is 3%.                                  |
253| -m,--mouse      | Sets the proportion of the random mouse event test.           | No  | The default value is 1%.                                  |
254| -k,--keyboard   | Sets the proportion of the random keyboard event test.        | No  | The default value is 2%.                                  |
255| -H,--hardkey    | Sets the proportion of the random hardkey test.             | No  | The default value is 2%.                                  |
256| -r,--rotate     | Sets the proportion of the random rotate event test.              | No  | The default value is 2%.                                  |
257| -C, --component | Sets the proportion of random component test.                | No  | The default value is 70%.                                 |
258| -I, --screenshot | Takes a screenshot for the component test.                | No  | - |
259| -T,--time       | Sets the total test time. This command conflicts with the **-c** command. Set either of them.| No  | The default value is 10, in minute.        |
260| -e, --allow ability   |  Sets the ability that allows testing.| No| - |
261| -E, --block ability   |  Sets the ability that blocks testing.| No| - |
262| -Y, --blockCompId     |  Sets the blocked **CompId**.| No| - |
263| -y, --blockCompType   |  Sets the blocked **CompType**.| No| - |
264| -B, --checkBWScreen   |  Enables black and white screen check.| No| - |
265
266### Samples
267
268```bash
269# wukong focus -s 10 -i 1000 -a 0.28 -t 0.72 -c 100
270```
271
272The parameters in the command are described as follows.
273| Command          | Value     |Description       |
274| -------------- | -------------- | -------------- |
275| wukong exec | -           | Works as the main command.               |
276| -s     | 10           | Sets the random seed. The seed value is **10**. |
277| -i  | 1000           | Sets the application startup interval to **1000** ms.|
278| -a  | 0.28          | Sets the proportion of the random application startup test to **28%**.   |
279| -t  | 0.72           | Sets the proportion of the random touch test to **72%**.   |
280| -c  | 100           | Sets the number of execution times to **100**.        |
281
282
283## Viewing the Test Result
284
285### Test Result Output Path
286
287After the test commands are executed, the test result is automatically generated. You can obtain the test result in the following directory:
288
289- For DevEco Studio versions earlier than September 22, 2022: /data/local/wukong/report/xxxxxxxx_xxxxxx/
290- For DevEco Studio versions later than September 22, 2022: /data/local/tmp/wukong/report/xxxxxxxx_xxxxxx/
291
292### Test Report Directories
293
294| Type                                | Description              |
295| ------------------------------------ | ------------------ |
296| exception/                           | Stores exception files generated during the test.|
297| screenshot/                          | Stores the screenshots of the test traversal. |
298| wukong_report.csv                    | Stores the test report summary.      |
299| wukong.log                | Indicates the test operation history.      |
300
301### Viewing Operation Logs
302
303You can run the hdc command to obtain logs to the local host and view the operation history.
304
305```bash
306// The path of the wukong.log file is as follows:
307/data/local/tmp/wukong/report/xxxxxxxx_xxxxxx/wukong.log
308
309// To view the directory of the wukong test report, run the following command:
310# cd /data/local/tmp/wukong/report/20170805_170053
311# ls
312data.js  exception  wukong.log  wukong_report.csv
313
314// Open the shell and run hdc file recv to obtain wukong logs.
315C:\Users\xxx>hdc file recv /data/local/tmp/wukong/report/20170805_170053/wukong.log C:\Users\xxx\Desktop\log
316[I][2024-01-03 20:08:02] HdcFile::TransferSummary success
317FileTransfer finish, Size:76492, File count = 1, time:16ms rate:4780.75kB/s
318```
319