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
README_zh.md
1# xdevice
2- [xdevice](#xdevice组件)
3 - [简介](#简介)
4 - [目录](#目录)
5 - [约束](#约束)
6 - [使用](#使用)
7 - [相关资料](#相关资料)
8 - [相关仓](#相关仓)
9
10## 简介
11xdevice是OpenHarmony中为测试框架的核心组件，提供用例执行所依赖的相关服务。
12
13xdevice主要包括以下几个主要模块：
14
15- command，用户与测试平台命令行交互模块，提供用户输入命令解析，命令处理。
16- config，测试框架配置模块，提供测试平台串口连接方式和USB连接方式的不同配置选项。
17- driver，测试用例执行器，提供测试用例分发，执行，结果收集等主要测试步骤定义。
18- report，测试报告模块，提供测试结果解析和测试报告生成。
19- scheduler，测试框架调度模块，提供不同类型的测试执行器调度的调度功能。
20- environment，测试框架的环境配置模块，提供设备发现，设备管理的功能。
21- testkit，测试框架工具模块，提供json解析，网络文件挂载等操作。
22- resource，测试框架资源模块，提供设备连接配置文件和报告模板定义。
23
24
25## 目录
26```
27xdevice
28├── config # xdevice组件配置
29│ ├── user_config.xml # xdevice环境配置
30├── src # 组件源码目录
31│ ├── xdevice
32├── plugins # xdevice扩展模块
33| |—— ohos # openharmony测试驱动插件
34│ ├── src # 扩展模块源码
35│ └── setup.py # ohos扩展模块安装脚本
36| |--devicetest # devicetest测试驱动插件
37| └── setup.py # deviectest扩展模块安装脚本
38```
39
40
41## 约束
42运行环境要求：
43
44- python版本>=3.7.5
45- pyserial>=3.3
46- paramiko>=2.7.1
47- rsa>=4.0
48
49## 使用
50- **安装xdevice**
51
52 1. 打开xdevice安装目录。
53
54 2. 打开控制台，执行如下命令：
55 ```
56 python setup.py install
57 ```
58
59- **安装ohos扩展模块**
60
61 1. 打开plugins\ohos安装目录。
62
63 2. 打开控制台，执行如下命令：
64 ```
65 python setup.py install
66 ```
67
68- **修改user\_config.xml**
69
70 user\_config.xml是框架提供的用户配置文件，用户可以根据自身环境信息配置相关内容，具体介绍如下：
71
72 1. **environment环境相关配置**
73
74 以下列出三种device配置。
75
76 ```xml
77 <environment>
78 <!-- 标准系统设备配置>
79 <device type="usb-hdc"> <!-- type: 设备连接方式,usb-hdc表示使用hdc命令控制设备(默认) -->
80 <ip></ip> <!-- ip: 远端设备地址,ip和port为空时使用本地设备,非空时使用远端设备 -->
81 <port></port> <!-- port: 远端设备端口号 -->
82 <sn></sn> <!-- sn: 设备串口号列表,串口号之间用分号;分隔,sn为空时使用所有本地设备,非空时使用指定的sn设备 -->
83 </device>
84
85 <!-- 轻量系统设备配置(轻量系统设备进行测试时，需要刷入已经集成好测试用例的系统，所以需要配置两个串口进行通信，如设备支持，可以将两个serial标签的com口设置为一致)，可配置多个 -->
86 <device type="com" label="wifiiot"> <!-- type: 设备连接方式，com表示连接方式为串口；label：设备种类，如wifiiot -->
87 <serial> <!-- serial：表示一个串口定义 -->
88 <com></com> <!-- serial：表示本地连接的串口，如COM4 -->
89 <type>cmd</type> <!-- type：表示串口类型，cmd为命令串口 -->
90 <baud_rate>115200</baud_rate> <!-- baud_rate、data_bits、stop_bits、timeout：为串口波特率等串口参数，一般采用默认值即可 -->
91 <data_bits>8</data_bits>
92 <stop_bits>1</stop_bits>
93 <timeout>20</timeout>
94 </serial>
95 <serial>
96 <com></com>
97 <type>deploy</type> <!-- type：表示串口类型，cmd为刷机串口 -->
98 <baud_rate>115200</baud_rate>
99 </serial>
100 </device>
101
102 <!-- 小型系统设备配置，可配置多个 -->
103 <device type="com" label="ipcamera">
104 <serial>
105 <com></com>
106 <type>cmd</type>
107 <baud_rate>115200</baud_rate>
108 <data_bits>8</data_bits>
109 <stop_bits>1</stop_bits>
110 <timeout>1</timeout>
111 </serial>
112 </device>
113 <device type="com" label="ipcamera">
114 <ip></ip>
115 <port></port>
116 </device>
117 </environment>
118 ```
119
120 2. **测试用例目录设置**
121
122 以下为testcase标签内容及作用。
123
124 ```xml
125 <testcases>
126 <!-- dir标签和server标签同时配置时只有一个会起作用 -->
127 <!-- 指定测试用例目录，为空则默认设置为当前项目下的testcase文件夹 -->
128 <dir></dir>
129 <!-- nfs挂载配置，label取值为NfsServer -->
130 <server label="NfsServer">
131 <ip></ip> <!-- 挂载环境IP地址 -->
132 <port></port> <!-- 挂载环境端口 -->
133 <dir></dir> <!-- 对应挂载的外部路径 -->
134 <username></username> <!-- 登录用户名(remote为false时，可不填或删除) -->
135 <password></password> <!-- 登录密码(remote为false时，可不填或删除) -->
136 <remote></remote> <!-- nfs服务器与xDevice执行机不在同一机器时，remote配置为true，否则为false -->
137 </server>
138 </testcases>
139 ```
140
141 3. **资源目录设置**
142
143 以下为resource标签内容及作用。
144
145 ```xml
146 <resource>
147 <!-- 指定资源目录，为空则默认设置为当前项目下的resource文件夹 -->
148 <dir></dir>
149 </resource>
150 ```
151
152 4. **日志打印等级设置**
153
154 以下为loglevel标签内容及作用。
155
156 ```xml
157 <!-- 默认为INFO，如需更详细信息可设置为DEBUG -->
158 <loglevel>INFO</loglevel>
159 ```
160
161
162- **选定任务类型**
163
164 设备执行的测试支撑套件是由测试配置文件所指定。
165
166 每类XTS测试套都有一个json格式的测试配置文件，主要配置了需要使用的kits(测试支撑套件)等信息，执行预制和清理操作。
167
168 以下为某个测试支撑套件的json配置文件样例。
169
170 ```json
171 {
172 //测试支撑套件描述
173 "description":"Configuration for acecshi Tests",
174
175 //指定执行当前测试支撑套件的设备
176 //environment设置为可选,如不设置,将从框架中注册的设备中选择一个符合的空闲设备执行用例
177 "environment":{
178 "type":"device",
179 "label":"wifiiot"
180 },
181
182 //指定设备执行的驱动
183 "driver":{
184 "type":"OHJSUnitTest",
185 "test-timeout":"700000",
186 "bundle-name":"com.open.harmony.acetestfive",
187 "package-name":"com.open.harmony.acetestfive",
188 "shell-timeout":"700000",
189 },
190
191 //kit的作用是为了支撑测试执行活动
192 "kits":[
193 {
194 "type":"ShellKit",
195 "run-command":[
196 "remount",
197 "mkdir /data/data/resource"
198 ],
199 "teardown-command":[
200 "remount",
201 "rm -rf /data/data/resource"
202 ]
203 }
204 ]
205 }
206 ```
207
208
209- **启动框架**
210
211 可以通过以下几种方式启动框架
212 - Linux系统可以运行根目录下的run.sh文件
213 - Windows系统可以运行根目录下的run.bat文件
214 - Linux和Windows系统皆可运行项目目录下的src\xdevice\\\_\__main___.py文件
215
216- **执行指令**
217
218 框架指令可以分为三组：help、list、run。在指令序列中，以run为最常用的执行指令。
219
220 1. **help**
221
222 输入help指令可以查询框架指令帮助信息。
223
224 ```bash
225 help:
226 use help to get information.
227 usage:
228 run: Display a list of supported run command.
229 list: Display a list of supported device and task record.
230 Examples:
231 help run
232 help list
233 ```
234
235 说明： help run：展示run指令相关说明 help list：展示 list指令相关说明。
236
237 2. **list**
238
239 list指令用来展示设备和相关的任务信息。
240
241 ```bash
242 list:
243 This command is used to display device list and task record.
244 usage:
245 list
246 list history
247 list <id>
248 Introduction:
249 list: display device list
250 list history: display history record of a serial of tasks
251 list <id>: display history record about task what contains specific id
252 Examples:
253 list
254 list history
255 list 6e****90
256 ```
257
258 说明： list: 展示设备信息 list history: 展示任务历史信息 list <id>: 展示特定id的任务其历史信息。
259
260 3. **run**
261
262 run指令主要用于执行测试任务。
263
264 ```bash
265 run:
266 This command is used to execute the selected testcases.
267 It includes a series of processes such as use case compilation, execution, and result collection.
268 usage: run [-l TESTLIST [TESTLIST ...] | -tf TESTFILE
269 [TESTFILE ...]] [-tc TESTCASE] [-c CONFIG] [-sn DEVICE_SN]
270 [-rp REPORT_PATH [REPORT_PATH ...]]
271 [-respath RESOURCE_PATH [RESOURCE_PATH ...]]
272 [-tcpath TESTCASES_PATH [TESTCASES_PATH ...]]
273 [-ta TESTARGS [TESTARGS ...]] [-pt]
274 [-env TEST_ENVIRONMENT [TEST_ENVIRONMENT ...]]
275 [-e EXECTYPE] [-t [TESTTYPE [TESTTYPE ...]]]
276 [-td TESTDRIVER] [-tl TESTLEVEL] [-bv BUILD_VARIANT]
277 [-cov COVERAGE] [--retry RETRY] [--session SESSION]
278 [--dryrun] [--reboot-per-module] [--check-device]
279 [--repeat REPEAT]
280 action task
281 Specify tests to run.
282 positional arguments:
283 action Specify action
284 task Specify task name,such as "ssts", "acts", "hits"
285 ```
286
287 run常用指令基本使用方式如下。
288
289 | xDevice命令 | 功能 | 示例 |
290 | :---------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
291 | run xts | 运行所有指定类型的xts模块，如acts，hits，ssts等 | run acts |
292 | run -l XXX | 运行指定测试套。如有多个测试套，测试套之间以分号分隔 | run -l ActsWifiServiceTest;ActsLwipTest（testcase目录下的测试套名称） |
293 | run -sn | 指定运行设备sn号，多个sn号之间以分号分隔 | run acts -sn 10.11.133.22:12345 <br/> run acts -sn 2222122;22321321 |
294 | run -rp | 指定报告生成路径，默认报告生成在项目根目录下的reports文件夹，以时间戳或任务id建立子目录 | run acts -rp /XXXX/XXX |
295 | run -respath | 指定测试资源路径，默认为项目根目录下的resource文件夹 | run -respath /XXX/XXX/XXX |
296 | run -tcpath | 指定测试用例路径,默认为项目根目录下的testcases文件夹 | run -tcpath /XXX/XXX/XXX |
297 | run - ta | 指定模块运行参数，可以指定运行测试套中的某个用例，多个用例之间以逗号分隔，目前只支持hits | run hits -ta size:large <br/> run hits -l XXXTest -ta class:XXXX(类名)#XXXXX(方法名) |
298 | run --retry | 重新运行上次失败的测试用例 | run --retry --session 2022-12-13-12-21-11(report任务报告目录) |
299 | run --reboot-per-module | 执行前先重启设备 | run --reboot-per-module -l XXXX |
300
301
302- **查看执行结果**
303
304 框架执行run指令，控制台会输出对应的log打印，还会生成对应的执行结果报告。如果使用了-rp参数指定报告路径，那么报告就会生成在指定的路径下。否则报告会存放在默认目录。
305
306 ```
307 当前报告目录（默认目录/指定目录）
308 ├── result（模块执行结果存放目录）
309 │ ├── <模块名>.xml
310 │ ├── ... ...
311 │
312 ├── log (设备和任务运行log存放目录)
313 │ ├── <设备1>.log
314 │ ├── ... ...
315 │ ├── <任务>.log
316 ├── summary_report.html（测试任务可视化报告）
317 ├── summary_report.html（测试任务数据化报告）
318 ├── detail_report.html（详细执行用例结果可视化报告）
319 ├── failures_report.html（失败用例可视化报告，无失败用例时不生成）
320 ├── summary.ini（记录测试类型，使用的设备，开始时间和结束时间等信息）
321 ├── task_info.record（记录执行命令，失败用例等清单信息）
322 ├── XXX.zip（对上述文件进行压缩得到的文件）
323 ├── summary_report.hash（对压缩文件进行SHA256加密得到的文件）
324 └── ... ...
325 ```
326
327## 相关仓
328
329 [测试子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E6%B5%8B%E8%AF%95%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
330
331 **test\_xdevice**
332
333 [test\_developertest](https://gitee.com/openharmony/test_developertest/blob/master/README_zh.md)
334
