1# xDevice测试调度执行框架使用指南 2 3 4## 概述 5 6OpenHarmony开源操作系统有众多芯片场景基于其之上进行开发版本等相关产品的开发，为了保障OpenHarmony生态的兼容性，OpenHarmony提供了[兼容性测试测评服务](https://www.openharmony.cn/certification/document/guid)，其中针对产品需要进行接口相关的测试执行验证，但是大量自动化用例的执行需要一套调度执行框架，并且支持生成可视化的测试报告等能力，故我们设计并开发了xdevice测试调度框架来支持该场景。 7 8### 简介 9 10xDevice测试调度框架是OpenHarmony中测试基础设施的核心组件，提供调度自动化用例执行所依赖的相关服务，支持大量自动化用例的调度执行能力，并可自带生成可视化测试报告。而xDevice二进制包会跟踪随OpenHarmony的XTS套件编译，开发者可以从XTS套件归档路径中获取xDevice工具， 11 12根据设备类型的不同，xDevice主要测试的任务场景有以下三个： 13 14- 对轻量系统设备进行XTS测试（如：Hi3861开发板) 15- 对小型系统设备进行XTS测试（如：Hi3516开发板) 16- 对标准系统设备进行XTS测试（如：RK3568开发板) 17 18### 实现原理 19 20xDevice包括以下功能模块： 21 22- command：用户与测试平台命令行交互模块，提供用户输入命令解析，命令处理。 23- config：测试框架配置模块，提供测试平台串口连接方式和USB连接方式的不同配置选项。 24- driver：测试用例执行器，提供测试用例分发，执行，结果收集等主要测试步骤定义。 25- report：测试报告模块，提供测试结果解析和测试报告生成。 26- scheduler：测试框架调度模块，提供不同类型的测试执行器调度的调度功能。 27- environment：测试框架的环境配置模块，提供设备发现，设备管理的功能。 28- testkit：测试框架工具模块，提供json解析，网络文件挂载等操作。 29- log：测试框架日志模块，提供记录任务日志以及设备日志的功能。 30 31除了上述功能模块之外，测试调度框架还依赖了用户自定义配置文件，配置文件主要分为两类。 32 33**测试任务配置文件** 34 35user_config.xml是框架提供的测试任务配置文件，用户可以根据自身环境信息配置相关内容，主要包括以下配置内容。 36 37environment环境相关配置，详解介绍如下。 38 39```xml 40<environment> 41 42 <!-- 富设备配置 --> 43<device type="usb-hdc"> <!-- type：设备连接方式,usb-hdc表示使用hdc控制设备(默认),当前框架只支持设置一个usb设备 --> 44 <ip></ip> <!-- ip: 远端设备地址,ip和port为空时使用本地设备,非空时使用远端设备 --> 45 <port></port> <!-- port: 远端设备端口号 --> 46 <sn></sn> <!-- sn: 设备串号列表，串号之间使用分号;分隔，sn为空时使用本地所有设备，非空时使用指定的sn设备 --> 47</device> 48 49<!-- 轻量系统设备配置 --> 50<device type="com" label="wifiiot"> <!-- type: 设备连接方式，com表示连接方式是串口; label: 表示设备种类，如wifiiot --> 51 <serial> <!-- serial: 表示一个串口定义 --> 52 <com></com> <!-- com: 表示本地连接的串口，如COM20 --> 53 <type>cmd</type> <!-- type 表示串口类型，cmd是命令串口 --> 54 <baud_rate>115200</baud_rate> <!-- baud_rate、data_bits、stop_bits、timeout: 为串口波特率等串口参数 ，一般采用默认值即可 --> 55 <data_bits>8</data_bits> 56 <stop_bits>1</stop_bits> 57 <timeout>20</timeout> 58 </serial> 59 <serial> 60 <com></com> 61 <type>deploy</type> <!-- type 表示串口类型，deploy是刷机串口 --> 62 <baud_rate>115200</baud_rate> 63 </serial> 64</device> 65 66<!-- 小型系统设备本地连接配置 --> 67<device type="com" label="ipcamera"> 68 <serial> 69 <com></com> 70 <type>cmd</type> 71 <baud_rate>115200</baud_rate> 72 <data_bits>8</data_bits> 73 <stop_bits>1</stop_bits> 74 <timeout>1</timeout> 75 </serial> 76</device> 77 78<!-- 小型系统设备远端连接配置,可配置多个 --> 79<device type="com" label="ipcamera"> 80 <ip></ip> 81 <port></port> 82</device> 83</environment> 84``` 85 86测试用例目录设置。 87 88```xml 89<testcases> 90 <!-- dir标签和server标签同时配置时只有一个会起作用 --> 91 <!-- 指定测试用例目录,为空则默认设置为当前项目下的testcase文件夹 --> 92 <dir></dir> 93 94 <!-- nfs挂载配置，label取值为NfsServer --> 95 <server label="NfsServer"> 96 <ip></ip> <!-- 挂载环境IP地址 --> 97 <port></port> <!-- 挂载环境端口 --> 98 <dir></dir> <!-- 对应挂载的外部路径 --> 99 <username></username> <!-- 登录用户名 --> 100 <password></password> <!-- 登录用户密码 --> 101 <remote></remote> <!-- nfs服务器与xDevice执行机不在同一台机器时,remote配置为true,否则为false --> 102 </server> 103</testcases> 104``` 105 106资源目录设置。 107 108```xml 109<resource> 110 <!-- 指定资源目录,为空则默认设置为当前项目下的resource文件夹 --> 111 <dir></dir> 112</resource> 113``` 114 115日志打印级别设置。 116 117```xml 118<!-- 默认为INFO,如需更加详细的信息可切换为DEBUG --> 119<loglevel>INFO</loglevel> 120``` 121 122**测试套配置文件** 123 124设备执行的测试支撑套件是由测试配置文件所指定。 125 126每个测试套都都有一个测试配置文件，主要配置了需要使用的测试支撑套件（kits）等信息，并支持配置执行预制和清理操作。 127 128以下为配置文件样例。 129 130```json 131{ 132 // 测试支撑套件描述 133 "description": "Configuration for aceceshi Tests", 134 135 // 指定执行当前测试支撑套的设备 136 "environment": { 137 "type": "device", 138 "label": "wifiiot" 139 }, 140 141 // 指定设备执行的驱动 142 "driver": { 143 "type": "OHJSUnitTest", 144 "test-timeout": "700000", 145 "bundle-name": "com.open.harmony.acetestfive", 146 "package-name": "com.open.harmony.acetestfive", 147 "shell-timeout": "700000" 148 }, 149 // kit的作用主要是为了支撑测试执行活动，在测试前执行预制操作(Setup)，在测试后执行清理操作(Teardown) 150 "kits": [ 151 { 152 "type": "ShellKit", 153 "run-command": [ 154 "remount", 155 "mkdir /data/data/resource", 156 "chmod -R 777 /data/data/resource", 157 "settings put secure adb_install_need_confirm 0" 158 ], 159 "teardown-command": [ 160 "remount", 161 "rm -rf /data/data/resource" 162 ] 163 }, 164 ] 165} 166``` 167 168### 测试命令 169 170测试命令可以分为三组：help、list、run。在指令序列中，以run为最常用的执行指令。 171 172------ 173 174输入help指令可以查询框架指令帮助信息。 175 176```text 177help: 178 use help to get information. 179usage: 180 run: Display a list of supported run command. 181 list: Display a list of supported device and task record. 182Examples: 183 help run 184 help list 185``` 186 187**说明：** 188 189help run：展示run指令相关说明 。 190 191help list：展示 list指令相关说明。 192 193------ 194 195list指令用来展示设备和相关的任务信息。 196 197```text 198list: 199 This command is used to display device list and task record. 200usage: 201 list 202 list history 203 list <id> 204Introduction: 205 list: display device list 206 list history: display history record of a serial of tasks 207 list <id>: display history record about task what contains specific id 208Examples: 209 list 210 list history 211 list 6e****90 212``` 213 214 **说明：** 215 216 list: 展示设备信息。 217 218 list history: 展示任务历史信息 。 219 220 list <id>: 展示特定id的任务其历史信息。 221 222------ 223 224run指令主要用于执行测试任务。 225 226```text 227run: 228 This command is used to execute the selected testcases. 229 It includes a series of processes such as use case compilation, execution, and result collection. 230usage: run [-l TESTLIST [TESTLIST ...] | -tf TESTFILE 231 [TESTFILE ...]] [-tc TESTCASE] [-c CONFIG] [-sn DEVICE_SN] 232 [-rp REPORT_PATH [REPORT_PATH ...]] 233 [-respath RESOURCE_PATH [RESOURCE_PATH ...]] 234 [-tcpath TESTCASES_PATH [TESTCASES_PATH ...]] 235 [-ta TESTARGS [TESTARGS ...]] [-pt] 236 [-env TEST_ENVIRONMENT [TEST_ENVIRONMENT ...]] 237 [-e EXECTYPE] [-t [TESTTYPE [TESTTYPE ...]]] 238 [-td TESTDRIVER] [-tl TESTLEVEL] [-bv BUILD_VARIANT] 239 [-cov COVERAGE] [--retry RETRY] [--session SESSION] 240 [--dryrun] [--reboot-per-module] [--check-device] 241 [--repeat REPEAT] 242 action task 243Specify tests to run. 244 positional arguments: 245 action Specify action 246 task Specify task name,such as "ssts", "acts", "hits" 247``` 248 249run指令基本使用方法如下。 250 251| xDevice命令 | 功能 | 示例 | 252| :----------: | :----------------------------------------------------------: | :----------------------------------------------------------: | 253| run xts | 运行所有指定类型的XTS模块，如acts，hits，ssys等 | run acts | 254| run -l xxx | 运行指定的模块测试套，模块间用分号隔离 | run -l ActsWifiServiceTest;ActsLwipTest | 255| run -sn | 指定运行设备的SN号，多个SN号用分号隔离 | run acts -sn 10.117.183.37:17001<br/>run acts -sn 88Y02******57723;VEG02******16642 | 256| run -rp | 指定报告生成的路径，默认会在工作目录的reports下用时间戳或任务ID建立子目录 | run acts -rp /suites/hits/xdevice_reports/2020.09.28-14.21.26 | 257| run -respath | 指定测试资源路径，默认为resource目录 | run acts -respath /cloud/zidane/xts/release/suites/resource | 258| run -ta | 指定模块运行参数，可以指定运行模块用例中指定的用例，多个用例用逗号隔离，目前支持JS驱动测试套 | run acts -ta class:ohos.hardware.soundtrigger.SoundTriggerTest#testKeyphraseParcelUnparcel_noUsers | 259| run --retry | 重新运行上一次任务的失败用例，生成新的测试报告 | run –retryrun --retry --session 2020-10-30-17-15-11（任务目录名） | 260 261### 测试报告 262 263框架执行run指令，控制台会输出对应的log打印，还会生成对应的执行结果报告。如果使用了-rp参数指定报告路径，那么报告就会生成在指定的路径下。否则报告会存放在默认目录。 264 265```text 266当前报告目录（默认目录/指定目录） 267 ├── result(模块执行结果存放目录) 268 │ ├── <模块名>.xml 269 │ ├── ... ... 270 │ 271 ├── log (设备和任务运行log存放目录) 272 │ ├── <设备1>.log 273 │ ├── ... ... 274 │ ├── <任务>.log 275 ├── summary_report.xml(任务汇总数据报告) 276 ├── summary_report.html(任务汇总可视化报告) 277 ├── details_report.html(用例执性可视化报告) 278 ├── failures_report.html(失败用例可视化报告,无失败用例时不生成) 279 ├── summary.ini(记录测试类型,使用的设备,开始和结束时间等信息) 280 ├── task_info.record(记录执行命令，失败用例清单等信息) 281 ├── xxxx.zip(对上述文件进行压缩得到的压缩文件) 282 ├── summary_report.hash(对压缩文件进行sha256加密得到的文件) 283 └── ... ... 284``` 285 286 287## 环境准备 288 289 290### 环境要求 291 292- python版本>=3.7 293- pyserial>=3.3 294- paramiko>=2.7.1 295- rsa>=4.0 296 297 298### 安装xDevice 299 300- 安装基础框架xDevice。 301 302 1. 进入xDevice根目录。 303 304 ```bash 305 cd testfwk_xdevice 306 ``` 307 308 2. 打开控制台，执行如下命令。 309 310 ```bash 311 python setup.py install 312 ``` 313 314- 安装OpenHarmony驱动插件ohos。 315 316 1. 进行plugin/ohos目录。 317 318 ```bash 319 cd testfwk_xdevice/plugin/ohos 320 ``` 321 322 2. 打开控制台，当前用户下执行如下命令。 323 324 ```bash 325 python setup.py install 326 ``` 327 328### 检验环境是否搭建成功 329 330检验xDevice是否安装成功。 331 3321. 进入xDevice根目录。 333 334 ```bash 335 cd testfwk_xdevice 336 ``` 337 3382. 打开控制台，执行如下命令。 339 340 ```bash 341 python -m pip list 342 ``` 343 3443. 查看是否已经成功安装**xdevice**以及**xdevice-ohos**两个库。 345 346 ```text 347 xdevice 0.0.0 348 xdevice-ohos 0.0.0 349 ``` 350 351查看xDevice工具是否能够正常运行。 352 3531. 进入xDevice根目录。 354 355 ```bash 356 cd testfwk_xdevice 357 ``` 358 3592. 打开控制台，执行如下命令。 360 361 ```bash 362 python -m xdevice 363 ``` 364 3653. 查看控制台是否正常输出如下信息。 366 367 ```text 368 [2022-10-13 15:43:31,284] [30076] [Main] [INFO] [*************** xDevice Test Framework 2.11.0.1091 Starting ***************] 369 [2022-10-13 15:43:31,286] [30076] [ManagerLite] [WARNING] [wifiiot local com cannot be empty, please check] 370 [2022-10-13 15:43:31,286] [30076] [ManagerLite] [WARNING] [ipcamera local com cannot be empty, please check] 371 [2022-10-13 15:43:31,287] [30076] [ManagerLite] [WARNING] [device com or ip cannot be empty, please check] 372 >>> 373 ``` 374 375 376## 轻量系统设备XTS测试指导（wifiiot） 377 3781. 识别串口用途，修改根目录中的user_config.xml文件。 379 380 type为cmd的com口对应板子上的AT命令串口，用于对设备发送指令，示例中配置为ChA(COM20)串口号。 381 382 type为deploy的com口对应板子上的日志输出串口，用于镜像烧录和日志打印，示例中配置为ChB(COM18)串口号。 383 384 若AT命令串口和日志输出串口共用，可以配置为相同，即user_config中的type为cmd的com口与type为deploy的com口可配置为一样的端口，如COM18。 385 386  387 388 user_config.xml的修改示例如下。 389 390 ```xml 391 <user_config> 392 <environment> 393 <device type="com" label="wifiiot"> 394 <serial> 395 <com>com20</com> 396 <type>cmd</type> 397 <baud_rate>115200</baud_rate> 398 <data_bits>8</data_bits> 399 <stop_bits>1</stop_bits> 400 <timeout>20</timeout> 401 </serial> 402 <serial> 403 <com>com18</com> 404 <type>deploy</type> 405 <baud_rate>115200</baud_rate> 406 </serial> 407 </device> 408 </environment> 409 <testcases> 410 <dir></dir> 411 <server label="NfsServer"> 412 <ip></ip> 413 <port></port> 414 <dir></dir> 415 <username></username> 416 <password></password> 417 <remote></remote> 418 </server> 419 </testcases> 420 <resource> 421 <dir></dir> 422 </resource> 423 <loglevel>DEBUG</loglevel> 424 </user_config> 425 ``` 426 4272. 在xDevice根目录下新建testcase文件夹用于存放测试套文件，具体XTS测试套从系统构建的每日构建中获取。 428 429 每日构建：http://ci.openharmony.cn/dailys/dailybuilds 430 431 测试套测试配置文件json，示例如下。 432 433 ```json 434 { 435 "description": "Config for ActsAllTest test cases", 436 "environment": [ 437 { 438 "type": "device", 439 "label": "wifiiot" 440 } 441 ], 442 "kits": [ 443 { 444 "type": "DeployKit", 445 "timeout": "20000", 446 "burn_file": "acts/Hi3861_wifiiot_app_allinone.bin" 447 } 448 ], 449 "driver": { 450 "type": "CTestLite" 451 } 452 } 453 ``` 454 4553. 执行用例 456 457 进入xDevice根目录；打开控制台进入xDevice控制台，执行如下命令。 458 459 ```bash 460 python -m xdevice 461 ``` 462 463 执行测试套命令。 464 465 ```text 466 run -l ActsAllTest 467 ``` 468 469 执行结果如下。 470 471  472 473## 小型系统设备XTS测试指导（ipcamera） 474 4751. 识别串口用途。 476 477 type为cmd的com口对应板子上的AT命令串口，用于对设备发送指令，示例中配置为ChA(COM20)串口号。 478 479  480 481 ipcamera设备有两种连接方式，一种是本地串口连接，一种是通过局域网ip连接。 482 4832. 配置NFS服务器 484 485 NFS挂载方式有两种，一种是远程PC挂载方式，一种是本地局域网挂载方式。 486 487 本地局域网NFS服务的配置方法如下。 488 489 1. 下载安装NFS服务器。下载地址：https://www.hanewin.net/nfs-e.htm 490 491 2. 配置输出->编辑输出表文件。 492 493  494 495 3. 添加路径NFS共享路径（如：D:\HS\NFS_Share_File -public –alldirs），这里要注意ftp的IP地址192.168.1.10为开发板的IP。 496 497  498 499 4. 停止NFS服务器->重启运行NFS服务器使刚才添加的共享路径生效。 500 501 5. 找到ipcamera设备在PC上面映射的网口：控制面板->网络和Internet->网络共享中心->以太网状态->以太网属性->手动设置IP地址为:192.168.1.11。 502 503  504 5053. 修改根目录中的user_config.xml文件，示例如下。 506 507 ```xml 508 <user_config> 509 <environment> 510 <device type="com" label="ipcamera"> <!--两种方式二选一：本地连接方式--> 511 <serial> 512 <com>com20</com> 513 <type>cmd</type> 514 <baud_rate>115200</baud_rate> 515 <data_bits>8</data_bits> 516 <stop_bits>1</stop_bits> 517 <timeout>1</timeout> 518 </serial> 519 </device> 520 <device type="com" label="ipcamera"> <!--两种方式二选一：局域网连接方式--> 521 <ip>10.176.49.47</ip> 522 <port>10003</port> 523 </device> 524 </environment> 525 <testcases> 526 <dir></dir> 527 <server label="NfsServer"> <!--两种方式二选一：远程挂载方式--> 528 <ip>10.176.48.202</ip> 529 <port>1022</port> 530 <dir>/data/data/local/</dir> 531 <username>root</username> 532 <password>xxx</password> 533 <remote>true</remote> 534 </server> 535 <server label="NfsServer"> <!--两种方式二选一：局域网挂载方式--> 536 <ip>192.168.1.11</ip> 537 <port>2049</port> 538 <dir>D:\test</dir> 539 <remote>false</remote> 540 </server> 541 </testcases> 542 <resource> 543 <dir></dir> 544 </resource> 545 <loglevel>DEBUG</loglevel> 546 </user_config> 547 ``` 548 5494. 在xDevice根目录下新建testcase文件夹用于存放测试套文件，具体XTS测试套从系统构建的每日构建。 550 551 每日构建：http://ci.openharmony.cn/dailys/dailybuilds 552 553 测试套测试配置文件json，示例如下。 554 555 ```json 556 { 557 "description": "Config for kernel test cases", 558 "environment": [ 559 { 560 "type": "device", 561 "label": "ipcamera" 562 } 563 ], 564 "kits": [ 565 { 566 "type": "MountKit", 567 "server": "NfsServer", 568 "mount": [ 569 { 570 "source": "testcases/kernel", 571 "target": "/test_root/kernel" 572 } 573 ] 574 } 575 ], 576 "driver": { 577 "type": "CppTestLite", 578 "excute": "/test_root/kernel/ActsKernelIPCTest.bin" 579 } 580 } 581 ``` 582 5835. 执行用例。 584 585 进入xDevice根目录，打开控制台进入xDevice控制台，执行如下命令。 586 587 ```bash 588 python -m xdevice 589 ``` 590 591 执行测试套命令。 592 593 ```text 594 run -l kernel 595 ``` 596 597 执行结果如下。 598 599  600 601## 标准系统设备XTS测试指导（RK3568） 602 6031. 配置hdc工具，从每日构建上下载ohos_sdk最新版本即可。 604 605 每日构建地址：http://ci.openharmony.cn/dailys/dailybuilds 606 607 下载工具后，把hdc配置到环境变量中，配置方法：右键单击我的电脑->属性->高级系统设置->环境变量->Path。 608 6092. 执行如下命令查看设备是否正常连接。 610 611 ```bash 612 hdc_std list targets 613 ``` 614 6153. 修改user_config.xml文件，示例如下。 616 617 ```xml 618 <user_config> 619 <environment> 620 <device type="usb-hdc"> 621 <ip></ip> 622 <port></port> 623 <sn>xxx;xxx</sn> <!--连接多个设备的SN号用分号分割--> 624 </device> 625 </environment> 626 <testcases> 627 <dir></dir> 628 </testcases> 629 <resource> 630 <dir></dir> 631 </resource> 632 <loglevel>DEBUG</loglevel> 633 </user_config> 634 ``` 635 6364. 在xDevice根目录下新建testcase文件夹用于存放测试套文件，具体XTS测试套从系统构建的每日构建中获取。 637 638 每日构建：http://ci.openharmony.cn/dailys/dailybuilds 639 640 测试套测试配置文件json，示例如下。 641 642 ```json 643 { 644 "description": "Configuration for hjunit demo Tests", 645 "driver": { 646 "type": "OHJSUnitTest", 647 "test-timeout": "180000", 648 "bundle-name": "ohos.acts.bundle.stage.test", 649 "module-name": "phone", 650 "shell-timeout": "600000", 651 "testcase-timeout": 70000 652 }, 653 "kits": [ 654 { 655 "test-file-name": [ 656 "ActBmsStageEtsTest.hap" 657 ], 658 "type": "AppInstallKit", 659 "cleanup-apps": true 660 }, 661 { 662 "type": "ShellKit", 663 "teardown-command":[ 664 "bm uninstall -n ohos.acts.bundle.stage.test" 665 ] 666 } 667 ] 668 } 669 ``` 670 6715. 执行用例。 672 673 进入xDevice根目录，打开控制台进入xDevice控制台，执行如下命令。 674 675 ```bash 676 python -m xdevice 677 ``` 678 679 执行测试套命令。 680 681 ```text 682 run -l ActBmsStageEtsTest 683 ``` 684 685 执行结果如下。 686 687  688 689## 常见问题 690 691### hdc list targets能查找到设备，但xDevice识别不到设备。 692 693**问题描述** 694 695出现如下错误。 696 697 698 699**可能原因** 700 701环境变量中曾设置过HDC_SERVER_PORT变量修改过hdc的端口，由于xDevice默认需要使用8710端口，若曾修改过该端口会导致xDevice框架无法识别设备。 702 703**解决方法** 704 705检查是否有设置HDC_SERVER_PROT变量，若有设置，请把该端口的值修改为8710，然后重启xDevice即可。 706 707
