1# AbilityDelegator 2 3The **AbilityDelegator** module provides APIs for managing [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instances that are used to monitor the lifecycle state changes of a specified ability. You can use the APIs to add and remove **AbilityMonitor** instances, wait for an ability to reach the **onCreate** lifecycle state, set the waiting time, obtain the lifecycle state of an ability, obtain the top ability of the current application, and start an ability. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> The APIs of this module can be used only in <!--RP1-->[arkxtest](../../application-test/arkxtest-guidelines.md)<!--RP1End-->. 10 11## Modules to Import 12 13```ts 14import { abilityDelegatorRegistry } from '@kit.TestKit'; 15``` 16 17## Usage 18 19An **AbilityDelegator** object is obtained by calling **getAbilityDelegator** in **abilityDelegatorRegistry**. 20```ts 21import { abilityDelegatorRegistry } from '@kit.TestKit'; 22``` 23 24## AbilityDelegator 25 26### addAbilityMonitor<sup>9+</sup> 27 28addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<void>): void 29 30Adds an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. Multi-thread concurrent calls are not supported. 31 32**Atomic service API**: This API can be used in atomic services since API version 11. 33 34**System capability**: SystemCapability.Ability.AbilityRuntime.Core 35 36**Parameters** 37 38| Name | Type | Mandatory| Description | 39| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 40| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 41| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the **AbilityMonitor** instance is added, **err** is **undefined**. Otherwise, **err** is an error object. | 42 43**Error codes** 44 45For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 46 47| ID| Error Message| 48| ------- | -------- | 49| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 50| 16000100 | Calling AddAbilityMonitor failed. | 51 52**Example** 53 54```ts 55import { abilityDelegatorRegistry } from '@kit.TestKit'; 56import { UIAbility } from '@kit.AbilityKit'; 57import { BusinessError } from '@kit.BasicServicesKit'; 58 59let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 60let monitor: abilityDelegatorRegistry.AbilityMonitor = { 61 abilityName: 'abilityname', 62 onAbilityCreate: onAbilityCreateCallback 63}; 64 65function onAbilityCreateCallback(data: UIAbility) { 66 console.info(`onAbilityCreateCallback, data: ${JSON.stringify(data)}`); 67} 68 69abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 70abilityDelegator.addAbilityMonitor(monitor, (error: BusinessError) => { 71 console.error(`addAbilityMonitor fail, error: ${JSON.stringify(error)}`); 72}); 73``` 74 75### addAbilityMonitor<sup>9+</sup> 76 77addAbilityMonitor(monitor: AbilityMonitor): Promise\<void> 78 79Adds an **AbilityMonitor** instance. This API uses a promise to return the result. Multi-thread concurrent calls are not supported. 80 81**Atomic service API**: This API can be used in atomic services since API version 11. 82 83**System capability**: SystemCapability.Ability.AbilityRuntime.Core 84 85**Parameters** 86 87| Name | Type | Mandatory| Description | 88| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 89| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 90 91**Return value** 92 93| Type | Description | 94| -------------- | ------------------- | 95| Promise\<void> |Promise that returns no value.| 96 97**Error codes** 98 99For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 100 101| ID| Error Message| 102| ------- | -------- | 103| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 104| 16000100 | Calling AddAbilityMonitor failed. | 105 106**Example** 107 108```ts 109import { abilityDelegatorRegistry } from '@kit.TestKit'; 110import { UIAbility } from '@kit.AbilityKit'; 111 112function onAbilityCreateCallback(data: UIAbility) { 113 console.info('onAbilityCreateCallback'); 114} 115 116let monitor: abilityDelegatorRegistry.AbilityMonitor = { 117 abilityName: 'abilityname', 118 onAbilityCreate: onAbilityCreateCallback 119}; 120let abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 121 122abilityDelegator.addAbilityMonitor(monitor).then(() => { 123 console.info('addAbilityMonitor promise'); 124}); 125``` 126 127### addAbilityMonitorSync<sup>10+</sup> 128 129addAbilityMonitorSync(monitor: AbilityMonitor): void 130 131Adds an **AbilityMonitor** instance. This API returns the result synchronously. Multi-thread concurrent calls are not supported. 132 133**Atomic service API**: This API can be used in atomic services since API version 11. 134 135**System capability**: SystemCapability.Ability.AbilityRuntime.Core 136 137**Parameters** 138 139| Name | Type | Mandatory| Description | 140| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 141| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 142 143**Error codes** 144 145For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 146 147| ID| Error Message| 148| ------- | -------- | 149| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 150| 16000100 | Calling AddAbilityMonitorSync failed. | 151 152**Example** 153 154```ts 155import { abilityDelegatorRegistry } from '@kit.TestKit'; 156import { UIAbility } from '@kit.AbilityKit'; 157 158let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 159 160function onAbilityCreateCallback(data: UIAbility) { 161 console.info('onAbilityCreateCallback'); 162} 163 164let monitor: abilityDelegatorRegistry.AbilityMonitor = { 165 abilityName: 'abilityname', 166 onAbilityCreate: onAbilityCreateCallback 167}; 168 169abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 170abilityDelegator.addAbilityMonitorSync(monitor); 171``` 172 173### removeAbilityMonitor<sup>9+</sup> 174 175removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<void>): void 176 177Removes an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. 178 179**Atomic service API**: This API can be used in atomic services since API version 11. 180 181**System capability**: SystemCapability.Ability.AbilityRuntime.Core 182 183**Parameters** 184 185| Name | Type | Mandatory| Description | 186| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 187| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 188| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the **AbilityMonitor** instance is removed, **err** is **undefined**. Otherwise, **err** is an error object. | 189 190**Error codes** 191 192For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 193 194| ID| Error Message| 195| ------- | -------- | 196| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 197| 16000100 | Calling RemoveAbilityMonitor failed. | 198 199**Example** 200 201```ts 202import { abilityDelegatorRegistry } from '@kit.TestKit'; 203import { UIAbility } from '@kit.AbilityKit'; 204import { BusinessError } from '@kit.BasicServicesKit'; 205 206let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 207 208function onAbilityCreateCallback(data: UIAbility) { 209 console.info('onAbilityCreateCallback'); 210} 211 212let monitor: abilityDelegatorRegistry.AbilityMonitor = { 213 abilityName: 'abilityname', 214 onAbilityCreate: onAbilityCreateCallback 215}; 216 217abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 218abilityDelegator.removeAbilityMonitor(monitor, (error: BusinessError) => { 219 console.error(`removeAbilityMonitor fail, error: ${JSON.stringify(error)}`); 220}); 221``` 222 223### removeAbilityMonitor<sup>9+</sup> 224 225removeAbilityMonitor(monitor: AbilityMonitor): Promise\<void> 226 227Removes an **AbilityMonitor** instance. This API uses a promise to return the result. Multi-thread concurrent calls are not supported. 228 229**Atomic service API**: This API can be used in atomic services since API version 11. 230 231**System capability**: SystemCapability.Ability.AbilityRuntime.Core 232 233**Parameters** 234 235| Name | Type | Mandatory| Description | 236| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 237| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 238 239**Return value** 240 241| Type | Description | 242| -------------- | ------------------- | 243| Promise\<void> | Promise that returns no value.| 244 245**Error codes** 246 247For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 248 249| ID| Error Message| 250| ------- | -------- | 251| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 252| 16000100 | Calling RemoveAbilityMonitor failed. | 253 254- Example 255 256```ts 257import { abilityDelegatorRegistry } from '@kit.TestKit'; 258import { UIAbility } from '@kit.AbilityKit'; 259 260let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 261let monitor: abilityDelegatorRegistry.AbilityMonitor = { 262 abilityName: 'abilityname', 263 onAbilityCreate: onAbilityCreateCallback 264}; 265 266function onAbilityCreateCallback(data: UIAbility) { 267 console.info('onAbilityCreateCallback'); 268} 269 270abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 271abilityDelegator.removeAbilityMonitor(monitor).then(() => { 272 console.info('removeAbilityMonitor promise'); 273}); 274``` 275 276### removeAbilityMonitorSync<sup>10+</sup> 277 278removeAbilityMonitorSync(monitor: AbilityMonitor): void 279 280Removes an **AbilityMonitor** instance. This API returns the result synchronously. Multi-thread concurrent calls are not supported. 281 282**Atomic service API**: This API can be used in atomic services since API version 11. 283 284**System capability**: SystemCapability.Ability.AbilityRuntime.Core 285 286**Parameters** 287 288| Name | Type | Mandatory| Description | 289| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 290| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 291 292**Error codes** 293 294For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 295 296| ID| Error Message| 297| ------- | -------- | 298| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 299| 16000100 | Calling RemoveAbilityMonitorSync failed. | 300 301**Example** 302 303```ts 304import { abilityDelegatorRegistry } from '@kit.TestKit'; 305import { UIAbility } from '@kit.AbilityKit'; 306 307let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 308let monitor: abilityDelegatorRegistry.AbilityMonitor = { 309 abilityName: 'abilityname', 310 onAbilityCreate: onAbilityCreateCallback 311}; 312 313function onAbilityCreateCallback(data: UIAbility) { 314 console.info('onAbilityCreateCallback'); 315} 316 317abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 318abilityDelegator.removeAbilityMonitorSync(monitor); 319``` 320 321### waitAbilityMonitor<sup>9+</sup> 322 323waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<UIAbility>): void 324 325Waits for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result. Multi-thread concurrent calls are not supported. 326 327**Atomic service API**: This API can be used in atomic services since API version 11. 328 329**System capability**: SystemCapability.Ability.AbilityRuntime.Core 330 331**Parameters** 332 333| Name | Type | Mandatory| Description | 334| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 335| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 336| callback | AsyncCallback\<[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the **Ability** instance obtained. Otherwise, **err** is an error object. | 337 338**Error codes** 339 340For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 341 342| ID| Error Message| 343| ------- | -------- | 344| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 345| 16000100 | Calling WaitAbilityMonitor failed. | 346 347**Example** 348 349```ts 350import { abilityDelegatorRegistry } from '@kit.TestKit'; 351import { UIAbility } from '@kit.AbilityKit'; 352import { BusinessError } from '@kit.BasicServicesKit'; 353 354let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 355let monitor: abilityDelegatorRegistry.AbilityMonitor = { 356 abilityName: 'abilityname', 357 onAbilityCreate: onAbilityCreateCallback 358}; 359 360function onAbilityCreateCallback(data: UIAbility) { 361 console.info('onAbilityCreateCallback'); 362} 363 364abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 365abilityDelegator.waitAbilityMonitor(monitor, (error: BusinessError, data: UIAbility) => { 366 if (error) { 367 console.error(`waitAbilityMonitor fail, error: ${JSON.stringify(error)}`); 368 } else { 369 console.log(`waitAbilityMonitor success, data: ${JSON.stringify(data)}`); 370 } 371}); 372``` 373 374### waitAbilityMonitor<sup>9+</sup> 375 376waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback\<UIAbility>): void 377 378Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result. Multi-thread concurrent calls are not supported. 379 380**Atomic service API**: This API can be used in atomic services since API version 11. 381 382**System capability**: SystemCapability.Ability.AbilityRuntime.Core 383 384**Parameters** 385 386| Name | Type | Mandatory| Description | 387| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 388| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 389| timeout | number | Yes | Maximum waiting time, in ms. | 390| callback | AsyncCallback\<[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | 391 392**Error codes** 393 394For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 395 396| ID| Error Message| 397| ------- | -------- | 398| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 399| 16000100 | Calling WaitAbilityMonitor failed. | 400 401**Example** 402 403```ts 404import { abilityDelegatorRegistry } from '@kit.TestKit'; 405import { UIAbility } from '@kit.AbilityKit'; 406import { BusinessError } from '@kit.BasicServicesKit'; 407 408let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 409let timeout = 100; 410let monitor: abilityDelegatorRegistry.AbilityMonitor = { 411 abilityName: 'abilityname', 412 onAbilityCreate: onAbilityCreateCallback 413}; 414 415function onAbilityCreateCallback(data: UIAbility) { 416 console.info('onAbilityCreateCallback'); 417} 418 419abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 420abilityDelegator.waitAbilityMonitor(monitor, timeout, (error: BusinessError, data: UIAbility) => { 421 if (error && error.code !== 0) { 422 console.error(`waitAbilityMonitor fail, error: ${JSON.stringify(error)}`); 423 } else { 424 console.log(`waitAbilityMonitor success, data: ${JSON.stringify(data)}`); 425 } 426}); 427``` 428 429 430 431### waitAbilityMonitor<sup>9+</sup> 432 433waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise\<UIAbility> 434 435Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses a promise to return the result. Multi-thread concurrent calls are not supported. 436 437**Atomic service API**: This API can be used in atomic services since API version 11. 438 439**System capability**: SystemCapability.Ability.AbilityRuntime.Core 440 441**Parameters** 442 443| Name | Type | Mandatory| Description | 444| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 445| monitor | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) | Yes | [AbilityMonitor](../apis-ability-kit/js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instance.| 446| timeout | number | No | Maximum waiting time, in ms. | 447 448**Return value** 449 450| Type | Description | 451| ----------------------------------------------------------- | -------------------------- | 452| Promise\<[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)> | Promise used to return the **Ability** instance obtained.| 453 454**Error codes** 455 456For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 457 458| ID| Error Message| 459| ------- | -------- | 460| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 461| 16000100 | Calling WaitAbilityMonitor failed. | 462 463**Example** 464 465```ts 466import { abilityDelegatorRegistry } from '@kit.TestKit'; 467import { UIAbility } from '@kit.AbilityKit'; 468 469let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 470let monitor: abilityDelegatorRegistry.AbilityMonitor = { 471 abilityName: 'abilityname', 472 onAbilityCreate: onAbilityCreateCallback 473}; 474 475function onAbilityCreateCallback(data: UIAbility) { 476 console.info('onAbilityCreateCallback'); 477} 478 479abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 480abilityDelegator.waitAbilityMonitor(monitor).then((data: UIAbility) => { 481 console.info('waitAbilityMonitor promise'); 482}); 483``` 484 485### getAppContext<sup>9+</sup> 486 487getAppContext(): Context 488 489Obtains the application context. 490 491**Atomic service API**: This API can be used in atomic services since API version 11. 492 493**System capability**: SystemCapability.Ability.AbilityRuntime.Core 494 495**Return value** 496 497| Type | Description | 498| ------------------------------------- | ------------------------------------------- | 499| [Context](../apis-ability-kit/js-apis-inner-application-context.md) | [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 500 501**Example** 502 503```ts 504import { abilityDelegatorRegistry } from '@kit.TestKit'; 505 506let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 507 508abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 509 510let context = abilityDelegator.getAppContext(); 511``` 512 513### getAbilityState<sup>9+</sup> 514 515getAbilityState(ability: UIAbility): number 516 517Obtains the lifecycle state of an ability. 518 519**Atomic service API**: This API can be used in atomic services since API version 11. 520 521**System capability**: SystemCapability.Ability.AbilityRuntime.Core 522 523**Parameters** 524 525| Name | Type | Mandatory| Description | 526| ------- | ------------------------------------------------- | ---- | --------------- | 527| ability | [UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md) | Yes | Target ability.| 528 529**Return value** 530 531| Type | Description | 532| ------ | ------------------------------------------------------------ | 533| number | Lifecycle state of the ability, which is defined by **AbilityLifecycleState**.| 534 535**Error codes** 536 537For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 538 539| ID| Error Message| 540| ------- | -------- | 541| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 542 543**Example** 544 545```ts 546import { abilityDelegatorRegistry } from '@kit.TestKit'; 547import { UIAbility } from '@kit.AbilityKit'; 548import { BusinessError } from '@kit.BasicServicesKit'; 549 550let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 551let ability: UIAbility; 552 553abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 554abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 555 console.info('getCurrentTopAbility callback'); 556 ability = data; 557 let state = abilityDelegator.getAbilityState(ability); 558 console.info('getAbilityState ${state}'); 559}); 560``` 561 562### getCurrentTopAbility<sup>9+</sup> 563 564getCurrentTopAbility(callback: AsyncCallback\<UIAbility>): void 565 566Obtains the top ability of this application. This API uses an asynchronous callback to return the result. It cannot be called in the worker thread. 567 568**Atomic service API**: This API can be used in atomic services since API version 11. 569 570**System capability**: SystemCapability.Ability.AbilityRuntime.Core 571 572**Parameters** 573 574| Name | Type | Mandatory| Description | 575| -------- | ------------------------------------------------------------ | ---- | ------------------ | 576| callback | AsyncCallback\<[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. If the top ability is obtained, **err** is **undefined** and **data** is the **Ability** instance obtained. Otherwise, **err** is an error object.| 577 578**Error codes** 579 580For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 581 582| ID| Error Message| 583| ------- | -------- | 584| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 585| 16000100 | Calling GetCurrentTopAbility failed. | 586 587**Example** 588 589```ts 590import { abilityDelegatorRegistry } from '@kit.TestKit'; 591import { UIAbility } from '@kit.AbilityKit'; 592import { BusinessError } from '@kit.BasicServicesKit'; 593 594let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 595let ability: UIAbility; 596 597abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 598abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 599 console.info('getCurrentTopAbility callback'); 600 ability = data; 601}); 602``` 603 604### getCurrentTopAbility<sup>9+</sup> 605 606getCurrentTopAbility(): Promise\<UIAbility> 607 608Obtains the top ability of this application. This API uses a promise to return the result. It cannot be called in the worker thread. 609 610**Atomic service API**: This API can be used in atomic services since API version 11. 611 612**System capability**: SystemCapability.Ability.AbilityRuntime.Core 613 614**Return value** 615 616| Type | Description | 617| ----------------------------------------------------------- | -------------------------------------- | 618| Promise\<[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)> | Promise used to return the top ability.| 619 620**Error codes** 621 622For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 623 624| ID| Error Message| 625| ------- | -------- | 626| 16000100 | Calling GetCurrentTopAbility failed. | 627 628**Example** 629 630```ts 631import { abilityDelegatorRegistry } from '@kit.TestKit'; 632import { UIAbility } from '@kit.AbilityKit'; 633 634let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 635let ability: UIAbility; 636 637abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 638abilityDelegator.getCurrentTopAbility().then((data: UIAbility) => { 639 console.info('getCurrentTopAbility promise'); 640 ability = data; 641}); 642``` 643 644### startAbility<sup>9+</sup> 645 646startAbility(want: Want, callback: AsyncCallback\<void>): void 647 648Starts an ability. This API uses an asynchronous callback to return the result. 649 650**Atomic service API**: This API can be used in atomic services since API version 11. 651 652**System capability**: SystemCapability.Ability.AbilityRuntime.Core 653 654**Parameters** 655 656| Name | Type | Mandatory| Description | 657| -------- | -------------------------------------- | ---- | ------------------ | 658| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | **Want** parameter for starting the ability. | 659| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the ability is started, **err** is **undefined**. Otherwise, **err** is an error object.| 660 661**Error codes** 662 663For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 664 665| ID| Error Message| 666| ------- | -------- | 667| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 668| 16000001 | The specified ability does not exist. | 669| 16000002 | Incorrect ability type. | 670| 16000004 | Failed to start the invisible ability. | 671| 16000005 | The specified process does not have the permission. | 672| 16000006 | Cross-user operations are not allowed. | 673| 16000008 | The crowdtesting application expires. | 674| 16000009 | An ability cannot be started or stopped in Wukong mode. | 675| 16000010 | The call with the continuation flag is forbidden. | 676| 16000011 | The context does not exist. | 677| 16000012 | The application is controlled. | 678| 16000013 | The application is controlled by EDM. | 679| 16000050 | Internal error. | 680| 16000053 | The ability is not on the top of the UI. | 681| 16000055 | Installation-free timed out. | 682| 16200001 | The caller has been released. | 683 684**Example** 685 686```ts 687import { abilityDelegatorRegistry } from '@kit.TestKit'; 688import { Want } from '@kit.AbilityKit'; 689import { BusinessError } from '@kit.BasicServicesKit'; 690 691let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 692let want: Want = { 693 bundleName: 'bundleName', 694 abilityName: 'abilityName' 695}; 696 697abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 698abilityDelegator.startAbility(want, (err: BusinessError, data: void) => { 699 console.info('startAbility callback'); 700}); 701``` 702 703### startAbility<sup>9+</sup> 704 705startAbility(want: Want): Promise\<void> 706 707Starts an ability. This API uses a promise to return the result. 708 709**Atomic service API**: This API can be used in atomic services since API version 11. 710 711**System capability**: SystemCapability.Ability.AbilityRuntime.Core 712 713**Parameters** 714 715| Name| Type | Mandatory| Description | 716| ------ | -------------------------------------- | ---- | --------------- | 717| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | **Want** parameter for starting the ability.| 718 719**Return value** 720 721| Type | Description | 722| -------------- | ------------------- | 723| Promise\<void> | Promise that returns no value.| 724 725**Error codes** 726 727For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 728 729| ID| Error Message| 730| ------- | -------- | 731| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 732| 16000001 | The specified ability does not exist. | 733| 16000002 | Incorrect ability type. | 734| 16000004 | Failed to start the invisible ability. | 735| 16000005 | The specified process does not have the permission. | 736| 16000006 | Cross-user operations are not allowed. | 737| 16000008 | The crowdtesting application expires. | 738| 16000009 | An ability cannot be started or stopped in Wukong mode. | 739| 16000010 | The call with the continuation flag is forbidden. | 740| 16000011 | The context does not exist. | 741| 16000012 | The application is controlled. | 742| 16000013 | The application is controlled by EDM. | 743| 16000050 | Internal error. | 744| 16000053 | The ability is not on the top of the UI. | 745| 16000055 | Installation-free timed out. | 746| 16200001 | The caller has been released. | 747 748**Example** 749 750```ts 751import { abilityDelegatorRegistry } from '@kit.TestKit'; 752import { Want } from '@kit.AbilityKit'; 753 754let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 755let want: Want = { 756 bundleName: 'bundleName', 757 abilityName: 'abilityName' 758}; 759 760abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 761abilityDelegator.startAbility(want).then((data: void) => { 762 console.info('startAbility promise'); 763}); 764``` 765 766### doAbilityForeground<sup>9+</sup> 767 768doAbilityForeground(ability: UIAbility, callback: AsyncCallback\<void>): void 769 770Schedules the lifecycle state of an ability to **Foreground**. This API uses an asynchronous callback to return the result. 771 772**Atomic service API**: This API can be used in atomic services since API version 11. 773 774**System capability**: SystemCapability.Ability.AbilityRuntime.Core 775 776**Parameters** 777 778| Name | Type | Mandatory| Description | 779| -------- | ----------------------- | ---- | ------------------------------------------------------- | 780| ability | UIAbility | Yes | Target ability. | 781| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the ability lifecycle state is changed to **Foreground**, **err** is **undefined**. Otherwise, **err** is an error object. | 782 783**Error codes** 784 785For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 786 787| ID| Error Message| 788| ------- | -------- | 789| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 790| 16000100 | Calling DoAbilityForeground failed. | 791 792**Example** 793 794```ts 795import { abilityDelegatorRegistry } from '@kit.TestKit'; 796import { UIAbility } from '@kit.AbilityKit'; 797import { BusinessError } from '@kit.BasicServicesKit'; 798 799let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 800let ability: UIAbility; 801 802abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 803abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 804 console.info('getCurrentTopAbility callback'); 805 ability = data; 806 abilityDelegator.doAbilityForeground(ability, (err: BusinessError) => { 807 console.info("doAbilityForeground callback"); 808 }); 809}); 810``` 811 812### doAbilityForeground<sup>9+</sup> 813 814doAbilityForeground(ability: UIAbility): Promise\<void> 815 816Schedules the lifecycle state of an ability to **Foreground**. This API uses a promise to return the result. 817 818**Atomic service API**: This API can be used in atomic services since API version 11. 819 820**System capability**: SystemCapability.Ability.AbilityRuntime.Core 821 822**Parameters** 823 824| Name | Type | Mandatory| Description | 825| ------- | ------- | ---- | --------------- | 826| ability | UIAbility | Yes | Target ability.| 827 828**Return value** 829 830| Type | Description | 831| ----------------- | ------------------------------------------------------------ | 832| Promise\<void> | Promise that returns no value. | 833 834**Error codes** 835 836For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 837 838| ID| Error Message| 839| ------- | -------- | 840| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 841| 16000100 | Calling DoAbilityForeground failed. | 842 843**Example** 844 845```ts 846import { abilityDelegatorRegistry } from '@kit.TestKit'; 847import { UIAbility } from '@kit.AbilityKit'; 848import { BusinessError } from '@kit.BasicServicesKit'; 849 850let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 851let ability: UIAbility; 852 853abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 854abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 855 console.info('getCurrentTopAbility callback'); 856 ability = data; 857 abilityDelegator.doAbilityForeground(ability).then(() => { 858 console.info("doAbilityForeground promise"); 859 }); 860}); 861``` 862 863### doAbilityBackground<sup>9+</sup> 864 865doAbilityBackground(ability: UIAbility, callback: AsyncCallback\<void>): void 866 867Schedules the lifecycle state of an ability to **Background**. This API uses an asynchronous callback to return the result. 868 869**Atomic service API**: This API can be used in atomic services since API version 11. 870 871**System capability**: SystemCapability.Ability.AbilityRuntime.Core 872 873**Parameters** 874 875| Name | Type | Mandatory| Description | 876| -------- | ----------------------- | ---- | ------------------------------------------------------- | 877| ability | UIAbility | Yes | Target ability. | 878| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the ability lifecycle state is changed to **Background**, **err** is **undefined**. Otherwise, **err** is an error object. | 879 880**Error codes** 881 882For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 883 884| ID| Error Message| 885| ------- | -------- | 886| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 887| 16000100 | Calling DoAbilityBackground failed. | 888 889**Example** 890 891```ts 892import { abilityDelegatorRegistry } from '@kit.TestKit'; 893import { UIAbility } from '@kit.AbilityKit'; 894import { BusinessError } from '@kit.BasicServicesKit'; 895 896let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 897let ability: UIAbility; 898 899abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 900abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 901 console.info('getCurrentTopAbility callback'); 902 ability = data; 903 abilityDelegator.doAbilityBackground(ability, (err: BusinessError) => { 904 console.info("doAbilityBackground callback"); 905 }); 906}); 907``` 908 909### doAbilityBackground<sup>9+</sup> 910 911doAbilityBackground(ability: UIAbility): Promise\<void> 912 913Schedules the lifecycle state of an ability to **Background**. This API uses a promise to return the result. 914 915**Atomic service API**: This API can be used in atomic services since API version 11. 916 917**System capability**: SystemCapability.Ability.AbilityRuntime.Core 918 919**Parameters** 920 921| Name | Type | Mandatory| Description | 922| ------- | ------- | ---- | --------------- | 923| ability | UIAbility | Yes | Target ability.| 924 925**Return value** 926 927| Type | Description | 928| ----------------- | ------------------------------------------------------------ | 929| Promise\<void> | Promise that returns no value. | 930 931**Error codes** 932 933For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 934 935| ID| Error Message| 936| ------- | -------- | 937| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 938| 16000100 | Calling DoAbilityBackground failed. | 939 940**Example** 941 942```ts 943import { abilityDelegatorRegistry } from '@kit.TestKit'; 944import { UIAbility } from '@kit.AbilityKit'; 945import { BusinessError } from '@kit.BasicServicesKit'; 946 947let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 948let ability: UIAbility; 949 950abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 951abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 952 console.info('getCurrentTopAbility callback'); 953 ability = data; 954 abilityDelegator.doAbilityBackground(ability).then(() => { 955 console.info("doAbilityBackground promise"); 956 }); 957}); 958``` 959 960### printSync<sup>9+</sup> 961 962printSync(msg: string): void 963 964Prints log information to the unit test console. 965 966**Atomic service API**: This API can be used in atomic services since API version 11. 967 968**System capability**: SystemCapability.Ability.AbilityRuntime.Core 969 970**Parameters** 971 972| Name| Type | Mandatory| Description | 973| ------ | ------ | ---- | ---------- | 974| msg | string | Yes | Log string.| 975 976**Error codes** 977 978For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 979 980| ID| Error Message| 981| ------- | -------- | 982| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 983 984**Example** 985 986```ts 987import { abilityDelegatorRegistry } from '@kit.TestKit'; 988 989let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 990let msg = 'msg'; 991 992abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 993abilityDelegator.printSync(msg); 994``` 995 996### print 997 998print(msg: string, callback: AsyncCallback\<void>): void 999 1000Prints log information to the unit test console. This API uses an asynchronous callback to return the result. 1001 1002**Atomic service API**: This API can be used in atomic services since API version 11. 1003 1004**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1005 1006**Parameters** 1007 1008| Name | Type | Mandatory| Description | 1009| -------- | -------------------- | ---- | ------------------ | 1010| msg | string | Yes | Log string. | 1011| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the log information is printed to the unit test console, **err** is **undefined**. Otherwise, **err** is an error object.| 1012 1013**Example** 1014 1015```ts 1016import { abilityDelegatorRegistry } from '@kit.TestKit'; 1017import { BusinessError } from '@kit.BasicServicesKit'; 1018 1019let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1020let msg = 'msg'; 1021 1022abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1023abilityDelegator.print(msg, (err: BusinessError) => { 1024 console.info('print callback'); 1025}); 1026``` 1027 1028### print 1029 1030print(msg: string): Promise\<void> 1031 1032Prints log information to the unit test console. This API uses a promise to return the result. 1033 1034**Atomic service API**: This API can be used in atomic services since API version 11. 1035 1036**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1037 1038**Parameters** 1039 1040| Name| Type | Mandatory| Description | 1041| ------ | ------ | ---- | ---------- | 1042| msg | string | Yes | Log string.| 1043 1044**Return value** 1045 1046| Type | Description | 1047| -------------- | ------------------- | 1048| Promise\<void> |Promise that returns no value.| 1049 1050**Example** 1051 1052```ts 1053import { abilityDelegatorRegistry } from '@kit.TestKit'; 1054 1055let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1056let msg = 'msg'; 1057 1058abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1059abilityDelegator.print(msg).then(() => { 1060 console.info('print promise'); 1061}); 1062``` 1063 1064### executeShellCommand 1065 1066executeShellCommand(cmd: string, callback: AsyncCallback\<ShellCmdResult>): void 1067 1068Executes a shell command. This API uses an asynchronous callback to return the result. 1069 1070Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1071 1072**Atomic service API**: This API can be used in atomic services since API version 11. 1073 1074**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1075 1076**Parameters** 1077 1078| Name | Type | Mandatory| Description | 1079| -------- | ------------------------------------------------------------ | ---- | ------------------ | 1080| cmd | string | Yes | Shell command string. | 1081| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#shellcmdresult)> | Yes | Callback used to return the result. If the shell command is executed, **err** is **undefined** and **data** is the execution result obtained. Otherwise, **err** is an error object.| 1082 1083**Example** 1084 1085```ts 1086import { abilityDelegatorRegistry } from '@kit.TestKit'; 1087import { BusinessError } from '@kit.BasicServicesKit'; 1088 1089let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1090let cmd = 'cmd'; 1091 1092abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1093abilityDelegator.executeShellCommand(cmd, (err: BusinessError, data: abilityDelegatorRegistry.ShellCmdResult) => { 1094 console.info('executeShellCommand callback'); 1095}); 1096``` 1097 1098### executeShellCommand 1099 1100executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback\<ShellCmdResult>): void 1101 1102Executes a shell command with the timeout period specified. This API uses an asynchronous callback to return the result. 1103 1104Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1105 1106**Atomic service API**: This API can be used in atomic services since API version 11. 1107 1108**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1109 1110**Parameters** 1111 1112| Name | Type | Mandatory| Description | 1113| ----------- | ------------------------------------------------------------ | ---- | ----------------------------- | 1114| cmd | string | Yes | Shell command string. | 1115| timeoutSecs | number | Yes | Command timeout period, in seconds.| 1116| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#shellcmdresult)> | Yes | Callback used to return the result. If the shell command is executed, **err** is **undefined** and **data** is the execution result obtained. Otherwise, **err** is an error object. | 1117 1118**Example** 1119 1120```ts 1121import { abilityDelegatorRegistry } from '@kit.TestKit'; 1122import { BusinessError } from '@kit.BasicServicesKit'; 1123 1124let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1125let cmd = 'cmd'; 1126let timeout = 100; 1127 1128abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1129abilityDelegator.executeShellCommand(cmd, timeout, (err: BusinessError, data: abilityDelegatorRegistry.ShellCmdResult) => { 1130 console.info('executeShellCommand callback'); 1131}); 1132``` 1133 1134### executeShellCommand 1135 1136executeShellCommand(cmd: string, timeoutSecs?: number): Promise\<ShellCmdResult> 1137 1138Executes a shell command with the timeout period specified. This API uses a promise to return the result. 1139 1140Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1141 1142**Atomic service API**: This API can be used in atomic services since API version 11. 1143 1144**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1145 1146**Parameters** 1147 1148| Name | Type | Mandatory| Description | 1149| ----------- | ------ | ---- | ----------------------------- | 1150| cmd | string | Yes | Shell command string. | 1151| timeoutSecs | number | No | Command timeout period, in seconds.| 1152 1153**Return value** 1154 1155| Type | Description | 1156| ------------------------------------------------------------ | ------------------------------------------------------------ | 1157| Promise\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#shellcmdresult)> | Promise used to return a [ShellCmdResult](js-apis-inner-application-shellCmdResult.md#shellcmdresult) object.| 1158 1159**Example** 1160 1161```ts 1162import { abilityDelegatorRegistry } from '@kit.TestKit'; 1163 1164let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1165let cmd = 'cmd'; 1166let timeout = 100; 1167 1168abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1169abilityDelegator.executeShellCommand(cmd, timeout).then((data) => { 1170 console.info('executeShellCommand promise'); 1171}); 1172``` 1173 1174### finishTest<sup>9+</sup> 1175 1176finishTest(msg: string, code: number, callback: AsyncCallback\<void>): void 1177 1178Finishes the test and prints log information to the unit test console. This API uses an asynchronous callback to return the result. 1179 1180**Atomic service API**: This API can be used in atomic services since API version 11. 1181 1182**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1183 1184**Parameters** 1185 1186| Name | Type | Mandatory| Description | 1187| -------- | -------------------- | ---- | ------------------ | 1188| msg | string | Yes | Log string. | 1189| code | number | Yes | Log code. | 1190| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the test finishes and the log information is printed to the unit test console, **err** is undefined. Otherwise, **err** is an error object.| 1191 1192**Error codes** 1193 1194For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1195 1196| ID| Error Message| 1197| ------- | -------- | 1198| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1199| 16000100 | Calling FinishTest failed. | 1200 1201**Example** 1202 1203```ts 1204import { abilityDelegatorRegistry } from '@kit.TestKit'; 1205import { BusinessError } from '@kit.BasicServicesKit'; 1206 1207let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1208let msg = 'msg'; 1209 1210abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1211abilityDelegator.finishTest(msg, 0, (err: BusinessError) => { 1212 console.info('finishTest callback'); 1213}); 1214``` 1215 1216### finishTest<sup>9+</sup> 1217 1218finishTest(msg: string, code: number): Promise\<void> 1219 1220Finishes the test and prints log information to the unit test console. This API uses a promise to return the result. 1221 1222**Atomic service API**: This API can be used in atomic services since API version 11. 1223 1224**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1225 1226**Parameters** 1227 1228| Name| Type | Mandatory| Description | 1229| ------ | ------ | ---- | ---------- | 1230| msg | string | Yes | Log string.| 1231| code | number | Yes | Log code. | 1232 1233**Return value** 1234 1235| Type | Description | 1236| -------------- | ------------------- | 1237| Promise\<void> | Promise that returns no value.| 1238 1239**Error codes** 1240 1241For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1242 1243| ID| Error Message| 1244| ------- | -------- | 1245| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1246| 16000100 | Calling FinishTest failed. | 1247 1248**Example** 1249 1250```ts 1251import { abilityDelegatorRegistry } from '@kit.TestKit'; 1252 1253let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1254let msg = 'msg'; 1255 1256abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1257abilityDelegator.finishTest(msg, 0).then(() => { 1258 console.info('finishTest promise'); 1259}); 1260``` 1261 1262### addAbilityStageMonitor<sup>9+</sup> 1263 1264addAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void 1265 1266Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses an asynchronous callback to return the result. 1267 1268**Atomic service API**: This API can be used in atomic services since API version 11. 1269 1270**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1271 1272**Parameters** 1273 1274| Name | Type | Mandatory| Description | 1275| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1276| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1277| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the **AbilityStageMonitor** instance is added, **err** is undefined. Otherwise, **err** is an error object. | 1278 1279**Error codes** 1280 1281For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1282 1283| ID| Error Message| 1284| ------- | -------- | 1285| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1286| 16000100 | Calling AddAbilityStageMonitor failed. | 1287 1288**Example** 1289 1290```ts 1291import { abilityDelegatorRegistry } from '@kit.TestKit'; 1292import { BusinessError } from '@kit.BasicServicesKit'; 1293 1294let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1295 1296abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1297abilityDelegator.addAbilityStageMonitor({ 1298 moduleName: 'moduleName', 1299 srcEntrance: 'srcEntrance', 1300}, (err: BusinessError) => { 1301 console.info('addAbilityStageMonitor callback'); 1302}); 1303``` 1304 1305### addAbilityStageMonitor<sup>9+</sup> 1306 1307addAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void> 1308 1309Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses a promise to return the result. 1310 1311**Atomic service API**: This API can be used in atomic services since API version 11. 1312 1313**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1314 1315**Parameters** 1316 1317| Name | Type | Mandatory| Description | 1318| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1319| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1320 1321**Return value** 1322 1323| Type | Description | 1324| -------------- | ------------------- | 1325| Promise\<void> | Promise that returns no value.| 1326 1327**Error codes** 1328 1329For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1330 1331| ID| Error Message| 1332| ------- | -------- | 1333| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1334| 16000100 | Calling AddAbilityStageMonitor failed. | 1335 1336**Example** 1337 1338```ts 1339import { abilityDelegatorRegistry } from '@kit.TestKit'; 1340 1341let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1342 1343abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1344abilityDelegator.addAbilityStageMonitor({ 1345 moduleName: 'moduleName', 1346 srcEntrance: 'srcEntrance', 1347}).then(() => { 1348 console.info('addAbilityStageMonitor promise'); 1349}); 1350``` 1351 1352### addAbilityStageMonitorSync<sup>10+</sup> 1353 1354addAbilityStageMonitorSync(monitor: AbilityStageMonitor): void 1355 1356Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API returns the result synchronously. 1357 1358**Atomic service API**: This API can be used in atomic services since API version 11. 1359 1360**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1361 1362**Parameters** 1363 1364| Name | Type | Mandatory| Description | 1365| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1366| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1367 1368**Error codes** 1369 1370For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1371 1372| ID| Error Message| 1373| ------- | -------- | 1374| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1375| 16000100 | Calling AddAbilityStageMonitorSync failed. | 1376 1377**Example** 1378 1379```ts 1380import { abilityDelegatorRegistry } from '@kit.TestKit'; 1381 1382let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1383 1384abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1385abilityDelegator.addAbilityStageMonitorSync({ 1386 moduleName: 'moduleName', 1387 srcEntrance: 'srcEntrance', 1388}); 1389``` 1390 1391### removeAbilityStageMonitor<sup>9+</sup> 1392 1393removeAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void 1394 1395Removes an **AbilityStageMonitor** instance from the application memory. This API uses an asynchronous callback to return the result. 1396 1397**Atomic service API**: This API can be used in atomic services since API version 11. 1398 1399**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1400 1401**Parameters** 1402 1403| Name | Type | Mandatory| Description | 1404| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1405| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1406| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the **AbilityStageMonitor** instance is removed, **err** is undefined. Otherwise, **err** is an error object.| 1407 1408**Error codes** 1409 1410For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1411 1412| ID| Error Message| 1413| ------- | -------- | 1414| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1415| 16000100 | Calling RemoveAbilityStageMonitor failed. | 1416 1417**Example** 1418 1419```ts 1420import { abilityDelegatorRegistry } from '@kit.TestKit'; 1421import { BusinessError } from '@kit.BasicServicesKit'; 1422 1423let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1424 1425abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1426abilityDelegator.removeAbilityStageMonitor({ 1427 moduleName: 'moduleName', 1428 srcEntrance: 'srcEntrance', 1429}, (err: BusinessError) => { 1430 console.info('removeAbilityStageMonitor callback'); 1431}); 1432``` 1433 1434### removeAbilityStageMonitor<sup>9+</sup> 1435 1436removeAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void> 1437 1438Removes an **AbilityStageMonitor** instance from the application memory. This API uses a promise to return the result. 1439 1440**Atomic service API**: This API can be used in atomic services since API version 11. 1441 1442**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1443 1444**Parameters** 1445 1446| Name | Type | Mandatory| Description | 1447| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1448| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1449 1450**Return value** 1451 1452| Type | Description | 1453| -------------- | ------------------- | 1454| Promise\<void> | Promise that returns no value.| 1455 1456**Error codes** 1457 1458For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1459 1460| ID| Error Message| 1461| ------- | -------- | 1462| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1463| 16000100 | Calling RemoveAbilityStageMonitor failed. | 1464 1465**Example** 1466 1467```ts 1468import { abilityDelegatorRegistry } from '@kit.TestKit'; 1469 1470let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1471 1472abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1473abilityDelegator.removeAbilityStageMonitor({ 1474 moduleName: 'moduleName', 1475 srcEntrance: 'srcEntrance', 1476}).then(() => { 1477 console.info('removeAbilityStageMonitor promise'); 1478}); 1479``` 1480 1481### removeAbilityStageMonitorSync<sup>10+</sup> 1482 1483removeAbilityStageMonitorSync(monitor: AbilityStageMonitor): void 1484 1485Removes an **AbilityStageMonitor** instance from the application memory. This API returns the result synchronously. 1486 1487**Atomic service API**: This API can be used in atomic services since API version 11. 1488 1489**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1490 1491**Parameters** 1492 1493| Name | Type | Mandatory| Description | 1494| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1495| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1496 1497**Error codes** 1498 1499For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1500 1501| ID| Error Message| 1502| ------- | -------- | 1503| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1504| 16000100 | Calling RemoveAbilityStageMonitorSync failed. | 1505 1506 1507**Example** 1508 1509```ts 1510import { abilityDelegatorRegistry } from '@kit.TestKit'; 1511 1512let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1513 1514abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1515abilityDelegator.removeAbilityStageMonitorSync({ 1516 moduleName: 'moduleName', 1517 srcEntrance: 'srcEntrance', 1518}); 1519``` 1520 1521### waitAbilityStageMonitor<sup>9+</sup> 1522 1523waitAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<AbilityStage>): void 1524 1525Waits for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses an asynchronous callback to return the result. 1526 1527**Atomic service API**: This API can be used in atomic services since API version 11. 1528 1529**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1530 1531**Parameters** 1532 1533| Name | Type | Mandatory| Description | 1534| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1535| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1536| callback | AsyncCallback\<AbilityStage> | Yes | Callback used to return the result. If the operation is successful, **err** is undefined and data is the [AbilityStage](../apis-ability-kit/js-apis-app-ability-abilityStage.md) instance obtained. Otherwise, **err** is an error object. | 1537 1538**Error codes** 1539 1540For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1541 1542| ID| Error Message| 1543| ------- | -------- | 1544| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1545| 16000100 | Calling WaitAbilityStageMonitor failed. | 1546 1547**Example** 1548 1549```ts 1550import { abilityDelegatorRegistry } from '@kit.TestKit'; 1551import { AbilityStage } from '@kit.AbilityKit'; 1552import { BusinessError } from '@kit.BasicServicesKit'; 1553 1554let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1555 1556abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1557abilityDelegator.waitAbilityStageMonitor({ 1558 moduleName: 'moduleName', 1559 srcEntrance: 'srcEntrance', 1560}, (err: BusinessError, data: AbilityStage) => { 1561 console.info('waitAbilityStageMonitor callback'); 1562}); 1563``` 1564 1565### waitAbilityStageMonitor<sup>9+</sup> 1566 1567waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout?: number): Promise\<AbilityStage> 1568 1569Waits for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses a promise to return the result. 1570 1571**Atomic service API**: This API can be used in atomic services since API version 11. 1572 1573**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1574 1575**Parameters** 1576 1577| Name | Type | Mandatory| Description | 1578| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1579| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1580| timeout | number | No | Maximum waiting time, in milliseconds.| 1581 1582**Return value** 1583 1584| Type | Description | 1585| -------------- | ------------------- | 1586| Promise\<AbilityStage> | Promise used to return the [AbilityStage](../apis-ability-kit/js-apis-app-ability-abilityStage.md) instance.| 1587 1588**Error codes** 1589 1590For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1591 1592| ID| Error Message| 1593| ------- | -------- | 1594| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1595| 16000100 | Calling WaitAbilityStageMonitor failed. | 1596 1597**Example** 1598 1599```ts 1600import { abilityDelegatorRegistry } from '@kit.TestKit'; 1601import { AbilityStage } from '@kit.AbilityKit'; 1602 1603let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1604 1605abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1606abilityDelegator.waitAbilityStageMonitor({ 1607 moduleName: 'moduleName', 1608 srcEntrance: 'srcEntrance', 1609}).then((data: AbilityStage) => { 1610 console.info('waitAbilityStageMonitor promise'); 1611}); 1612``` 1613 1614### waitAbilityStageMonitor<sup>9+</sup> 1615 1616waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout: number, callback: AsyncCallback\<AbilityStage>): void 1617 1618Waits for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses an asynchronous callback to return the result. 1619 1620**Atomic service API**: This API can be used in atomic services since API version 11. 1621 1622**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1623 1624**Parameters** 1625 1626| Name | Type | Mandatory| Description | 1627| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1628| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1629| timeout | number | Yes | Maximum waiting time, in milliseconds.| 1630| callback | AsyncCallback\<AbilityStage> | Yes | Callback used to return the result. If the operation is successful, **err** is undefined and data is the [AbilityStage](../apis-ability-kit/js-apis-app-ability-abilityStage.md) instance obtained. Otherwise, **err** is an error object. | 1631 1632**Error codes** 1633 1634For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1635 1636| ID| Error Message| 1637| ------- | -------- | 1638| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1639| 16000100 | Calling WaitAbilityStageMonitor failed. | 1640 1641**Example** 1642 1643```ts 1644import { abilityDelegatorRegistry } from '@kit.TestKit'; 1645import { AbilityStage } from '@kit.AbilityKit'; 1646import { BusinessError } from '@kit.BasicServicesKit'; 1647 1648let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1649let timeout = 100; 1650 1651abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1652abilityDelegator.waitAbilityStageMonitor({ 1653 moduleName: 'moduleName', 1654 srcEntrance: 'srcEntrance', 1655}, timeout, (err: BusinessError, data: AbilityStage) => { 1656 console.info('waitAbilityStageMonitor callback'); 1657}); 1658``` 1659 1660### setMockList<sup>11+</sup> 1661 1662setMockList(mockList: Record\<string, string>): void 1663 1664Sets a list of mock data. 1665 1666**Atomic service API**: This API can be used in atomic services since API version 11. 1667 1668**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1669 1670**Parameters** 1671 1672| Name | Type | Mandatory| Description | 1673| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 1674| mockList | Record\<string, string> | Yes | Key-value object of the mock, where **key** is the target path to be replaced and **value** is the path of the mock implementation to be used for the replacement.| 1675 1676**Error codes** 1677 1678For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1679 1680| ID| Error Message | 1681| -------- | --------------- | 1682| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1683| 16000050 | Internal error. | 1684 1685**Example** 1686 1687```ts 1688import { abilityDelegatorRegistry } from '@kit.TestKit'; 1689 1690let mockList: Record<string, string> = { 1691 '@ohos.router': 'src/main/mock/ohos/router.mock', 1692 'common.time': 'src/main/mock/common/time.mock', 1693}; 1694let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1695 1696abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1697abilityDelegator.setMockList(mockList); 1698``` 1699