1# @ohos.test.PerfTest 2 3<!--Kit: Test Kit--> 4<!--Subsystem: Test--> 5<!--Owner: @inter515--> 6<!--Designer: @inter515--> 7<!--Tester: @laonie666--> 8<!--Adviser: @Brilliantry_Rui--> 9 10PerfTest提供白盒性能测试能力，供开发者在测试场景使用，支持对指定代码段或指定场景的性能数据测试，支持自动化执行测试代码段，并采集耗时、CPU、内存、时延、帧率等性能数据。 11 12> **说明：** 13> - 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> - 本模块接口在<!--RP1-->[自动化测试脚本](../../application-test/arkxtest-guidelines.md)<!--RP1End-->中使用。 15> - 本模块接口不支持并发调用。 16> - 本模块接口适用于手机、平板、PC/2in1、智慧屏、车机。 17 18 19## 导入模块 20 21```ts 22import { PerfMetric, PerfTest, PerfTestStrategy, PerfMeasureResult } from '@kit.TestKit'; 23``` 24 25## PerfMetric 26 27框架支持采集的性能指标。 28 29**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 30 31**系统能力**：SystemCapability.Test.PerfTest 32 33| 名称 | 值 | 说明 | 34| ---------- | ---- | -------- | 35| DURATION | 0 | 代码段执行耗时，单位：ms。 | 36| CPU_LOAD | 1 | 应用进程CPU负载，取值为百分比。 | 37| CPU_USAGE | 2 | 应用进程CPU使用率，取值为百分比。 | 38| MEMORY_RSS | 3 | 代码段单次执行结束时，应用进程占用物理内存（含共享库），单位：KB。 | 39| MEMORY_PSS | 4 | 代码段单次执行结束时，应用进程占用物理内存（不含共享库），单位：KB。 | 40| APP_START_RESPONSE_TIME | 5 | 应用启动的响应时延，单位：ms。 | 41| APP_START_COMPLETE_TIME | 6 | 应用启动的完成时延，单位：ms。 | 42| PAGE_SWITCH_COMPLETE_TIME | 7 | 应用内页面切换的完成时延，单位：ms。 | 43| LIST_SWIPE_FPS | 8 | 应用内列表滑动的帧率，单位：fps。 | 44 45> **说明** 46> 47> 1. 以上指标均用于采集指定应用进程的性能数据，非系统整机性能数据。 48> 2. CPU（CPU_LOAD/CPU_USAGE）、内存（MEMORY_RSS/MEMORY_PSS）数据采集说明如下： 49> - 测试过程中，代码段执行开始前和代码段执行结束后，会分别采集指定应用进程的CPU和内存数据，因此测试过程中需要保证被测应用进程一直存在。 50> 3. 应用启动时延（APP_START_RESPONSE_TIME/APP_START_COMPLETE_TIME）数据采集说明如下： 51> - 应用启动时延数据受系统打点上报限制，开始时间为点击事件上报时间点，响应时延结束时间为点击后系统响应首帧的上屏时间点（首帧显示在屏幕上的时间点），完成时延结束时间为应用启动后的首帧上屏时间点，与端到端用户感知时延存在差异。 52> - 应用启动时延数据采集支持的场景：桌面点击应用图标启动、Dock栏点击应用图标启动、应用中心点击应用图标启动。 53> - 单次测试期间，仅第一次指定应用启动的时延数据会被采集。 54> 4. 页面切换时延（PAGE_SWITCH_COMPLETE_TIME）数据采集说明如下： 55> - 页面切换时延计算受系统打点上报限制，开始时间为点击事件上报时间点，完成时延结束时间为页面切换后的首帧上屏时间点，与端到端用户感知时延存在差异。 56> - 页面切换时延数据采集支持的场景：Router、Navigation控件内的页面切换。 57> - 单次测试期间，仅指定应用内第一次页面切换的时延数据会被采集。 58> 5. 列表滑动帧率（LIST_SWIPE_FPS）数据采集说明如下： 59> - 列表滑动帧率：指的是在列表滑动时，屏幕每秒钟渲染更新帧的次数。 60> - 列表滑动帧率数据采集支持的场景：ArkUI子系统List、Grid、scroll、waterflow滚动控件列表的滑动。 61> - 单次测试期间，仅指定应用内第一次列表滑动的帧率数据会被采集。 62 63 64## PerfTestStrategy 65 66性能测试执行策略。 67 68**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 69 70**系统能力**：SystemCapability.Test.PerfTest 71 72| 名称 | 类型 | 只读 | 可选 | 说明 | 73| ---- | ------ | ---- | ---- |-----------| 74| metrics | Array\<[PerfMetric](#perfmetric)> | 否 | 否 | 被测性能指标列表。 | 75| actionCode | Callback\<Callback\<boolean>> | 否 | 否 | 测试代码段。 | 76| resetCode | Callback\<Callback\<boolean>> | 否 | 是 | 测试结束环境重置代码段。默认为空，框架运行时不执行此代码段。 | 77| bundleName | string | 否 | 是 | 被测应用包名。默认为""，框架运行时测试当前测试应用的性能数据。 | 78| iterations | number | 否 | 是 | 测试迭代执行次数，默认值为5。 | 79| timeout | number | 否 | 是 | 单次代码段（actionCode/resetCode）执行的超时时间，默认值为10000ms。 | 80 81> **说明** 82> 83> 属性actionCode和resetCode的入参类型为回调函数"Callback\<boolean>"。在代码段中需要主动调用此回调函数，通知框架代码段执行完成，否则会导致代码段执行超时。 84> 其中，回调函数的参数为boolean类型，true代表代码段执行符合预期，false代码段执行不符合预期。[代码示例](#create)。 85 86## PerfMeasureResult 87 88性能指标对应测量结果数据。 89 90**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 91 92**系统能力**：SystemCapability.Test.PerfTest 93 94| 名称 | 类型 | 只读 | 可选 | 说明 | 95| ------ | ------ | ---- | ---- | ------------------------- | 96| metric | [PerfMetric](#perfmetric) | 是 | 否 | 被测性能指标。 | 97| roundValues | Array\<number> | 是 | 否 | 被测性能指标的各轮测量数据值。当数据采集失败时返回-1。 | 98| maximum | number | 是 | 否 | 各轮测量数据最大值（剔除为-1的数据后计算）。 | 99| minimum | number | 是 | 否 | 各轮测量数据最小值（剔除为-1的数据后计算）。 | 100| average | number | 是 | 否 | 各轮测量数据平均值（剔除为-1的数据后计算）。 | 101 102 103## PerfTest 104 105PerfTest类为白盒性能测试框架的总入口，提供测试任务创建、测试代码段执行和数据采集、测量结果获取等能力。 106 107### create 108 109static create(strategy: PerfTestStrategy): PerfTest 110 111静态方法，构造一个PerfTest对象，并返回该对象。 112 113**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 114 115**系统能力**：SystemCapability.Test.PerfTest 116 117**参数：** 118 119| 参数名 | 类型 | 必填 | 说明 | 120| -------- | ------ | ---- | ------------------------------- | 121| strategy | [PerfTestStrategy](#perfteststrategy) | 是 | 性能测试执行策略。 | 122 123**返回值：** 124 125| 类型 | 说明 | 126| -------- | ---------------------- | 127| [PerfTest](#perftest) | 返回构造的PerfTest对象。 | 128 129**错误码：** 130 131以下错误码的详细介绍请参见[perftest错误码](errorcode-perftest.md)。 132 133| 错误码ID | 错误信息 | 134| -------- | ---------------------- | 135| 32400001 | Initialization failed. | 136| 32400002 | Internal error. Possible causes: 1. IPC connection failed. 2. The object does not exist. | 137| 32400003 | Parameter verification failed. | 138| 32400007 | The API does not support concurrent calls. | 139 140**示例：** 141 142```ts 143import { PerfMetric, PerfTest, PerfTestStrategy } from '@kit.TestKit'; 144 145async function demo() { 146 let metrics: Array<PerfMetric> = [PerfMetric.DURATION]; 147 let num = 0; 148 let actionCode = async (finish: Callback<boolean>) => { // 定义测试代码段，入参类型'Callback<boolean>'，命名为finish 149 for (let index = 0; index < 10000; index++) { 150 num++; 151 } 152 finish(true); // 调用finish回调函数，通知代码段执行结束，且执行符合预期 153 } 154 let resetCode = async (finish: Callback<boolean>) => { // 定义测试结束环境重置代码段 155 num = 0; 156 finish(true); 157 } 158 let perfTestStrategy: PerfTestStrategy = { 159 metrics: metrics, 160 actionCode: actionCode, 161 resetCode: resetCode, 162 timeout: 30000, 163 iterations: 10, 164 }; 165 let perfTest: PerfTest = PerfTest.create(perfTestStrategy); // 构造一个PerfTest对象，创建测试任务 166} 167``` 168 169### run 170 171run(): Promise\<void> 172 173运行性能测试，迭代执行测试代码段并采集性能数据，使用Promise回调。 174 175**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 176 177**系统能力**：SystemCapability.Test.PerfTest 178 179**返回值：** 180 181| 类型 | 说明 | 182| -------- | ---------------------- | 183| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 184 185**错误码：** 186 187以下错误码的详细介绍请参见[perftest错误码](errorcode-perftest.md)。 188 189| 错误码ID | 错误信息 | 190| -------- | ---------------------- | 191| 32400002 | Internal error. Possible causes: 1. IPC connection failed. 2. The object does not exist. | 192| 32400004 | Failed to execute the callback. Possible causes: 1. An exception is thrown in the callback. 2. Callback execution timed out. | 193| 32400005 | Failed to collect metric data. | 194| 32400007 | The API does not support concurrent calls. | 195 196**示例：** 197 198```ts 199import { PerfMetric, PerfTest, PerfTestStrategy } from '@kit.TestKit'; 200 201async function demo() { 202 let metrics: Array<PerfMetric> = [PerfMetric.DURATION]; 203 let num = 0; 204 let actionCode = async (finish: Callback<boolean>) => { 205 for (let index = 0; index < 10000; index++) { 206 num++; 207 } 208 finish(true); 209 } 210 let perfTestStrategy: PerfTestStrategy = { 211 metrics: metrics, 212 actionCode: actionCode 213 }; 214 let perfTest: PerfTest = PerfTest.create(perfTestStrategy); 215 await perfTest.run(); // 运行性能测试 216} 217``` 218 219### getMeasureResult 220 221getMeasureResult(metric: PerfMetric): PerfMeasureResult 222 223获取指定性能指标的测量数据。 224 225**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 226 227**系统能力**：SystemCapability.Test.PerfTest 228 229**参数：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| -------- | ------ | ---- | ------------------------------- | 233| metric | [PerfMetric](#perfmetric) | 是 | 性能指标。 | 234 235**返回值：** 236 237| 类型 | 说明 | 238| -------- | ---------------------- | 239| [PerfMeasureResult](#perfmeasureresult) | 性能指标对应测量结果数据。 | 240 241**错误码：** 242 243以下错误码的详细介绍请参见[perftest错误码](errorcode-perftest.md)。 244 245| 错误码ID | 错误信息 | 246| -------- | ---------------------- | 247| 32400002 | Internal error. Possible causes: 1. IPC connection failed. 2. The object does not exist. | 248| 32400003 | Parameter verification failed. | 249| 32400006 | Failed to obtain the measurement result. | 250| 32400007 | The API does not support concurrent calls. | 251 252**示例：** 253 254```ts 255import { PerfMetric, PerfTest, PerfTestStrategy } from '@kit.TestKit'; 256 257async function demo() { 258 let metrics: Array<PerfMetric> = [PerfMetric.DURATION]; 259 let num = 0; 260 let actionCode = async (finish: Callback<boolean>) => { 261 for (let index = 0; index < 10000; index++) { 262 num++; 263 } 264 finish(true); 265 } 266 let perfTestStrategy: PerfTestStrategy = { 267 metrics: metrics, 268 actionCode: actionCode 269 }; 270 let perfTest: PerfTest = PerfTest.create(perfTestStrategy); 271 await perfTest.run(); 272 let res = perfTest.getMeasureResult(PerfMetric.DURATION); // 获取指定性能指标的测量数据 273} 274``` 275 276### destroy 277 278destroy(): void 279 280销毁PerfTest对象。 281 282**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 283 284**系统能力**：SystemCapability.Test.PerfTest 285 286**错误码：** 287 288以下错误码的详细介绍请参见[perftest错误码](errorcode-perftest.md)。 289 290| 错误码ID | 错误信息 | 291| -------- | ---------------------- | 292| 32400002 | Internal error. Possible causes: 1. IPC connection failed. 2. The object does not exist. | 293| 32400007 | The API does not support concurrent calls. | 294 295**示例：** 296 297```ts 298import { PerfMetric, PerfTest, PerfTestStrategy } from '@kit.TestKit'; 299 300async function demo() { 301 let metrics: Array<PerfMetric> = [PerfMetric.DURATION]; 302 let num = 0; 303 let actionCode = async (finish: Callback<boolean>) => { 304 for (let index = 0; index < 10000; index++) { 305 num++; 306 } 307 finish(true); 308 } 309 let perfTestStrategy: PerfTestStrategy = { 310 metrics: metrics, 311 actionCode: actionCode 312 }; 313 let perfTest: PerfTest = PerfTest.create(perfTestStrategy); 314 await perfTest.run(); 315 perfTest.destroy(); // 销毁PerfTest对象 316} 317```