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