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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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**Example** 536 537```ts 538import { abilityDelegatorRegistry } from '@kit.TestKit'; 539import { UIAbility } from '@kit.AbilityKit'; 540import { BusinessError } from '@kit.BasicServicesKit'; 541 542let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 543let ability: UIAbility; 544 545abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 546abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 547 console.info('getCurrentTopAbility callback'); 548 ability = data; 549 let state = abilityDelegator.getAbilityState(ability); 550 console.info('getAbilityState ${state}'); 551}); 552``` 553 554### getCurrentTopAbility<sup>9+</sup> 555 556getCurrentTopAbility(callback: AsyncCallback\<UIAbility>): void 557 558Obtains the top ability of this application. This API uses an asynchronous callback to return the result. It cannot be called in the worker thread. 559 560**Atomic service API**: This API can be used in atomic services since API version 11. 561 562**System capability**: SystemCapability.Ability.AbilityRuntime.Core 563 564**Parameters** 565 566| Name | Type | Mandatory| Description | 567| -------- | ------------------------------------------------------------ | ---- | ------------------ | 568| 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.| 569 570**Error codes** 571 572For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 573 574| ID| Error Message| 575| ------- | -------- | 576| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 577| 16000100 | GetCurrentTopAbility failed. | 578 579**Example** 580 581```ts 582import { abilityDelegatorRegistry } from '@kit.TestKit'; 583import { UIAbility } from '@kit.AbilityKit'; 584import { BusinessError } from '@kit.BasicServicesKit'; 585 586let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 587let ability: UIAbility; 588 589abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 590abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 591 console.info('getCurrentTopAbility callback'); 592 ability = data; 593}); 594``` 595 596### getCurrentTopAbility<sup>9+</sup> 597 598getCurrentTopAbility(): Promise\<UIAbility> 599 600Obtains the top ability of this application. This API uses a promise to return the result. It cannot be called in the worker thread. 601 602**Atomic service API**: This API can be used in atomic services since API version 11. 603 604**System capability**: SystemCapability.Ability.AbilityRuntime.Core 605 606**Return value** 607 608| Type | Description | 609| ----------------------------------------------------------- | -------------------------------------- | 610| Promise\<[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)> | Promise used to return the top ability.| 611 612**Error codes** 613 614For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 615 616| ID| Error Message| 617| ------- | -------- | 618| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 619| 16000100 | GetCurrentTopAbility failed. | 620 621**Example** 622 623```ts 624import { abilityDelegatorRegistry } from '@kit.TestKit'; 625import { UIAbility } from '@kit.AbilityKit'; 626 627let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 628let ability: UIAbility; 629 630abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 631abilityDelegator.getCurrentTopAbility().then((data: UIAbility) => { 632 console.info('getCurrentTopAbility promise'); 633 ability = data; 634}); 635``` 636 637### startAbility<sup>9+</sup> 638 639startAbility(want: Want, callback: AsyncCallback\<void>): void 640 641Starts an ability. This API uses an asynchronous callback to return the result. 642 643**Atomic service API**: This API can be used in atomic services since API version 11. 644 645**System capability**: SystemCapability.Ability.AbilityRuntime.Core 646 647**Parameters** 648 649| Name | Type | Mandatory| Description | 650| -------- | -------------------------------------- | ---- | ------------------ | 651| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | **Want** parameter for starting the ability. | 652| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the ability is started, **err** is **undefined**. Otherwise, **err** is an error object.| 653 654**Error codes** 655 656For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 657 658| ID| Error Message| 659| ------- | -------- | 660| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 661| 16000001 | The specified ability does not exist. | 662| 16000002 | Incorrect ability type. | 663| 16000004 | Can not start invisible component. | 664| 16000005 | The specified process does not have the permission. | 665| 16000006 | Cross-user operations are not allowed. | 666| 16000008 | The crowdtesting application expires. | 667| 16000009 | An ability cannot be started or stopped in Wukong mode. | 668| 16000010 | The call with the continuation flag is forbidden. | 669| 16000011 | The context does not exist. | 670| 16000012 | The application is controlled. | 671| 16000013 | The application is controlled by EDM. | 672| 16000050 | Internal error. | 673| 16000053 | The ability is not on the top of the UI. | 674| 16000055 | Installation-free timed out. | 675| 16200001 | The caller has been released. | 676 677**Example** 678 679```ts 680import { abilityDelegatorRegistry } from '@kit.TestKit'; 681import { Want } from '@kit.AbilityKit'; 682import { BusinessError } from '@kit.BasicServicesKit'; 683 684let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 685let want: Want = { 686 bundleName: 'bundleName', 687 abilityName: 'abilityName' 688}; 689 690abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 691abilityDelegator.startAbility(want, (err: BusinessError, data: void) => { 692 console.info('startAbility callback'); 693}); 694``` 695 696### startAbility<sup>9+</sup> 697 698startAbility(want: Want): Promise\<void> 699 700Starts an ability. This API uses a promise to return the result. 701 702**Atomic service API**: This API can be used in atomic services since API version 11. 703 704**System capability**: SystemCapability.Ability.AbilityRuntime.Core 705 706**Parameters** 707 708| Name| Type | Mandatory| Description | 709| ------ | -------------------------------------- | ---- | --------------- | 710| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | **Want** parameter for starting the ability.| 711 712**Return value** 713 714| Type | Description | 715| -------------- | ------------------- | 716| Promise\<void> | Promise that returns no value.| 717 718**Error codes** 719 720For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 721 722| ID| Error Message| 723| ------- | -------- | 724| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 725| 16000001 | The specified ability does not exist. | 726| 16000002 | Incorrect ability type. | 727| 16000004 | Can not start invisible component. | 728| 16000005 | The specified process does not have the permission. | 729| 16000006 | Cross-user operations are not allowed. | 730| 16000008 | The crowdtesting application expires. | 731| 16000009 | An ability cannot be started or stopped in Wukong mode. | 732| 16000010 | The call with the continuation flag is forbidden. | 733| 16000011 | The context does not exist. | 734| 16000012 | The application is controlled. | 735| 16000013 | The application is controlled by EDM. | 736| 16000050 | Internal error. | 737| 16000053 | The ability is not on the top of the UI. | 738| 16000055 | Installation-free timed out. | 739| 16200001 | The caller has been released. | 740 741**Example** 742 743```ts 744import { abilityDelegatorRegistry } from '@kit.TestKit'; 745import { Want } from '@kit.AbilityKit'; 746 747let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 748let want: Want = { 749 bundleName: 'bundleName', 750 abilityName: 'abilityName' 751}; 752 753abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 754abilityDelegator.startAbility(want).then((data: void) => { 755 console.info('startAbility promise'); 756}); 757``` 758 759### doAbilityForeground<sup>9+</sup> 760 761doAbilityForeground(ability: UIAbility, callback: AsyncCallback\<void>): void 762 763Schedules the lifecycle state of an ability to **Foreground**. This API uses an asynchronous callback to return the result. 764 765**Atomic service API**: This API can be used in atomic services since API version 11. 766 767**System capability**: SystemCapability.Ability.AbilityRuntime.Core 768 769**Parameters** 770 771| Name | Type | Mandatory| Description | 772| -------- | ----------------------- | ---- | ------------------------------------------------------- | 773| ability | UIAbility | Yes | Target ability. | 774| 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. | 775 776**Error codes** 777 778For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 779 780| ID| Error Message| 781| ------- | -------- | 782| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 783| 16000100 | DoAbilityForeground failed. | 784 785**Example** 786 787```ts 788import { abilityDelegatorRegistry } from '@kit.TestKit'; 789import { UIAbility } from '@kit.AbilityKit'; 790import { BusinessError } from '@kit.BasicServicesKit'; 791 792let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 793let ability: UIAbility; 794 795abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 796abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 797 console.info('getCurrentTopAbility callback'); 798 ability = data; 799 abilityDelegator.doAbilityForeground(ability, (err: BusinessError) => { 800 console.info("doAbilityForeground callback"); 801 }); 802}); 803``` 804 805### doAbilityForeground<sup>9+</sup> 806 807doAbilityForeground(ability: UIAbility): Promise\<void> 808 809Schedules the lifecycle state of an ability to **Foreground**. This API uses a promise to return the result. 810 811**Atomic service API**: This API can be used in atomic services since API version 11. 812 813**System capability**: SystemCapability.Ability.AbilityRuntime.Core 814 815**Parameters** 816 817| Name | Type | Mandatory| Description | 818| ------- | ------- | ---- | --------------- | 819| ability | UIAbility | Yes | Target ability.| 820 821**Return value** 822 823| Type | Description | 824| ----------------- | ------------------------------------------------------------ | 825| Promise\<void> | Promise that returns no value. | 826 827**Error codes** 828 829For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 830 831| ID| Error Message| 832| ------- | -------- | 833| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 834| 16000100 | DoAbilityForeground failed. | 835 836**Example** 837 838```ts 839import { abilityDelegatorRegistry } from '@kit.TestKit'; 840import { UIAbility } from '@kit.AbilityKit'; 841import { BusinessError } from '@kit.BasicServicesKit'; 842 843let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 844let ability: UIAbility; 845 846abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 847abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 848 console.info('getCurrentTopAbility callback'); 849 ability = data; 850 abilityDelegator.doAbilityForeground(ability).then(() => { 851 console.info("doAbilityForeground promise"); 852 }); 853}); 854``` 855 856### doAbilityBackground<sup>9+</sup> 857 858doAbilityBackground(ability: UIAbility, callback: AsyncCallback\<void>): void 859 860Schedules the lifecycle state of an ability to **Background**. This API uses an asynchronous callback to return the result. 861 862**Atomic service API**: This API can be used in atomic services since API version 11. 863 864**System capability**: SystemCapability.Ability.AbilityRuntime.Core 865 866**Parameters** 867 868| Name | Type | Mandatory| Description | 869| -------- | ----------------------- | ---- | ------------------------------------------------------- | 870| ability | UIAbility | Yes | Target ability. | 871| 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. | 872 873**Error codes** 874 875For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 876 877| ID| Error Message| 878| ------- | -------- | 879| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 880| 16000100 | DoAbilityBackground failed. | 881 882**Example** 883 884```ts 885import { abilityDelegatorRegistry } from '@kit.TestKit'; 886import { UIAbility } from '@kit.AbilityKit'; 887import { BusinessError } from '@kit.BasicServicesKit'; 888 889let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 890let ability: UIAbility; 891 892abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 893abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 894 console.info('getCurrentTopAbility callback'); 895 ability = data; 896 abilityDelegator.doAbilityBackground(ability, (err: BusinessError) => { 897 console.info("doAbilityBackground callback"); 898 }); 899}); 900``` 901 902### doAbilityBackground<sup>9+</sup> 903 904doAbilityBackground(ability: UIAbility): Promise\<void> 905 906Schedules the lifecycle state of an ability to **Background**. This API uses a promise to return the result. 907 908**Atomic service API**: This API can be used in atomic services since API version 11. 909 910**System capability**: SystemCapability.Ability.AbilityRuntime.Core 911 912**Parameters** 913 914| Name | Type | Mandatory| Description | 915| ------- | ------- | ---- | --------------- | 916| ability | UIAbility | Yes | Target ability.| 917 918**Return value** 919 920| Type | Description | 921| ----------------- | ------------------------------------------------------------ | 922| Promise\<void> | Promise that returns no value. | 923 924**Error codes** 925 926For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 927 928| ID| Error Message| 929| ------- | -------- | 930| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 931| 16000100 | DoAbilityBackground failed. | 932 933**Example** 934 935```ts 936import { abilityDelegatorRegistry } from '@kit.TestKit'; 937import { UIAbility } from '@kit.AbilityKit'; 938import { BusinessError } from '@kit.BasicServicesKit'; 939 940let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 941let ability: UIAbility; 942 943abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 944abilityDelegator.getCurrentTopAbility((err: BusinessError, data: UIAbility) => { 945 console.info('getCurrentTopAbility callback'); 946 ability = data; 947 abilityDelegator.doAbilityBackground(ability).then(() => { 948 console.info("doAbilityBackground promise"); 949 }); 950 951``` 952 953### printSync<sup>9+</sup> 954 955printSync(msg: string): void 956 957Prints log information to the unit test console. 958 959**Atomic service API**: This API can be used in atomic services since API version 11. 960 961**System capability**: SystemCapability.Ability.AbilityRuntime.Core 962 963**Parameters** 964 965| Name| Type | Mandatory| Description | 966| ------ | ------ | ---- | ---------- | 967| msg | string | Yes | Log string.| 968 969**Example** 970 971```ts 972import { abilityDelegatorRegistry } from '@kit.TestKit'; 973 974let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 975let msg = 'msg'; 976 977abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 978abilityDelegator.printSync(msg); 979``` 980 981### print 982 983print(msg: string, callback: AsyncCallback\<void>): void 984 985Prints log information to the unit test console. This API uses an asynchronous callback to return the result. 986 987**Atomic service API**: This API can be used in atomic services since API version 11. 988 989**System capability**: SystemCapability.Ability.AbilityRuntime.Core 990 991**Parameters** 992 993| Name | Type | Mandatory| Description | 994| -------- | -------------------- | ---- | ------------------ | 995| msg | string | Yes | Log string. | 996| 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.| 997 998**Example** 999 1000```ts 1001import { abilityDelegatorRegistry } from '@kit.TestKit'; 1002import { BusinessError } from '@kit.BasicServicesKit'; 1003 1004let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1005let msg = 'msg'; 1006 1007abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1008abilityDelegator.print(msg, (err: BusinessError) => { 1009 console.info('print callback'); 1010}); 1011``` 1012 1013### print 1014 1015print(msg: string): Promise\<void> 1016 1017Prints log information to the unit test console. This API uses a promise to return the result. 1018 1019**Atomic service API**: This API can be used in atomic services since API version 11. 1020 1021**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1022 1023**Parameters** 1024 1025| Name| Type | Mandatory| Description | 1026| ------ | ------ | ---- | ---------- | 1027| msg | string | Yes | Log string.| 1028 1029**Return value** 1030 1031| Type | Description | 1032| -------------- | ------------------- | 1033| Promise\<void> |Promise that returns no value.| 1034 1035**Example** 1036 1037```ts 1038import { abilityDelegatorRegistry } from '@kit.TestKit'; 1039 1040let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1041let msg = 'msg'; 1042 1043abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1044abilityDelegator.print(msg).then(() => { 1045 console.info('print promise'); 1046}); 1047``` 1048 1049### executeShellCommand 1050 1051executeShellCommand(cmd: string, callback: AsyncCallback\<ShellCmdResult>): void 1052 1053Executes a shell command. This API uses an asynchronous callback to return the result. 1054 1055Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1056 1057**Atomic service API**: This API can be used in atomic services since API version 11. 1058 1059**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1060 1061**Parameters** 1062 1063| Name | Type | Mandatory| Description | 1064| -------- | ------------------------------------------------------------ | ---- | ------------------ | 1065| cmd | string | Yes | Shell command string. | 1066| 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.| 1067 1068**Example** 1069 1070```ts 1071import { abilityDelegatorRegistry } from '@kit.TestKit'; 1072import { BusinessError } from '@kit.BasicServicesKit'; 1073 1074let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1075let cmd = 'cmd'; 1076 1077abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1078abilityDelegator.executeShellCommand(cmd, (err: BusinessError, data: abilityDelegatorRegistry.ShellCmdResult) => { 1079 console.info('executeShellCommand callback'); 1080}); 1081``` 1082 1083### executeShellCommand 1084 1085executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback\<ShellCmdResult>): void 1086 1087Executes a shell command with the timeout period specified. This API uses an asynchronous callback to return the result. 1088 1089Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1090 1091**Atomic service API**: This API can be used in atomic services since API version 11. 1092 1093**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1094 1095**Parameters** 1096 1097| Name | Type | Mandatory| Description | 1098| ----------- | ------------------------------------------------------------ | ---- | ----------------------------- | 1099| cmd | string | Yes | Shell command string. | 1100| timeoutSecs | number | Yes | Command timeout period, in seconds.| 1101| 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. | 1102 1103**Example** 1104 1105```ts 1106import { abilityDelegatorRegistry } from '@kit.TestKit'; 1107import { BusinessError } from '@kit.BasicServicesKit'; 1108 1109let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1110let cmd = 'cmd'; 1111let timeout = 100; 1112 1113abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1114abilityDelegator.executeShellCommand(cmd, timeout, (err: BusinessError, data: abilityDelegatorRegistry.ShellCmdResult) => { 1115 console.info('executeShellCommand callback'); 1116}); 1117``` 1118 1119### executeShellCommand 1120 1121executeShellCommand(cmd: string, timeoutSecs?: number): Promise\<ShellCmdResult> 1122 1123Executes a shell command with the timeout period specified. This API uses a promise to return the result. 1124 1125Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1126 1127**Atomic service API**: This API can be used in atomic services since API version 11. 1128 1129**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1130 1131**Parameters** 1132 1133| Name | Type | Mandatory| Description | 1134| ----------- | ------ | ---- | ----------------------------- | 1135| cmd | string | Yes | Shell command string. | 1136| timeoutSecs | number | No | Command timeout period, in seconds.| 1137 1138**Return value** 1139 1140| Type | Description | 1141| ------------------------------------------------------------ | ------------------------------------------------------------ | 1142| Promise\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#shellcmdresult)> | Promise used to return a [ShellCmdResult](js-apis-inner-application-shellCmdResult.md#shellcmdresult) object.| 1143 1144**Example** 1145 1146```ts 1147import { abilityDelegatorRegistry } from '@kit.TestKit'; 1148 1149let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1150let cmd = 'cmd'; 1151let timeout = 100; 1152 1153abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1154abilityDelegator.executeShellCommand(cmd, timeout).then((data) => { 1155 console.info('executeShellCommand promise'); 1156}); 1157``` 1158 1159### finishTest<sup>9+</sup> 1160 1161finishTest(msg: string, code: number, callback: AsyncCallback\<void>): void 1162 1163Finishes the test and prints log information to the unit test console. This API uses an asynchronous callback to return the result. 1164 1165**Atomic service API**: This API can be used in atomic services since API version 11. 1166 1167**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1168 1169**Parameters** 1170 1171| Name | Type | Mandatory| Description | 1172| -------- | -------------------- | ---- | ------------------ | 1173| msg | string | Yes | Log string. | 1174| code | number | Yes | Log code. | 1175| 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.| 1176 1177**Error codes** 1178 1179For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1180 1181| ID| Error Message| 1182| ------- | -------- | 1183| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1184| 16000100 | FinishTest failed. | 1185 1186**Example** 1187 1188```ts 1189import { abilityDelegatorRegistry } from '@kit.TestKit'; 1190import { BusinessError } from '@kit.BasicServicesKit'; 1191 1192let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1193let msg = 'msg'; 1194 1195abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1196abilityDelegator.finishTest(msg, 0, (err: BusinessError) => { 1197 console.info('finishTest callback'); 1198}); 1199``` 1200 1201### finishTest<sup>9+</sup> 1202 1203finishTest(msg: string, code: number): Promise\<void> 1204 1205Finishes the test and prints log information to the unit test console. This API uses a promise to return the result. 1206 1207**Atomic service API**: This API can be used in atomic services since API version 11. 1208 1209**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1210 1211**Parameters** 1212 1213| Name| Type | Mandatory| Description | 1214| ------ | ------ | ---- | ---------- | 1215| msg | string | Yes | Log string.| 1216| code | number | Yes | Log code. | 1217 1218**Return value** 1219 1220| Type | Description | 1221| -------------- | ------------------- | 1222| Promise\<void> | Promise that returns no value.| 1223 1224**Error codes** 1225 1226For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1227 1228| ID| Error Message| 1229| ------- | -------- | 1230| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1231| 16000100 | FinishTest failed. | 1232 1233**Example** 1234 1235```ts 1236import { abilityDelegatorRegistry } from '@kit.TestKit'; 1237 1238let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1239let msg = 'msg'; 1240 1241abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1242abilityDelegator.finishTest(msg, 0).then(() => { 1243 console.info('finishTest promise'); 1244}); 1245``` 1246 1247### addAbilityStageMonitor<sup>9+</sup> 1248 1249addAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void 1250 1251Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses an asynchronous callback to return the result. 1252 1253**Atomic service API**: This API can be used in atomic services since API version 11. 1254 1255**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1256 1257**Parameters** 1258 1259| Name | Type | Mandatory| Description | 1260| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1261| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1262| 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. | 1263 1264**Error codes** 1265 1266For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1267 1268| ID| Error Message| 1269| ------- | -------- | 1270| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1271| 16000100 | AddAbilityStageMonitor failed. | 1272 1273**Example** 1274 1275```ts 1276import { abilityDelegatorRegistry } from '@kit.TestKit'; 1277import { BusinessError } from '@kit.BasicServicesKit'; 1278 1279let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1280 1281abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1282abilityDelegator.addAbilityStageMonitor({ 1283 moduleName: 'moduleName', 1284 srcEntrance: 'srcEntrance', 1285}, (err: BusinessError) => { 1286 console.info('addAbilityStageMonitor callback'); 1287}); 1288``` 1289 1290### addAbilityStageMonitor<sup>9+</sup> 1291 1292addAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void> 1293 1294Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses a promise to return the result. 1295 1296**Atomic service API**: This API can be used in atomic services since API version 11. 1297 1298**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1299 1300**Parameters** 1301 1302| Name | Type | Mandatory| Description | 1303| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1304| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1305 1306**Return value** 1307 1308| Type | Description | 1309| -------------- | ------------------- | 1310| Promise\<void> | Promise that returns no value.| 1311 1312**Error codes** 1313 1314For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1315 1316| ID| Error Message| 1317| ------- | -------- | 1318| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1319| 16000100 | AddAbilityStageMonitor failed. | 1320 1321**Example** 1322 1323```ts 1324import { abilityDelegatorRegistry } from '@kit.TestKit'; 1325 1326let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1327 1328abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1329abilityDelegator.addAbilityStageMonitor({ 1330 moduleName: 'moduleName', 1331 srcEntrance: 'srcEntrance', 1332}).then(() => { 1333 console.info('addAbilityStageMonitor promise'); 1334}); 1335``` 1336 1337### addAbilityStageMonitorSync<sup>10+</sup> 1338 1339addAbilityStageMonitorSync(monitor: AbilityStageMonitor): void 1340 1341Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API returns the result synchronously. 1342 1343**Atomic service API**: This API can be used in atomic services since API version 11. 1344 1345**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1346 1347**Parameters** 1348 1349| Name | Type | Mandatory| Description | 1350| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1351| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1352 1353**Error codes** 1354 1355For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1356 1357| ID| Error Message| 1358| ------- | -------- | 1359| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1360| 16000100 | AddAbilityStageMonitorSync failed. | 1361 1362**Example** 1363 1364```ts 1365import { abilityDelegatorRegistry } from '@kit.TestKit'; 1366 1367let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1368 1369abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1370abilityDelegator.addAbilityStageMonitorSync({ 1371 moduleName: 'moduleName', 1372 srcEntrance: 'srcEntrance', 1373}); 1374``` 1375 1376### removeAbilityStageMonitor<sup>9+</sup> 1377 1378removeAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void 1379 1380Removes an **AbilityStageMonitor** instance from the application memory. This API uses an asynchronous callback to return the result. 1381 1382**Atomic service API**: This API can be used in atomic services since API version 11. 1383 1384**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1385 1386**Parameters** 1387 1388| Name | Type | Mandatory| Description | 1389| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1390| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1391| 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.| 1392 1393**Error codes** 1394 1395For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1396 1397| ID| Error Message| 1398| ------- | -------- | 1399| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1400| 16000100 | RemoveAbilityStageMonitor failed. | 1401 1402**Example** 1403 1404```ts 1405import { abilityDelegatorRegistry } from '@kit.TestKit'; 1406import { BusinessError } from '@kit.BasicServicesKit'; 1407 1408let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1409 1410abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1411abilityDelegator.removeAbilityStageMonitor({ 1412 moduleName: 'moduleName', 1413 srcEntrance: 'srcEntrance', 1414}, (err: BusinessError) => { 1415 console.info('removeAbilityStageMonitor callback'); 1416}); 1417``` 1418 1419### removeAbilityStageMonitor<sup>9+</sup> 1420 1421removeAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void> 1422 1423Removes an **AbilityStageMonitor** instance from the application memory. This API uses a promise to return the result. 1424 1425**Atomic service API**: This API can be used in atomic services since API version 11. 1426 1427**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1428 1429**Parameters** 1430 1431| Name | Type | Mandatory| Description | 1432| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1433| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1434 1435**Return value** 1436 1437| Type | Description | 1438| -------------- | ------------------- | 1439| Promise\<void> | Promise that returns no value.| 1440 1441**Error codes** 1442 1443For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1444 1445| ID| Error Message| 1446| ------- | -------- | 1447| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1448| 16000100 | RemoveAbilityStageMonitor failed. | 1449 1450**Example** 1451 1452```ts 1453import { abilityDelegatorRegistry } from '@kit.TestKit'; 1454 1455let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1456 1457abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1458abilityDelegator.removeAbilityStageMonitor({ 1459 moduleName: 'moduleName', 1460 srcEntrance: 'srcEntrance', 1461}).then(() => { 1462 console.info('removeAbilityStageMonitor promise'); 1463}); 1464``` 1465 1466### removeAbilityStageMonitorSync<sup>10+</sup> 1467 1468removeAbilityStageMonitorSync(monitor: AbilityStageMonitor): void 1469 1470Removes an **AbilityStageMonitor** instance from the application memory. This API returns the result synchronously. 1471 1472**Atomic service API**: This API can be used in atomic services since API version 11. 1473 1474**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1475 1476**Parameters** 1477 1478| Name | Type | Mandatory| Description | 1479| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1480| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1481 1482**Error codes** 1483 1484For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1485 1486| ID| Error Message| 1487| ------- | -------- | 1488| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1489| 16000100 | removeAbilityStageMonitorSync failed. | 1490 1491 1492**Example** 1493 1494```ts 1495import { abilityDelegatorRegistry } from '@kit.TestKit'; 1496 1497let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1498 1499abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1500abilityDelegator.removeAbilityStageMonitorSync({ 1501 moduleName: 'moduleName', 1502 srcEntrance: 'srcEntrance', 1503}); 1504``` 1505 1506### waitAbilityStageMonitor<sup>9+</sup> 1507 1508waitAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<AbilityStage>): void 1509 1510Waits 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. 1511 1512**Atomic service API**: This API can be used in atomic services since API version 11. 1513 1514**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1515 1516**Parameters** 1517 1518| Name | Type | Mandatory| Description | 1519| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1520| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1521| 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. | 1522 1523**Error codes** 1524 1525For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1526 1527| ID| Error Message| 1528| ------- | -------- | 1529| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1530| 16000100 | WaitAbilityStageMonitor failed. | 1531 1532**Example** 1533 1534```ts 1535import { abilityDelegatorRegistry } from '@kit.TestKit'; 1536import { AbilityStage } from '@kit.AbilityKit'; 1537import { BusinessError } from '@kit.BasicServicesKit'; 1538 1539let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1540 1541abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1542abilityDelegator.waitAbilityStageMonitor({ 1543 moduleName: 'moduleName', 1544 srcEntrance: 'srcEntrance', 1545}, (err: BusinessError, data: AbilityStage) => { 1546 console.info('waitAbilityStageMonitor callback'); 1547}); 1548``` 1549 1550### waitAbilityStageMonitor<sup>9+</sup> 1551 1552waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout?: number): Promise\<AbilityStage> 1553 1554Waits 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. 1555 1556**Atomic service API**: This API can be used in atomic services since API version 11. 1557 1558**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1559 1560**Parameters** 1561 1562| Name | Type | Mandatory| Description | 1563| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1564| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1565| timeout | number | No | Maximum waiting time, in milliseconds.| 1566 1567**Return value** 1568 1569| Type | Description | 1570| -------------- | ------------------- | 1571| Promise\<AbilityStage> | Promise used to return the [AbilityStage](../apis-ability-kit/js-apis-app-ability-abilityStage.md) instance.| 1572 1573**Error codes** 1574 1575For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1576 1577| ID| Error Message| 1578| ------- | -------- | 1579| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1580| 16000100 | WaitAbilityStageMonitor failed. | 1581 1582**Example** 1583 1584```ts 1585import { abilityDelegatorRegistry } from '@kit.TestKit'; 1586import { AbilityStage } from '@kit.AbilityKit'; 1587 1588let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1589 1590abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1591abilityDelegator.waitAbilityStageMonitor({ 1592 moduleName: 'moduleName', 1593 srcEntrance: 'srcEntrance', 1594}).then((data: AbilityStage) => { 1595 console.info('waitAbilityStageMonitor promise'); 1596}); 1597``` 1598 1599### waitAbilityStageMonitor<sup>9+</sup> 1600 1601waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout: number, callback: AsyncCallback\<AbilityStage>): void 1602 1603Waits a period of time 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. 1604 1605**Atomic service API**: This API can be used in atomic services since API version 11. 1606 1607**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1608 1609**Parameters** 1610 1611| Name | Type | Mandatory| Description | 1612| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1613| monitor | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](../apis-ability-kit/js-apis-inner-application-abilityStageMonitor.md) instance.| 1614| timeout | number | Yes | Maximum waiting time, in milliseconds.| 1615| 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. | 1616 1617**Error codes** 1618 1619For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1620 1621| ID| Error Message| 1622| ------- | -------- | 1623| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1624| 16000100 | WaitAbilityStageMonitor failed. | 1625 1626**Example** 1627 1628```ts 1629import { abilityDelegatorRegistry } from '@kit.TestKit'; 1630import { AbilityStage } from '@kit.AbilityKit'; 1631import { BusinessError } from '@kit.BasicServicesKit'; 1632 1633let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1634let timeout = 100; 1635 1636abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1637abilityDelegator.waitAbilityStageMonitor({ 1638 moduleName: 'moduleName', 1639 srcEntrance: 'srcEntrance', 1640}, timeout, (err: BusinessError, data: AbilityStage) => { 1641 console.info('waitAbilityStageMonitor callback'); 1642}); 1643``` 1644 1645### setMockList<sup>11+</sup> 1646 1647setMockList(mockList: Record\<string, string>): void 1648 1649Sets a list of mock data. 1650 1651**Atomic service API**: This API can be used in atomic services since API version 11. 1652 1653**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1654 1655**Parameters** 1656 1657| Name | Type | Mandatory| Description | 1658| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 1659| 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.| 1660 1661**Error codes** 1662 1663For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](../apis-ability-kit/errorcode-ability.md). 1664 1665| ID| Error Message | 1666| -------- | --------------- | 1667| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1668| 16000050 | Internal error. | 1669 1670**Example** 1671 1672```ts 1673import { abilityDelegatorRegistry } from '@kit.TestKit'; 1674 1675let mockList: Record<string, string> = { 1676 '@ohos.router': 'src/main/mock/ohos/router.mock', 1677 'common.time': 'src/main/mock/common/time.mock', 1678}; 1679let abilityDelegator: abilityDelegatorRegistry.AbilityDelegator; 1680 1681abilityDelegator = abilityDelegatorRegistry.getAbilityDelegator(); 1682abilityDelegator.setMockList(mockList); 1683``` 1684