README.md
1# 调试调优自动化测试框架使用指南
2
3[TOC]
4
5## 1 框架设计
6
7调试调优的通用流程可抽象为如下步骤：
8
9- IDE将应用推入设备，并拉起应用（或attach到已启动应用上）
10
11- IDE与应用建立websocket连接
12- IDE与应用之间通过websocket发送和接受调试调优相关的业务消息，消息格式遵循CDP协议
13
14该自动化框架依据以上流程，实现了应用启动、websocket连接、消息交互等步骤的自动化，基于此可以进行调试调优用例的执行与开发
15
16框架的目录结构与功能描述如下：
17
18### aw
19
20封装了自动化框架通用的Action Words，包括：
21
22- `application.py`：应用启动、停止、安装、卸载等相关接口
23- `fport.py`：执行hdc fport命令的相关接口，指定端口号、进程ID和线程ID等，用于后续的websocket连接
24- `utils.py`：封装各种通用的工具类接口
25- `websocket.py`：websocket连接的关键基础类，功能包括：
26 - connect server和debugger server的websocket连接
27 - 采用消息队列实现websocket的消息发送与接收
28 - **支持多实例应用的实现**：connect server的消息接收队列持续监听addInstance消息，一旦接收到新的instance后，便会创建对应的debugger server连接
29 - **异步实现**：多条websocket连接的消息接收与发送通道均实现为协程，可被提交到taskpool中作为异步任务执行
30- `taskpool.py`：异步任务池，功能包括：
31 - 采用队列实现任务池的生命周期控制
32 - **可在任意时刻提交任务到taskpool中进行异步执行**
33 - 可为每个任务添加任意多个回调函数，在任务结束后执行
34- `cdp`：cdp协议的封装
35
36### scenario_test
37
38场景测试用例目录
39
40- `conftest.py`：基于pytest fixture实现的测试套方法
41- `test_name_number.py`：测试用例文件
42
43### resource
44
45用于放置编译后的应用hap包
46
47目录下的archive.json记录了应用工程名、hap包名和bundle name的对应关系
48
49### pytest.ini
50
51python pytest库的配置文件
52
53### run.py
54
55批量执行测试用例的入口文件
56
57### requirements.txt
58
59自动化测试框架的python库依赖
60
61## 2 测试用例执行
62
63### 准备工作
64
65- 操作系统为Windows
66
67- 已安装hdc.exe并配置好环境变量，可通过cmd启动执行
68
69- 测试设备已连接，且开启USB调试
70
71- 下载自动化测试项目
72
73 代码仓：https://gitee.com/openharmony/arkcompiler_toolchain
74
75 项目目录：`.\arkcompiler_toolchain\test\autotest`
76
77- Python已安装且版本 >= 3.8.0
78
79- 安装Python依赖
80
81 ```powershell
82 > cd .\arkcompiler_toolchain\test\autotest
83 > python -m pip install -r requirements.txt [--trusted-host hostname -i Python_Package_Index]
84 ```
85
86- 下载hap包
87
88 通过归档链接下载hap包，并将所有hap包移动到.\arkcompiler_toolchain\test\autotest\resource目录下
89
90### 执行用例
91
92cmd进入`.\arkcompiler_toolchain\test\autotest`目录，执行：
93
94```python
95> python .\run.py
96```
97
98用例执行过程中，cmd会实时输出用例日志信息，执行完成后，cmd会展示执行结果，同时会生成测试报告，并导出hilog日志：
99
100- `.\arkcompiler_toolchain\test\autotest\report\report.html`：测试报告
101
102- `.\arkcompiler_toolchain\test\autotest\report\xxx.hilog.txt`：每个测试用例对应一份debug级别的hilog日志
103
104- `.\arkcompiler_toolchain\test\autotest\report\faultlogger`：用例执行过程中产生的错误日志
105
106## 3 测试用例开发
107
108### 测试应用
109
110根据测试用例场景，确定并开发你的测试应用，编译后将应用hap包放在`.\arkcompiler_toolchain\test\autotest\resource`目录下
111
112### 测试套
113
114测试套以pytest fixture形式开发，对应于`.\arkcompiler_toolchain\test\autotest\scenario_test\conftest.py`中的一个方法；
115
116对于一个确定的测试应用，和一套固定的配置信息，我们可以将他们抽象出来作为一个fixture，基于该fixture我们可以开发多个测试用例
117
118fixture写法举例如下：
119
120```python
121@pytest.fixture(scope='class') # 该装饰器指定下面的函数是一个fixture
122def test_suite_debug_01(): # fixture名称
123 logging.info('running test_suite_debug_01')
124
125 bundle_name = 'com.example.worker'
126 hap_name = 'MyApplicationWorker.hap'
127
128 config = {'connect_server_port': 15678,
129 'debugger_server_port': 15679,
130 'bundle_name': bundle_name,
131 'hap_path': rf'{os.path.dirname(__file__)}\..\resource\{hap_name}'}
132
133 # 将应用推入设备，并以-D模式启动
134 pid = Application.launch_application(config['bundle_name'], config['hap_path'], start_mode='-D')
135 assert pid != 0, logging.error(f'Pid of {hap_name} is 0!')
136 config['pid'] = pid
137
138 # hdc fport
139 Fport.clear_fport()
140 Fport.fport_connect_server(config['connect_server_port'], config['pid'], config['bundle_name'])
141
142 # 实例化WebSocket对象
143 config['websocket'] = WebSocket(config['connect_server_port'], config['debugger_server_port'])
144
145 # 实例化TaskPool对象
146 config['taskpool'] = TaskPool()
147
148 return config
149
150```
151
152样例参考：`.\arkcompiler_toolchain\test\autotest\scenario_test\conftest.py => test_suite_debug_01`
153
154### 测试用例
155
156测试用例放置在`.\arkcompiler_toolchain\test\autotest\scenario_test\`目录下，每个.py文件对应一个测试用例，命名规则为`test\_测试项\_编号.py`
157
158测试用例代码文件结构如下：
159
160```python
161@pytest.mark.debug
162@pytest.mark.timeout(40)
163class TestDebug01:
164 def setup_method(self):
165 pass
166
167 def teardown_method(self):
168 pass
169
170 def test(self, test_suite_debug_01):
171 pass
172
173 async def procedure(self, websocket):
174 pass
175
176```
177
178- 装饰器`@pytest.mark.debug`标明该用例是一个测试debug功能的用例，debug可以改为其它任意名字，如cpu_profiler
179
180- 装饰器`@pytest.mark.timeout(40)`标明该用例必须在40s内执行完毕，否则不通过
181
182- `class TestDebug01` 是该测试用例对应的测试类，测试类必须以**Test**开头
183
184- `setup_class` 方法在用例开始执行前被执行，其中放置一些需要初始化的内容
185
186- `teardown_clas` 方法在用例结束执行后被执行，其中放置一些需要结束或清理的内容
187
188- `test` 方法是测试用例执行的入口，注意以下几点：
189
190 - 第二个参数为fixture，不仅可以标识该用例属于哪个测试套，还可以获取该fixture执行后的返回结果；在test方法被执行前，fixture会首先被执行
191
192 - 通过下面的代码，将websocket中封装的main task提交到taskpool，等待所有任务结束并捕获异常
193
194 ```Python
195 taskpool.submit(websocket.main_task(taskpool, websocket, self.procedure, pid))
196 taskpool.await_taskpool()
197 taskpool.task_join()
198 if taskpool.task_exception:
199 raise taskpool.task_exception
200 ```
201
202- **`procedure`方法**：测试步骤和预期结果执行的位置，在test方法中，procedure作为参数被提交到taskpool中，因此其同样作为一个**异步任务**在执行
203
204当我们新增一个测试用例时，主要工作就是在procedure方法中放置我们的测试步骤和预期结果。首先，我们可以手动执行一次测试用例，并抓出connect server、debugger server交互的日志信息。此后，我们可以对照日志信息在procedure方法中添加内容，每一次消息发送可以当作一个测试步骤，每一次消息接收可以当作一次预期结果
205
206例如：
207
208```Python
209################################################################################################################
210# main thread: Debugger.getPossibleAndSetBreakpointByUrl
211################################################################################################################
212id = next(self.id_generator) # 获取此次发送消息的id
213
214# 构造断点信息
215locations = [debugger.BreakLocationUrl(url='entry|entry|1.0.0|src/main/ets/pages/Index.ts', line_number=22),
216 debugger.BreakLocationUrl(url='entry|entry|1.0.0|src/main/ets/pages/Index.ts', line_number=26)]
217
218# 发送消息并获取返回值，调用cdp库中的debugger.get_possible_and_set_breakpoint_by_url(locations)可以自动拼接cdp消息
219response = await communicate_with_debugger_server(main_thread_instance_id,
220 main_thread_to_send_queue,
221 main_thread_received_queue,
222 debugger.get_possible_and_set_breakpoint_by_url(locations),
223 id)
224
225# 判断返回结果是否符合预期
226response = json.loads(response)
227assert response['id'] == id
228assert response['result']['locations'][0]['id'] == 'id:22:0:entry|entry|1.0.0|src/main/ets/pages/Index.ts'
229assert response['result']['locations'][1]['id'] == 'id:26:0:entry|entry|1.0.0|src/main/ets/pages/Index.ts'
230```
231
232注意：
233
234- 建议在测试类声明后，用类注释写明该测试用例的内容；
235- 每个测试步骤和预期结果之间，用上述注释方式隔开，并标明此次测试步骤的操作；
236- 对于aw中未实现的CDP协议，请封装在aw/cdp目录下对应的domain文件中
237
238样例参考：`.\arkcompiler_toolchain\test\autotest\scenario_test\test_debug_01.py`
239
240