1/* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit TestKit 19 */ 20 21import { Callback } from './@ohos.base'; 22 23/** 24 * Enumerates the metric type of performance test. 25 * 26 * @enum { number } 27 * @syscap SystemCapability.Test.PerfTest 28 * @atomicservice 29 * @since 20 30 * @test 31 */ 32declare enum PerfMetric { 33 /** 34 * Duration of the single execution, the unit is ms. 35 * 36 * @syscap SystemCapability.Test.PerfTest 37 * @atomicservice 38 * @since 20 39 * @test 40 */ 41 DURATION = 0, 42 43 /** 44 * Process CPU load during a single execution, the unit is %. 45 * 46 * @syscap SystemCapability.Test.PerfTest 47 * @atomicservice 48 * @since 20 49 * @test 50 */ 51 CPU_LOAD = 1, 52 53 /** 54 * Process CPU usage during a single execution, the unit is %. 55 * 56 * @syscap SystemCapability.Test.PerfTest 57 * @atomicservice 58 * @since 20 59 * @test 60 */ 61 CPU_USAGE = 2, 62 63 /** 64 * Memory change before and after a single execution, including the shared library, the unit is KB. 65 * 66 * @syscap SystemCapability.Test.PerfTest 67 * @atomicservice 68 * @since 20 69 * @test 70 */ 71 MEMORY_RSS = 3, 72 73 /** 74 * Memory change before and after a single execution, excluding shared libraries, the unit is KB. 75 * 76 * @syscap SystemCapability.Test.PerfTest 77 * @atomicservice 78 * @since 20 79 * @test 80 */ 81 MEMORY_PSS = 4, 82 83 /** 84 * Application start response delay, the unit is ms. 85 * Marks: 86 * 1) Delay calculation is restricted by system dotting reporting. The start time is the time when the click event is reported, 87 * and the end time of the response delay is the time when the system responds to the first frame after the click. 88 * It is different from the end-to-end user-perceived delay. 89 * 2) Application start delay can be collected in the following scenarios: clicking the application icon on the desktop; 90 * clicking the application on the Multi-Task Center; clicking the application icon on the Dock; 91 * clicking the application icon on the application center. 92 * 3) This metric does not support the test of current application. 93 * 4) During the test, only the data of the first startup of the specified application can be collected. 94 * 95 * @syscap SystemCapability.Test.PerfTest 96 * @atomicservice 97 * @since 20 98 * @test 99 */ 100 APP_START_RESPONSE_TIME = 5, 101 102 /** 103 * Application start completion delay, the unit is ms. 104 * Marks: 105 * 1) Delay calculation is restricted by system dotting reporting. The start time is the time when the click event is reported, 106 * and the end time of the completion delay is the time when the first frame is displayed after the application is started. 107 * It is different from the end-to-end user-perceived delay. 108 * 2) Application start delay can be collected in the following scenarios: clicking the application icon on the desktop; 109 * clicking the application on the Multi-Task Center; clicking the application icon on the Dock; 110 * clicking the application icon on the application center. 111 * 3) This metric does not support the test of current application. 112 * 4) During the test, only the data of the first start of specified application can be collected. 113 * 114 * @syscap SystemCapability.Test.PerfTest 115 * @atomicservice 116 * @since 20 117 * @test 118 */ 119 APP_START_COMPLETE_TIME = 6, 120 121 /** 122 * Page switching completion delay, the unit is ms. 123 * Marks: 124 * 1) Delay calculation is restricted by system dotting and reporting. The start time is the time when the click event is reported, 125 * and the end time of the completion delay is the time when the first frame is displayed after page is switched. 126 * It is different from the end-to-end user-perceived delay. 127 * 2) Page switching delay can be collected in the page switchover scenario of the Router or Navigation component. 128 * 3) During the test, only the data of the first page switching in specified application can be collected. 129 * 130 * @syscap SystemCapability.Test.PerfTest 131 * @atomicservice 132 * @since 20 133 * @test 134 */ 135 PAGE_SWITCH_COMPLETE_TIME = 7, 136 137 /** 138 * List sliding frame rate, the unit is fps. 139 * Mark: 140 * 1) List sliding frame rate: refers to the frequency at which the screen can be refreshed when the list is sliding. 141 * Only the sliding frame rate of the List, grid, scroll, and waterflow scroll components of ArKUI subsystems can be collected. 142 * 2) During the test, only the data of the first sliding of the component in specified application can be collected. 143 * 144 * @syscap SystemCapability.Test.PerfTest 145 * @atomicservice 146 * @since 20 147 * @test 148 */ 149 LIST_SWIPE_FPS = 8, 150} 151 152/** 153 * Test task execution strategy, which is used to initialize the PerfTest object in {@link PerfTest.create}. 154 * 155 * @typedef PerfTestStrategy 156 * @syscap SystemCapability.Test.PerfTest 157 * @atomicservice 158 * @since 20 159 * @test 160 */ 161declare interface PerfTestStrategy { 162 /** 163 * List of performance metrics to be collected. 164 * 165 * @type { Array<PerfMetric> } 166 * @syscap SystemCapability.Test.PerfTest 167 * @atomicservice 168 * @since 20 169 * @test 170 */ 171 metrics: Array<PerfMetric>; 172 173 /** 174 * Code segment for performance testing. 175 * The input parameter type of actionCode is {@link Callback<boolean>}. As actionCode can be defined as asynchronous function, 176 * developers need to invoke this callback function when the execution of actionCode is complete, 177 * to help PerfTest identify the time when the execution of the actionCode is complete. 178 * For example, the input parameter callback function of actionCode is defined as "(finish: Callback<boolean>)". 179 * When actionCode is executed completly, "finish(true)" should be invoked, the value true indicates actionCode is successfully executed. 180 * When an exception occurs, "finish(false)" should be invoked, the value false indicates actionCode is unsuccessfully executed. 181 * 182 * @type { Callback<Callback<boolean>> } 183 * @syscap SystemCapability.Test.PerfTest 184 * @atomicservice 185 * @since 20 186 * @test 187 */ 188 actionCode: Callback<Callback<boolean>>; 189 190 /** 191 * Reset code segment after each test. It is executed after {@link actionCode}. Data collection is not performed during this execution. 192 * The input parameter type of resetCode is {@link Callback<boolean>}. As resetCode can be defined as asynchronous function, 193 * developers need to invoke this callback function when the execution of resetCode is complete, 194 * to help PerfTest identify the time when the execution of the resetCode is complete. 195 * For example, the input parameter callback function of resetCode is defined as "(finish: Callback<boolean>)". 196 * When resetCode is executed completly, "finish(true)" should be invoked, the value true indicates resetCode is successfully executed. 197 * When an exception occurs, "finish(false)" should be invoked, the value false indicates resetCode is unsuccessfully executed. 198 * 199 * @type { ?Callback<Callback<boolean>> } 200 * @syscap SystemCapability.Test.PerfTest 201 * @atomicservice 202 * @since 20 203 * @test 204 */ 205 resetCode?: Callback<Callback<boolean>>; 206 207 /** 208 * The package name of the application to be tested. The default value is the package name of current application. 209 * 210 * @type { ?string } 211 * @syscap SystemCapability.Test.PerfTest 212 * @atomicservice 213 * @since 20 214 * @test 215 */ 216 bundleName?: string; 217 218 /** 219 * Iterations of the test, default is 5. 220 * 221 * @type { ?number } 222 * @syscap SystemCapability.Test.PerfTest 223 * @atomicservice 224 * @since 20 225 * @test 226 */ 227 iterations?: number; 228 229 /** 230 * Timeout in millisecond for executing a single-time {@link actionCode} or {@link resetCode}, default is 10000. 231 * 232 * @type { ?number } 233 * @syscap SystemCapability.Test.PerfTest 234 * @atomicservice 235 * @since 20 236 * @test 237 */ 238 timeout?: number; 239} 240 241/** 242 * Test results of specified performance metric. 243 * 244 * @typedef PerfMeasureResult 245 * @syscap SystemCapability.Test.PerfTest 246 * @atomicservice 247 * @since 20 248 * @test 249 */ 250declare interface PerfMeasureResult { 251 /** 252 * The metric this result belongs to. 253 * 254 * @type { PerfMetric } 255 * @readonly 256 * @syscap SystemCapability.Test.PerfTest 257 * @atomicservice 258 * @since 20 259 * @test 260 */ 261 readonly metric: PerfMetric; 262 263 /** 264 * The round values of the specified metric in the test. 265 * 266 * @type { Array<number> } 267 * @readonly 268 * @syscap SystemCapability.Test.PerfTest 269 * @atomicservice 270 * @since 20 271 * @test 272 */ 273 readonly roundValues: Array<number>; 274 275 /** 276 * The maximum of the specified metric in the test. 277 * 278 * @type { number } 279 * @readonly 280 * @syscap SystemCapability.Test.PerfTest 281 * @atomicservice 282 * @since 20 283 * @test 284 */ 285 readonly maximum: number; 286 287 /** 288 * The minimum of the specified metric in the test. 289 * 290 * @type { number } 291 * @readonly 292 * @syscap SystemCapability.Test.PerfTest 293 * @atomicservice 294 * @since 20 295 * @test 296 */ 297 readonly minimum: number; 298 299 /** 300 * The average of the specified metric in the test. 301 * 302 * @type { number } 303 * @readonly 304 * @syscap SystemCapability.Test.PerfTest 305 * @atomicservice 306 * @since 20 307 * @test 308 */ 309 readonly average: number; 310} 311 312/** 313 * The unified facade of PerformanceTest framework, can be used to executing the performance test task. 314 * 315 * @syscap SystemCapability.Test.PerfTest 316 * @atomicservice 317 * @since 20 318 * @test 319 */ 320declare class PerfTest { 321 /** 322 * Create an {@link PerfTest} object. 323 * 324 * @param { PerfTestStrategy } strategy - test task execution strategy. 325 * @returns { PerfTest } the {@link PerfTest} object. 326 * @throws { BusinessError } 32400001 - Initialization failed. 327 * @throws { BusinessError } 32400002 - Internal error. Possible causes: 1. IPC connection failed. 2. The object does not exist. 328 * @throws { BusinessError } 32400003 - Parameter verification failed. 329 * @throws { BusinessError } 32400007 - The API does not support concurrent calls. 330 * @static 331 * @syscap SystemCapability.Test.PerfTest 332 * @atomicservice 333 * @since 20 334 * @test 335 */ 336 static create(strategy: PerfTestStrategy): PerfTest; 337 338 /** 339 * Start the performance test. 340 * 341 * @returns { Promise<void> } 342 * @throws { BusinessError } 32400002 - Internal error. Possible causes: 1. IPC connection failed. 2. The object does not exist. 343 * @throws { BusinessError } 32400004 - Failed to execute the callback. Possible causes: 1. An exception is thrown in the callback. 2. Callback execution timed out. 344 * @throws { BusinessError } 32400005 - Failed to collect metric data. 345 * @throws { BusinessError } 32400007 - The API does not support concurrent calls. 346 * 347 * @syscap SystemCapability.Test.PerfTest 348 * @atomicservice 349 * @since 20 350 * @test 351 */ 352 run(): Promise<void>; 353 354 /** 355 * Get the test result of a specified performance metric. If no test result exist, -1 is returned for all results. 356 * 357 * @param { PerfMetric } metric - performance metric for which the result will be get. 358 * @returns { PerfMeasureResult } test results of specified performance metric. 359 * @throws { BusinessError } 32400002 - Internal error. Possible causes: 1. IPC connection failed. 2. The object does not exist. 360 * @throws { BusinessError } 32400003 - Parameter verification failed. 361 * @throws { BusinessError } 32400006 - Failed to obtain the measurement result. 362 * @throws { BusinessError } 32400007 - The API does not support concurrent calls. 363 * @syscap SystemCapability.Test.PerfTest 364 * @atomicservice 365 * @since 20 366 * @test 367 */ 368 getMeasureResult(metric: PerfMetric): PerfMeasureResult; 369 370 /** 371 * Destroy the {@link PerfTest} object. 372 * @throws { BusinessError } 32400002 - Internal error. Possible causes: 1. IPC connection failed. 2. The object does not exist. 373 * @throws { BusinessError } 32400007 - The API does not support concurrent calls. 374 * @syscap SystemCapability.Test.PerfTest 375 * @atomicservice 376 * @since 20 377 * @test 378 */ 379 destroy(): void; 380} 381 382export { 383 PerfMetric, 384 PerfTestStrategy, 385 PerfMeasureResult, 386 PerfTest 387}; 388