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├── src # Source code
31│ ├── xdevice
32├── plugins # XDevice plugins
33│ ├── ohos # OpenHarmony plugins
34| ├── src # OpenHarmony plugins source code
35│ └── setup.py # Installation script of the plugins
36```
37
38## Constraints<a name="section118067583303"></a>
39
40The environment requirements for using this module are as follows:
41
42- Python version: 3.7.5 or later
43- pySerial version: 3.3 or later
44- Paramiko version: 2.7.1 or later
45- RSA version: 4.0 or later
46
47## Usage<a name="section2036431583"></a>
48
49- **Installing XDevice**
50 1. Go to the installation directory of XDevice.
51 2. Open the console window and run the following command:
52
53 ```
54 python setup.py install
55 ```
56
57
58- **Installing the extension**
59 1. Go to the installation directory of the XDevice extension.
60 2. Open the console and run the following command:
61
62 ```
63 python setup.py install
64 ```
65
66
67- **Modifying the user\_config.xml file**
68
69 Configure information about your environment in the **user\_config.xml** file.
70
71 **1. Configure the environment.**
72
73 - For devices that support hdc connection, refer to the following note to configure the environment.
74
75 > **NOTE:**
76 >**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.
77 >**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 \(;\).
78
79 - For devices that support serial port connection, refer to the following note to configure the environment.
80
81 > **NOTE:**
82 >**type**: device connection mode. The **com** mode indicates that the device is connected through the serial port.
83 >**label**: device type, for example, **wifiiot**
84 >**serial**: serial port
85 >- **serial/com**: serial port for local connection, for example, **COM20**
86 >- **serial/type**: serial port type. The value can be **cmd** \(serial port for test case execution\) or **deploy** \(serial port for system upgrade\).
87 > For the open-source project, the **cmd** and **deploy** serial ports are the same, and their **com** values are the same too.
88 > **serial/baud\_rate, data\_bits, stop\_bits** and **timeout**: serial port parameters. You can use the default values.
89
90
91 **2. Set the test case directory.**
92
93 **dir**: test case directory
94
95 **3. Mount the NFS.**
96
97 > **NOTE:**
98 >**server**: NFS mounting configuration. Set the value to **NfsServer**.
99 >**server/ip**: IP address of the mounting environment
100 >**server/port**: port number of the mounting environment
101 >**server/username**: user name for logging in to the server
102 >**server/password**: password for logging in to the server
103 >**server/dir**: external mount path
104 >**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**.
105
106- **Specify the task type.**
107- **Start the test framework.**
108- **Execute test commands.**
109
110 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.
111
112 **help**
113
114 Queries help information about test framework commands.
115
116 ```
117 help:
118 use help to get information.
119 usage:
120 run: Display a list of supported run command.
121 list: Display a list of supported device and task record.
122 Examples:
123 help run
124 help list
125 ```
126
127 > **NOTE:**
128 >**help run**: displays the description of **run** commands.
129 >**help list**: displays the description of **list** commands.
130
131 **list**
132
133 Displays device information and related task information.
134
135 ```
136 list:
137 This command is used to display device list and task record.
138 usage:
139 list
140 list history
141 list <id>
142 Introduction:
143 list: display device list
144 list history: display history record of a serial of tasks
145 list <id>: display history record about task what contains specific id
146 Examples:
147 list
148 list history
149 list 6e****90
150 ```
151
152 > **NOTE:**
153 >**list**: displays device information.
154 >**list history**: displays historical task information.
155 >**list <id\>**: displays historical information about tasks with specified IDs.
156
157 **run**
158
159 Executes test tasks.
160
161 ```
162 run:
163 This command is used to execute the selected testcases.
164 It includes a series of processes such as use case compilation, execution, and result collection.
165 usage: run [-l TESTLIST [TESTLIST ...] | -tf TESTFILE
166 [TESTFILE ...]] [-tc TESTCASE] [-c CONFIG] [-sn DEVICE_SN]
167 [-rp REPORT_PATH [REPORT_PATH ...]]
168 [-respath RESOURCE_PATH [RESOURCE_PATH ...]]
169 [-tcpath TESTCASES_PATH [TESTCASES_PATH ...]]
170 [-ta TESTARGS [TESTARGS ...]] [-pt]
171 [-env TEST_ENVIRONMENT [TEST_ENVIRONMENT ...]]
172 [-e EXECTYPE] [-t [TESTTYPE [TESTTYPE ...]]]
173 [-td TESTDRIVER] [-tl TESTLEVEL] [-bv BUILD_VARIANT]
174 [-cov COVERAGE] [--retry RETRY] [--session SESSION]
175 [--dryrun] [--reboot-per-module] [--check-device]
176 [--repeat REPEAT]
177 action task
178 Specify tests to run.
179 positional arguments:
180 action Specify action
181 task Specify task name,such as "ssts", "acts", "hits"
182 ```
183
184 > **NOTE:**
185 >The structure of a basic **run** command is as follows:
186 >```
187 >run [task name] -l module1;moudle2
188 >```
189 >**task name**: task type. This parameter is optional. Generally, the value is **ssts**, **acts**, or **hits**.
190 >**-l**: test cases to execute. Use semicolons \(;\) to separate each two test cases.
191 >**module**: module to test. Generally, there is a **.json** file of the module in the **testcases** directory.
192 >In addition, other parameters can be attached to this command as constraints. Common parameters are as follows:
193 >**-sn**: specifies the devices for test case execution. If this parameter is set to **SN1**, only device SN1 executes the test cases.
194 >**-c**: specifies a new **user\_config.xml** file.
195 >**-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.
196 >**-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.
197 >**-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.
198 >**--reboot-per-module**: restarts the device before test case execution.
199
200- **View the execution result.**
201
202 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.
203
204 ```
205 Structure of the report directory (the default or the specified one)
206 ├── result # Test case execution results of the module
207 │ ├── module name.xml
208 │ ├── ... ...
209 │
210 ├── log # Running logs of devices and tasks
211 │ ├── device 1.log
212 │ ├── ... ...
213 │ ├── task.log
214 ├── summary_report.html # Visual report
215 ├── summary_report.html # Statistical report
216 └── ... ...
217 ```
218
219
220## Repositories Involved<a name="section260848241"></a>
221
222[testing subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/test.md)
223
224**test\_xdevice**
225
226[test\_developertest](https://gitee.com/openharmony/test_developertest/blob/master/README.md)
227
