README.md
1# XDevice<a name="EN-US_TOPIC_0000001083129731"></a>
2
3- [Introduction](#section15701932113019)
4- [Directory Structure](#section1791423143211)
5- [Constraints](#section118067583303)
6- [Usage](#section2036431583)
7- [Repositories Involved](#section260848241)
8
9## Introduction<a name="section15701932113019"></a>
10
11XDevice, a core module of the OpenHarmony test framework, provides services on which test case execution depends.
12
13XDevice consists of the following sub-modules:
14
15- **command**: enables command-based interactions between users and the test platform. It parses and processes user commands.
16- **config**: sets test framework configurations and provides different configuration options for the serial port connection and USB connection modes.
17- **driver**: functions as a test case executor, which defines main test steps, such as test case distribution, execution, and result collection.
18- **report**: parses test results and generates test reports.
19- **scheduler**: schedules various test case executors in the test framework.
20- **environment**: configures the test framework environment, enabling device discovery and device management.
21- **testkit**: provides test tools to implement JSON parsing, network file mounting, etc.
22- **resource**: provides the device connection configuration file and report template definitions.
23
24## Directory Structure<a name="section1791423143211"></a>
25
26```
27xdevice
28├── config # XDevice configuration
29│ ├── user_config.xml # XDevice environment configuration
30├── resource # XDevice resources
31│ ├── tools # Burning tools
32├── src # Source code
33│ ├── xdevice
34├── extension # XDevice extension
35│ ├── src # Source code of the extension
36│ └── setup.py # Installation script of the extension
37```
38
39## Constraints<a name="section118067583303"></a>
40
41The environment requirements for using this module are as follows:
42
43- Python version: 3.7.5 or later
44- pySerial version: 3.3 or later
45- Paramiko version: 2.7.1 or later
46- RSA version: 4.0 or later
47
48## Usage<a name="section2036431583"></a>
49
50- **Installing XDevice**
51 1. Go to the installation directory of XDevice.
52 2. Open the console window and run the following command:
53
54 ```
55 python setup.py install
56 ```
57
58
59- **Installing the extension**
60 1. Go to the installation directory of the XDevice extension.
61 2. Open the console and run the following command:
62
63 ```
64 python setup.py install
65 ```
66
67
68- **Modifying the user\_config.xml file**
69
70 Configure information about your environment in the **user\_config.xml** file.
71
72 **1. Configure the environment.**
73
74 - For devices that support hdc connection, refer to the following note to configure the environment.
75
76 > **NOTE:**
77 >**ip/port**: IP address and port of a remote device. By default, the parameter is left blank, indicating that the local device \(IP address: 127.0.0.1; port: the one used for hdc startup\) is used as the test device.
78 >**sn**: SN of the test devices specified for command execution. If this parameter is set to **SN1**, only device SN1 can execute the subsequent **run** commands. In this case, other devices are set as **Ignored** and not involved in the command execution. You can run the **list devices** command and check the value of **Allocation** to view the **sn** values. You can set multiple SNs and separate each two of them with a semicolon \(;\).
79
80 - For devices that support serial port connection, refer to the following note to configure the environment.
81
82 > **NOTE:**
83 >**type**: device connection mode. The **com** mode indicates that the device is connected through the serial port.
84 >**label**: device type, for example, **wifiiot**
85 >**serial**: serial port
86 >- **serial/com**: serial port for local connection, for example, **COM20**
87 >- **serial/type**: serial port type. The value can be **cmd** \(serial port for test case execution\) or **deploy** \(serial port for system upgrade\).
88 > For the open-source project, the **cmd** and **deploy** serial ports are the same, and their **com** values are the same too.
89 >**serial/baud\_rate, data\_bits, stop\_bits** and **timeout**: serial port parameters. You can use the default values.
90
91
92 **2. Set the test case directory.**
93
94 **dir**: test case directory
95
96 **3. Mount the NFS.**
97
98 > **NOTE:**
99 >**server**: NFS mounting configuration. Set the value to **NfsServer**.
100 >**server/ip**: IP address of the mounting environment
101 >**server/port**: port number of the mounting environment
102 >**server/username**: user name for logging in to the server
103 >**server/password**: password for logging in to the server
104 >**server/dir**: external mount path
105 >**server/remote**: whether the NFS server and the XDevice executor are deployed on different devices. If yes, set this parameter to **true**. Otherwise, set it to **false**.
106
107- **Specify the task type.**
108- **Start the test framework.**
109- **Execute test commands.**
110
111 Test framework commands can be classified into three groups: **help**, **list**, and **run**. Among them, **run** commands are most commonly used in the instruction sequence.
112
113 **help**
114
115 Queries help information about test framework commands.
116
117 ```
118 help:
119 use help to get information.
120 usage:
121 run: Display a list of supported run command.
122 list: Display a list of supported device and task record.
123 Examples:
124 help run
125 help list
126 ```
127
128 > **NOTE:**
129 >**help run**: displays the description of **run** commands.
130 >**help list**: displays the description of **list** commands.
131
132 **list**
133
134 Displays device information and related task information.
135
136 ```
137 list:
138 This command is used to display device list and task record.
139 usage:
140 list
141 list history
142 list <id>
143 Introduction:
144 list: display device list
145 list history: display history record of a serial of tasks
146 list <id>: display history record about task what contains specific id
147 Examples:
148 list
149 list history
150 list 6e****90
151 ```
152
153 > **NOTE:**
154 >**list**: displays device information.
155 >**list history**: displays historical task information.
156 >**list <id\>**: displays historical information about tasks with specified IDs.
157
158 **run**
159
160 Executes test tasks.
161
162 ```
163 run:
164 This command is used to execute the selected testcases.
165 It includes a series of processes such as use case compilation, execution, and result collection.
166 usage: run [-l TESTLIST [TESTLIST ...] | -tf TESTFILE
167 [TESTFILE ...]] [-tc TESTCASE] [-c CONFIG] [-sn DEVICE_SN]
168 [-rp REPORT_PATH [REPORT_PATH ...]]
169 [-respath RESOURCE_PATH [RESOURCE_PATH ...]]
170 [-tcpath TESTCASES_PATH [TESTCASES_PATH ...]]
171 [-ta TESTARGS [TESTARGS ...]] [-pt]
172 [-env TEST_ENVIRONMENT [TEST_ENVIRONMENT ...]]
173 [-e EXECTYPE] [-t [TESTTYPE [TESTTYPE ...]]]
174 [-td TESTDRIVER] [-tl TESTLEVEL] [-bv BUILD_VARIANT]
175 [-cov COVERAGE] [--retry RETRY] [--session SESSION]
176 [--dryrun] [--reboot-per-module] [--check-device]
177 [--repeat REPEAT]
178 action task
179 Specify tests to run.
180 positional arguments:
181 action Specify action
182 task Specify task name,such as "ssts", "acts", "hits"
183 ```
184
185 > **NOTE:**
186 >The structure of a basic **run** command is as follows:
187 >```
188 >run [task name] -l module1;moudle2
189 >```
190 >**task name**: task type. This parameter is optional. Generally, the value is **ssts**, **acts**, or **hits**.
191 >**-l**: test cases to execute. Use semicolons \(;\) to separate each two test cases.
192 >**module**: module to test. Generally, there is a **.json** file of the module in the **testcases** directory.
193 >In addition, other parameters can be attached to this command as constraints. Common parameters are as follows:
194 >**-sn**: specifies the devices for test case execution. If this parameter is set to **SN1**, only device SN1 executes the test cases.
195 >**-c**: specifies a new **user\_config.xml** file.
196 >**-rp**: indicates the path where the report is generated. The default directory is **xxx/xdevice/reports**. Priority of a specified directory is higher than that of the default one.
197 >**-tcpath**: indicates the environment directory, which is **xxx/xdevice/testcases** by default. Priority of a specified directory is higher than that of the default one.
198 >**-respath**: indicates the test suite directory, which is **xxx/xdevice/resource** by default. Priority of a specified directory is higher than that of the default one.
199 >**--reboot-per-module**: restarts the device before test case execution.
200
201- **View the execution result.**
202
203 After executing the **run** commands, the test framework displays the corresponding logs on the console, and generates the execution report in the directory specified by the **-rp** parameter. If the parameter is not set, the report will be generated in the default directory.
204
205 ```
206 Structure of the report directory (the default or the specified one)
207 ├── result # Test case execution results of the module
208 │ ├── module name.xml
209 │ ├── ... ...
210 │
211 ├── log # Running logs of devices and tasks
212 │ ├── device 1.log
213 │ ├── ... ...
214 │ ├── task.log
215 ├── summary_report.html # Visual report
216 ├── summary_report.html # Statistical report
217 └── ... ...
218 ```
219
220
221## Repositories Involved<a name="section260848241"></a>
222
223[testing subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/testing-subsystem.md)
224
225**test\_xdevice**
226
227[test\_developertest](https://gitee.com/openharmony/test_developertest/blob/master/README.md)
228
