1# @ohos.UiTest 2 3The **UiTest** module provides APIs that you can use to simulate UI actions during testing, such as clicks, double-clicks, long-clicks, and swipes. 4 5This module provides the following functions: 6 7- [On<sup>9+</sup>](#on9): provides UI component feature description APIs for component filtering and matching. 8- [Component<sup>9+</sup>](#component9): represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. 9- [Driver<sup>9+</sup>](#driver9): works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. 10- [UiWindow<sup>9+</sup>](#uiwindow9): works as the entry class and provides APIs for obtaining window attributes, dragging windows, and adjusting window sizes. 11- [By<sup>(deprecated)</sup>](#bydeprecated): provides UI component feature description APIs for component filtering and matching. This class is deprecated since API version 9. You are advised to use [On<sup>9+</sup>](#on9) instead. 12- [UiComponent<sup>(deprecated)</sup>](#uicomponentdeprecated): represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. This class is deprecated since API version 9. You are advised to use [Component<sup>9+</sup>](#component9) instead. 13- [UiDriver<sup>(deprecated)</sup>](#uidriverdeprecated): works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. This class is deprecated since API version 9. You are advised to use [Driver<sup>9+</sup>](#driver9) instead. 14 15> **NOTE** 16> - 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. 17> - The APIs of this module can be used only in <!--RP1-->[arkxtest](../../application-test/arkxtest-guidelines.md)<!--RP1End-->. 18> - The APIs of this module do not support concurrent calls. 19> - The APIs of this module are applicable to phones, tablets, PCs/2-in-1devices, wearables, smart visions, and head units. 20 21 22## Modules to Import 23 24```ts 25import { UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton, UIElementInfo, UIEventObserver } from '@kit.TestKit'; 26``` 27 28## MatchPattern 29 30Enumerates the match patterns supported for component attributes. 31 32**System capability**: SystemCapability.Test.UiTest 33 34| Name | Value| Description | 35|-----------------------|---|---------------------------------------------------------------------| 36| EQUALS | 0 | Equals the given value.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 37| CONTAINS | 1 | Contains the given value.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 38| STARTS_WITH | 2 | Starts with the given value.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 39| ENDS_WITH | 3 | Ends with the given value.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 40| REG_EXP<sup>18+</sup> | 4 | Uses regular expression matching.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 41| REG_EXP_ICASE<sup>18+</sup> | 5 | Uses case-insensitive regular expression matching.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 42## ResizeDirection<sup>9+</sup> 43 44Enumerates the directions in which a window can be resized. 45 46**Atomic service API**: This API can be used in atomic services since API version 11. 47 48**System capability**: SystemCapability.Test.UiTest 49 50| Name | Value | Description | 51| ---------- | ---- | -------- | 52| LEFT | 0 | Left. | 53| RIGHT | 1 | Right. | 54| UP | 2 | Up. | 55| DOWN | 3 | Down. | 56| LEFT_UP | 4 | Upper left.| 57| LEFT_DOWN | 5 | Lower left.| 58| RIGHT_UP | 6 | Upper right.| 59| RIGHT_DOWN | 7 | Lower right.| 60 61## Point<sup>9+</sup> 62 63Provides the coordinates of a point. 64 65**System capability**: SystemCapability.Test.UiTest 66 67| Name| Type | Read-Only| Optional| Description | 68| ---- | ------ | ---- | ---- |-----------| 69| x | number | No | No | Horizontal coordinate of a coordinate point. The value is an integer greater than 0.<br> **Note**: Since API version 20, this attribute is no longer read-only.<br> **Atomic service API**: This API can be used in atomic services since API version 11.| 70| y | number | No | No | Vertical coordinate of a coordinate point. The value is an integer greater than 0.<br> **Note**: Since API version 20, this attribute is no longer read-only.<br> **Atomic service API**: This API can be used in atomic services since API version 11.| 71| displayId<sup>20+</sup> | number | No | Yes | ID of the display to which the coordinate point belongs. The value is an integer greater than or equal to 0. The default value is the default screen ID of the device.<br> **Atomic service API**: This API can be used in atomic services since API version 20.| 72 73## Rect<sup>9+</sup> 74 75Provides bounds information of a component. 76 77**System capability**: SystemCapability.Test.UiTest 78 79| Name | Type | Read-Only| Optional| Description | 80| ------ | ------ | ---- | ---- | ------------------------- | 81| left | number | No | No|X coordinate of the upper left corner of the component border. The value is an integer greater than 0.<br> **Note**: Since API version 20, this attribute is no longer read-only.<br> **Atomic service API**: This API can be used in atomic services since API version 11.| 82| top | number | No | No|Y coordinate of the upper left corner of the component border. The value is an integer greater than 0.<br> **Note**: Since API version 20, this attribute is no longer read-only.<br> **Atomic service API**: This API can be used in atomic services since API version 11. | 83| right | number | No | No|X coordinate of the lower right corner of the component border. The value is an integer greater than 0.<br> **Note**: Since API version 20, this attribute is no longer read-only.<br> **Atomic service API**: This API can be used in atomic services since API version 11. | 84| bottom | number | No | No|Y coordinate of the lower right corner of the component border. The value is an integer greater than 0.<br> **Note**: Since API version 20, this attribute is no longer read-only.<br> **Atomic service API**: This API can be used in atomic services since API version 11. | 85| displayId<sup>20+</sup> | number | No | Yes|ID of the display to which the component border belongs. The value is an integer greater than or equal to 0. The default value is the default screen ID of the device.<br> **Atomic service API**: This API can be used in atomic services since API version 20. | 86 87## WindowMode<sup>9+</sup> 88 89Enumerates the window modes. 90 91**Atomic service API**: This API can be used in atomic services since API version 11. 92 93**System capability**: SystemCapability.Test.UiTest 94 95| Name | Value | Description | 96| ---------- | ---- | ---------- | 97| FULLSCREEN | 0 | Full-screen mode.| 98| PRIMARY | 1 | Primary window mode. | 99| SECONDARY | 2 | Secondary window mode.| 100| FLOATING | 3 | Floating window mode.| 101 102## DisplayRotation<sup>9+</sup> 103 104Describes the display rotation of the device. 105 106**Atomic service API**: This API can be used in atomic services since API version 11. 107 108**System capability**: SystemCapability.Test.UiTest 109 110| Name | Value | Description | 111| ------------ | ---- | ---------------------------------------- | 112| ROTATION_0 | 0 | The device display is not rotated and is in its original vertical orientation. | 113| ROTATION_90 | 1 | The device display rotates 90° clockwise and is in landscape orientation. | 114| ROTATION_180 | 2 | The device display rotates 180° clockwise and is in reverse vertical orientation.| 115| ROTATION_270 | 3 | The device display rotates 270° clockwise and is in reverse landscape orientation.| 116 117## WindowFilter<sup>9+</sup> 118 119Provides the flag attributes of this window. 120 121**System capability**: SystemCapability.Test.UiTest 122 123| Name | Type | Read-Only| Optional| Description | 124| -------------------- | ------- | ---- | ---- |----------------------------------------------------------------------------------------| 125| bundleName | string | No | Yes | Bundle name of the application to which the window belongs. The default value is empty.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 126| title | string | No | Yes | Title of the window. The default value is empty.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 127| focused | boolean | No | Yes | Whether the window is focused. The value **true** indicates that the window is focused, and **false** indicates the opposite. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 128| actived(deprecated) | boolean | No | Yes | Whether the window is interacting with the user. The value **true** indicates that the window is interacting with the user, and **false** indicates the opposite.<br>This API is deprecated since API version 11. You are advised to use the **active** API instead. | 129| active<sup>11+</sup> | boolean | No | Yes | Whether the window is interacting with the user. The value **true** indicates that the window is interacting with the user, and **false** indicates the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 130| displayId<sup>20+</sup> | number | No | Yes | ID of the display to which the window belongs. The value is an integer greater than or equal to 0. The default value is the default screen ID of the device.<br> **Atomic service API**: This API can be used in atomic services since API version 20.| 131 132## UiDirection<sup>10+</sup> 133 134Describes the direction of a UI operation such as fling. 135 136**Atomic service API**: This API can be used in atomic services since API version 11. 137 138**System capability**: SystemCapability.Test.UiTest 139 140| Name | Value | Description | 141| ----- | ---- | ------ | 142| LEFT | 0 | Leftward.| 143| RIGHT | 1 | Rightward.| 144| UP | 2 | Upward.| 145| DOWN | 3 | Downward.| 146 147## MouseButton<sup>10+</sup> 148 149Describes the injected simulated mouse button. 150 151**Atomic service API**: This API can be used in atomic services since API version 11. 152 153**System capability**: SystemCapability.Test.UiTest 154 155| Name | Value | Description | 156| ------------------- | ---- | ------------ | 157| MOUSE_BUTTON_LEFT | 0 | Left button on the mouse. | 158| MOUSE_BUTTON_RIGHT | 1 | Right button on the mouse. | 159| MOUSE_BUTTON_MIDDLE | 2 | Middle button on the mouse.| 160 161## UIElementInfo<sup>10+</sup> 162 163Provides information about the UI event. 164 165**Atomic service API**: This API can be used in atomic services since API version 11. 166 167**System capability**: SystemCapability.Test.UiTest 168 169| Name | Type | Read-Only| Optional| Description | 170| ---------- | ------ | ---- | ---- | --------------------- | 171| bundleName | string | Yes | No | Bundle name of the home application. | 172| type | string | Yes | No | Component or window type. | 173| text | string | Yes | No | Text information of the component or window.| 174 175 176## TouchPadSwipeOptions<sup>18+</sup> 177 178Describes information about the touchpad swipe gesture option. 179 180**Atomic service API**: This API can be used in atomic services since API version 18. 181 182**System capability**: SystemCapability.Test.UiTest 183 184| Name | Type | Read-Only| Optional| Description | 185| ---------- | ------ |----|----|--------------------------------------------------------| 186| stay | boolean | No | Yes | Whether the swipe gesture stays on the touchpad for 1s before it is lifted. The value **true** indicates that the swipe gesture stays on the touchpad for 1s, and **false** indicates the opposite. The default value is **false**.| 187| speed | number | No | Yes | Swipe speed, in px/s. The value is an integer ranges from 200 to 40000. If the set value is not in the range, the default value **2000** is used. | 188 189 190## InputTextMode<sup>20+</sup> 191 192Describes the text input mode. 193 194**Atomic service API**: This API can be used in atomic services since API version 20. 195 196**System capability**: SystemCapability.Test.UiTest 197 198| Name | Type | Read-Only| Optional| Description | 199| ---------- | ------ |----|----|----------------------------------------------------------| 200| paste | boolean | No | Yes | Whether to copy and paste text. The value **true** means to copy and paste text, and **false** means to type text. Default value: **false**<br> **NOTE**<br>1. If the input text contains Chinese characters or special characters or contains more than 200 characters, the text is copied and pasted regardless of the value of this parameter.<br>2. For smart wearable devices, this API does not support input in copy and paste mode.| 201| addition | boolean | No | Yes | Whether to input text in addition mode. The value **true** means to input text in addition mode, and **false** means the opposite. Default value: **false**| 202 203 204## On<sup>9+</sup> 205 206Since API version 9, the UiTest framework provides a wide range of UI component feature description APIs in the **On** class to filter and match components.<br> 207The APIs provided by the **On** class exhibit the following features:<br>1. Allow one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component.<br>2. Provide multiple match patterns for component attributes.<br>3. Support absolute positioning and relative positioning for components. APIs such as [ON.isBefore](#isbefore9) and [ON.isAfter](#isafter9) can be used to specify the features of adjacent components to assist positioning.<br>All APIs provided in the **On** class are synchronous. You are advised to use the static constructor **ON** to create an **On** object in chain mode. 208 209```ts 210import { ON } from '@kit.TestKit'; 211 212ON.text('123').type('Button'); 213``` 214 215### text<sup>9+</sup> 216 217text(txt: string, pattern?: MatchPattern): On 218 219Specifies the text attribute of the target component. Multiple match patterns are supported. 220 221> **NOTE** 222> 223> If the [accessibilityLevel](../apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md#accessibilitylevel) of a component is set to **no** or **no-hide-descendants**, this API cannot be used to specify the text attribute of the target component for searching for the component. In this case, you can use the [On.originalText ()](#originaltext20) API. 224 225**Atomic service API**: This API can be used in atomic services since API version 11. 226 227**System capability**: SystemCapability.Test.UiTest 228 229**Parameters** 230 231| Name | Type | Mandatory| Description | 232| ------- | ----------------------------- | ---- | --------------------------------------------------- | 233| txt | string | Yes | Component text, used to match the target component. | 234| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 235 236**Return value** 237 238| Type | Description | 239| ---------- | ---------------------------------- | 240| [On](#on9) | **On** object that matches the text attribute of the target component.| 241 242**Error codes** 243 244For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 245 246| ID| Error Message | 247| -------- | ------------------------------------------------------------ | 248| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 249 250**Example** 251 252```ts 253import { On, ON } from '@kit.TestKit'; 254let on:On = ON.text('123'); // Use the static constructor ON to create an On object and specify the text attribute of the target component. 255``` 256 257### id<sup>9+</sup> 258 259id(id: string): On 260 261Specifies the ID attribute of the target component. 262 263**Atomic service API**: This API can be used in atomic services since API version 11. 264 265**System capability**: SystemCapability.Test.UiTest 266 267**Parameters** 268 269| Name| Type | Mandatory| Description | 270| ------ | ------ | ---- | ---------------- | 271| id | string | Yes | Component ID.| 272 273**Return value** 274 275| Type | Description | 276| ---------- | -------------------------------- | 277| [On](#on9) | **On** object that matches the ID attribute of the target component.| 278 279**Error codes** 280 281For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 282 283| ID| Error Message | 284| -------- | ------------------------------------------------------------ | 285| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 286 287**Example** 288 289```ts 290import { On, ON } from '@kit.TestKit'; 291 292let on:On = ON.id('123'); // Use the static constructor ON to create an On object and specify the id attribute of the target component. 293``` 294 295### id<sup>18+</sup> 296 297id(id: string, pattern: MatchPattern): On 298 299Specifies the ID attribute of the target component. 300 301**Atomic service API**: This API can be used in atomic services since API version 18. 302 303**System capability**: SystemCapability.Test.UiTest 304 305**Parameters** 306 307| Name | Type | Mandatory| Description | 308|-----------------------| ------ |----|---------------------------------------| 309| id | string | Yes | Component ID. | 310| pattern | [MatchPattern](#matchpattern) | Yes | Text matching pattern.| 311 312**Return value** 313 314| Type | Description | 315| ---------- | -------------------------------- | 316| [On](#on9) | **On** object that matches the ID attribute of the target component.| 317 318**Error codes** 319 320For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 321 322| ID| Error Message | 323| -------- | ------------------------------------------------------------ | 324| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 325 326**Example** 327 328```ts 329import { MatchPattern, On, ON } from '@kit.TestKit'; 330 331let on:On = ON.id('id', MatchPattern.REG_EXP_ICASE) // Use case-insensitive regular expression to match the ID attribute value of the component. 332``` 333 334### type<sup>9+</sup> 335 336type(tp: string): On 337 338Specifies the type attribute of the target component. 339 340>**NOTE** 341> 342>You can define the type of the component. In addition, you can use [DevEco Testing](https://developer.huawei.com/consumer/en/download) to query the type information of the component. 343 344**Atomic service API**: This API can be used in atomic services since API version 11. 345 346**System capability**: SystemCapability.Test.UiTest 347 348**Parameters** 349 350| Name| Type | Mandatory| Description | 351| ------ | ------ | ---- | -------------- | 352| tp | string | Yes | Component type.| 353 354**Return value** 355 356| Type | Description | 357| ---------- | ---------------------------------------- | 358| [On](#on9) | **On** object that matches the type attribute of the target component.| 359 360**Error codes** 361 362For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 363 364| ID| Error Message | 365| -------- | ------------------------------------------------------------ | 366| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 367 368**Example** 369 370```ts 371import { On, ON } from '@kit.TestKit'; 372let on:On = ON.type('Button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component. 373``` 374 375### type<sup>18+</sup> 376 377type(tp: string, pattern: MatchPattern): On 378 379Specifies the type attribute of the target component. 380 381>**NOTE** 382> 383>You can define the type of the component. In addition, you can use [DevEco Testing](https://developer.huawei.com/consumer/en/download) to query the type information of the component. 384 385**Atomic service API**: This API can be used in atomic services since API version 18. 386 387**System capability**: SystemCapability.Test.UiTest 388 389**Parameters** 390 391| Name | Type | Mandatory| Description | 392|-----------------------| ------ |----|---------------------------------------| 393| tp | string | Yes | Component type. | 394| pattern | [MatchPattern](#matchpattern) | Yes | Text matching pattern.| 395 396**Return value** 397 398| Type | Description | 399| ---------- | ---------------------------------------- | 400| [On](#on9) | **On** object that matches the type attribute of the target component.| 401 402**Error codes** 403 404For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 405 406| ID| Error Message | 407| -------- | ------------------------------------------------------------ | 408| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 409 410**Example** 411 412```ts 413import { On, ON } from '@kit.TestKit'; 414let on:On = ON.type('Button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component. 415``` 416 417### clickable<sup>9+</sup> 418 419clickable(b?: boolean): On 420 421Specifies the clickable attribute of the target component. 422 423**Atomic service API**: This API can be used in atomic services since API version 11. 424 425**System capability**: SystemCapability.Test.UiTest 426 427**Parameters** 428 429| Name| Type | Mandatory| Description | 430| ------ | ------- | ---- | ------------------------------------------------------------ | 431| b | boolean | No | Clickable status of the component. The value **true** indicates that the component is clickable, and **false** indicates the opposite. Default value: **true**| 432 433**Return value** 434 435| Type | Description | 436| ---------- | ------------------------------------------ | 437| [On](#on9) | **On** object that matches the clickable attribute of the target component.| 438 439**Error codes** 440 441For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 442 443| ID| Error Message | 444| -------- | ------------------------------------------------------------ | 445| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 446 447**Example** 448 449```ts 450import { On, ON } from '@kit.TestKit'; 451let on:On = ON.clickable(true); // Use the static constructor ON to create an On object and specify the clickable attribute of the target component. 452``` 453 454### longClickable<sup>9+</sup> 455 456longClickable(b?: boolean): On 457 458Specifies the long-clickable attribute of the target component. 459 460**Atomic service API**: This API can be used in atomic services since API version 11. 461 462**System capability**: SystemCapability.Test.UiTest 463 464**Parameters** 465 466| Name| Type | Mandatory| Description | 467| ------ | ------- | ---- | ------------------------------------------------------------ | 468| b | boolean | No | Long-clickable status of the component. The value **true** indicates that the component is long-clickable, and **false** indicates the opposite. Default value: **true**| 469 470**Return value** 471 472| Type | Description | 473| ---------- | ---------------------------------------------- | 474| [On](#on9) | **On** object that matches the long-clickable attribute of the target component.| 475 476**Error codes** 477 478For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 479 480| ID| Error Message | 481| -------- | ------------------------------------------------------------ | 482| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 483 484**Example** 485 486```ts 487import { On, ON } from '@kit.TestKit'; 488let on:On = ON.longClickable(true); // Use the static constructor ON to create an On object and specify the longClickable attribute of the target component. 489``` 490 491### scrollable<sup>9+</sup> 492 493scrollable(b?: boolean): On 494 495Specifies the scrollable attribute of the target component. 496 497**Atomic service API**: This API can be used in atomic services since API version 11. 498 499**System capability**: SystemCapability.Test.UiTest 500 501**Parameters** 502 503| Name| Type | Mandatory| Description | 504| ------ | ------- | ---- | ----------------------------------------------------------- | 505| b | boolean | No | Scrollable status of the component. The value **true** indicates that the component is scrollable, and **false** indicates the opposite. Default value: **true**| 506 507**Return value** 508 509| Type | Description | 510| ---------- | ------------------------------------------ | 511| [On](#on9) | **On** object that matches the scrollable attribute of the target component.| 512 513**Error codes** 514 515For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 516 517| ID| Error Message | 518| -------- | ------------------------------------------------------------ | 519| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 520 521**Example** 522 523```ts 524import { On, ON } from '@kit.TestKit'; 525let on:On = ON.scrollable(true); // Use the static constructor ON to create an On object and specify the scrollable attribute of the target component. 526``` 527 528### enabled<sup>9+</sup> 529 530enabled(b?: boolean): On 531 532Specifies the enabled attribute of the target component. 533 534**Atomic service API**: This API can be used in atomic services since API version 11. 535 536**System capability**: SystemCapability.Test.UiTest 537 538**Parameters** 539 540| Name| Type | Mandatory| Description | 541| ------ | ------- | ---- | --------------------------------------------------------- | 542| b | boolean | No | Enabled status of the component. The value **true** indicates that the component is enabled, and **false** indicates the opposite. Default value: **true**| 543 544**Return value** 545 546| Type | Description | 547| ---------- | ---------------------------------------- | 548| [On](#on9) | **On** object that matches the enabled attribute of the target component.| 549 550**Error codes** 551 552For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 553 554| ID| Error Message | 555| -------- | ------------------------------------------------------------ | 556| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 557 558**Example** 559 560```ts 561import { On, ON } from '@kit.TestKit'; 562let on:On = ON.enabled(true); // Use the static constructor ON to create an On object and specify the enabled attribute of the target component. 563``` 564 565### focused<sup>9+</sup> 566 567focused(b?: boolean): On 568 569Specifies the focused attribute of the target component. 570 571**Atomic service API**: This API can be used in atomic services since API version 11. 572 573**System capability**: SystemCapability.Test.UiTest 574 575**Parameters** 576 577| Name| Type | Mandatory| Description | 578| ------ | ------- | ---- | ----------------------------------------------------- | 579| b | boolean | No | Focused status of the component. The value **true** indicates that the component is focused, and **false** indicates the opposite. Default value: **true**| 580 581**Return value** 582 583| Type | Description | 584| ---------- | ---------------------------------------- | 585| [On](#on9) | **On** object that matches the focused attribute of the target component.| 586 587**Error codes** 588 589For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 590 591| ID| Error Message | 592| -------- | ------------------------------------------------------------ | 593| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 594 595**Example** 596 597```ts 598import { On, ON } from '@kit.TestKit'; 599let on:On = ON.focused(true); // Use the static constructor ON to create an On object and specify the focused attribute of the target component. 600``` 601 602### selected<sup>9+</sup> 603 604selected(b?: boolean): On 605 606Specifies the selected attribute of the target component. 607 608**Atomic service API**: This API can be used in atomic services since API version 11. 609 610**System capability**: SystemCapability.Test.UiTest 611 612**Parameters** 613 614| Name| Type | Mandatory| Description | 615| ------ | ------- | ---- | ------------------------------------------------------------ | 616| b | boolean | No | Selected status of the component. The value **true** indicates that the component is selected, and **false** indicates the opposite. Default value: **true**| 617 618**Return value** 619 620| Type | Description | 621| ---------- | ------------------------------------------ | 622| [On](#on9) | **On** object that matches the selected attribute of the target component.| 623 624**Error codes** 625 626For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 627 628| ID| Error Message | 629| -------- | ------------------------------------------------------------ | 630| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 631 632**Example** 633 634```ts 635import { On, ON } from '@kit.TestKit'; 636let on:On = ON.selected(true); // Use the static constructor ON to create an On object and specify the selected attribute of the target component. 637``` 638 639### checked<sup>9+</sup> 640 641checked(b?: boolean): On 642 643Specifies the checked attribute of the target component. 644 645**Atomic service API**: This API can be used in atomic services since API version 11. 646 647**System capability**: SystemCapability.Test.UiTest 648 649**Parameters** 650 651| Name| Type | Mandatory| Description | 652| ------ | ------- | ---- | ------------------------------------------------------------ | 653| b | boolean | No | Checked status of the component. The value **true** indicates that the component is checked, and **false** indicates the opposite. Default value: **true**| 654 655**Return value** 656 657| Type | Description | 658| ---------- | ------------------------------------------ | 659| [On](#on9) | **On** object that matches the checked attribute of the target component.| 660 661**Error codes** 662 663For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 664 665| ID| Error Message | 666| -------- | ------------------------------------------------------------ | 667| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 668 669**Example** 670 671```ts 672import { On, ON } from '@kit.TestKit'; 673let on:On = ON.checked(true); // Use the static constructor ON to create an On object and specify the checked attribute of the target component. 674``` 675 676### checkable<sup>9+</sup> 677 678checkable(b?: boolean): On 679 680Specifies the checkable attribute of the target component. 681 682**Atomic service API**: This API can be used in atomic services since API version 11. 683 684**System capability**: SystemCapability.Test.UiTest 685 686**Parameters** 687 688| Name| Type | Mandatory| Description | 689| ------ | ------- | ---- | ------------------------------------------------------------ | 690| b | boolean | No | Checkable status of the component. The value **true** indicates that the component is checkable, and **false** indicates the opposite. Default value: **true**| 691 692**Return value** 693 694| Type | Description | 695| ---------- | -------------------------------------------- | 696| [On](#on9) | **On** object that matches the checkable attribute of the target component.| 697 698**Error codes** 699 700For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 701 702| ID| Error Message | 703| -------- | ------------------------------------------------------------ | 704| 401 | Parameter error. 1. Incorrect parameter types; 2. Parameter verification failed. | 705 706**Example** 707 708```ts 709import { On, ON } from '@kit.TestKit'; 710let on:On = ON.checkable(true); // Use the static constructor ON to create an On object and specify the checkable attribute of the target component. 711``` 712 713### isBefore<sup>9+</sup> 714 715isBefore(on: On): On 716 717Specifies that the target component is located before the given attribute component. 718 719**Atomic service API**: This API can be used in atomic services since API version 11. 720 721**System capability**: SystemCapability.Test.UiTest 722 723**Parameters** 724 725| Name| Type | Mandatory| Description | 726| ------ | ---------- | ---- | -------------------- | 727| on | [On](#on9) | Yes | Information about the attribute component.| 728 729**Return value** 730 731| Type | Description | 732| ---------- | ---------------------------------------------------- | 733| [On](#on9) | **On** object.| 734 735**Error codes** 736 737For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 738 739| ID| Error Message | 740| -------- | ------------------------------------------------------------ | 741| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 742 743**Example** 744 745```ts 746import { On, ON } from '@kit.TestKit'; 747 748// Use the static constructor ON to create an On object and specify that the target component is located before the given attribute component. 749let on:On = ON.type('Button').isBefore(ON.text('123')); // Search for the first <Button> component located before the component whose text is 123. 750``` 751 752### isAfter<sup>9+</sup> 753 754isAfter(on: On): On 755 756Specifies that the target component is located after the given attribute component. 757 758**Atomic service API**: This API can be used in atomic services since API version 11. 759 760**System capability**: SystemCapability.Test.UiTest 761 762**Parameters** 763 764| Name| Type | Mandatory| Description | 765| ------ | ---------- | ---- | -------------------- | 766| on | [On](#on9) | Yes | Information about the attribute component.| 767 768**Return value** 769 770| Type | Description | 771| ---------- | ---------------------------------------------------- | 772| [On](#on9) | **On** object.| 773 774**Error codes** 775 776For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 777 778| ID| Error Message | 779| -------- | ------------------------------------------------------------ | 780| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 781 782**Example** 783 784```ts 785import { On, ON } from '@kit.TestKit'; 786 787// Use the static constructor ON to create an On object and specify that the target component is located after the given attribute component. 788let on:On = ON.type('Text').isAfter(ON.text('123')); // Search for the first <Text> component located after the component whose text is 123. 789``` 790 791### within<sup>10+</sup> 792 793within(on: On): On 794 795Specifies that the target component is located within the given attribute component. 796 797**Atomic service API**: This API can be used in atomic services since API version 11. 798 799**System capability**: SystemCapability.Test.UiTest 800 801**Parameters** 802 803| Name| Type | Mandatory| Description | 804| ------ | ---------- | ---- | -------------------- | 805| on | [On](#on9) | Yes | Information about the attribute component.| 806 807**Return value** 808 809| Type | Description | 810| ---------- | -------------------------------------------------- | 811| [On](#on9) | **On** object.| 812 813**Error codes** 814 815For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 816 817| ID| Error Message | 818| -------- | ------------------------------------------------------------ | 819| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 820 821**Example** 822 823```ts 824import { On, ON } from '@kit.TestKit'; 825// Use the static constructor ON to create an On object and specify that the target component is located within the given attribute component. 826let on:On = ON.text('java').within(ON.type('Scroll')); // Search for the child component whose text is java within the <Scroller> component. 827``` 828 829### inWindow<sup>10+</sup> 830 831inWindow(bundleName: string): On 832 833Specifies that the target component is located within the given application window. 834 835**Atomic service API**: This API can be used in atomic services since API version 11. 836 837**System capability**: SystemCapability.Test.UiTest 838 839**Parameters** 840 841| Name | Type | Mandatory| Description | 842| ---------- | ------ | ---- | ---------------- | 843| bundleName | string | Yes | Bundle name of the application window.| 844 845**Return value** 846 847| Type | Description | 848| ---------- | ---------------------------------------------- | 849| [On](#on9) | **On** object.| 850 851**Error codes** 852 853For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 854 855| ID| Error Message | 856| -------- | ------------------------------------------------------------ | 857| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 858 859**Example** 860 861```ts 862import { On, ON } from '@kit.TestKit'; 863let on:On = ON.inWindow('com.uitestScene.acts'); // Use the static constructor ON to create an On object and specify that the target component is located within the given application window. 864``` 865 866### description<sup>11+</sup> 867 868description(val: string, pattern?: MatchPattern): On 869 870Specifies the description of the target component. Multiple match patterns are supported. 871 872**Atomic service API**: This API can be used in atomic services since API version 11. 873 874**System capability**: SystemCapability.Test.UiTest 875 876**Parameters** 877 878| Name | Type | Mandatory| Description | 879| ------- | ----------------------------- | ---- | --------------------------------------------------- | 880| val | string | Yes | Description of the component. | 881| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 882 883**Return value** 884 885| Type | Description | 886| ---------- | ----------------------------------------- | 887| [On](#on9) | **On** object.| 888 889**Error codes** 890 891For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 892 893| ID| Error Message | 894| -------- | ------------------------------------------------------------ | 895| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 896 897**Example** 898 899```ts 900import { On, ON } from '@kit.TestKit'; 901let on:On = ON.description('123'); // Use the static constructor ON to create an On object and specify the description attribute of the target component. 902``` 903 904### hint<sup>18+</sup> 905 906hint(val: string, pattern?: MatchPattern): On 907 908Obtains the component object of the specified hint text and returns the **On** object. 909 910**Atomic service API**: This API can be used in atomic services since API version 18. 911 912**System capability**: SystemCapability.Test.UiTest 913 914**Parameters** 915 916| Name| Type | Mandatory| Description | 917| ------ | ------ |----|---------------------------------------| 918| val | string | Yes | The specified hint text of the component. | 919| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 920 921**Return value** 922 923| Type | Description | 924| ---------- | ---------------------------------------- | 925| [On](#on9) | The **On** object of the specified hint text component.| 926 927**Error codes** 928 929For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 930 931| ID| Error Message | 932| -------- | ------------------------------------------------------------ | 933| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 934 935**Example** 936 937```ts 938 import { MatchPattern, On, ON } from '@kit.TestKit'; 939 940 let on:On = ON.hint('welcome', MatchPattern.EQUALS); // Use the static constructor ON to create an On object with the hint text attribute of the target component specified. 941``` 942 943### belongingDisplay<sup>20+</sup> 944 945belongingDisplay(displayId: number): On 946 947Obtains the component object on the specified display. 948 949**Atomic service API**: This API can be used in atomic services since API version 20. 950 951**System capability**: SystemCapability.Test.UiTest 952 953**Parameters** 954 955| Name| Type | Mandatory| Description | 956| ------ | ------ |----|---------------------------------------| 957| displayId | number | Yes | ID of the display to which the component belongs. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. You can use [getAllDisplays](../apis-arkui/js-apis-display.md#displaygetalldisplays9) to obtain all current **display** objects and use them to obtain the corresponding display IDs.| 958 959**Return value** 960 961| Type | Description | 962| ---------- | ---------------------------------------- | 963| [On](#on9) | The **On** object of the display to which the specified component belongs.| 964 965**Error codes** 966 967For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 968 969| ID| Error Message | 970| -------- | ------------------------------------------------------------ | 971| 17000007 | Parameter verification failed.| 972 973**Example** 974 975```ts 976 import { On, ON } from '@kit.TestKit'; 977 978 let on:On = ON.belongingDisplay (0); // Use the static constructor ON to create an On object and specify the ID of the display to which the target component belongs. 979``` 980 981### originalText<sup>20+</sup> 982 983originalText(text: string, pattern?: MatchPattern): On 984 985Specifies the text attribute of the target component. Multiple match patterns are supported. 986 987> **NOTE** 988> 989> If the [accessibilityLevel](../apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md#accessibilitylevel) of a component is set to **no** or **no-hide-descendants**, this API can be used to specify the text attribute of the target component for searching for the component. In this case, the [On.text()](#text9) API does not take effect. 990 991**Atomic service API**: This API can be used in atomic services since API version 20. 992 993**System capability**: SystemCapability.Test.UiTest 994 995**Parameters** 996 997| Name | Type | Mandatory| Description | 998| ------- | ----------------------------- | ---- | --------------------------------------------------- | 999| text | string | Yes | Component text, used to match the target component. | 1000| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 1001 1002**Return value** 1003 1004| Type | Description | 1005| ---------- | ---------------------------------- | 1006| [On](#on9) | **On** object that matches the text attribute of the target component.| 1007 1008**Error codes** 1009 1010For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1011 1012| ID| Error Message | 1013| -------- | ------------------------------------------------------------ | 1014| 17000007 | Parameter verification failed.| 1015 1016**Example** 1017 1018```ts 1019import { On, ON } from '@kit.TestKit'; 1020 1021let on:On = ON.originalText('123'); // Use the static constructor ON to create an On object and specify the originalText attribute of the target component. 1022``` 1023 1024## Component<sup>9+</sup> 1025 1026Represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. 1027All APIs provided in this class use a promise to return the result and must be invoked using **await**. 1028 1029### click<sup>9+</sup> 1030 1031click(): Promise\<void> 1032 1033Clicks a component object. This API uses a promise to return the result. 1034 1035**Atomic service API**: This API can be used in atomic services since API version 11. 1036 1037**System capability**: SystemCapability.Test.UiTest 1038 1039**Return value** 1040 1041| Type | Description | 1042|----------------|-----------------| 1043| Promise\<void> | Promise that returns no value.| 1044 1045**Error codes** 1046 1047For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1048 1049| ID| Error Message | 1050| -------- | ---------------------------------------- | 1051| 17000002 | The async function is not called with await. | 1052| 17000004 | The window or component is invisible or destroyed. | 1053 1054**Example** 1055 1056```ts 1057import { Driver, ON, Component } from '@kit.TestKit'; 1058async function demo() { 1059 let driver:Driver = Driver.create(); 1060 let button: Component = await driver.findComponent(ON.type('Button')); 1061 await button.click(); 1062} 1063``` 1064 1065### doubleClick<sup>9+</sup> 1066 1067doubleClick(): Promise\<void> 1068 1069Double-clicks a component object. This API uses a promise to return the result. 1070 1071**Atomic service API**: This API can be used in atomic services since API version 11. 1072 1073**System capability**: SystemCapability.Test.UiTest 1074 1075**Return value** 1076 1077| Type | Description | 1078|----------------|-----------------| 1079| Promise\<void> | Promise that returns no value.| 1080 1081**Error codes** 1082 1083For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1084 1085| ID| Error Message | 1086| -------- | ---------------------------------------- | 1087| 17000002 | The async function is not called with await. | 1088| 17000004 | The window or component is invisible or destroyed. | 1089 1090**Example** 1091 1092```ts 1093import {Component, Driver, ON } from '@kit.TestKit'; 1094async function demo() { 1095 let driver: Driver = Driver.create(); 1096 let button: Component = await driver.findComponent(ON.type('Button')); 1097 await button.doubleClick(); 1098} 1099``` 1100 1101### longClick<sup>9+</sup> 1102 1103longClick(): Promise\<void> 1104 1105Long-clicks a component object. This API uses a promise to return the result. 1106 1107**Atomic service API**: This API can be used in atomic services since API version 11. 1108 1109**System capability**: SystemCapability.Test.UiTest 1110 1111**Return value** 1112 1113| Type | Description | 1114|----------------|-----------------| 1115| Promise\<void> | Promise that returns no value.| 1116 1117**Error codes** 1118 1119For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1120 1121| ID| Error Message | 1122| -------- | ---------------------------------------- | 1123| 17000002 | The async function is not called with await. | 1124| 17000004 | The window or component is invisible or destroyed. | 1125 1126**Example** 1127 1128```ts 1129import { Component, Driver, ON } from '@kit.TestKit'; 1130async function demo() { 1131 let driver: Driver = Driver.create(); 1132 let button: Component = await driver.findComponent(ON.type('Button')); 1133 await button.longClick(); 1134} 1135``` 1136 1137### getId<sup>9+</sup> 1138 1139getId(): Promise\<string> 1140 1141Obtains the ID of a component object. This API uses a promise to return the result. 1142 1143**Atomic service API**: This API can be used in atomic services since API version 11. 1144 1145**System capability**: SystemCapability.Test.UiTest 1146 1147**Return value** 1148 1149| Type | Description | 1150| ---------------- | ------------------------------- | 1151| Promise\<string> | Promise used to return the component ID.| 1152 1153**Error codes** 1154 1155For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1156 1157| ID| Error Message | 1158| -------- | ---------------------------------------- | 1159| 17000002 | The async function is not called with await. | 1160| 17000004 | The window or component is invisible or destroyed. | 1161 1162**Example** 1163 1164```ts 1165import { Component, Driver, ON } from '@kit.TestKit'; 1166async function demo() { 1167 let driver: Driver = Driver.create(); 1168 let button: Component = await driver.findComponent(ON.type('Button')); 1169 let id = await button.getId(); 1170} 1171``` 1172 1173### getText<sup>9+</sup> 1174 1175getText(): Promise\<string> 1176 1177Obtains the text information of this component. This API uses a promise to return the result. 1178 1179> **NOTE** 1180> 1181> If the [accessibilityLevel](../apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md#accessibilitylevel) attribute of the component is set to **no** or **no-hide-descendants**, this API cannot be used to obtain the text information of the component. In this case, you can use [Component.getOriginalText ()](#getoriginaltext20) to obtain the text information of the component. 1182 1183**Atomic service API**: This API can be used in atomic services since API version 11. 1184 1185**System capability**: SystemCapability.Test.UiTest 1186 1187**Return value** 1188 1189| Type | Description | 1190| ---------------- | --------------------------------- | 1191| Promise\<string> | Promise used to return the text information of the component.| 1192 1193**Error codes** 1194 1195For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1196 1197| ID| Error Message | 1198| -------- | ---------------------------------------- | 1199| 17000002 | The async function is not called with await. | 1200| 17000004 | The window or component is invisible or destroyed. | 1201 1202**Example** 1203 1204```ts 1205import { Component, Driver, ON } from '@kit.TestKit'; 1206async function demo() { 1207 let driver: Driver = Driver.create(); 1208 let button: Component = await driver.findComponent(ON.type('Button')); 1209 let text = await button.getText(); 1210} 1211``` 1212 1213### getType<sup>9+</sup> 1214 1215getType(): Promise\<string> 1216 1217Obtains the type of a component object. This API uses a promise to return the result. 1218 1219**Atomic service API**: This API can be used in atomic services since API version 11. 1220 1221**System capability**: SystemCapability.Test.UiTest 1222 1223**Return value** 1224 1225| Type | Description | 1226| ---------------- | ----------------------------- | 1227| Promise\<string> | Promise used to return the component type.| 1228 1229**Error codes** 1230 1231For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1232 1233| ID| Error Message | 1234| -------- | ---------------------------------------- | 1235| 17000002 | The async function is not called with await. | 1236| 17000004 | The window or component is invisible or destroyed. | 1237 1238**Example** 1239 1240```ts 1241import { Component, Driver, ON } from '@kit.TestKit'; 1242async function demo() { 1243 let driver: Driver = Driver.create(); 1244 let button: Component = await driver.findComponent(ON.type('Button')); 1245 let type = await button.getType(); 1246} 1247``` 1248 1249### getBounds<sup>9+</sup> 1250 1251getBounds(): Promise\<Rect> 1252 1253Obtains the bound information of this component. This API uses a promise to return the result. 1254 1255**Atomic service API**: This API can be used in atomic services since API version 11. 1256 1257**System capability**: SystemCapability.Test.UiTest 1258 1259**Return value** 1260 1261| Type | Description | 1262| ------------------------ | ------------------------------------- | 1263| Promise\<[Rect](#rect9)> | Promise used to return the bound information of the component object.| 1264 1265**Error codes** 1266 1267For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1268 1269| ID| Error Message | 1270| -------- | ---------------------------------------- | 1271| 17000002 | The async function is not called with await. | 1272| 17000004 | The window or component is invisible or destroyed. | 1273 1274**Example** 1275 1276```ts 1277import { Component, Driver, ON } from '@kit.TestKit'; 1278async function demo() { 1279 let driver: Driver = Driver.create(); 1280 let button: Component = await driver.findComponent(ON.type('Button')); 1281 let rect = await button.getBounds(); 1282} 1283``` 1284 1285### getBoundsCenter<sup>9+</sup> 1286 1287getBoundsCenter(): Promise\<Point> 1288 1289Obtains the center point of the area occupied by a component object. This API uses a promise to return the result. 1290 1291**Atomic service API**: This API can be used in atomic services since API version 11. 1292 1293**System capability**: SystemCapability.Test.UiTest 1294 1295**Return value** 1296 1297| Type | Description | 1298| -------------------------- | ----------------------------------------------- | 1299| Promise\<[Point](#point9)> | Promise used to return the center point of the area occupied by the component object.| 1300 1301**Error codes** 1302 1303For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1304 1305| ID| Error Message | 1306| -------- | ---------------------------------------- | 1307| 17000002 | The async function is not called with await. | 1308| 17000004 | The window or component is invisible or destroyed. | 1309 1310**Example** 1311 1312```ts 1313import { Component, Driver, ON } from '@kit.TestKit'; 1314async function demo() { 1315 let driver: Driver = Driver.create(); 1316 let button: Component = await driver.findComponent(ON.type('Button')); 1317 let point = await button.getBoundsCenter(); 1318} 1319``` 1320 1321### isClickable<sup>9+</sup> 1322 1323isClickable(): Promise\<boolean> 1324 1325Obtains the clickable attribute of a component object. This API uses a promise to return the result. 1326 1327**Atomic service API**: This API can be used in atomic services since API version 11. 1328 1329**System capability**: SystemCapability.Test.UiTest 1330 1331**Return value** 1332 1333| Type | Description | 1334| ----------------- | ------------------------------------------------------------ | 1335| Promise\<boolean> | Promise used to return whether the component object is clickable. The value **true** indicates that the component is clickable, and **false** indicates the opposite.| 1336 1337**Error codes** 1338 1339For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1340 1341| ID| Error Message | 1342| -------- | ---------------------------------------- | 1343| 17000002 | The async function is not called with await. | 1344| 17000004 | The window or component is invisible or destroyed. | 1345 1346**Example** 1347 1348```ts 1349import { Component, Driver, ON } from '@kit.TestKit'; 1350async function demo() { 1351 let driver: Driver = Driver.create(); 1352 let button: Component = await driver.findComponent(ON.type('Button')); 1353 if(await button.isClickable()) { 1354 console.info('This button can be Clicked'); 1355 } else { 1356 console.info('This button can not be Clicked'); 1357 } 1358} 1359``` 1360 1361### isLongClickable<sup>9+</sup> 1362 1363isLongClickable(): Promise\<boolean> 1364 1365Obtains the long-clickable attribute of a component object. This API uses a promise to return the result. 1366 1367**Atomic service API**: This API can be used in atomic services since API version 11. 1368 1369**System capability**: SystemCapability.Test.UiTest 1370 1371**Return value** 1372 1373| Type | Description | 1374| ----------------- |--------------------------------------------------| 1375| Promise\<boolean> | Promise used to return whether the component object is long-clickable. The value **true** indicates that the component is long-clickable, and **false** indicates the opposite.| 1376 1377**Error codes** 1378 1379For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1380 1381| ID| Error Message | 1382| -------- | ---------------------------------------- | 1383| 17000002 | The async function is not called with await. | 1384| 17000004 | The window or component is invisible or destroyed. | 1385 1386**Example** 1387 1388```ts 1389import { Component, Driver, ON } from '@kit.TestKit'; 1390async function demo() { 1391 let driver: Driver = Driver.create(); 1392 let button: Component = await driver.findComponent(ON.type('Button')); 1393 if(await button.isLongClickable()) { 1394 console.info('This button can longClick'); 1395 } else { 1396 console.info('This button can not longClick'); 1397 } 1398} 1399``` 1400 1401### isChecked<sup>9+</sup> 1402 1403isChecked(): Promise\<boolean> 1404 1405Obtains the checked status of a component object. This API uses a promise to return the result. 1406 1407**Atomic service API**: This API can be used in atomic services since API version 11. 1408 1409**System capability**: SystemCapability.Test.UiTest 1410 1411**Return value** 1412 1413| Type | Description | 1414| ----------------- | ------------------------------------------------------------ | 1415| Promise\<boolean> | Promise used to return the checked status of the component object. The value **true** indicates that the component is checked, and **false** indicates the opposite.| 1416 1417**Error codes** 1418 1419For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1420 1421| ID| Error Message | 1422| -------- | ---------------------------------------- | 1423| 17000002 | The async function is not called with await. | 1424| 17000004 | The window or component is invisible or destroyed. | 1425 1426**Example** 1427 1428```ts 1429import { Component, Driver, ON } from '@kit.TestKit'; 1430async function demo() { 1431 let driver: Driver = Driver.create(); 1432 let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); 1433 if(await checkBox.isChecked()) { 1434 console.info('This checkBox is checked'); 1435 } else { 1436 console.info('This checkBox is not checked'); 1437 } 1438} 1439``` 1440 1441### isCheckable<sup>9+</sup> 1442 1443isCheckable(): Promise\<boolean> 1444 1445Obtains whether a component object is checkable. This API uses a promise to return the result. 1446 1447**Atomic service API**: This API can be used in atomic services since API version 11. 1448 1449**System capability**: SystemCapability.Test.UiTest 1450 1451**Return value** 1452 1453| Type | Description | 1454| ----------------- | ------------------------------------------------------------ | 1455| Promise\<boolean> | Promise used to return whether the component object is checkable. The value **true** indicates that the component is checkable, and **false** indicates the opposite.| 1456 1457**Error codes** 1458 1459For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1460 1461| ID| Error Message | 1462| -------- | ---------------------------------------- | 1463| 17000002 | The async function is not called with await. | 1464| 17000004 | The window or component is invisible or destroyed. | 1465 1466**Example** 1467 1468```ts 1469import { Component, Driver, ON } from '@kit.TestKit'; 1470async function demo() { 1471 let driver: Driver = Driver.create(); 1472 let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); 1473 if(await checkBox.isCheckable()) { 1474 console.info('This checkBox is checkable'); 1475 } else { 1476 console.info('This checkBox is not checkable'); 1477 } 1478} 1479``` 1480 1481### isScrollable<sup>9+</sup> 1482 1483isScrollable(): Promise\<boolean> 1484 1485Obtains whether a component object is scrollable. This API uses a promise to return the result. 1486 1487**Atomic service API**: This API can be used in atomic services since API version 11. 1488 1489**System capability**: SystemCapability.Test.UiTest 1490 1491**Return value** 1492 1493| Type | Description | 1494| ----------------- | ------------------------------------------------------------ | 1495| Promise\<boolean> | Promise used to return whether the component object is scrollable. The value **true** indicates that the component is scrollable, and **false** indicates the opposite.| 1496 1497**Error codes** 1498 1499For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1500 1501| ID| Error Message | 1502| -------- | ---------------------------------------- | 1503| 17000002 | The async function is not called with await. | 1504| 17000004 | The window or component is invisible or destroyed. | 1505 1506**Example** 1507 1508```ts 1509import { Component, Driver, ON } from '@kit.TestKit'; 1510async function demo() { 1511 let driver: Driver = Driver.create(); 1512 let scrollBar: Component = await driver.findComponent(ON.scrollable(true)); 1513 if(await scrollBar.isScrollable()) { 1514 console.info('This scrollBar can be operated'); 1515 } else { 1516 console.info('This scrollBar can not be operated'); 1517 } 1518} 1519``` 1520 1521 1522### isEnabled<sup>9+</sup> 1523 1524isEnabled(): Promise\<boolean> 1525 1526Obtains whether the component is enabled. This API uses a promise to return the result. 1527 1528**Atomic service API**: This API can be used in atomic services since API version 11. 1529 1530**System capability**: SystemCapability.Test.UiTest 1531 1532**Return value** 1533 1534| Type | Description | 1535| ----------------- | ---------------------------------------------------------- | 1536| Promise\<boolean> | Promise used to return whether the component is enabled. The value **true** indicates that the component is enabled, and **false** indicates the opposite.| 1537 1538**Error codes** 1539 1540For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1541 1542| ID| Error Message | 1543| -------- | ---------------------------------------- | 1544| 17000002 | The async function is not called with await. | 1545| 17000004 | The window or component is invisible or destroyed. | 1546 1547**Example** 1548 1549```ts 1550import { Component, Driver, ON } from '@kit.TestKit'; 1551async function demo() { 1552 let driver: Driver = Driver.create(); 1553 let button: Component = await driver.findComponent(ON.type('Button')); 1554 if(await button.isEnabled()) { 1555 console.info('This button can be operated'); 1556 } else { 1557 console.info('This button can not be operated'); 1558 } 1559} 1560``` 1561 1562### isFocused<sup>9+</sup> 1563 1564isFocused(): Promise\<boolean> 1565 1566Checks whether the component is focused. This API uses a promise to return the result. 1567 1568**Atomic service API**: This API can be used in atomic services since API version 11. 1569 1570**System capability**: SystemCapability.Test.UiTest 1571 1572**Return value** 1573 1574| Type | Description | 1575| ----------------- | ------------------------------------------------------------ | 1576| Promise\<boolean> | Promise used to return whether the component is focused. The value **true** indicates that the component is focused, and **false** indicates the opposite.| 1577 1578**Error codes** 1579 1580For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1581 1582| ID| Error Message | 1583| -------- | ---------------------------------------- | 1584| 17000002 | The async function is not called with await. | 1585| 17000004 | The window or component is invisible or destroyed. | 1586 1587**Example** 1588 1589```ts 1590import { Component, Driver, ON } from '@kit.TestKit'; 1591async function demo() { 1592 let driver: Driver = Driver.create(); 1593 let button: Component = await driver.findComponent(ON.type('Button')); 1594 if(await button.isFocused()) { 1595 console.info('This button is focused'); 1596 } else { 1597 console.info('This button is not focused'); 1598 } 1599} 1600``` 1601 1602### isSelected<sup>9+</sup> 1603 1604isSelected(): Promise\<boolean> 1605 1606Obtains whether a component is selected. This API uses a promise to return the result. 1607 1608**Atomic service API**: This API can be used in atomic services since API version 11. 1609 1610**System capability**: SystemCapability.Test.UiTest 1611 1612**Return value** 1613 1614| Type | Description | 1615| ----------------- | --------------------------------------------------- | 1616| Promise\<boolean> | Promise used to return whether the component is selected. The value **true** indicates that the component is selected, and **false** indicates the opposite.| 1617 1618**Error codes** 1619 1620For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1621 1622| ID| Error Message | 1623| -------- | ---------------------------------------- | 1624| 17000002 | The async function is not called with await. | 1625| 17000004 | The window or component is invisible or destroyed. | 1626 1627**Example** 1628 1629```ts 1630import { Component, Driver, ON } from '@kit.TestKit'; 1631async function demo() { 1632 let driver: Driver = Driver.create(); 1633 let button: Component = await driver.findComponent(ON.type('Button')); 1634 if(await button.isSelected()) { 1635 console.info('This button is selected'); 1636 } else { 1637 console.info('This button is not selected'); 1638 } 1639} 1640``` 1641 1642### inputText<sup>9+</sup> 1643 1644inputText(text: string): Promise\<void> 1645 1646Inputs text in a text box component after clearing its original text. This API uses a promise to return the result. 1647 1648**Atomic service API**: This API can be used in atomic services since API version 11. 1649 1650**System capability**: SystemCapability.Test.UiTest 1651 1652**Return value** 1653 1654| Type | Description | 1655|----------------|-----------------| 1656| Promise\<void> | Promise that returns no value.| 1657 1658**Parameters** 1659 1660| Name| Type | Mandatory| Description | 1661| ------ | ------ | ---- | ---------------------------------------- | 1662| text | string | Yes | Input text. Currently, English, Chinese, and special characters are supported.<br> **Note**: For wearables, this API does not support Chinese characters.| 1663 1664**Error codes** 1665 1666For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 1667 1668| ID| Error Message | 1669| -------- | ---------------------------------------- | 1670| 17000002 | The async function is not called with await. | 1671| 17000004 | The window or component is invisible or destroyed. | 1672| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1673 1674**Example** 1675 1676```ts 1677import { Component, Driver, ON } from '@kit.TestKit'; 1678async function demo() { 1679 let driver: Driver = Driver.create(); 1680 let text: Component = await driver.findComponent(ON.text('hello world')); 1681 await text.inputText('123'); 1682} 1683``` 1684 1685### inputText<sup>20+</sup> 1686 1687inputText(text: string, mode: InputTextMode): Promise\<void> 1688 1689Inputs text to a text box component with a specified text input mode supported. This API uses a promise to return the result. 1690 1691**Atomic service API**: This API can be used in atomic services since API version 20. 1692 1693**System capability**: SystemCapability.Test.UiTest 1694 1695**Parameters** 1696 1697| Name| Type | Mandatory| Description | 1698| ------ | ------ | ---- | ---------------------------------------- | 1699| text | string | Yes | Input text. Currently, English, Chinese, and special characters are supported.<br> **Note**: For wearables, this API does not support Chinese characters.| 1700| mode | [InputTextMode](#inputtextmode20) | Yes | Text input mode. For details, see [InputTextMode](#inputtextmode20).<br> **Note**: If **InputTextMode.addition** is set to **true**, the specified text is added to the end of the existing text in the component. Otherwise, the specified text overwrites the existing text of the component.| 1701 1702**Return value** 1703 1704| Type | Description | 1705|----------------|-----------------| 1706| Promise\<void> | Promise that returns no value.| 1707 1708**Error codes** 1709 1710For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 1711 1712| ID| Error Message | 1713| -------- | ---------------------------------------- | 1714| 17000002 | The async function is not called with await. | 1715| 17000004 | The window or component is invisible or destroyed. | 1716| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1717| 801 | Capability not support, function can not work correctly due to limited device capabilities.| 1718 1719**Example** 1720```ts 1721import { Component, Driver, ON } from '@kit.TestKit'; 1722 1723async function mode_demo() { 1724 let driver: Driver = Driver.create(); 1725 let text: Component = await driver.findComponent(ON.text('hello world')); 1726 await text.inputText('123', { paste: true, addition: false }); 1727} 1728``` 1729 1730 1731### clearText<sup>9+</sup> 1732 1733clearText(): Promise\<void> 1734 1735Clears the text in a text box component. This API uses a promise to return the result. 1736 1737**Atomic service API**: This API can be used in atomic services since API version 11. 1738 1739**System capability**: SystemCapability.Test.UiTest 1740 1741**Return value** 1742 1743| Type | Description | 1744|----------------|-----------------| 1745| Promise\<void> | Promise that returns no value.| 1746 1747**Error codes** 1748For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1749 1750| ID| Error Message | 1751| -------- | ---------------------------------------- | 1752| 17000002 | The async function is not called with await. | 1753| 17000004 | The window or component is invisible or destroyed. | 1754 1755**Example** 1756 1757```ts 1758import { Component, Driver, ON } from '@kit.TestKit'; 1759async function demo() { 1760 let driver: Driver = Driver.create(); 1761 let text: Component = await driver.findComponent(ON.text('hello world')); 1762 await text.clearText(); 1763} 1764``` 1765 1766### scrollSearch<sup>9+</sup> 1767 1768scrollSearch(on: On): Promise\<Component> 1769 1770Scrolls on this component to search for the target component. This API is applicable to components that support scrolling and uses a promise to return the result. 1771 1772**Atomic service API**: This API can be used in atomic services since API version 11. 1773 1774**System capability**: SystemCapability.Test.UiTest 1775 1776**Parameters** 1777 1778| Name| Type | Mandatory| Description | 1779| ------ | ---------- | ---- | -------------------- | 1780| on | [On](#on9) | Yes | Attributes of the target component.| 1781 1782**Return value** 1783 1784| Type | Description | 1785| ---------------------------------- | ------------------------------------- | 1786| Promise\<[Component](#component9)> | Promise used to return the target component.| 1787 1788**Error codes** 1789 1790For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 1791 1792| ID| Error Message | 1793| -------- | ---------------------------------------- | 1794| 17000002 | The async function is not called with await. | 1795| 17000004 | The window or component is invisible or destroyed. | 1796| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1797 1798**Example** 1799 1800```ts 1801import { Component, Driver, ON } from '@kit.TestKit'; 1802 1803async function demo() { 1804 let driver: Driver = Driver.create(); 1805 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1806 let button = await scrollBar.scrollSearch(ON.text('next page')); 1807} 1808``` 1809 1810### scrollSearch<sup>18+</sup> 1811 1812scrollSearch(on: On, vertical?: boolean, offset?: number): Promise\<Component> 1813 1814Scrolls on this component to search for the target component. This API is applicable to components that support scrolling and uses a promise to return the result. 1815 1816**Atomic service API**: This API can be used in atomic services since API version 18. 1817 1818**System capability**: SystemCapability.Test.UiTest 1819 1820**Parameters** 1821 1822| Name | Type | Mandatory| Description | 1823|------------------------| ---------- | ---- |-----------------------------------| 1824| on | [On](#on9) | Yes | Attributes of the target component. | 1825| vertical | boolean | No| Whether the search direction is vertical. The default value **true** indicates that the search direction is vertical. **false** indicates that the search direction is horizontal.| 1826| offset | number| No| Offset from the scrolling start/end point to the component border, in pixels. The default value is **80**. The value is an integer greater than or equal to 0. | 1827 1828**Return value** 1829 1830| Type | Description | 1831| ---------------------------------- | ------------------------------------- | 1832| Promise\<[Component](#component9)> | Promise used to return the target component.| 1833 1834**Error codes** 1835 1836For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 1837 1838| ID| Error Message | 1839| -------- | ---------------------------------------- | 1840| 17000002 | The async function is not called with await. | 1841| 17000004 | The window or component is invisible or destroyed. | 1842| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1843 1844**Example** 1845 1846```ts 1847import { Component, Driver, ON } from '@kit.TestKit'; 1848async function demo() { 1849 let driver: Driver = Driver.create(); 1850 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1851 let button = await scrollBar.scrollSearch(ON.text('next page')); 1852} 1853``` 1854 1855### scrollToTop<sup>9+</sup> 1856 1857scrollToTop(speed?: number): Promise\<void> 1858 1859Scrolls to the top of a scrollable component. This API uses a promise to return the result. 1860 1861**Atomic service API**: This API can be used in atomic services since API version 11. 1862 1863**System capability**: SystemCapability.Test.UiTest 1864 1865**Parameters** 1866 1867| Name| Type | Mandatory| Description | 1868| ------ | ------ | ---- |--------------------------------------------------------| 1869| speed | number | No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 1870 1871**Return value** 1872 1873| Type | Description | 1874|----------------|-----------------| 1875| Promise\<void> | Promise that returns no value.| 1876 1877**Error codes** 1878 1879For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 1880 1881| ID| Error Message | 1882| -------- | ---------------------------------------- | 1883| 17000002 | The async function is not called with await. | 1884| 17000004 | The window or component is invisible or destroyed. | 1885| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 1886 1887**Example** 1888 1889```ts 1890import { Component, Driver, ON } from '@kit.TestKit'; 1891async function demo() { 1892 let driver: Driver = Driver.create(); 1893 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1894 await scrollBar.scrollToTop(); 1895} 1896``` 1897 1898### scrollToBottom<sup>9+</sup> 1899 1900scrollToBottom(speed?: number): Promise\<void> 1901 1902Scrolls to the bottom of a scrollable component. This API uses a promise to return the result. 1903 1904**Atomic service API**: This API can be used in atomic services since API version 11. 1905 1906**System capability**: SystemCapability.Test.UiTest 1907 1908**Parameters** 1909 1910| Name| Type | Mandatory| Description | 1911| ------ | ------ | ---- |--------------------------------------------------------| 1912| speed | number | No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 1913 1914**Return value** 1915 1916| Type | Description | 1917|----------------|-----------------| 1918| Promise\<void> | Promise that returns no value.| 1919 1920**Error codes** 1921 1922For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 1923 1924| ID| Error Message | 1925| -------- | ---------------------------------------- | 1926| 17000002 | The async function is not called with await. | 1927| 17000004 | The window or component is invisible or destroyed. | 1928| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 1929 1930**Example** 1931 1932```ts 1933import { Component, Driver, ON } from '@kit.TestKit'; 1934async function demo() { 1935 let driver: Driver = Driver.create(); 1936 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1937 await scrollBar.scrollToBottom(); 1938} 1939``` 1940 1941### dragTo<sup>9+</sup> 1942 1943dragTo(target: Component): Promise\<void> 1944 1945Drags a component to the target component. This API uses a promise to return the result. 1946 1947> **NOTE** 1948> 1949> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 1950 1951**Atomic service API**: This API can be used in atomic services since API version 11. 1952 1953**System capability**: SystemCapability.Test.UiTest 1954 1955**Parameters** 1956 1957| Name| Type | Mandatory| Description | 1958| ------ | ------------------------ | ---- | ---------- | 1959| target | [Component](#component9) | Yes | Target component.| 1960 1961**Return value** 1962 1963| Type | Description | 1964|----------------|-----------------| 1965| Promise\<void> | Promise that returns no value.| 1966 1967**Error codes** 1968 1969For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 1970 1971| ID| Error Message | 1972| -------- | ---------------------------------------- | 1973| 17000002 | The async function is not called with await. | 1974| 17000004 | The window or component is invisible or destroyed. | 1975| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1976 1977**Example** 1978 1979```ts 1980import { Component, Driver, ON } from '@kit.TestKit'; 1981async function demo() { 1982 let driver: Driver = Driver.create(); 1983 let button: Component = await driver.findComponent(ON.type('Button')); 1984 let text: Component = await driver.findComponent(ON.text('hello world')); 1985 await button.dragTo(text); 1986} 1987``` 1988 1989### pinchOut<sup>9+</sup> 1990 1991pinchOut(scale: number): Promise\<void> 1992 1993Pinches a component to zoom in based on the specified scale. This API uses a promise to return the result. 1994 1995**Atomic service API**: This API can be used in atomic services since API version 11. 1996 1997**System capability**: SystemCapability.Test.UiTest 1998 1999**Parameters** 2000 2001| Name| Type | Mandatory| Description | 2002| ------ | ------ | ---- | ------------------------------- | 2003| scale | number | Yes | Scale factor, which is a value greater than 1.| 2004 2005**Return value** 2006 2007| Type | Description | 2008|----------------|-----------------| 2009| Promise\<void> | Promise that returns no value.| 2010 2011**Error codes** 2012 2013For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2014 2015| ID| Error Message | 2016| -------- | ---------------------------------------- | 2017| 17000002 | The async function is not called with await. | 2018| 17000004 | The window or component is invisible or destroyed. | 2019| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2020 2021**Example** 2022 2023```ts 2024import { Component, Driver, ON } from '@kit.TestKit'; 2025async function demo() { 2026 let driver: Driver = Driver.create(); 2027 let image: Component = await driver.findComponent(ON.type('Image')); 2028 await image.pinchOut(1.5); 2029} 2030``` 2031 2032### pinchIn<sup>9+</sup> 2033 2034pinchIn(scale: number): Promise\<void> 2035 2036Pinches a component to zoom out based on the specified scale. This API uses a promise to return the result. 2037 2038**Atomic service API**: This API can be used in atomic services since API version 11. 2039 2040**System capability**: SystemCapability.Test.UiTest 2041 2042**Parameters** 2043 2044| Name| Type | Mandatory| Description | 2045| ------ | ------ | ---- | ------------------------------- | 2046| scale | number | Yes | Scale factor, which is a value ranging from 0 to 1.| 2047 2048**Return value** 2049 2050| Type | Description | 2051|----------------|-----------------| 2052| Promise\<void> | Promise that returns no value.| 2053 2054**Error codes** 2055 2056For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2057 2058| ID| Error Message | 2059| -------- | ---------------------------------------- | 2060| 17000002 | The async function is not called with await. | 2061| 17000004 | The window or component is invisible or destroyed. | 2062| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2063 2064**Example** 2065 2066```ts 2067import { Component, Driver, ON } from '@kit.TestKit'; 2068async function demo() { 2069 let driver: Driver = Driver.create(); 2070 let image: Component = await driver.findComponent(ON.type('Image')); 2071 await image.pinchIn(0.5); 2072} 2073``` 2074 2075### getDescription<sup>11+</sup> 2076 2077getDescription(): Promise\<string> 2078 2079Obtains the description of this component. This API uses a promise to return the result. 2080 2081**Atomic service API**: This API can be used in atomic services since API version 11. 2082 2083**System capability**: SystemCapability.Test.UiTest 2084 2085**Return value** 2086 2087| Type | Description | 2088| ---------------- | --------------------------------- | 2089| Promise\<string> | Promise used to return the description of the component.| 2090 2091**Error codes** 2092 2093For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2094 2095| ID| Error Message | 2096| -------- | ------------------------------------------------------------ | 2097| 17000002 | The async function is not called with await. | 2098| 17000004 | The window or component is invisible or destroyed. | 2099 2100**Example** 2101 2102```ts 2103import { Component, Driver, ON } from '@kit.TestKit'; 2104async function demo() { 2105 let driver: Driver = Driver.create(); 2106 let button: Component = await driver.findComponent(ON.type('Button')); 2107 let description = await button.getDescription(); 2108} 2109``` 2110### getHint<sup>18+</sup> 2111 2112getHint(): Promise\<string> 2113 2114Obtains the hint text of a component. This API uses a promise to return the result. 2115 2116**Atomic service API**: This API can be used in atomic services since API version 18. 2117 2118**System capability**: SystemCapability.Test.UiTest 2119 2120**Return value** 2121 2122| Type | Description | 2123| ---------------- |----------------------| 2124| Promise\<string> | Promise used to return the hint text of a component.| 2125 2126**Error codes** 2127 2128For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2129 2130| ID| Error Message | 2131| -------- | ---------------------------------------- | 2132| 17000002 | The async function is not called with await. | 2133| 17000004 | The window or component is invisible or destroyed. | 2134 2135**Example** 2136 2137```ts 2138import { Component, Driver, ON } from '@kit.TestKit'; 2139async function demo() { 2140 let driver: Driver = Driver.create(); 2141 let button: Component = await driver.findComponent(ON.type('TextInput')); 2142 let hints = await button.getHint(); 2143} 2144``` 2145### getDisplayId<sup>20+</sup> 2146 2147getDisplayId(): Promise\<number> 2148 2149Obtains the ID of the display to which the component belongs. This API uses a promise to return the result. 2150 2151**Atomic service API**: This API can be used in atomic services since API version 20. 2152 2153**System capability**: SystemCapability.Test.UiTest 2154 2155**Return value** 2156 2157| Type | Description | 2158| ---------------- |----------------------| 2159| Promise\<number> | Promise used to return the ID of the display to which the component belongs.| 2160 2161**Error codes** 2162 2163For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2164 2165| ID| Error Message | 2166| -------- | ---------------------------------------- | 2167| 17000002 | The async function is not called with await. | 2168| 17000004 | The window or component is invisible or destroyed. | 2169 2170**Example** 2171 2172```ts 2173import { Component, Driver, ON } from '@kit.TestKit'; 2174 2175async function demo() { 2176 let driver: Driver = Driver.create(); 2177 let button: Component = await driver.findComponent(ON.type('TextInput')); 2178 let displayId = await button.getDisplayId(); 2179} 2180``` 2181 2182### getOriginalText<sup>20+</sup> 2183 2184getOriginalText(): Promise\<string> 2185 2186Obtains the original text information of this component. This API uses a promise to return the result. 2187 2188> **NOTE** 2189> 2190> If the [accessibilityLevel](../apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md#accessibilitylevel) attribute of the component is set to **no** or **no-hide-descendants**, this API can be used to obtain the text information of the component, but [Component.getText()](#gettext9) cannot. 2191 2192**Atomic service API**: This API can be used in atomic services since API version 20. 2193 2194**System capability**: SystemCapability.Test.UiTest 2195 2196**Return value** 2197 2198| Type | Description | 2199| ---------------- | --------------------------------- | 2200| Promise\<string> | Promise used to return the original text information of the component.| 2201 2202**Error codes** 2203 2204For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2205 2206| ID| Error Message | 2207| -------- | ---------------------------------------- | 2208| 17000002 | The async function is not called with await. | 2209| 17000004 | The window or component is invisible or destroyed. | 2210 2211**Example** 2212 2213```ts 2214import { Component, Driver, ON } from '@kit.TestKit'; 2215 2216async function demo() { 2217 let driver: Driver = Driver.create(); 2218 let button: Component = await driver.findComponent(ON.type('Button')); 2219 let text = await button.getOriginalText(); 2220} 2221``` 2222 2223## Driver<sup>9+</sup> 2224 2225The **Driver** class is the main entry to the UiTest framework. It provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. 2226All APIs provided by this class, except **Driver.create()**, use a promise to return the result and must be invoked using **await**. 2227 2228### create<sup>9+</sup> 2229 2230static create(): Driver 2231 2232Creates a **Driver** object and returns the object created. This API is a static API. 2233 2234**Atomic service API**: This API can be used in atomic services since API version 11. 2235 2236**System capability**: SystemCapability.Test.UiTest 2237 2238**Return value** 2239 2240| Type| Description | 2241| -------- | ---------------------- | 2242| Driver | **Driver** object created.| 2243 2244**Error codes** 2245 2246For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2247 2248| ID| Error Message | 2249| -------- | ---------------------- | 2250| 17000001 | Initialization failed. | 2251 2252**Example** 2253 2254```ts 2255import { Driver } from '@kit.TestKit'; 2256async function demo() { 2257 let driver: Driver = Driver.create(); 2258} 2259``` 2260 2261### delayMs<sup>9+</sup> 2262 2263delayMs(duration: number): Promise\<void> 2264 2265Delays within a specified period. This API uses a promise to return the result. 2266 2267**Atomic service API**: This API can be used in atomic services since API version 11. 2268 2269**System capability**: SystemCapability.Test.UiTest 2270 2271**Parameters** 2272 2273| Name | Type | Mandatory| Description | 2274| -------- | ------ | ---- | ------------------------------- | 2275| duration | number | Yes | Specified time, in ms. The value is an integer greater than or equal to 0.| 2276 2277**Return value** 2278 2279| Type | Description | 2280|----------------|-----------------| 2281| Promise\<void> | Promise that returns no value.| 2282 2283**Error codes** 2284 2285For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2286 2287| ID| Error Message | 2288| -------- | ---------------------------------------- | 2289| 17000002 | The async function is not called with await. | 2290| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2291 2292**Example** 2293 2294```ts 2295import { Driver } from '@kit.TestKit'; 2296async function demo() { 2297 let driver: Driver = Driver.create(); 2298 await driver.delayMs(1000); 2299} 2300``` 2301 2302### findComponent<sup>9+</sup> 2303 2304findComponent(on: On): Promise\<Component> 2305 2306Searches for the target component based on the specified attributes. This API uses a promise to return the result. 2307 2308**Atomic service API**: This API can be used in atomic services since API version 11. 2309 2310**System capability**: SystemCapability.Test.UiTest 2311 2312**Parameters** 2313 2314| Name| Type | Mandatory| Description | 2315| ------ | ---------- | ---- | -------------------- | 2316| on | [On](#on9) | Yes | Attributes of the target component.| 2317 2318**Return value** 2319 2320| Type | Description | 2321| ---------------------------------- | --------------------------------- | 2322| Promise\<[Component](#component9)> | Promise used to return the component.| 2323 2324**Error codes** 2325 2326For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2327 2328| ID| Error Message | 2329| -------- | ---------------------------------------- | 2330| 17000002 | The async function is not called with await. | 2331| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2332 2333**Example** 2334 2335```ts 2336import { Component, Driver, ON } from '@kit.TestKit'; 2337async function demo() { 2338 let driver: Driver = Driver.create(); 2339 let button: Component = await driver.findComponent(ON.text('next page')); 2340} 2341``` 2342 2343### findComponents<sup>9+</sup> 2344 2345findComponents(on: On): Promise\<Array\<Component>> 2346 2347Searches for all matched components based on the given attributes and saves them in a list. This API uses a promise to return the result. 2348 2349**Atomic service API**: This API can be used in atomic services since API version 11. 2350 2351**System capability**: SystemCapability.Test.UiTest 2352 2353**Parameters** 2354 2355| Name| Type | Mandatory| Description | 2356| ------ | ---------- | ---- | -------------------- | 2357| on | [On](#on9) | Yes | Attributes of the target component.| 2358 2359**Return value** 2360 2361| Type | Description | 2362| ------------------------------------------ | --------------------------------------- | 2363| Promise\<Array\<[Component](#component9)>> | Promise used to return the list of components.| 2364 2365**Error codes** 2366 2367For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2368 2369| ID| Error Message | 2370| -------- | ---------------------------------------- | 2371| 17000002 | The async function is not called with await. | 2372| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2373 2374**Example** 2375 2376```ts 2377import { Component, Driver, ON } from '@kit.TestKit'; 2378async function demo() { 2379 let driver: Driver = Driver.create(); 2380 let buttonList: Array<Component> = await driver.findComponents(ON.text('next page')); 2381} 2382``` 2383 2384### findWindow<sup>9+</sup> 2385 2386findWindow(filter: WindowFilter): Promise\<UiWindow> 2387 2388Searches for a window based on the attributes. This API uses a promise to return the result. 2389 2390**Atomic service API**: This API can be used in atomic services since API version 11. 2391 2392**System capability**: SystemCapability.Test.UiTest 2393 2394**Parameters** 2395 2396| Name| Type | Mandatory| Description | 2397| ------ | ------------------------------ | ---- | ---------------- | 2398| filter | [WindowFilter](#windowfilter9) | Yes | Attributes of the target window.| 2399 2400**Return value** 2401 2402| Type | Description | 2403| -------------------------------- | ------------------------------------- | 2404| Promise\<[UiWindow](#uiwindow9)> | Promise used to return the target window.| 2405 2406**Error codes** 2407 2408For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2409 2410| ID| Error Message | 2411| -------- | ---------------------------------------- | 2412| 17000002 | The async function is not called with await. | 2413| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2414 2415**Example** 2416 2417```ts 2418import { Driver, UiWindow } from '@kit.TestKit'; 2419async function demo() { 2420 let driver: Driver = Driver.create(); 2421 let window: UiWindow = await driver.findWindow({actived: true}); 2422} 2423``` 2424 2425### waitForComponent<sup>9+</sup> 2426 2427waitForComponent(on: On, time: number): Promise\<Component> 2428 2429Searches for the target component based on the attributes within a specified time. This API uses a promise to return the result. 2430 2431**Atomic service API**: This API can be used in atomic services since API version 11. 2432 2433**System capability**: SystemCapability.Test.UiTest 2434 2435**Parameters** 2436 2437| Name| Type | Mandatory| Description | 2438| ------ | ---------- | ---- | ----------------------------------------- | 2439| on | [On](#on9) | Yes | Attributes of the target component. | 2440| time | number | Yes | Duration for searching for the target component, in ms. The value is an integer greater than or equal to 0.| 2441 2442**Return value** 2443 2444| Type | Description | 2445| --------------------------------- | --------------------------------- | 2446| Promise\<[Component](#component9)> | Promise used to return the component.| 2447 2448**Error codes** 2449 2450For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2451 2452| ID| Error Message | 2453| -------- | ---------------------------------------- | 2454| 17000002 | The async function is not called with await. | 2455| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2456 2457**Example** 2458 2459```ts 2460import { Component, Driver, ON } from '@kit.TestKit'; 2461async function demo() { 2462 let driver: Driver = Driver.create(); 2463 let button: Component = await driver.waitForComponent(ON.text('next page'),500); 2464} 2465``` 2466 2467### assertComponentExist<sup>9+</sup> 2468 2469assertComponentExist(on: On): Promise\<void> 2470 2471Asserts whether a component matches the specified attributes exists on the current page. This API uses a promise to return the result. 2472 2473**Atomic service API**: This API can be used in atomic services since API version 11. 2474 2475**System capability**: SystemCapability.Test.UiTest 2476 2477**Parameters** 2478 2479| Name| Type | Mandatory| Description | 2480| ------ | ---------- | ---- | -------------------- | 2481| on | [On](#on9) | Yes | Attributes of the target component.| 2482 2483**Return value** 2484 2485| Type | Description | 2486|----------------|-----------------| 2487| Promise\<void> | Promise that returns no value.| 2488 2489**Error codes** 2490 2491For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2492 2493| ID| Error Message | 2494| -------- | ---------------------------------------- | 2495| 17000002 | The async function is not called with await. | 2496| 17000003 | Assertion failed. | 2497| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2498 2499**Example** 2500 2501```ts 2502import { Driver, ON } from '@kit.TestKit'; 2503async function demo() { 2504 let driver: Driver = Driver.create(); 2505 await driver.assertComponentExist(ON.text('next page')); 2506} 2507``` 2508 2509### pressBack<sup>9+</sup> 2510 2511pressBack(): Promise\<void> 2512 2513Presses the BACK button. This API uses a promise to return the result. 2514 2515**Atomic service API**: This API can be used in atomic services since API version 11. 2516 2517**System capability**: SystemCapability.Test.UiTest 2518 2519**Return value** 2520 2521| Type | Description | 2522|----------------|-----------------| 2523| Promise\<void> | Promise that returns no value.| 2524 2525**Error codes** 2526 2527For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2528 2529| ID| Error Message | 2530| -------- | ---------------------------------------- | 2531| 17000002 | The async function is not called with await. | 2532 2533**Example** 2534 2535```ts 2536import { Driver } from '@kit.TestKit'; 2537async function demo() { 2538 let driver: Driver = Driver.create(); 2539 await driver.pressBack(); 2540} 2541``` 2542 2543### pressBack<sup>20+</sup> 2544 2545pressBack(displayId: number): Promise\<void> 2546 2547Presses the **BACK** button on a specified display. This API uses a promise to return the result. 2548 2549**Atomic service API**: This API can be used in atomic services since API version 20. 2550 2551**System capability**: SystemCapability.Test.UiTest 2552 2553**Parameters** 2554 2555| Name | Type | Mandatory| Description | 2556| ------- | ------ | ---- | ------------- | 2557| displayId | number | Yes | Display ID. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. | 2558 2559**Return value** 2560 2561| Type | Description | 2562|----------------|-----------------| 2563| Promise\<void> | Promise that returns no value.| 2564 2565**Error codes** 2566 2567For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2568 2569| ID| Error Message | 2570| -------- | ---------------------------------------- | 2571| 17000002 | The async function is not called with await. | 2572| 17000007 | Parameter verification failed. | 2573 2574**Example** 2575 2576```ts 2577import { Driver } from '@kit.TestKit'; 2578async function demo() { 2579 let driver: Driver = Driver.create(); 2580 await driver.pressBack(0); 2581} 2582``` 2583 2584### triggerKey<sup>9+</sup> 2585 2586triggerKey(keyCode: number): Promise\<void> 2587 2588Triggers a key event based on the key value. This API uses a promise to return the result. 2589 2590**Atomic service API**: This API can be used in atomic services since API version 11. 2591 2592**System capability**: SystemCapability.Test.UiTest 2593 2594**Parameters** 2595 2596| Name | Type | Mandatory| Description | 2597| ------- | ------ | ---- | ------------- | 2598| keyCode | number | Yes | Key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode).| 2599 2600**Return value** 2601 2602| Type | Description | 2603|----------------|-----------------| 2604| Promise\<void> | Promise that returns no value.| 2605 2606**Error codes** 2607 2608For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2609 2610| ID| Error Message | 2611| -------- | ---------------------------------------- | 2612| 17000002 | The async function is not called with await. | 2613| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2614 2615**Example** 2616 2617```ts 2618import { Driver } from '@kit.TestKit'; 2619async function demo() { 2620 let driver: Driver = Driver.create(); 2621 await driver.triggerKey(123); 2622} 2623``` 2624 2625### triggerKey<sup>20+</sup> 2626 2627triggerKey(keyCode: number, displayId: number): Promise\<void> 2628 2629Triggers a key event on the specified display based on the key value. This API uses a promise to return the result. 2630 2631**Atomic service API**: This API can be used in atomic services since API version 20. 2632 2633**System capability**: SystemCapability.Test.UiTest 2634 2635**Parameters** 2636 2637| Name | Type | Mandatory| Description | 2638| ------- | ------ | ---- | ------------- | 2639| keyCode | number | Yes | Key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode).| 2640| displayId | number | Yes | Display ID. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. | 2641 2642**Return value** 2643 2644| Type | Description | 2645|----------------|-----------------| 2646| Promise\<void> | Promise that returns no value.| 2647 2648**Error codes** 2649 2650For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2651 2652| ID| Error Message | 2653| -------- | ---------------------------------------- | 2654| 17000002 | The async function is not called with await. | 2655| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2656 2657**Example** 2658 2659```ts 2660import { Driver } from '@kit.TestKit'; 2661 2662async function demo() { 2663 let driver: Driver = Driver.create(); 2664 await driver.triggerKey(123, 0); 2665} 2666``` 2667 2668### triggerCombineKeys<sup>9+</sup> 2669 2670triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\<void> 2671 2672Triggers a combination key event based on the specified key values. This API uses a promise to return the result. For example, if the value of **Key** is (2072, 2019), the combination key that matches the value is found and clicked, for example, **Ctrl+C**. 2673 2674**Atomic service API**: This API can be used in atomic services since API version 11. 2675 2676**System capability**: SystemCapability.Test.UiTest 2677 2678**Parameters** 2679 2680| Name| Type | Mandatory| Description | 2681| ------ | ------ | ---- | ------------------------------ | 2682| key0 | number | Yes | First key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). | 2683| key1 | number | Yes | Second key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). | 2684| key2 | number | No | Third key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 2685 2686**Return value** 2687 2688| Type | Description | 2689|----------------|-----------------| 2690| Promise\<void> | Promise that returns no value.| 2691 2692**Error codes** 2693 2694For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2695 2696| ID| Error Message | 2697| -------- | ---------------------------------------- | 2698| 17000002 | The async function is not called with await. | 2699| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2700 2701**Example** 2702 2703```ts 2704import { Driver } from '@kit.TestKit'; 2705async function demo() { 2706 let driver: Driver = Driver.create(); 2707 await driver.triggerCombineKeys(2072, 2047, 2035); 2708} 2709``` 2710 2711### triggerCombineKeys<sup>20+</sup> 2712 2713triggerCombineKeys(key0: number, key1: number, key2?: number, displayId?: number): Promise\<void> 2714 2715Triggers a combination key event on the specified display based on the specified key values. This API uses a promise to return the result. For example, if the value of **Key** is (2072, 2019), the combination key that matches the value is found and clicked, for example, **Ctrl+C**. 2716 2717**Atomic service API**: This API can be used in atomic services since API version 20. 2718 2719**System capability**: SystemCapability.Test.UiTest 2720 2721**Parameters** 2722 2723| Name| Type | Mandatory| Description | 2724| ------ | ------ | ---- | ------------------------------ | 2725| key0 | number | Yes | First key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). | 2726| key1 | number | Yes | Second key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). | 2727| key2 | number | No | Third key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 2728| displayId | number | No | Display ID. The value is an integer greater than or equal to 0. The default value is the default display ID of the device.| 2729 2730**Return value** 2731 2732| Type | Description | 2733|----------------|-----------------| 2734| Promise\<void> | Promise that returns no value.| 2735 2736**Error codes** 2737 2738For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2739 2740| ID| Error Message | 2741| -------- | ---------------------------------------- | 2742| 17000002 | The async function is not called with await. | 2743| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2744 2745**Example** 2746 2747```ts 2748import { Driver } from '@kit.TestKit'; 2749 2750async function demo() { 2751 let driver: Driver = Driver.create(); 2752 await driver.triggerCombineKeys(2072, 2047, 2035, 0); 2753} 2754``` 2755 2756### click<sup>9+</sup> 2757 2758click(x: number, y: number): Promise\<void> 2759 2760Clicks the target coordinate. This API uses a promise to return the result. 2761 2762**Atomic service API**: This API can be used in atomic services since API version 11. 2763 2764**System capability**: SystemCapability.Test.UiTest 2765 2766**Parameters** 2767 2768| Name| Type | Mandatory| Description | 2769| ------ | ------ | ---- | ----------------------------------------------- | 2770| x | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.| 2771| y | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.| 2772 2773**Return value** 2774 2775| Type | Description | 2776|----------------|-----------------| 2777| Promise\<void> | Promise that returns no value.| 2778 2779**Error codes** 2780 2781For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2782 2783| ID| Error Message | 2784| -------- | ---------------------------------------- | 2785| 17000002 | The async function is not called with await. | 2786| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2787 2788**Example** 2789 2790```ts 2791import { Driver } from '@kit.TestKit'; 2792async function demo() { 2793 let driver: Driver = Driver.create(); 2794 await driver.click(100,100); 2795} 2796``` 2797 2798### clickAt<sup>20+</sup> 2799 2800clickAt(point: Point): Promise\<void> 2801 2802Clicks the target coordinate point. This API uses a promise to return the result. 2803 2804**Atomic service API**: This API can be used in atomic services since API version 20. 2805 2806**System capability**: SystemCapability.Test.UiTest 2807 2808**Parameters** 2809 2810| Name| Type | Mandatory| Description | 2811| ------ | ------ | ---- | ----------------------------------------------- | 2812| point | [Point](#point9) | Yes | Point object, which is used to transfer the target point information.| 2813 2814**Return value** 2815 2816| Type | Description | 2817|----------------|-----------------| 2818| Promise\<void> | Promise that returns no value.| 2819 2820**Error codes** 2821 2822For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2823 2824| ID| Error Message | 2825| -------- | ---------------------------------------- | 2826| 17000002 | The async function is not called with await. | 2827| 17000007 | Parameter verification failed. | 2828 2829**Example** 2830 2831```ts 2832import { Driver } from '@kit.TestKit'; 2833 2834async function demo() { 2835 let driver: Driver = Driver.create(); 2836 await driver.clickAt({ x: 100, y: 100, displayId: 0 }); 2837} 2838``` 2839 2840### doubleClick<sup>9+</sup> 2841 2842doubleClick(x: number, y: number): Promise\<void> 2843 2844Double-clicks the target point. This API uses a promise to return the result. 2845 2846**Atomic service API**: This API can be used in atomic services since API version 11. 2847 2848**System capability**: SystemCapability.Test.UiTest 2849 2850**Parameters** 2851 2852| Name| Type | Mandatory| Description | 2853| ------ | ------ | ---- | ----------------------------------------------- | 2854| x | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.| 2855| y | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.| 2856 2857**Return value** 2858 2859| Type | Description | 2860|----------------|-----------------| 2861| Promise\<void> | Promise that returns no value.| 2862 2863**Error codes** 2864 2865For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2866 2867| ID| Error Message | 2868| -------- | ---------------------------------------- | 2869| 17000002 | The async function is not called with await. | 2870| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2871 2872**Example** 2873 2874```ts 2875import { Driver } from '@kit.TestKit'; 2876async function demo() { 2877 let driver: Driver = Driver.create(); 2878 await driver.doubleClick(100,100); 2879} 2880``` 2881 2882### doubleClickAt<sup>20+</sup> 2883 2884doubleClickAt(point: Point): Promise\<void> 2885 2886Double-clicks the target coordinate point. This API uses a promise to return the result. 2887 2888**Atomic service API**: This API can be used in atomic services since API version 20. 2889 2890**System capability**: SystemCapability.Test.UiTest 2891 2892**Parameters** 2893 2894| Name| Type | Mandatory| Description | 2895| ------ | ------ | ---- | ----------------------------------------------- | 2896| point | [Point](#point9) | Yes | Point object, which is used to transfer the target point information.| 2897 2898**Return value** 2899 2900| Type | Description | 2901|----------------|-----------------| 2902| Promise\<void> | Promise that returns no value.| 2903 2904**Error codes** 2905 2906For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2907 2908| ID| Error Message | 2909| -------- | ---------------------------------------- | 2910| 17000002 | The async function is not called with await. | 2911| 17000007 | Parameter verification failed. | 2912 2913**Example** 2914 2915```ts 2916import { Driver } from '@kit.TestKit'; 2917 2918async function demo() { 2919 let driver: Driver = Driver.create(); 2920 await driver.doubleClickAt({ x: 100, y: 100, displayId: 0 }); 2921} 2922``` 2923 2924### longClick<sup>9+</sup> 2925 2926longClick(x: number, y: number): Promise\<void> 2927 2928Long-clicks the target point. This API uses a promise to return the result. 2929 2930**Atomic service API**: This API can be used in atomic services since API version 11. 2931 2932**System capability**: SystemCapability.Test.UiTest 2933 2934**Parameters** 2935 2936| Name| Type | Mandatory| Description | 2937| ------ | ------ | ---- | ----------------------------------------------- | 2938| x | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.| 2939| y | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.| 2940 2941**Return value** 2942 2943| Type | Description | 2944|----------------|-----------------| 2945| Promise\<void> | Promise that returns no value.| 2946 2947**Error codes** 2948 2949For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 2950 2951| ID| Error Message | 2952| -------- | ---------------------------------------- | 2953| 17000002 | The async function is not called with await. | 2954| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2955 2956**Example** 2957 2958```ts 2959import { Driver } from '@kit.TestKit'; 2960async function demo() { 2961 let driver: Driver = Driver.create(); 2962 await driver.longClick(100,100); 2963} 2964``` 2965 2966### longClickAt<sup>20+</sup> 2967 2968longClickAt(point: Point, duration?: number): Promise\<void> 2969 2970Long-clicks the target coordinate point for a specified duration. This promise uses a promise to return the result. 2971 2972**Atomic service API**: This API can be used in atomic services since API version 20. 2973 2974**System capability**: SystemCapability.Test.UiTest 2975 2976**Parameters** 2977 2978| Name| Type | Mandatory| Description | 2979| ------ | ------ | ---- | ----------------------------------------------- | 2980| point | [Point](#point9) | Yes | Point object, which is used to transfer the target point information.| 2981| duration | number | No | Long-click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.| 2982 2983**Return value** 2984 2985| Type | Description | 2986|----------------|-----------------| 2987| Promise\<void> | Promise that returns no value.| 2988 2989**Error codes** 2990 2991For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2992 2993| ID| Error Message | 2994| -------- | ---------------------------------------- | 2995| 17000002 | The async function is not called with await. | 2996| 17000007 | Parameter verification failed. | 2997 2998**Example** 2999 3000```ts 3001import { Driver } from '@kit.TestKit'; 3002 3003async function demo() { 3004 let driver: Driver = Driver.create(); 3005 await driver.longClickAt({ x: 100, y: 100, displayId: 0 }, 1500); 3006} 3007``` 3008 3009### swipe<sup>9+</sup> 3010 3011swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 3012 3013Swipes from the start coordinate point to the target coordinate point. This API uses a promise to return the result. 3014 3015**Atomic service API**: This API can be used in atomic services since API version 11. 3016 3017**System capability**: SystemCapability.Test.UiTest 3018 3019**Parameters** 3020 3021| Name| Type | Mandatory| Description | 3022| ------ | ------ | ---- |------------------------------------------------------| 3023| startx | number | Yes | Number, which indicates the horizontal coordinate of the start point. The value is an integer greater than or equal to 0. | 3024| starty | number | Yes | Number, which indicates the vertical coordinate of the start point. The value is an integer greater than or equal to 0. | 3025| endx | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0. | 3026| endy | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0. | 3027| speed | number | No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 3028 3029**Return value** 3030 3031| Type | Description | 3032|----------------|-----------------| 3033| Promise\<void> | Promise that returns no value.| 3034 3035**Error codes** 3036 3037For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3038 3039| ID| Error Message | 3040| -------- | ---------------------------------------- | 3041| 17000002 | The async function is not called with await. | 3042| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3043 3044**Example** 3045 3046```ts 3047import { Driver } from '@kit.TestKit'; 3048async function demo() { 3049 let driver: Driver = Driver.create(); 3050 await driver.swipe(100,100,200,200,600); 3051} 3052``` 3053 3054### swipeBetween<sup>20+</sup> 3055 3056swipeBetween(from: Point, to: Point, speed?: number): Promise\<void> 3057 3058Swipes from the start coordinate point to the target coordinate point. This API uses a promise to return the result. 3059 3060**Atomic service API**: This API can be used in atomic services since API version 20. 3061 3062**System capability**: SystemCapability.Test.UiTest 3063 3064**Parameters** 3065 3066| Name| Type | Mandatory| Description | 3067| ------ | ------ | ---- |------------------------------------------------------| 3068| from | [Point](#point9) | Yes | Point object, which transfers the coordinates of the start point and the ID of the display to which the start point belongs. | 3069| to | [Point](#point9) | Yes | Point object, which transfers the coordinates of the target point and the ID of the display to which it belongs.<br> **Note**: The target point and the start point must be on the same screen. Otherwise, the **17000007** exception is thrown. | 3070| speed | number | No | Swipe speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 3071 3072**Return value** 3073 3074| Type | Description | 3075|----------------|-----------------| 3076| Promise\<void> | Promise that returns no value.| 3077 3078**Error codes** 3079 3080For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3081 3082| ID| Error Message | 3083| -------- | ---------------------------------------- | 3084| 17000002 | The async function is not called with await. | 3085| 17000007 | Parameter verification failed. | 3086 3087**Example** 3088 3089```ts 3090import { Driver } from '@kit.TestKit'; 3091 3092async function demo() { 3093 let driver: Driver = Driver.create(); 3094 await driver.swipeBetween({x: 100, y: 100, displayId: 0}, {x: 1000, y: 1000, displayId: 0}, 800); 3095} 3096``` 3097 3098### drag<sup>9+</sup> 3099 3100drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 3101 3102Drags from the start coordinate point to the target coordinate point. This API uses a promise to return the result. 3103 3104> **NOTE** 3105> 3106> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 3107 3108**Atomic service API**: This API can be used in atomic services since API version 11. 3109 3110**System capability**: SystemCapability.Test.UiTest 3111 3112**Parameters** 3113 3114| Name| Type | Mandatory| Description | 3115| ------ | ------ | ---- | ------------------------------------------------------------ | 3116| startx | number | Yes | Number, which indicates the horizontal coordinate of the start point. The value is an integer greater than or equal to 0. | 3117| starty | number | Yes | Number, which indicates the vertical coordinate of the start point. The value is an integer greater than or equal to 0. | 3118| endx | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0. | 3119| endy | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0. | 3120| speed | number | No | Drag speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 3121 3122**Return value** 3123 3124| Type | Description | 3125|----------------|-----------------| 3126| Promise\<void> | Promise that returns no value.| 3127 3128**Error codes** 3129 3130For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3131 3132| ID| Error Message | 3133| -------- | ---------------------------------------- | 3134| 17000002 | The async function is not called with await. | 3135| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3136 3137**Example** 3138 3139```ts 3140import { Driver } from '@kit.TestKit'; 3141 3142async function demo() { 3143 let driver: Driver = Driver.create(); 3144 await driver.drag(100, 100, 200, 200, 600); 3145} 3146``` 3147 3148### dragBetween<sup>20+</sup> 3149 3150dragBetween(from: Point, to: Point, speed?: number, duration?: number): Promise\<void> 3151 3152Drags from the start point to the target point. You can specify the drag speed and the click duration before dragging. This API uses a promise to return the result. 3153 3154> **NOTE** 3155> 3156> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 3157 3158**Atomic service API**: This API can be used in atomic services since API version 20. 3159 3160**System capability**: SystemCapability.Test.UiTest 3161 3162**Parameters** 3163 3164| Name| Type | Mandatory| Description | 3165| ------ | ------ | ---- |--------------------------------------------------------| 3166| from | [Point](#point9) | Yes | Point object, which transfers the coordinates of the start point and the ID of the display to which the start point belongs. | 3167| to | [Point](#point9) | Yes | Point object, which transfers the coordinates of the target point and the ID of the display to which it belongs.<br> **Note**: The target point and the start point must be on the same screen. Otherwise, the **17000007** exception is thrown. | 3168| speed | number | No | Drag speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 3169| duration | number | No | Click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.| 3170 3171**Return value** 3172 3173| Type | Description | 3174|----------------|-----------------| 3175| Promise\<void> | Promise that returns no value.| 3176 3177**Error codes** 3178 3179For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3180 3181| ID| Error Message | 3182| -------- | ---------------------------------------- | 3183| 17000002 | The async function is not called with await. | 3184| 17000007 | Parameter verification failed. | 3185 3186**Example** 3187 3188```ts 3189import { Driver } from '@kit.TestKit'; 3190 3191async function demo() { 3192 let driver: Driver = Driver.create(); 3193 await driver.dragBetween( {x: 100, y: 100, displayId: 0}, {x: 1000, y: 1000, displayId: 0}, 800, 1500); 3194} 3195``` 3196 3197### screenCap<sup>9+</sup> 3198 3199screenCap(savePath: string): Promise\<boolean> 3200 3201Captures the current screen and saves it as a PNG image to the specified path. This API uses a promise to return the result. This API can be used in scenarios where screenshots are supported. 3202 3203**Atomic service API**: This API can be used in atomic services since API version 11. 3204 3205**System capability**: SystemCapability.Test.UiTest 3206 3207**Parameters** 3208 3209| Name | Type | Mandatory| Description | 3210| -------- | ------ | ---- | ------------------------------------------ | 3211| savePath | string | Yes | File save path. The path must be the [sandbox path](../../file-management/app-sandbox-directory.md) of the current application.| 3212 3213**Return value** 3214 3215| Type | Description | 3216| ----------------- |-------------------------------------------| 3217| Promise\<boolean> | Promise used to return whether the screenshot operation is successful. The value **true** indicates that the screen capture operation is successful, and **false** indicates the opposite.| 3218 3219**Error codes** 3220 3221For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3222 3223| ID| Error Message | 3224| -------- | ---------------------------------------- | 3225| 17000002 | The async function is not called with await. | 3226| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3227 3228**Example** 3229 3230```ts 3231import { Driver } from '@kit.TestKit'; 3232async function demo() { 3233 let driver: Driver = Driver.create(); 3234 await driver.screenCap('/data/storage/el2/base/cache/1.png'); 3235} 3236``` 3237 3238### screenCap<sup>20+</sup> 3239 3240screenCap(savePath: string, displayId: number): Promise\<boolean> 3241 3242Captures the specified screen and saves it as a PNG image to the specified path. This API uses a promise to return the result. This API can be used in scenarios where screenshots are supported. 3243 3244**Atomic service API**: This API can be used in atomic services since API version 20. 3245 3246**System capability**: SystemCapability.Test.UiTest 3247 3248**Parameters** 3249 3250| Name | Type | Mandatory| Description | 3251| -------- | ------ | ---- | ------------------------------------------ | 3252| savePath | string | Yes | File save path. The path must be the [sandbox path](../../file-management/app-sandbox-directory.md) of the current application.| 3253| displayId | number | Yes | Display ID. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. | 3254 3255**Return value** 3256 3257| Type | Description | 3258| ----------------- |-------------------------------------------| 3259| Promise\<boolean> | Promise used to return whether the screenshot operation is successful. The value **true** indicates that the screen capture operation is successful, and **false** indicates the opposite.| 3260 3261**Error codes** 3262 3263For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3264 3265| ID| Error Message | 3266| -------- | ---------------------------------------- | 3267| 17000002 | The async function is not called with await. | 3268| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3269 3270**Example** 3271 3272```ts 3273import { Driver } from '@kit.TestKit'; 3274 3275async function demo() { 3276 let driver: Driver = Driver.create(); 3277 await driver.screenCap('/data/storage/el2/base/cache/1.png', 0); 3278} 3279``` 3280 3281### setDisplayRotation<sup>9+</sup> 3282 3283setDisplayRotation(rotation: DisplayRotation): Promise\<void> 3284 3285Sets the display rotation of the current scene to the specified direction. This API uses a promise to return the result. It applies to rotatable scenarios. 3286 3287> **NOTE** 3288> 3289> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 3290 3291**Atomic service API**: This API can be used in atomic services since API version 11. 3292 3293**System capability**: SystemCapability.Test.UiTest 3294 3295**Parameters** 3296 3297| Name | Type | Mandatory| Description | 3298| -------- | ------------------------------------ | ---- | ---------------- | 3299| rotation | [DisplayRotation](#displayrotation9) | Yes | Display rotation of the device.| 3300 3301**Return value** 3302 3303| Type | Description | 3304|----------------|-----------------| 3305| Promise\<void> | Promise that returns no value.| 3306 3307**Error codes** 3308 3309For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3310 3311| ID| Error Message | 3312| -------- | ---------------------------------------- | 3313| 17000002 | The async function is not called with await. | 3314| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3315 3316**Example** 3317 3318```ts 3319import { Driver, DisplayRotation } from '@kit.TestKit'; 3320async function demo() { 3321 let driver: Driver = Driver.create(); 3322 await driver.setDisplayRotation(DisplayRotation.ROTATION_180); 3323} 3324``` 3325 3326### getDisplayRotation<sup>9+</sup> 3327 3328getDisplayRotation(): Promise\<DisplayRotation> 3329 3330Obtains the display rotation of the current device. This API uses a promise to return the result. 3331 3332**Atomic service API**: This API can be used in atomic services since API version 11. 3333 3334**System capability**: SystemCapability.Test.UiTest 3335 3336**Return value** 3337 3338| Type | Description | 3339| ---------------------------------------------- | --------------------------------------- | 3340| Promise\<[DisplayRotation](#displayrotation9)> | Promise used to return the display rotation of the current device.| 3341 3342**Error codes** 3343 3344For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3345 3346| ID| Error Message | 3347| -------- | ---------------------------------------- | 3348| 17000002 | The async function is not called with await. | 3349 3350**Example** 3351 3352```ts 3353import { DisplayRotation, Driver } from '@kit.TestKit'; 3354async function demo() { 3355 let driver: Driver = Driver.create(); 3356 let rotation: DisplayRotation = await driver.getDisplayRotation(); 3357} 3358``` 3359 3360### getDisplayRotation<sup>20+</sup> 3361 3362getDisplayRotation(displayId: number): Promise\<DisplayRotation> 3363 3364Obtains the display rotation of the specified device. This API uses a promise to return the result. 3365 3366**Atomic service API**: This API can be used in atomic services since API version 20. 3367 3368**System capability**: SystemCapability.Test.UiTest 3369 3370**Parameters** 3371 3372| Name | Type | Mandatory| Description | 3373| -------- | ------ | ---- | ------------------------------------------ | 3374| displayId | number | Yes | Display ID. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. | 3375 3376**Return value** 3377 3378| Type | Description | 3379| ---------------------------------------------- | --------------------------------------- | 3380| Promise\<[DisplayRotation](#displayrotation9)> | Promise used to return the display rotation of the specified device.| 3381 3382**Error codes** 3383 3384For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3385 3386| ID| Error Message | 3387| -------- | ---------------------------------------- | 3388| 17000002 | The async function is not called with await. | 3389| 17000007 | Parameter verification failed. | 3390 3391**Example** 3392 3393```ts 3394import { DisplayRotation, Driver } from '@kit.TestKit'; 3395 3396async function demo() { 3397 let driver: Driver = Driver.create(); 3398 let rotation: DisplayRotation = await driver.getDisplayRotation(0); 3399} 3400``` 3401 3402### setDisplayRotationEnabled<sup>9+</sup> 3403 3404setDisplayRotationEnabled(enabled: boolean): Promise\<void> 3405 3406Sets whether to enable the screen rotation feature. This API uses a promise to return the result. 3407 3408> **NOTE** 3409> 3410> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 3411 3412**Atomic service API**: This API can be used in atomic services since API version 11. 3413 3414**System capability**: SystemCapability.Test.UiTest 3415 3416**Parameters** 3417 3418| Name | Type | Mandatory| Description | 3419| ------- | ------- | ---- | ------------------------------------------------------- | 3420| enabled | boolean | Yes | Whether the screen can be rotated. The value **true** indicates that the screen can be rotated, and **false** indicates the opposite.| 3421 3422**Return value** 3423 3424| Type | Description | 3425|----------------|-----------------| 3426| Promise\<void> | Promise that returns no value.| 3427 3428**Error codes** 3429 3430For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3431 3432| ID| Error Message | 3433| -------- | ---------------------------------------- | 3434| 17000002 | The async function is not called with await. | 3435| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3436 3437**Example** 3438 3439```ts 3440import { Driver } from '@kit.TestKit'; 3441async function demo() { 3442 let driver: Driver = Driver.create(); 3443 await driver.setDisplayRotationEnabled(false); 3444} 3445``` 3446 3447### getDisplaySize<sup>9+</sup> 3448 3449getDisplaySize(): Promise\<Point> 3450 3451Obtains the display size of the current device. This API uses a promise to return the result. 3452 3453**Atomic service API**: This API can be used in atomic services since API version 11. 3454 3455**System capability**: SystemCapability.Test.UiTest 3456 3457**Return value** 3458 3459| Type | Description | 3460| -------------------------- | --------------------------------------- | 3461| Promise\<[Point](#point9)> | Promise used to return the **Point** object. The size of the current device screen is **Point.x * Point.y**.| 3462 3463**Error codes** 3464 3465For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3466 3467| ID| Error Message | 3468| -------- | ---------------------------------------- | 3469| 17000002 | The async function is not called with await. | 3470 3471**Example** 3472 3473```ts 3474import { Driver } from '@kit.TestKit'; 3475 3476async function demo() { 3477 let driver: Driver = Driver.create(); 3478 let size = await driver.getDisplaySize(); 3479} 3480``` 3481 3482### getDisplaySize<sup>20+</sup> 3483 3484getDisplaySize(displayId: number): Promise\<Point> 3485 3486Obtains the size of the specified display of the current device. This API uses a promise to return the result. 3487 3488**Atomic service API**: This API can be used in atomic services since API version 20. 3489 3490**System capability**: SystemCapability.Test.UiTest 3491 3492**Parameters** 3493 3494| Name | Type | Mandatory| Description | 3495| -------- | ------ | ---- | ------------------------------------------ | 3496| displayId | number | Yes | Display ID. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. | 3497 3498**Return value** 3499 3500| Type | Description | 3501| -------------------------- | --------------------------------------- | 3502| Promise\<[Point](#point9)> | Promise used to return the **Point** object. The size of the specified display is **Point.x * Point.y**.| 3503 3504**Error codes** 3505 3506For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3507 3508| ID| Error Message | 3509| -------- | ---------------------------------------- | 3510| 17000002 | The async function is not called with await. | 3511| 17000007 | Parameter verification failed. | 3512 3513**Example** 3514 3515```ts 3516import { Driver } from '@kit.TestKit'; 3517 3518async function demo() { 3519 let driver: Driver = Driver.create(); 3520 let size = await driver.getDisplaySize(0); 3521} 3522``` 3523 3524### getDisplayDensity<sup>9+</sup> 3525 3526getDisplayDensity(): Promise\<Point> 3527 3528Obtains the display density of the current device. This API uses a promise to return the result. 3529 3530**Atomic service API**: This API can be used in atomic services since API version 11. 3531 3532**System capability**: SystemCapability.Test.UiTest 3533 3534**Return value** 3535 3536| Type | Description | 3537| -------------------------- | ----------------------------------------- | 3538| Promise\<[Point](#point9)> | Promise used to return the **Point** object. The density of the current device display is **Point.x*Point.y**.| 3539 3540**Error codes** 3541 3542For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3543 3544| ID| Error Message | 3545| -------- | ---------------------------------------- | 3546| 17000002 | The async function is not called with await. | 3547 3548**Example** 3549 3550```ts 3551import { Driver } from '@kit.TestKit'; 3552async function demo() { 3553 let driver: Driver = Driver.create(); 3554 let density = await driver.getDisplayDensity(); 3555} 3556``` 3557 3558### getDisplayDensity<sup>20+</sup> 3559 3560getDisplayDensity(displayId: number): Promise\<Point> 3561 3562Obtains the density of the specified display of the current device. This API uses a promise to return the result. 3563 3564**Atomic service API**: This API can be used in atomic services since API version 20. 3565 3566**System capability**: SystemCapability.Test.UiTest 3567 3568**Parameters** 3569 3570| Name | Type | Mandatory| Description | 3571| -------- | ------ | ---- | ------------------------------------------ | 3572| displayId | number | Yes | Display ID. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. | 3573 3574**Return value** 3575 3576| Type | Description | 3577| -------------------------- | ----------------------------------------- | 3578| Promise\<[Point](#point9)> | Promise used to return the **Point** object. The density of the specified display is **Point.x*Point.y**.| 3579 3580**Error codes** 3581 3582For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3583 3584| ID| Error Message | 3585| -------- | ---------------------------------------- | 3586| 17000002 | The async function is not called with await. | 3587| 17000007 | Parameter verification failed. | 3588 3589**Example** 3590 3591```ts 3592import { Driver } from '@kit.TestKit'; 3593 3594async function demo() { 3595 let driver: Driver = Driver.create(); 3596 let density = await driver.getDisplayDensity(0); 3597} 3598``` 3599 3600### wakeUpDisplay<sup>9+</sup> 3601 3602wakeUpDisplay(): Promise\<void> 3603 3604Wakes up the current display. This API uses a promise to return the result. 3605 3606**Atomic service API**: This API can be used in atomic services since API version 11. 3607 3608**System capability**: SystemCapability.Test.UiTest 3609 3610**Return value** 3611 3612| Type | Description | 3613|----------------|-----------------| 3614| Promise\<void> | Promise that returns no value.| 3615 3616**Error codes** 3617 3618For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3619 3620| ID| Error Message | 3621| -------- | ---------------------------------------- | 3622| 17000002 | The async function is not called with await. | 3623 3624**Example** 3625 3626```ts 3627import { Driver } from '@kit.TestKit'; 3628async function demo() { 3629 let driver: Driver = Driver.create(); 3630 await driver.wakeUpDisplay(); 3631} 3632``` 3633 3634### pressHome<sup>9+</sup> 3635 3636pressHome(): Promise\<void> 3637 3638Injects an operation of returning to the home screen on the device. This API uses a promise to return the result. 3639 3640> **NOTE** 3641> 3642> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 3643 3644**Atomic service API**: This API can be used in atomic services since API version 11. 3645 3646**System capability**: SystemCapability.Test.UiTest 3647 3648**Return value** 3649 3650| Type | Description | 3651|----------------|-----------------| 3652| Promise\<void> | Promise that returns no value.| 3653 3654**Error codes** 3655 3656For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3657 3658| ID| Error Message | 3659| -------- | ---------------------------------------- | 3660| 17000002 | The async function is not called with await. | 3661 3662**Example** 3663 3664```ts 3665import { Driver } from '@kit.TestKit'; 3666async function demo() { 3667 let driver: Driver = Driver.create(); 3668 await driver.pressHome(); 3669} 3670``` 3671 3672### pressHome<sup>20+</sup> 3673 3674pressHome(displayId: number): Promise\<void> 3675 3676Injects the operation of returning to the home screen on the specified display. This API uses a promise to return the result. 3677 3678> **NOTE** 3679> 3680> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 3681 3682**Atomic service API**: This API can be used in atomic services since API version 20. 3683 3684**System capability**: SystemCapability.Test.UiTest 3685 3686**Parameters** 3687 3688| Name | Type | Mandatory| Description | 3689| -------- | ------ | ---- | ------------------------------------------ | 3690| displayId | number | Yes | Display ID. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. | 3691 3692**Return value** 3693 3694| Type | Description | 3695|----------------|-----------------| 3696| Promise\<void> | Promise that returns no value.| 3697 3698**Error codes** 3699 3700For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3701 3702| ID| Error Message | 3703| -------- | ---------------------------------------- | 3704| 17000002 | The async function is not called with await. | 3705| 17000007 | Parameter verification failed. | 3706 3707**Example** 3708 3709```ts 3710import { Driver } from '@kit.TestKit'; 3711 3712async function demo() { 3713 let driver: Driver = Driver.create(); 3714 await driver.pressHome(0); 3715} 3716``` 3717 3718### waitForIdle<sup>9+</sup> 3719 3720waitForIdle(idleTime: number, timeout: number): Promise\<boolean> 3721 3722Checks whether all components on the current page are idle. This API uses a promise to return the result. 3723 3724**Atomic service API**: This API can be used in atomic services since API version 11. 3725 3726**System capability**: SystemCapability.Test.UiTest 3727 3728**Parameters** 3729 3730| Name | Type | Mandatory| Description | 3731| -------- | ------ | ---- | ------------------------------------------------------------ | 3732| idleTime | number | Yes | Idle time threshold, in ms. If the duration for which a component remains inactive reaches this threshold, it is considered as idle. The value must be an integer greater than or equal to 0.| 3733| timeout | number | Yes | Maximum waiting time, in milliseconds. The value is an integer greater than or equal to 0. | 3734 3735**Return value** 3736 3737| Type | Description | 3738| ----------------- |---------------------------------------------------| 3739| Promise\<boolean> | Promise used to return whether all components on the current UI are idle. The value true indicates that all components on the current UI are idle, and false indicates the opposite.| 3740 3741**Error codes** 3742 3743For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3744 3745| ID| Error Message | 3746| -------- | ---------------------------------------- | 3747| 17000002 | The async function is not called with await. | 3748| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3749 3750**Example** 3751 3752```ts 3753import { Driver } from '@kit.TestKit'; 3754async function demo() { 3755 let driver: Driver = Driver.create(); 3756 let idled:boolean = await driver.waitForIdle(4000,5000); 3757} 3758``` 3759 3760### fling<sup>9+</sup> 3761 3762fling(from: Point, to: Point, stepLen: number, speed: number): Promise\<void> 3763 3764Simulates a fling operation. This API uses a promise to return the result. 3765 3766**Atomic service API**: This API can be used in atomic services since API version 11. 3767 3768**System capability**: SystemCapability.Test.UiTest 3769 3770**Parameters** 3771 3772| Name | Type | Mandatory| Description | 3773| ------- | ---------------- | ---- |------------------------------------------------------| 3774| from | [Point](#point9) | Yes | Coordinates of the point where the finger touches the screen. | 3775| to | [Point](#point9) | Yes | Coordinates of the point where the finger leaves the screen. | 3776| stepLen | number | Yes | Step length, in pixels. The value is an integer greater than or equal to 0. | 3777| speed | number | Yes | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 3778 3779**Return value** 3780 3781| Type | Description | 3782|----------------|-----------------| 3783| Promise\<void> | Promise that returns no value.| 3784 3785**Error codes** 3786 3787For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3788 3789| ID| Error Message | 3790| -------- | ---------------------------------------- | 3791| 17000002 | The async function is not called with await. | 3792| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3793 3794**Example** 3795 3796```ts 3797import { Driver } from '@kit.TestKit'; 3798 3799async function demo() { 3800 let driver: Driver = Driver.create(); 3801 await driver.fling({x: 500, y: 480},{x: 450, y: 480}, 5, 600); 3802} 3803``` 3804 3805### injectMultiPointerAction<sup>9+</sup> 3806 3807injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\<boolean> 3808 3809Injects a multi-finger operation into a device. This API uses a promise to return the result. 3810 3811**Atomic service API**: This API can be used in atomic services since API version 11. 3812 3813**System capability**: SystemCapability.Test.UiTest 3814 3815**Parameters** 3816 3817| Name | Type | Mandatory| Description | 3818| -------- | -------------------------------- | ---- |--------------------------------------------------------| 3819| pointers | [PointerMatrix](#pointermatrix9) | Yes | Scroll trajectory, including the number of fingers and an array of coordinates along the trajectory. | 3820| speed | number | No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 3821 3822**Return value** 3823 3824| Type | Description | 3825| ----------------- | ------------------------------------- | 3826| Promise\<boolean> | Promise used to return whether the operation is successful. The value **true** indicates that the operation is successful, and **false** indicates the opposite.| 3827 3828**Error codes** 3829 3830For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3831 3832| ID| Error Message | 3833| -------- | ---------------------------------------- | 3834| 17000002 | The async function is not called with await. | 3835| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3836 3837**Example** 3838 3839```ts 3840import { Driver, PointerMatrix } from '@kit.TestKit'; 3841 3842async function demo() { 3843 let driver: Driver = Driver.create(); 3844 let pointers: PointerMatrix = PointerMatrix.create(2, 5); 3845 pointers.setPoint(0, 0, {x:250, y:480}); 3846 pointers.setPoint(0, 1, {x:250, y:440}); 3847 pointers.setPoint(0, 2, {x:250, y:400}); 3848 pointers.setPoint(0, 3, {x:250, y:360}); 3849 pointers.setPoint(0, 4, {x:250, y:320}); 3850 pointers.setPoint(1, 0, {x:250, y:480}); 3851 pointers.setPoint(1, 1, {x:250, y:440}); 3852 pointers.setPoint(1, 2, {x:250, y:400}); 3853 pointers.setPoint(1, 3, {x:250, y:360}); 3854 pointers.setPoint(1, 4, {x:250, y:320}); 3855 await driver.injectMultiPointerAction(pointers); 3856} 3857``` 3858 3859### fling<sup>10+</sup> 3860 3861fling(direction: UiDirection, speed: number): Promise\<void>; 3862 3863Simulates a fling operation with the specified direction and speed. This API uses a promise to return the result. 3864 3865**Atomic service API**: This API can be used in atomic services since API version 11. 3866 3867**System capability**: SystemCapability.Test.UiTest 3868 3869**Parameters** 3870 3871| Name | Type | Mandatory| Description | 3872| --------- | ----------------------------- | ---- |--------------------------------------------------------| 3873| direction | [UiDirection](#uidirection10) | Yes | Direction of the fling operation. | 3874| speed | number | Yes | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 3875 3876**Return value** 3877 3878| Type | Description | 3879|----------------|-----------------| 3880| Promise\<void> | Promise that returns no value.| 3881 3882**Error codes** 3883 3884For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3885 3886| ID| Error Message | 3887| -------- | ------------------------------------------------------------ | 3888| 17000002 | The async function is not called with await. | 3889| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3890 3891**Example** 3892 3893```ts 3894import { Driver, UiDirection } from '@kit.TestKit'; 3895async function demo() { 3896 let driver: Driver = Driver.create(); 3897 await driver.fling(UiDirection.DOWN, 10000); 3898} 3899``` 3900 3901### fling<sup>20+</sup> 3902 3903fling(direction: UiDirection, speed: number, displayId: number): Promise\<void> 3904 3905Simulates a fling operation on a specified display with the specified direction and speed. This API uses a promise to return the result. 3906 3907**Atomic service API**: This API can be used in atomic services since API version 20. 3908 3909**System capability**: SystemCapability.Test.UiTest 3910 3911**Parameters** 3912 3913| Name | Type | Mandatory| Description | 3914| --------- | ----------------------------- | ---- |--------------------------------------------------------| 3915| direction | [UiDirection](#uidirection10) | Yes | Direction of the fling operation. | 3916| speed | number | Yes | Fling speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 3917| displayId | number | Yes | Display ID. The value is an integer greater than or equal to 0.<br> **Note**: If the input **displayId** does not exist, the exception **17000007** is reported. | 3918 3919**Return value** 3920 3921| Type | Description | 3922|----------------|-----------------| 3923| Promise\<void> | Promise that returns no value.| 3924 3925**Error codes** 3926 3927For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3928 3929| ID| Error Message | 3930| -------- | ------------------------------------------------------------ | 3931| 17000002 | The async function is not called with await. | 3932| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3933 3934**Example** 3935 3936```ts 3937import { Driver, UiDirection } from '@kit.TestKit'; 3938 3939async function demo() { 3940 let driver: Driver = Driver.create(); 3941 await driver.fling(UiDirection.DOWN, 10000, 0); 3942} 3943``` 3944 3945### screenCapture<sup>10+</sup> 3946 3947screenCapture(savePath: string, rect?: Rect): Promise\<boolean>; 3948 3949Captures the specified area of the current screen and saves it as a PNG image to the specified path. This API uses a promise to return the result. This API can be used in scenarios where screenshots are supported. 3950 3951**Atomic service API**: This API can be used in atomic services since API version 11. 3952 3953**System capability**: SystemCapability.Test.UiTest 3954 3955**Parameters** 3956 3957| Name | Type | Mandatory| Description | 3958| -------- | -------------- | ---- | ------------------------------------------ | 3959| savePath | string | Yes | File save path. The path must be the [sandbox path](../../file-management/app-sandbox-directory.md) of the current application.| 3960| rect | [Rect](#rect9) | No | Area of the screen to capture. The default value is the entire screen. | 3961 3962**Return value** 3963 3964| Type | Description | 3965| ----------------- |---------------------------------------------| 3966| Promise\<boolean> | Promise used to return whether the screenshot operation is successful. The value **true** indicates the screenshot operation is successful, and **false** indicates the opposite.| 3967 3968**Error codes** 3969 3970For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3971 3972| ID| Error Message | 3973| -------- | ------------------------------------------------------------ | 3974| 17000002 | The async function is not called with await. | 3975| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3976 3977**Example** 3978 3979```ts 3980import { Driver } from '@kit.TestKit'; 3981async function demo() { 3982 let driver: Driver = Driver.create(); 3983 await driver.screenCapture('/data/storage/el2/base/cache/1.png', {left: 0, top: 0, right: 100, bottom: 100}); 3984} 3985``` 3986 3987### mouseClick<sup>10+</sup> 3988 3989mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void>; 3990 3991Injects a mouse click action at a specified coordinate point and presses the corresponding combination key at the same time. This API uses a promise to return the result. For example, if the value of **key1** is **2072**, the **Ctrl** button is pressed with the mouse click. 3992 3993**Atomic service API**: This API can be used in atomic services since API version 11. 3994 3995**System capability**: SystemCapability.Test.UiTest 3996 3997**Parameters** 3998 3999| Name| Type | Mandatory| Description | 4000| ------ | ----------------------------- | ---- | ------------------------------ | 4001| p | [Point](#point9) | Yes | Coordinates of the mouse click. | 4002| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressed. | 4003| key1 | number | No | First key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 4004| key2 | number | No | Second key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 4005 4006**Return value** 4007 4008| Type | Description | 4009|----------------|-----------------| 4010| Promise\<void> | Promise that returns no value.| 4011 4012**Error codes** 4013 4014For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4015 4016| ID| Error Message | 4017| -------- | ------------------------------------------------------------ | 4018| 17000002 | The async function is not called with await. | 4019| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4020 4021**Example** 4022 4023```ts 4024import { Driver,MouseButton } from '@kit.TestKit'; 4025async function demo() { 4026 let driver: Driver = Driver.create(); 4027 await driver.mouseClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 4028} 4029``` 4030 4031### mouseScroll<sup>10+</sup> 4032 4033mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): Promise\<void>; 4034 4035Injects a mouse scrolling action at a specified coordinate point and presses the corresponding combination key at the same time. This API uses a promise to return the result. For example, if the value of **key1** is **2072**, the **Ctrl** button is pressed with mouse scrolling. 4036 4037**Atomic service API**: This API can be used in atomic services since API version 11. 4038 4039**System capability**: SystemCapability.Test.UiTest 4040 4041**Parameters** 4042 4043| Name| Type | Mandatory| Description | 4044| ------ | ---------------- | ---- | ----------------------------------------------------------- | 4045| p | [Point](#point9) | Yes | Coordinates of the mouse click. | 4046| down | boolean | Yes | Whether the scroll wheel scrolls downward. The value **true** indicates the scroll wheel scrolls downward, and **false** indicates the scroll wheel scrolls upward.| 4047| d | number | Yes | Number of ticks scrolled by the mouse wheel. A tick indicates a 120 px shift to the target point. The value is an integer greater than or equal to 0. | 4048| key1 | number | No | First key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0. | 4049| key2 | number | No | Second key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0. | 4050 4051**Return value** 4052 4053| Type | Description | 4054|----------------|-----------------| 4055| Promise\<void> | Promise that returns no value.| 4056 4057**Error codes** 4058 4059For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4060 4061| ID| Error Message | 4062| -------- | ------------------------------------------------------------ | 4063| 17000002 | The async function is not called with await. | 4064| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4065 4066**Example** 4067 4068```ts 4069import { Driver } from '@kit.TestKit'; 4070 4071async function demo() { 4072 let driver: Driver = Driver.create(); 4073 await driver.mouseScroll({x:360, y:640}, true, 30, 2072); 4074} 4075``` 4076 4077### mouseMoveTo<sup>10+</sup> 4078 4079mouseMoveTo(p: Point): Promise\<void>; 4080 4081Moves the cursor to the target point. This API uses a promise to return the result. 4082 4083**System capability**: SystemCapability.Test.UiTest 4084 4085**Atomic service API**: This API can be used in atomic services since API version 11. 4086 4087**Parameters** 4088 4089| Name| Type | Mandatory| Description | 4090| ------ | ---------------- | ---- | -------------- | 4091| p | [Point](#point9) | Yes | Coordinates of the end point.| 4092 4093**Return value** 4094 4095| Type | Description | 4096|----------------|-----------------| 4097| Promise\<void> | Promise that returns no value.| 4098 4099**Error codes** 4100 4101For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4102 4103| ID| Error Message | 4104| -------- | ------------------------------------------------------------ | 4105| 17000002 | The async function is not called with await. | 4106| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4107 4108**Example** 4109 4110```ts 4111import { Driver } from '@kit.TestKit'; 4112 4113async function demo() { 4114 let driver: Driver = Driver.create(); 4115 await driver.mouseMoveTo({x:100, y:100}); 4116} 4117``` 4118 4119### createUIEventObserver<sup>10+</sup> 4120 4121createUIEventObserver(): UIEventObserver; 4122 4123Creates a UI event listener. 4124 4125**Atomic service API**: This API can be used in atomic services since API version 11. 4126 4127**System capability**: SystemCapability.Test.UiTest 4128 4129**Return value** 4130 4131| Type | Description | 4132| ------------------------------------ | ------------------------------------- | 4133|[UIEventObserver](#uieventobserver10) | UI event listener.| 4134 4135**Error codes** 4136 4137For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 4138 4139| ID| Error Message | 4140| -------- | ---------------------------------------- | 4141| 17000002 | The async function is not called with await. | 4142 4143**Example** 4144 4145```ts 4146import { Driver, UIEventObserver } from '@kit.TestKit'; 4147 4148async function demo() { 4149 let driver: Driver = Driver.create(); 4150 let observer: UIEventObserver = await driver.createUIEventObserver(); 4151} 4152``` 4153 4154### mouseScroll<sup>11+</sup> 4155 4156mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number, speed?: number): Promise\<void> 4157 4158Injects a mouse wheel scrolling action at the specified coordinate point. The corresponding combination key can be pressed at the same time and the scrolling speed can be specified. This API uses a promise to return the result. 4159 4160**Atomic service API**: This API can be used in atomic services since API version 11. 4161 4162**System capability**: SystemCapability.Test.UiTest 4163 4164**Parameters** 4165 4166| Name| Type | Mandatory| Description | 4167| ------ | ---------------- | ---- | ------------------------------------------------------------ | 4168| p | [Point](#point9) | Yes | Coordinates of the mouse click. | 4169| down | boolean | Yes | Whether the scroll wheel scrolls downward. The value **true** indicates the scroll wheel scrolls downward, and **false** indicates the scroll wheel scrolls upward. | 4170| d | number | Yes | Number of ticks scrolled by the mouse wheel. A tick indicates a 120 px shift to the target point. The value is an integer greater than or equal to 0. | 4171| key1 | number | No | First key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0. | 4172| key2 | number | No | Second key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0. | 4173| speed | number | No | Scroll speed of the mouse wheel, in ticks/second. The value is an integer ranging from 1 to 500. If the value is not within the range, the default value **20** will be used.| 4174 4175**Return value** 4176 4177| Type | Description | 4178|----------------|-----------------| 4179| Promise\<void> | Promise that returns no value.| 4180 4181**Error codes** 4182 4183For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4184 4185| ID| Error Message | 4186| -------- | ------------------------------------------------------------ | 4187| 17000002 | The async function is not called with await. | 4188| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4189 4190**Example** 4191 4192```ts 4193import { Driver } from '@kit.TestKit'; 4194 4195async function demo() { 4196 let driver: Driver = Driver.create(); 4197 await driver.mouseScroll({x:360, y:640}, true, 30, 2072,20); 4198} 4199``` 4200 4201### mouseDoubleClick<sup>11+</sup> 4202 4203mouseDoubleClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void> 4204 4205Injects a mouse double-click action at a specified coordinate point. The corresponding combination key can be pressed at the same time. This API uses a promise to return the result. For example, if the value of **key** is **2072**, the **Ctrl** button is pressed with the double-click. 4206 4207**Atomic service API**: This API can be used in atomic services since API version 11. 4208 4209**System capability**: SystemCapability.Test.UiTest 4210 4211**Parameters** 4212 4213| Name| Type | Mandatory| Description | 4214| ------ | ----------------------------- | ---- | ------------------------------ | 4215| p | [Point](#point9) | Yes | Coordinates of the double-click. | 4216| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressed. | 4217| key1 | number | No | First key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 4218| key2 | number | No | Second key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 4219 4220**Return value** 4221 4222| Type | Description | 4223|----------------|-----------------| 4224| Promise\<void> | Promise that returns no value.| 4225 4226**Error codes** 4227 4228For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4229 4230| ID| Error Message | 4231| -------- | ------------------------------------------------------------ | 4232| 17000002 | The async function is not called with await. | 4233| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4234 4235**Example** 4236 4237```ts 4238import { Driver,MouseButton } from '@kit.TestKit'; 4239async function demo() { 4240 let driver: Driver = Driver.create(); 4241 await driver.mouseDoubleClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 4242} 4243``` 4244 4245### mouseLongClick<sup>11+</sup> 4246 4247mouseLongClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void> 4248 4249Injects a mouse long-click action at a specified coordinate point. The corresponding combination key can be pressed at the same time. This API uses a promise to return the result. For example, if the value of **Key** is **2072**, the **Ctrl** button is long-clicked with the mouse device. 4250 4251**Atomic service API**: This API can be used in atomic services since API version 11. 4252 4253**System capability**: SystemCapability.Test.UiTest 4254 4255**Parameters** 4256 4257| Name| Type | Mandatory| Description | 4258| ------ | ----------------------------- | ---- | ------------------------------ | 4259| p | [Point](#point9) | Yes | Coordinates of the long-click of the mouse device. | 4260| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressed. | 4261| key1 | number | No | First key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 4262| key2 | number | No | Second key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 4263 4264**Return value** 4265 4266| Type | Description | 4267|----------------|-----------------| 4268| Promise\<void> | Promise that returns no value.| 4269 4270**Error codes** 4271 4272For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4273 4274| ID| Error Message | 4275| -------- | ------------------------------------------------------------ | 4276| 17000002 | The async function is not called with await. | 4277| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4278 4279**Example** 4280 4281```ts 4282import { Driver,MouseButton } from '@kit.TestKit'; 4283async function demo() { 4284 let driver:Driver = Driver.create(); 4285 await driver.mouseLongClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 4286} 4287``` 4288 4289### mouseLongClick<sup>20+</sup> 4290 4291mouseLongClick(p: Point, btnId: MouseButton, key1?: number, key2?: number, duration?: number): Promise\<void> 4292 4293Injects a mouse long-click action at a specified coordinate point. The corresponding combination key can be pressed at the same time and the click duration can be specified. This API uses a promise to return the result. For example, if the value of **Key** is **2072**, the **Ctrl** button is long-clicked with the mouse device. 4294 4295**Atomic service API**: This API can be used in atomic services since API version 20. 4296 4297**System capability**: SystemCapability.Test.UiTest 4298 4299**Parameters** 4300 4301| Name| Type | Mandatory| Description | 4302| -------- | ----------------------------- | ---- | ------------------------------ | 4303| p | [Point](#point9) | Yes | Coordinates of the long-click of the mouse device. | 4304| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressed. | 4305| key1 | number | No | First key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 4306| key2 | number | No | Second key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode). The default value is 0.| 4307| duration | number | No | Long-click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.| 4308 4309**Return value** 4310 4311| Type | Description | 4312|----------------|-----------------| 4313| Promise\<void> | Promise that returns no value.| 4314 4315**Error codes** 4316 4317For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4318 4319| ID| Error Message | 4320| -------- | ------------------------------------------------------------ | 4321| 17000002 | The async function is not called with await. | 4322| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4323 4324**Example** 4325 4326```ts 4327import { Driver,MouseButton } from '@kit.TestKit'; 4328 4329async function demo() { 4330 let driver:Driver = Driver.create(); 4331 await driver.mouseLongClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072, 0, 2000); 4332} 4333``` 4334 4335### mouseMoveWithTrack<sup>11+</sup> 4336 4337mouseMoveWithTrack(from: Point, to: Point, speed?: number): Promise\<void> 4338 4339Moves the mouse from the start point to the end point. This API uses a promise to return the result. 4340 4341**Atomic service API**: This API can be used in atomic services since API version 11. 4342 4343**System capability**: SystemCapability.Test.UiTest 4344 4345**Parameters** 4346 4347| Name| Type | Mandatory| Description | 4348| ------ | ---------------- | ---- |--------------------------------------------------------| 4349| from | [Point](#point9) | Yes | Coordinates of the start point. | 4350| to | [Point](#point9) | Yes | Coordinates of the end point. | 4351| speed | number | No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 4352 4353**Return value** 4354 4355| Type | Description | 4356|----------------|-----------------| 4357| Promise\<void> | Promise that returns no value.| 4358 4359**Error codes** 4360 4361For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4362 4363| ID| Error Message | 4364| -------- | ------------------------------------------------------------ | 4365| 17000002 | The async function is not called with await. | 4366| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4367 4368**Example** 4369 4370```ts 4371import { Driver } from '@kit.TestKit'; 4372 4373async function demo() { 4374 let driver: Driver = Driver.create(); 4375 await driver.mouseMoveWithTrack({x:100, y:100}, {x:200, y:200}, 600); 4376} 4377``` 4378 4379### mouseDrag<sup>11+</sup> 4380 4381mouseDrag(from: Point, to: Point, speed?: number): Promise\<void> 4382 4383Drags the mouse from the start point to the end point with the left mouse button clicked. This API uses a promise to return the result. 4384 4385> **NOTE** 4386> 4387> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 4388 4389**Atomic service API**: This API can be used in atomic services since API version 11. 4390 4391**System capability**: SystemCapability.Test.UiTest 4392 4393**Parameters** 4394 4395| Name| Type | Mandatory| Description | 4396| ------ | ---------------- | ---- |--------------------------------------------------------| 4397| from | [Point](#point9) | Yes | Coordinates of the start point. | 4398| to | [Point](#point9) | Yes | Coordinates of the end point. | 4399| speed | number | No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 4400 4401**Return value** 4402 4403| Type | Description | 4404|----------------|-----------------| 4405| Promise\<void> | Promise that returns no value.| 4406 4407**Error codes** 4408 4409For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4410 4411| ID| Error Message | 4412| -------- | ------------------------------------------------------------ | 4413| 17000002 | The async function is not called with await. | 4414| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4415 4416**Example** 4417 4418```ts 4419import { Driver } from '@kit.TestKit'; 4420 4421async function demo() { 4422 let driver: Driver = Driver.create(); 4423 await driver.mouseDrag({x:100, y:100},{x:200, y:200}, 600); 4424} 4425``` 4426 4427### mouseDrag<sup>20+</sup> 4428 4429mouseDrag(from: Point, to: Point, speed?: number, duration?: number): Promise\<void> 4430 4431Drags the mouse from the start point to the end point with the left mouse button clicked. You can specify the drag speed and click duration before dragging. This API uses a promise to return the result. 4432 4433> **NOTE** 4434> 4435> This API takes effect only on phones, tablets, and PCs/2-in-1 devices. 4436 4437**Atomic service API**: This API can be used in atomic services since API version 20. 4438 4439**System capability**: SystemCapability.Test.UiTest 4440 4441**Parameters** 4442 4443| Name | Type | Mandatory| Description | 4444| --------- | ---------------- | ---- |--------------------------------------------------------| 4445| from | [Point](#point9) | Yes | Coordinates of the start point. | 4446| to | [Point](#point9) | Yes | Coordinates of the end point. | 4447| speed | number | No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 4448| duration | number | No | Click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.| 4449 4450**Return value** 4451 4452| Type | Description | 4453|----------------|-----------------| 4454| Promise\<void> | Promise that returns no value.| 4455 4456**Error codes** 4457 4458For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4459 4460| ID| Error Message | 4461| -------- | ------------------------------------------------------------ | 4462| 17000002 | The async function is not called with await. | 4463| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4464 4465**Example** 4466 4467```ts 4468import { Driver } from '@kit.TestKit'; 4469 4470async function demo() { 4471 let driver: Driver = Driver.create(); 4472 await driver.mouseDrag({x:100, y:100},{x:200, y:200}, 600, 2000); 4473} 4474``` 4475 4476### inputText<sup>11+</sup> 4477 4478inputText(p: Point, text: string): Promise\<void> 4479 4480Inputs text at a specified coordinate without clearing the original text in the component. This API uses a promise to return the result. 4481 4482**Atomic service API**: This API can be used in atomic services since API version 11. 4483 4484**System capability**: SystemCapability.Test.UiTest 4485 4486**Parameters** 4487 4488| Name| Type | Mandatory| Description | 4489| ------ | ---------------- | ---- | ------------------ | 4490| p | [Point](#point9) | Yes | Coordinates of the end point.| 4491| text | string | Yes |Input text. Currently, English, Chinese, and special characters are supported.<br> **Note**: For wearables, this API does not support Chinese characters.| 4492 4493**Return value** 4494 4495| Type | Description | 4496|----------------|-----------------| 4497| Promise\<void> | Promise that returns no value.| 4498 4499**Error codes** 4500 4501For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4502 4503| ID| Error Message | 4504| -------- | ------------------------------------------------------------ | 4505| 17000002 | The async function is not called with await. | 4506| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4507 4508**Example** 4509 4510```ts 4511import { Component, Driver, ON } from '@kit.TestKit'; 4512async function demo() { 4513 let driver:Driver = Driver.create(); 4514 let text: Component = await driver.findComponent(ON.type('TextInput')); 4515 let point = await text.getBoundsCenter(); 4516 await driver.inputText(point, '123'); 4517} 4518``` 4519 4520### inputText<sup>20+</sup> 4521 4522inputText(p: Point, text: string, mode: InputTextMode): Promise\<void> 4523 4524Inputs text at a specified coordinate point in a specified input mode. This API uses a promise to return the result. 4525 4526**Atomic service API**: This API can be used in atomic services since API version 20. 4527 4528**System capability**: SystemCapability.Test.UiTest 4529 4530**Parameters** 4531 4532| Name| Type | Mandatory| Description | 4533| ------ | ---------------- | ---- | ------------------ | 4534| p | [Point](#point9) | Yes | Coordinates of the end point.| 4535| text | string | Yes |Input text. Currently, English, Chinese, and special characters are supported.<br> **Note**: For wearables, this API does not support Chinese characters.| 4536| mode | [InputTextMode](#inputtextmode20) | Yes | Text input mode. For details, see [InputTextMode](#inputtextmode20).<br> **Note**: If **InputTextMode.addition** is set to true, the cursor moves to the end of the text and the specified text is input. If the value is **false**, the specified text is input at the coordinate point.| 4537 4538**Return value** 4539 4540| Type | Description | 4541|----------------|-----------------| 4542| Promise\<void> | Promise that returns no value.| 4543 4544**Error codes** 4545 4546For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4547 4548| ID| Error Message | 4549| -------- | ------------------------------------------------------------ | 4550| 17000002 | The async function is not called with await. | 4551| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4552| 801 | Capability not support, function can not work correctly due to limited device capabilities.| 4553 4554**Example** 4555 4556```ts 4557import { Component, Driver, ON } from '@kit.TestKit'; 4558 4559async function demo() { 4560 let driver: Driver = Driver.create(); 4561 let text: Component = await driver.findComponent(ON.type('TextInput')); 4562 let point = await text.getBoundsCenter(); 4563 await driver.inputText(point, '123', {paste: true, addition: false}); 4564} 4565 4566async function demo_Chinese() { 4567 let driver: Driver = Driver.create(); 4568 let text: Component = await driver.findComponent(ON.type('TextInput')); 4569 let point = await text.getBoundsCenter(); 4570 await driver.inputText(point, 'Chinese&', { paste: false, addition: true }); 4571 // Copy and paste Chinese and a special character to the end of the specified text. 4572} 4573``` 4574 4575### touchPadMultiFingerSwipe<sup>18+</sup> 4576 4577touchPadMultiFingerSwipe(fingers: number, direction: UiDirection, options?: TouchPadSwipeOptions): Promise\<void> 4578 4579Simulates a multi-finger swipe gesture on the touchpad. This API uses a promise to return the result. 4580 4581> **NOTE** 4582> 4583> This API takes effect only on PCs/2-in-1 devices. 4584 4585**Atomic service API**: This API can be used in atomic services since API version 18. 4586 4587**System capability**: SystemCapability.Test.UiTest 4588 4589**Parameters** 4590 4591| Name| Type | Mandatory| Description | 4592| ------ |-----------------------------------------------|----|-----------------------| 4593| fingers | number | Yes | Number of fingers. The value can be 3 or 4.| 4594| direction | [UiDirection](#uidirection10) | Yes | Swipe direction. | 4595| options | [TouchPadSwipeOptions](#touchpadswipeoptions18) | No | Additional options. | 4596 4597**Return value** 4598 4599| Type | Description | 4600|----------------|-----------------| 4601| Promise\<void> | Promise that returns no value.| 4602 4603**Error codes** 4604 4605For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4606 4607| ID| Error Message | 4608| -------- | ------------------------------------------------------------ | 4609| 17000002 | The async function is not called with await. | 4610| 17000005 | This operation is not supported. | 4611| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4612 4613**Example** 4614 4615```ts 4616import { Driver, UiDirection } from '@kit.TestKit'; 4617async function demo() { 4618 let driver:Driver = Driver.create(); 4619 await driver.touchPadMultiFingerSwipe(3, UiDirection.UP); 4620} 4621``` 4622 4623### penClick<sup>18+</sup> 4624 4625penClick(point: Point): Promise\<void> 4626 4627Simulates a pen click. This API uses a promise to return the result. 4628 4629**Atomic service API**: This API can be used in atomic services since API version 18. 4630 4631**System capability**: SystemCapability.Test.UiTest 4632 4633**Parameters** 4634 4635| Name| Type | Mandatory| Description | 4636| ------ |-----------------------------------------------|----|---------| 4637| point | [Point](#point9) | Yes | Coordinates of the clicked point.| 4638 4639**Return value** 4640 4641| Type | Description | 4642|----------------|-----------------| 4643| Promise\<void> | Promise that returns no value.| 4644 4645**Error codes** 4646 4647For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4648 4649| ID| Error Message | 4650| -------- | ------------------------------------------------------------ | 4651| 17000002 | The async function is not called with await. | 4652| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4653 4654**Example** 4655 4656```ts 4657import { Driver } from '@kit.TestKit'; 4658async function demo() { 4659 let driver: Driver = Driver.create(); 4660 await driver.penClick({x: 100, y: 100}); 4661} 4662``` 4663 4664### penLongClick<sup>18+</sup> 4665 4666penLongClick(point: Point, pressure?: number): Promise\<void> 4667 4668Simulates a pen long-click. This API uses a promise to return the result. 4669 4670**Atomic service API**: This API can be used in atomic services since API version 18. 4671 4672**System capability**: SystemCapability.Test.UiTest 4673 4674**Parameters** 4675 4676| Name| Type | Mandatory| Description | 4677| ------ |-----------------------------------------------|----|-------------------------------| 4678| point | [Point](#point9) | Yes | Coordinates of the long-clicked point. | 4679| pressure | number | No | Swipe pressure of the pen. The value ranges from 0.0 to 1.0. The default value is **1.0**.| 4680 4681**Return value** 4682 4683| Type | Description | 4684|----------------|-----------------| 4685| Promise\<void> | Promise that returns no value.| 4686 4687**Error codes** 4688 4689For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4690 4691| ID| Error Message | 4692| -------- | ------------------------------------------------------------ | 4693| 17000002 | The async function is not called with await. | 4694| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4695 4696**Example** 4697 4698```ts 4699import { Driver } from '@kit.TestKit'; 4700async function demo() { 4701 let driver: Driver = Driver.create(); 4702 await driver.penLongClick({x: 100, y: 100}, 0.5); 4703} 4704``` 4705 4706### penDoubleClick<sup>18+</sup> 4707 4708penDoubleClick(point: Point): Promise\<void> 4709 4710Simulates a pen double-click. This API uses a promise to return the result. 4711 4712**Atomic service API**: This API can be used in atomic services since API version 18. 4713 4714**System capability**: SystemCapability.Test.UiTest 4715 4716**Parameters** 4717 4718| Name| Type | Mandatory| Description | 4719| ------ |-----------------------------------------------|----|---------| 4720| point | [Point](#point9) | Yes | Coordinates of the double-clicked point.| 4721 4722 4723**Return value** 4724 4725| Type | Description | 4726|----------------|-----------------| 4727| Promise\<void> | Promise that returns no value.| 4728 4729**Error codes** 4730 4731For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4732 4733| ID| Error Message | 4734| -------- | ------------------------------------------------------------ | 4735| 17000002 | The async function is not called with await. | 4736| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4737 4738**Example** 4739 4740```ts 4741import { Driver } from '@kit.TestKit'; 4742async function demo() { 4743 let driver: Driver = Driver.create(); 4744 await driver.penDoubleClick({x: 100, y: 100}); 4745} 4746``` 4747 4748### penSwipe<sup>18+</sup> 4749 4750penSwipe(startPoint: Point, endPoint: Point, speed?: number, pressure?: number): Promise\<void> 4751 4752Simulates a pen swipe. This API uses a promise to return the result. 4753 4754**Atomic service API**: This API can be used in atomic services since API version 18. 4755 4756**System capability**: SystemCapability.Test.UiTest 4757 4758**Parameters** 4759 4760| Name| Type | Mandatory| Description | 4761| ------ |-----------------------------------------------|----|--------------------------------------------------------| 4762| startPoint | [Point](#point9) | Yes | Coordinates of the start point. | 4763| endPoint | [Point](#point9) | Yes | Coordinates of the end point. | 4764| speed | number | No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used.| 4765| pressure | number | No | Swipe pressure of the pen. The value ranges from 0.0 to 1.0. The default value is **1.0**. | 4766 4767**Return value** 4768 4769| Type | Description | 4770|----------------|-----------------| 4771| Promise\<void> | Promise that returns no value.| 4772 4773**Error codes** 4774 4775For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4776 4777| ID| Error Message | 4778| -------- | ------------------------------------------------------------ | 4779| 17000002 | The async function is not called with await. | 4780| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4781 4782**Example** 4783 4784```ts 4785 import { Driver } from '@kit.TestKit'; 4786async function demo() { 4787 let driver: Driver = Driver.create(); 4788 await driver.penSwipe({x: 100, y: 100}, {x: 100, y: 500}, 600, 0.5); 4789} 4790``` 4791 4792### injectPenPointerAction<sup>18+</sup> 4793 4794injectPenPointerAction(pointers: PointerMatrix, speed?: number, pressure?: number): Promise\<void> 4795 4796Simulates a continuous multi-point pen injection. This API uses a promise to return the result. 4797 4798**Atomic service API**: This API can be used in atomic services since API version 18. 4799 4800**System capability**: SystemCapability.Test.UiTest 4801 4802**Parameters** 4803 4804| Name| Type | Mandatory| Description | 4805| ------ |-----------------------------------------------|----|-------------------------------------------------------------------| 4806| pointers | [PointerMatrix](#pointermatrix9) | Yes |Scroll trajectory, including the number of fingers and an array of coordinates along the trajectory. Currently, only the single-finger operation is supported. The value of **fingers** in **PointerMatrix** must be set to 1.| 4807| speed | number| No | Scroll speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **600** is used. | 4808| pressure | number | No | Injection pressure. The value ranges from 0.0 to 1.0. The default value is **1.0**. | 4809 4810 4811**Return value** 4812 4813| Type | Description | 4814|----------------|-----------------| 4815| Promise\<void> | Promise that returns no value.| 4816 4817**Error codes** 4818 4819For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4820 4821| ID| Error Message | 4822| -------- | ------------------------------------------------------------ | 4823| 17000002 | The async function is not called with await. | 4824| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4825 4826**Example** 4827 4828```ts 4829import { Driver, PointerMatrix } from '@kit.TestKit'; 4830async function demo() { 4831 let driver: Driver = Driver.create(); 4832 let pointer = PointerMatrix.create(1, 8); 4833 for (let step = 0; step < 8; step++) { 4834 pointer.setPoint(0, step, {x: 500, y: 1100 - 100 *step}); 4835 } 4836 await driver.injectPenPointerAction(pointer, 600, 0.5); 4837} 4838``` 4839 4840### crownRotate<sup>20+</sup> 4841 4842crownRotate(d: number, speed?: number): Promise\<void> 4843 4844Injects a crown rotation event. You can specify the rotation speed. This API uses a promise to return the result. 4845 4846This API takes effect only on wearables. 4847 4848**Atomic service API**: This API can be used in atomic services since API version 20. 4849 4850**System capability**: SystemCapability.Test.UiTest 4851 4852**Parameters** 4853 4854| Name| Type | Mandatory| Description | 4855| ------ |-----------------------------------------------|----|-------------------------------------------------------------------| 4856| d | number | Yes | Number of rotation ticks. A positive value indicates rotation, and a negative value indicates counterclockwise rotation. The value must be an integer. | 4857| speed | number | No | Rotation speed, in ticks/s. The value is an integer ranging from 1 to 500. The default value is 20.<br> **Note**: If the set value is not in the range, the default value 20 is used.| 4858 4859**Return value** 4860 4861| Type | Description | 4862|----------------|-----------------| 4863| Promise\<void> | Promise that returns no value.| 4864 4865**Error codes** 4866 4867For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 4868 4869| ID| Error Message | 4870| -------- | ------------------------------------------------------------ | 4871| 17000002 | The async function is not called with await. | 4872| 17000007 | Parameter verification failed. | 4873| 801 | Capability not support, function can not work correctly due to limited device capabilities. | 4874 4875**Example** 4876 4877```ts 4878import { Driver } from '@kit.TestKit'; 4879 4880async function demo() { 4881 let driver: Driver = Driver.create(); 4882 // Rotate 50 ticks clockwise at a speed of 30 ticks per second. 4883 await driver.crownRotate(50, 30); 4884 // Rotate 20 ticks counterclockwise at a speed of 30 ticks per second. 4885 await driver.crownRotate(-20, 30); 4886} 4887``` 4888 4889## PointerMatrix<sup>9+</sup> 4890 4891Implements a **PointerMatrix** object that stores coordinates and behaviors of each action of each finger in a multi-touch operation. 4892 4893### create<sup>9+</sup> 4894 4895static create(fingers: number, steps: number): PointerMatrix 4896 4897Creates a **PointerMatrix** object and returns the object created. This API is a static API. 4898 4899**Atomic service API**: This API can be used in atomic services since API version 11. 4900 4901**System capability**: SystemCapability.Test.UiTest 4902 4903**Parameters** 4904 4905| Name | Type | Mandatory| Description | 4906| ------- | ------ | ---- | ------------------------------------------ | 4907| fingers | number | Yes | Number of fingers injected during the multi-finger operation. The value is an integer ranging from 1 to 10.| 4908| steps | number | Yes | Number of steps performed by a finger. The value is an integer ranging from 1 to 1000.| 4909 4910**Return value** 4911 4912| Type | Description | 4913| -------------------------------- | ----------------------------- | 4914| [PointerMatrix](#pointermatrix9) | **PointerMatrix** object created.| 4915 4916**Error codes** 4917 4918For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4919 4920| ID| Error Message | 4921| -------- | ------------------------------------------------------------ | 4922| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4923 4924**Example** 4925 4926```ts 4927import { PointerMatrix } from '@kit.TestKit'; 4928 4929async function demo() { 4930 let pointerMatrix: PointerMatrix = PointerMatrix.create(2, 3); 4931} 4932``` 4933 4934### setPoint<sup>9+</sup> 4935 4936setPoint(finger: number, step: number, point: Point): void 4937 4938Sets the coordinates for the action corresponding to the specified finger and step in the **PointerMatrix** object. 4939 4940**Atomic service API**: This API can be used in atomic services since API version 11. 4941 4942**System capability**: SystemCapability.Test.UiTest 4943 4944**Parameters** 4945 4946| Name| Type | Mandatory| Description | 4947| ------ | ---------------- | ---- | ---------------------------------------------------------- | 4948| finger | number | Yes | Number of fingers. The value is an integer greater than or equal to 0 and cannot exceed the number of fingers set when the **PointerMatrix** object is constructed. | 4949| step | number | Yes | Number of steps. The value is an integer greater than or equal to 0 and cannot exceed the number of steps set when the **PointerMatrix** object is constructed. | 4950| point | [Point](#point9) | Yes | Coordinates of the action. It is recommended that the distance between adjacent coordinates be within the range of 10 px to 80 px.| 4951 4952**Error codes** 4953 4954For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4955 4956| ID| Error Message | 4957| -------- | ------------------------------------------------------------ | 4958| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4959 4960**Example** 4961 4962```ts 4963import { PointerMatrix } from '@kit.TestKit'; 4964 4965async function demo() { 4966 let pointers: PointerMatrix = PointerMatrix.create(2, 5); 4967 pointers.setPoint(0, 0, {x:250, y:480}); 4968 pointers.setPoint(0, 1, {x:250, y:440}); 4969 pointers.setPoint(0, 2, {x:250, y:400}); 4970 pointers.setPoint(0, 3, {x:250, y:360}); 4971 pointers.setPoint(0, 4, {x:250, y:320}); 4972 pointers.setPoint(1, 0, {x:250, y:480}); 4973 pointers.setPoint(1, 1, {x:250, y:440}); 4974 pointers.setPoint(1, 2, {x:250, y:400}); 4975 pointers.setPoint(1, 3, {x:250, y:360}); 4976 pointers.setPoint(1, 4, {x:250, y:320}); 4977} 4978``` 4979 4980## UiWindow<sup>9+</sup> 4981 4982The **UiWindow** class represents a window on the UI and provides APIs for obtaining window attributes, dragging a window, and adjusting the window size. 4983All APIs provided in this class use a promise to return the result and must be invoked using **await**. 4984 4985### getBundleName<sup>9+</sup> 4986 4987getBundleName(): Promise\<string> 4988 4989Obtains the bundle name of the application to which the window belongs. This API uses a promise to return the result. 4990 4991**Atomic service API**: This API can be used in atomic services since API version 11. 4992 4993**System capability**: SystemCapability.Test.UiTest 4994 4995**Return value** 4996 4997| Type | Description | 4998| ---------------- | ----------------------------------------- | 4999| Promise\<string> | Promise used to return the bundle name of the application to which the window belongs.| 5000 5001**Error codes** 5002 5003For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5004 5005| ID| Error Message | 5006| -------- | ---------------------------------------- | 5007| 17000002 | The async function is not called with await. | 5008| 17000004 | The window or component is invisible or destroyed. | 5009 5010**Example** 5011 5012```ts 5013import { Driver, UiWindow } from '@kit.TestKit'; 5014 5015async function demo() { 5016 let driver: Driver = Driver.create(); 5017 let window: UiWindow = await driver.findWindow({actived: true}); 5018 let name: string = await window.getBundleName(); 5019} 5020``` 5021 5022### getBounds<sup>9+</sup> 5023 5024getBounds(): Promise\<Rect> 5025 5026Obtains the border information of a window. This API uses a promise to return the result. 5027 5028**Atomic service API**: This API can be used in atomic services since API version 11. 5029 5030**System capability**: SystemCapability.Test.UiTest 5031 5032**Return value** 5033 5034| Type | Description | 5035| ------------------------ | --------------------------------- | 5036| Promise\<[Rect](#rect9)> | Promise used to return the window border information.| 5037 5038**Error codes** 5039 5040For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5041 5042| ID| Error Message | 5043| -------- | ---------------------------------------- | 5044| 17000002 | The async function is not called with await. | 5045| 17000004 | The window or component is invisible or destroyed. | 5046 5047**Example** 5048 5049```ts 5050import { Driver, UiWindow } from '@kit.TestKit'; 5051async function demo() { 5052 let driver: Driver = Driver.create(); 5053 let window: UiWindow = await driver.findWindow({actived: true}); 5054 let rect = await window.getBounds(); 5055} 5056``` 5057 5058### getTitle<sup>9+</sup> 5059 5060getTitle(): Promise\<string> 5061 5062Obtains the window title. This API uses a promise to return the result. 5063 5064**Atomic service API**: This API can be used in atomic services since API version 11. 5065 5066**System capability**: SystemCapability.Test.UiTest 5067 5068**Return value** 5069 5070| Type | Description | 5071| ---------------- | --------------------------------- | 5072| Promise\<string> | Promise used to return the window title.| 5073 5074**Error codes** 5075 5076For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5077 5078| ID| Error Message | 5079| -------- | ---------------------------------------- | 5080| 17000002 | The async function is not called with await. | 5081| 17000004 | The window or component is invisible or destroyed. | 5082 5083**Example** 5084 5085```ts 5086import { Driver, UiWindow } from '@kit.TestKit'; 5087async function demo() { 5088 let driver: Driver = Driver.create(); 5089 let window: UiWindow = await driver.findWindow({actived: true}); 5090 let title = await window.getTitle(); 5091} 5092``` 5093 5094### getWindowMode<sup>9+</sup> 5095 5096getWindowMode(): Promise\<WindowMode> 5097 5098Obtains the window mode information. This API uses a promise to return the result. 5099 5100**Atomic service API**: This API can be used in atomic services since API version 11. 5101 5102**System capability**: SystemCapability.Test.UiTest 5103 5104**Return value** 5105 5106| Type | Description | 5107| ------------------------------------ | ------------------------------------- | 5108| Promise\<[WindowMode](#windowmode9)> | Promise used to return the window mode information.| 5109 5110**Error codes** 5111 5112For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5113 5114| ID| Error Message | 5115| -------- | ---------------------------------------- | 5116| 17000002 | The async function is not called with await. | 5117| 17000004 | The window or component is invisible or destroyed. | 5118 5119**Example** 5120 5121```ts 5122import { Driver, UiWindow } from '@kit.TestKit'; 5123async function demo() { 5124 let driver: Driver = Driver.create(); 5125 let window: UiWindow = await driver.findWindow({actived: true}); 5126 let mode = await window.getWindowMode(); 5127} 5128``` 5129 5130### isFocused<sup>9+</sup> 5131 5132isFocused(): Promise\<boolean> 5133 5134Checks whether the window is focused. This API uses a promise to return the result. 5135 5136**Atomic service API**: This API can be used in atomic services since API version 11. 5137 5138**System capability**: SystemCapability.Test.UiTest 5139 5140**Return value** 5141 5142| Type | Description | 5143| ----------------- | ------------------------------------------------------------ | 5144| Promise\<boolean> | Promise used to return whether the window is focused. The value **true** indicates that the window is focused, and **false** indicates the opposite.| 5145 5146**Error codes** 5147 5148For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5149 5150| ID| Error Message | 5151| -------- | ---------------------------------------- | 5152| 17000002 | The async function is not called with await. | 5153| 17000004 | The window or component is invisible or destroyed. | 5154 5155**Example** 5156 5157```ts 5158import { Driver, UiWindow } from '@kit.TestKit'; 5159async function demo() { 5160 let driver: Driver = Driver.create(); 5161 let window: UiWindow = await driver.findWindow({actived: true}); 5162 let focused = await window.isFocused(); 5163} 5164``` 5165 5166### isActived<sup>(deprecated)</sup> 5167 5168isActived(): Promise\<boolean> 5169 5170Checks whether this window is active. This API uses a promise to return the result. 5171 5172This API is supported since API version 9 and deprecated since API version 11. You are advised to use [isActive<sup>11+</sup>](#isactive11) instead. 5173 5174**System capability**: SystemCapability.Test.UiTest 5175 5176**Return value** 5177 5178| Type | Description | 5179| ----------------- | ------------------------------------------------------------ | 5180| Promise\<boolean> | Promise used to return whether the window is active. The value **true** indicates that the window is active, and **false** indicates the opposite.| 5181 5182**Error codes** 5183 5184For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5185 5186| ID| Error Message | 5187| -------- | ---------------------------------------- | 5188| 17000002 | The async function is not called with await. | 5189| 17000004 | The window or component is invisible or destroyed. | 5190 5191**Example** 5192 5193```ts 5194import { Driver, UiWindow } from '@kit.TestKit'; 5195async function demo() { 5196 let driver: Driver = Driver.create(); 5197 let window: UiWindow = await driver.findWindow({actived: true}); 5198 let focused = await window.isActived(); 5199} 5200``` 5201 5202### focus<sup>9+</sup> 5203 5204focus(): Promise\<void> 5205 5206Focuses the window. This API uses a promise to return the result. 5207 5208**Atomic service API**: This API can be used in atomic services since API version 11. 5209 5210**System capability**: SystemCapability.Test.UiTest 5211 5212**Return value** 5213 5214| Type | Description | 5215|----------------|-----------------| 5216| Promise\<void> | Promise that returns no value.| 5217 5218**Error codes** 5219 5220For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5221 5222| ID| Error Message | 5223| -------- | ---------------------------------------- | 5224| 17000002 | The async function is not called with await. | 5225| 17000004 | The window or component is invisible or destroyed. | 5226 5227**Example** 5228 5229```ts 5230import { Driver, UiWindow } from '@kit.TestKit'; 5231async function demo() { 5232 let driver: Driver = Driver.create(); 5233 let window: UiWindow = await driver.findWindow({actived: true}); 5234 await window.focus(); 5235} 5236``` 5237 5238### moveTo<sup>9+</sup> 5239 5240moveTo(x: number, y: number): Promise\<void> 5241 5242Moves a window to the target point. This API uses a promise to return the result. This API is applicable to moveable windows. 5243 5244**Atomic service API**: This API can be used in atomic services since API version 11. 5245 5246**System capability**: SystemCapability.Test.UiTest 5247 5248**Parameters** 5249 5250| Name| Type | Mandatory| Description | 5251| ------ | ------ | ---- | ----------------------------------------------- | 5252| x | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.| 5253| y | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.| 5254 5255**Return value** 5256 5257| Type | Description | 5258|----------------|-----------------| 5259| Promise\<void> | Promise that returns no value.| 5260 5261**Error codes** 5262 5263For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 5264 5265| ID| Error Message | 5266| -------- | ---------------------------------------- | 5267| 17000002 | The async function is not called with await. | 5268| 17000004 | The window or component is invisible or destroyed. | 5269| 17000005 | This operation is not supported. | 5270| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 5271 5272**Example** 5273 5274```ts 5275import { Driver, UiWindow } from '@kit.TestKit'; 5276async function demo() { 5277 let driver: Driver = Driver.create(); 5278 let window: UiWindow = await driver.findWindow({actived: true}); 5279 await window.moveTo(100, 100); 5280} 5281``` 5282 5283### resize<sup>9+</sup> 5284 5285resize(wide: number, height: number, direction: ResizeDirection): Promise\<void> 5286 5287Resizes the window based on the specified width, height, and direction. This API uses a promise to return the result. This API is applicable to resizable windows. 5288 5289**Atomic service API**: This API can be used in atomic services since API version 11. 5290 5291**System capability**: SystemCapability.Test.UiTest 5292 5293**Parameters** 5294 5295| Name | Type | Mandatory| Description | 5296| --------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 5297| wide | number | Yes | Width of the adjusted window, in number format. The value is an integer greater than or equal to 0. | 5298| height | number | Yes | Height of the adjusted window, in number format. The value is an integer greater than or equal to 0. | 5299| direction | [ResizeDirection](#resizedirection9) | Yes | Resize direction.| 5300 5301**Return value** 5302 5303| Type | Description | 5304|----------------|-----------------| 5305| Promise\<void> | Promise that returns no value.| 5306 5307**Error codes** 5308 5309For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 5310 5311| ID| Error Message | 5312| -------- | ---------------------------------------- | 5313| 17000002 | The async function is not called with await. | 5314| 17000004 | The window or component is invisible or destroyed. | 5315| 17000005 | This operation is not supported. | 5316| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 5317 5318**Example** 5319 5320```ts 5321import { Driver, ResizeDirection, UiWindow } from '@kit.TestKit'; 5322async function demo() { 5323 let driver: Driver = Driver.create(); 5324 let window: UiWindow = await driver.findWindow({actived: true}); 5325 await window.resize(100, 100, ResizeDirection.LEFT); 5326} 5327``` 5328 5329### split<sup>9+</sup> 5330 5331split(): Promise\<void> 5332 5333Switches to the split-screen mode. This API uses a promise to return the result. This API is applicable to windows that support screen splitting. 5334 5335> **NOTE** 5336> 5337> This API takes effect only on tablets and PCs/2-in-1 devices. 5338 5339**Atomic service API**: This API can be used in atomic services since API version 11. 5340 5341**System capability**: SystemCapability.Test.UiTest 5342 5343**Return value** 5344 5345| Type | Description | 5346|----------------|-----------------| 5347| Promise\<void> | Promise that returns no value.| 5348 5349**Error codes** 5350 5351For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5352 5353| ID| Error Message | 5354| -------- | ---------------------------------------- | 5355| 17000002 | The async function is not called with await. | 5356| 17000004 | The window or component is invisible or destroyed. | 5357| 17000005 | This operation is not supported. | 5358 5359**Example** 5360 5361```ts 5362import { Driver, UiWindow } from '@kit.TestKit'; 5363async function demo() { 5364 let driver: Driver = Driver.create(); 5365 let window: UiWindow = await driver.findWindow({actived: true}); 5366 await window.split(); 5367} 5368``` 5369 5370### maximize<sup>9+</sup> 5371 5372maximize(): Promise\<void> 5373 5374Maximizes a window. This API uses a promise to return the result. This API is applicable to windows that can be maximized. 5375 5376> **NOTE** 5377> 5378> This API takes effect only on tablets and PCs/2-in-1 devices. 5379 5380**Atomic service API**: This API can be used in atomic services since API version 11. 5381 5382**System capability**: SystemCapability.Test.UiTest 5383 5384**Return value** 5385 5386| Type | Description | 5387|----------------|-----------------| 5388| Promise\<void> | Promise that returns no value.| 5389 5390**Error codes** 5391 5392For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5393 5394| ID| Error Message | 5395| -------- | ---------------------------------------- | 5396| 17000002 | The async function is not called with await. | 5397| 17000004 | The window or component is invisible or destroyed. | 5398| 17000005 | This operation is not supported. | 5399 5400**Example** 5401 5402```ts 5403import { Driver, UiWindow } from '@kit.TestKit'; 5404async function demo() { 5405 let driver: Driver = Driver.create(); 5406 let window: UiWindow = await driver.findWindow({actived: true}); 5407 await window.maximize(); 5408} 5409``` 5410 5411### minimize<sup>9+</sup> 5412 5413minimize(): Promise\<void> 5414 5415Minimizes a window. This API uses a promise to return the result. This API is applicable to windows that can be minimized. 5416 5417> **NOTE** 5418> 5419> This API takes effect only on tablets and PCs/2-in-1 devices. 5420 5421**Atomic service API**: This API can be used in atomic services since API version 11. 5422 5423**System capability**: SystemCapability.Test.UiTest 5424 5425**Return value** 5426 5427| Type | Description | 5428|----------------|-----------------| 5429| Promise\<void> | Promise that returns no value.| 5430 5431**Error codes** 5432 5433For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5434 5435| ID| Error Message | 5436| -------- | ---------------------------------------- | 5437| 17000002 | The async function is not called with await. | 5438| 17000004 | The window or component is invisible or destroyed. | 5439| 17000005 | This operation is not supported. | 5440 5441**Example** 5442 5443```ts 5444import { Driver, UiWindow } from '@kit.TestKit'; 5445async function demo() { 5446 let driver: Driver = Driver.create(); 5447 let window: UiWindow = await driver.findWindow({actived: true}); 5448 await window.minimize(); 5449} 5450``` 5451 5452### resume<sup>9+</sup> 5453 5454resume(): Promise\<void> 5455 5456Restores a window to its previous mode. This API uses a promise to return the result. 5457 5458> **NOTE** 5459> 5460> This API takes effect only on tablets and PCs/2-in-1 devices. 5461 5462**Atomic service API**: This API can be used in atomic services since API version 11. 5463 5464**System capability**: SystemCapability.Test.UiTest 5465 5466**Return value** 5467 5468| Type | Description | 5469|----------------|-----------------| 5470| Promise\<void> | Promise that returns no value.| 5471 5472**Error codes** 5473 5474For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5475 5476| ID| Error Message | 5477| -------- | ---------------------------------------- | 5478| 17000002 | The async function is not called with await. | 5479| 17000004 | The window or component is invisible or destroyed. | 5480| 17000005 | This operation is not supported. | 5481 5482**Example** 5483 5484```ts 5485import { Driver, UiWindow } from '@kit.TestKit'; 5486async function demo() { 5487 let driver: Driver = Driver.create(); 5488 let window: UiWindow = await driver.findWindow({actived: true}); 5489 await window.resume(); 5490} 5491``` 5492 5493### close<sup>9+</sup> 5494 5495close(): Promise\<void> 5496 5497Closes a window. This API uses a promise to return the result. 5498 5499> **NOTE** 5500> 5501> This API takes effect only on tablets and PCs/2-in-1 devices. 5502 5503**Atomic service API**: This API can be used in atomic services since API version 11. 5504 5505**System capability**: SystemCapability.Test.UiTest 5506 5507**Return value** 5508 5509| Type | Description | 5510|----------------|-----------------| 5511| Promise\<void> | Promise that returns no value.| 5512 5513**Error codes** 5514 5515For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5516 5517| ID| Error Message | 5518| -------- | ---------------------------------------- | 5519| 17000002 | The async function is not called with await. | 5520| 17000004 | The window or component is invisible or destroyed. | 5521| 17000005 | This operation is not supported. | 5522 5523**Example** 5524 5525```ts 5526import { Driver, UiWindow } from '@kit.TestKit'; 5527async function demo() { 5528 let driver:Driver = Driver.create(); 5529 let window: UiWindow = await driver.findWindow({actived: true}); 5530 await window.close(); 5531} 5532``` 5533 5534### isActive<sup>11+</sup> 5535 5536isActive(): Promise\<boolean> 5537 5538Checks whether this window is active. This API uses a promise to return the result. 5539 5540**Atomic service API**: This API can be used in atomic services since API version 11. 5541 5542**System capability**: SystemCapability.Test.UiTest 5543 5544**Return value** 5545 5546| Type | Description | 5547| ----------------- | ------------------------------------------------------------ | 5548| Promise\<boolean> | Promise used to return whether the window is active. The value **true** indicates that the window is active, and **false** indicates the opposite.| 5549 5550**Error codes** 5551 5552For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5553 5554| ID| Error Message | 5555| -------- | ------------------------------------------------ | 5556| 17000002 | The async function is not called with await. | 5557| 17000004 | The window or component is invisible or destroyed. | 5558 5559**Example** 5560 5561```ts 5562import { Driver, UiWindow } from '@kit.TestKit'; 5563async function demo() { 5564 let driver: Driver = Driver.create(); 5565 let window: UiWindow = await driver.findWindow({active: true}); 5566 let focused = await window.isActive(); 5567} 5568``` 5569 5570### getDisplayId<sup>20+</sup> 5571 5572getDisplayId(): Promise\<number> 5573 5574Obtains the ID of the display to which the window belongs. This API uses a promise to return the result. 5575 5576**Atomic service API**: This API can be used in atomic services since API version 20. 5577 5578**System capability**: SystemCapability.Test.UiTest 5579 5580**Return value** 5581 5582| Type | Description | 5583| ---------------- |----------------------| 5584| Promise\<number> | Promise used to return the ID of the display to which the window belongs.| 5585 5586**Error codes** 5587 5588For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5589 5590| ID| Error Message | 5591| -------- | ---------------------------------------- | 5592| 17000002 | The async function is not called with await. | 5593| 17000004 | The window or component is invisible or destroyed. | 5594 5595**Example** 5596 5597```ts 5598import { UiWindow, Driver } from '@kit.TestKit'; 5599 5600async function demo() { 5601 let driver: Driver = Driver.create(); 5602 let window: UiWindow = await driver.findWindow({active: true}); 5603 let id = await window.getDisplayId(); 5604} 5605``` 5606 5607## UIEventObserver<sup>10+</sup> 5608 5609UI event listener. 5610 5611### once('toastShow') 5612 5613once(type: 'toastShow', callback: Callback\<UIElementInfo>): void; 5614 5615Subscribes to events of the toast component. This API uses a callback to return the result. 5616 5617**Atomic service API**: This API can be used in atomic services since API version 11. 5618 5619**System capability**: SystemCapability.Test.UiTest 5620 5621**Parameters** 5622 5623| Name | Type | Mandatory| Description | 5624| -------- | -------------------------------------------- | ---- | --------------------------------- | 5625| type | string | Yes | Event type. The value is fixed at **'toastShow'**.| 5626| callback | Callback\<[UIElementInfo](#uielementinfo10)> | Yes | Callback used to return the result. | 5627 5628**Error codes** 5629 5630For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5631 5632| ID| Error Message | 5633| -------- | ------------------------------------------------------------ | 5634| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 5635 5636**Example** 5637 5638```ts 5639import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit'; 5640 5641async function demo() { 5642 let driver: Driver = Driver.create(); 5643 let observer: UIEventObserver = await driver.createUIEventObserver(); 5644 let callback = (UIElementInfo: UIElementInfo)=>{ 5645 console.info(UIElementInfo.bundleName); 5646 console.info(UIElementInfo.text); 5647 console.info(UIElementInfo.type); 5648 } 5649 observer.once('toastShow', callback); 5650} 5651``` 5652 5653### once('dialogShow') 5654 5655once(type: 'dialogShow', callback: Callback\<UIElementInfo>): void; 5656 5657Subscribes to events of the dialog component. This API uses a callback to return the result. 5658 5659**Atomic service API**: This API can be used in atomic services since API version 11. 5660 5661**System capability**: SystemCapability.Test.UiTest 5662 5663**Parameters** 5664 5665| Name | Type | Mandatory| Description | 5666| -------- | -------------------------------------------- | ---- | ---------------------------------- | 5667| type | string | Yes | Event type. The value is fixed at **'dialogShow'**.| 5668| callback | Callback\<[UIElementInfo](#uielementinfo10)> | Yes | Callback used to return the result. | 5669 5670**Error codes** 5671 5672For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5673 5674| ID| Error Message | 5675| -------- | ------------------------------------------------------------ | 5676| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 5677 5678**Example** 5679 5680```ts 5681import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit'; 5682 5683async function demo() { 5684 let driver: Driver = Driver.create(); 5685 let observer: UIEventObserver = await driver.createUIEventObserver(); 5686 let callback = (UIElementInfo: UIElementInfo)=>{ 5687 console.info(UIElementInfo.bundleName); 5688 console.info(UIElementInfo.text); 5689 console.info(UIElementInfo.type); 5690 } 5691 observer.once('dialogShow', callback); 5692} 5693``` 5694 5695## By<sup>(deprecated)</sup> 5696 5697The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components.<br> 5698The APIs provided by the **By** class exhibit the following features:<br>1. Allow one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component.<br>2. Provide multiple match patterns for component attributes.<br>3. Support absolute positioning and relative positioning for components. APIs such as [By.isBefore<sup>(deprecated)</sup>](#isbeforedeprecated) and [By.isAfter<sup>(deprecated)</sup>](#isafterdeprecated) can be used to specify the features of adjacent components to assist positioning.<br>All APIs provided in the **By** class are synchronous. You are advised to use the static constructor **BY** to create a **By** object in chain mode. 5699 5700This class is deprecated since API version 9. You are advised to use [On<sup>9+</sup>](#on9) instead. 5701 5702```ts 5703import { BY } from '@kit.TestKit'; 5704BY.text('123').type('Button'); 5705``` 5706 5707### text<sup>(deprecated)</sup> 5708 5709text(txt: string, pattern?: MatchPattern): By 5710 5711Specifies the text attribute of the target component. Multiple match patterns are supported. 5712 5713This API is deprecated since API version 9. You are advised to use [text<sup>9+</sup>](#text9) instead. 5714 5715**System capability**: SystemCapability.Test.UiTest 5716 5717**Parameters** 5718 5719| Name | Type | Mandatory| Description | 5720| ------- | ----------------------------- | ---- | --------------------------------------------------- | 5721| txt | string | Yes | Component text, used to match the target component. | 5722| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 5723 5724**Return value** 5725 5726| Type | Description | 5727| ------------------- | ---------------------------------- | 5728| [By](#bydeprecated) | **By** object that matches the text attribute of the target component.| 5729 5730**Example** 5731 5732```ts 5733import { BY, By } from '@kit.TestKit'; 5734let by: By = BY.text('123'); // Use the static constructor BY to create a By object and specify the text attribute of the target component. 5735``` 5736 5737 5738### key<sup>(deprecated)</sup> 5739 5740key(key: string): By 5741 5742Specifies the key attribute of the target component. 5743 5744This API is deprecated since API version 9. You are advised to use [id<sup>9+</sup>](#id9) instead. 5745 5746**System capability**: SystemCapability.Test.UiTest 5747 5748**Parameters** 5749 5750| Name| Type | Mandatory| Description | 5751| ------ | ------ | ---- | ----------------- | 5752| key | string | Yes | Component key.| 5753 5754**Return value** 5755 5756| Type | Description | 5757| ------------------- | ----------------------------------- | 5758| [By](#bydeprecated) | **By** object that matches the key attribute of the target component.| 5759 5760**Example** 5761 5762```ts 5763import { By, BY } from '@kit.TestKit'; 5764let by: By = BY.key('123'); // Use the static constructor BY to create a By object and specify the key attribute of the target component. 5765``` 5766 5767 5768### id<sup>(deprecated)</sup> 5769 5770id(id: number): By 5771 5772Specifies the ID attribute of the target component. 5773 5774This API is deprecated since API version 9. 5775 5776**System capability**: SystemCapability.Test.UiTest 5777 5778**Parameters** 5779 5780| Name| Type | Mandatory| Description | 5781| ------ | ------ | ---- | ---------------- | 5782| id | number | Yes | Component ID.| 5783 5784**Return value** 5785 5786| Type | Description | 5787| ------------------- | -------------------------------- | 5788| [By](#bydeprecated) | **By** object that matches the ID attribute of the target component.| 5789 5790**Example** 5791 5792```ts 5793import { By, BY } from '@kit.TestKit'; 5794let by: By = BY.id(123); // Use the static constructor BY to create a By object and specify the id attribute of the target component. 5795``` 5796 5797 5798### type<sup>(deprecated)</sup> 5799 5800type(tp: string): By 5801 5802Specifies the type attribute of the target component. 5803 5804This API is deprecated since API version 9. You are advised to use [type<sup>9+</sup>](#type9) instead. 5805 5806**System capability**: SystemCapability.Test.UiTest 5807 5808**Parameters** 5809 5810| Name| Type | Mandatory| Description | 5811| ------ | ------ | ---- | -------------- | 5812| tp | string | Yes | Component type.| 5813 5814**Return value** 5815 5816| Type | Description | 5817| ------------------- | ---------------------------------------- | 5818| [By](#bydeprecated) | **By** object that matches the type attribute of the target component.| 5819 5820**Example** 5821 5822```ts 5823import { By, BY } from '@kit.TestKit'; 5824let by: By = BY.type('Button'); // Use the static constructor BY to create a By object and specify the type attribute of the target component. 5825``` 5826 5827 5828### clickable<sup>(deprecated)</sup> 5829 5830clickable(b?: boolean): By 5831 5832Specifies the clickable attribute of the target component. 5833 5834This API is deprecated since API version 9. You are advised to use [clickable<sup>9+</sup>](#clickable9) instead. 5835 5836**System capability**: SystemCapability.Test.UiTest 5837 5838**Parameters** 5839 5840| Name| Type | Mandatory| Description | 5841| ------ | ------- | ---- | ------------------------------------------------------------ | 5842| b | boolean | No | Clickable status of the component. The value **true** indicates that the component is clickable, and **false** indicates the opposite. Default value: **true**| 5843 5844**Return value** 5845 5846| Type | Description | 5847| ------------------- | ------------------------------------------ | 5848| [By](#bydeprecated) | **By** object that matches the clickable attribute of the target component.| 5849 5850**Example** 5851 5852```ts 5853import { By, BY } from '@kit.TestKit'; 5854let by: By = BY.clickable(true); // Use the static constructor BY to create a By object and specify the clickable attribute of the target component. 5855``` 5856 5857 5858### scrollable<sup>(deprecated)</sup> 5859 5860scrollable(b?: boolean): By 5861 5862Specifies the scrollable attribute of the target component. 5863 5864This API is deprecated since API version 9. You are advised to use [scrollable<sup>9+</sup>](#scrollable9) instead. 5865 5866**System capability**: SystemCapability.Test.UiTest 5867 5868**Parameters** 5869 5870| Name| Type | Mandatory| Description | 5871| ------ | ------- | ---- | ----------------------------------------------------------- | 5872| b | boolean | No | Scrollable status of the component. The value **true** indicates that the component is scrollable, and **false** indicates the opposite. Default value: **true**| 5873 5874**Return value** 5875 5876| Type | Description | 5877| ------------------- | ------------------------------------------ | 5878| [By](#bydeprecated) | **By** object that matches the scrollable attribute of the target component.| 5879 5880**Example** 5881 5882```ts 5883import { By, BY } from '@kit.TestKit'; 5884let by: By = BY.scrollable(true); // Use the static constructor BY to create a By object and specify the scrollable attribute of the target component. 5885``` 5886 5887### enabled<sup>(deprecated)</sup> 5888 5889enabled(b?: boolean): By 5890 5891Specifies the enabled attribute of the target component. 5892 5893This API is deprecated since API version 9. You are advised to use [enabled<sup>9+</sup>](#enabled9) instead. 5894 5895**System capability**: SystemCapability.Test.UiTest 5896 5897**Parameters** 5898 5899| Name| Type | Mandatory| Description | 5900| ------ | ------- | ---- | --------------------------------------------------------- | 5901| b | boolean | No | Enabled status of the component. The value **true** indicates that the component is enabled, and **false** indicates the opposite. Default value: **true**| 5902 5903**Return value** 5904 5905| Type | Description | 5906| ------------------- | ---------------------------------------- | 5907| [By](#bydeprecated) | **By** object that matches the enabled attribute of the target component.| 5908 5909**Example** 5910 5911```ts 5912import { By, BY } from '@kit.TestKit'; 5913let by: By = BY.enabled(true); // Use the static constructor BY to create a By object and specify the enabled attribute of the target component. 5914``` 5915 5916### focused<sup>(deprecated)</sup> 5917 5918focused(b?: boolean): By 5919 5920Specifies the focused attribute of the target component. 5921 5922This API is deprecated since API version 9. You are advised to use [focused<sup>9+</sup>](#focused9) instead. 5923 5924**System capability**: SystemCapability.Test.UiTest 5925 5926**Parameters** 5927 5928| Name| Type | Mandatory| Description | 5929| ------ | ------- | ---- | ----------------------------------------------------- | 5930| b | boolean | No | Focused status of the component. The value **true** indicates that the component is focused, and **false** indicates the opposite. Default value: **true**| 5931 5932**Return value** 5933 5934| Type | Description | 5935| ------------------- | ---------------------------------------- | 5936| [By](#bydeprecated) | **By** object that matches the focused attribute of the target component.| 5937 5938**Example** 5939 5940```ts 5941import { By, BY } from '@kit.TestKit'; 5942let by: By = BY.focused(true); // Use the static constructor BY to create a By object and specify the focused attribute of the target component. 5943``` 5944 5945### selected<sup>(deprecated)</sup> 5946 5947selected(b?: boolean): By 5948 5949Specifies the selected status of the target component. 5950 5951This API is deprecated since API version 9. You are advised to use [selected<sup>9+</sup>](#selected9) instead. 5952 5953**System capability**: SystemCapability.Test.UiTest 5954 5955**Parameters** 5956 5957| Name| Type | Mandatory| Description | 5958| ------ | ------- | ---- | ------------------------------------------------------------ | 5959| b | boolean | No | Selected status of the component. The value **true** indicates that the component is selected, and **false** indicates the opposite. Default value: **true**| 5960 5961**Return value** 5962 5963| Type | Description | 5964| ------------------- | ------------------------------------------ | 5965| [By](#bydeprecated) | **By** object that matches the selected attribute of the target component.| 5966 5967**Example** 5968 5969```ts 5970import { By, BY } from '@kit.TestKit'; 5971let by: By = BY.selected(true); // Use the static constructor BY to create a By object and specify the selected attribute of the target component. 5972``` 5973 5974### isBefore<sup>(deprecated)</sup> 5975 5976isBefore(by: By): By 5977 5978Specifies that the target component is located before the given attribute component. 5979 5980This API is deprecated since API version 9. You are advised to use [isBefore<sup>9+</sup>](#isbefore9) instead. 5981 5982**System capability**: SystemCapability.Test.UiTest 5983 5984**Parameters** 5985 5986| Name| Type | Mandatory| Description | 5987| ------ | ------------------- | ---- | ---------------- | 5988| by | [By](#bydeprecated) | Yes | Information about the attribute component.| 5989 5990**Return value** 5991 5992| Type | Description | 5993| ------------------- | ---------------------------------------------------- | 5994| [By](#bydeprecated) | **By** object.| 5995 5996**Example** 5997 5998```ts 5999import { By, BY } from '@kit.TestKit'; 6000 6001// Use the static constructor BY to create a by object and specify that the target component is located before the given attribute component. 6002let by: By = BY.type('Button').isBefore(BY.text('123')); // Search for the first <Button> component located before the component whose text is 123. 6003``` 6004 6005### isAfter<sup>(deprecated)</sup> 6006 6007isAfter(by: By): By 6008 6009Specifies that the target component is located after the given attribute component. 6010 6011This API is deprecated since API version 9. You are advised to use [isAfter<sup>9+</sup>](#isafter9) instead. 6012 6013**System capability**: SystemCapability.Test.UiTest 6014 6015**Parameters** 6016 6017| Name| Type | Mandatory| Description | 6018| ------ | ------------------- | ---- | ---------------- | 6019| by | [By](#bydeprecated) | Yes | Information about the attribute component.| 6020 6021**Return value** 6022 6023| Type | Description | 6024| ------------------- | ---------------------------------------------------- | 6025| [By](#bydeprecated) | **By** object.| 6026 6027**Example** 6028 6029```ts 6030import { By, BY } from '@kit.TestKit'; 6031 6032// Use the static constructor BY to create a by object and specify that the target component is located after the given attribute component. 6033let by: By = BY.type('Text').isAfter(BY.text('123')); // Search for the first <Text> component located after the component whose text is 123. 6034``` 6035 6036## UiComponent<sup>(deprecated)</sup> 6037 6038In **UiTest**, the **UiComponent** class represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. 6039All APIs provided in this class use a promise to return the result and must be invoked using **await**. 6040 6041This class is deprecated since API version 9. You are advised to use [Component<sup>9+</sup>](#component9) instead. 6042 6043### click<sup>(deprecated)</sup> 6044 6045click(): Promise\<void> 6046 6047Clicks this component. 6048 6049This API is deprecated since API version 9. You are advised to use [click<sup>9+</sup>](#click9) instead. 6050 6051**System capability**: SystemCapability.Test.UiTest 6052 6053**Example** 6054 6055```ts 6056import { UiDriver, BY, Driver, UiComponent } from '@kit.TestKit'; 6057async function demo() { 6058 let driver: UiDriver = UiDriver.create(); 6059 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6060 await button.click(); 6061} 6062``` 6063 6064### doubleClick<sup>(deprecated)</sup> 6065 6066doubleClick(): Promise\<void> 6067 6068Double-clicks this component. 6069 6070This API is deprecated since API version 9. You are advised to use [doubleClick<sup>9+</sup>](#doubleclick9) instead. 6071 6072**System capability**: SystemCapability.Test.UiTest 6073 6074**Example** 6075 6076```ts 6077import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6078async function demo() { 6079 let driver: UiDriver = UiDriver.create(); 6080 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6081 await button.doubleClick(); 6082} 6083``` 6084 6085### longClick<sup>(deprecated)</sup> 6086 6087longClick(): Promise\<void> 6088 6089Long-clicks this component. 6090 6091This API is deprecated since API version 9. You are advised to use [longClick<sup>9+</sup>](#longclick9) instead. 6092 6093**System capability**: SystemCapability.Test.UiTest 6094 6095**Example** 6096 6097```ts 6098import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6099async function demo() { 6100 let driver: UiDriver = UiDriver.create(); 6101 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6102 await button.longClick(); 6103} 6104``` 6105 6106### getId<sup>(deprecated)</sup> 6107 6108getId(): Promise\<number> 6109 6110Obtains the ID of this component. 6111 6112This API is deprecated since API version 9. 6113 6114**System capability**: SystemCapability.Test.UiTest 6115 6116**Return value** 6117 6118| Type | Description | 6119| ---------------- | ------------------------------- | 6120| Promise\<number> | Promise used to return the component ID.| 6121 6122**Example** 6123 6124```ts 6125import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6126async function demo() { 6127 let driver: UiDriver = UiDriver.create(); 6128 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6129 let id = await button.getId(); 6130} 6131``` 6132 6133### getKey<sup>(deprecated)</sup> 6134 6135getKey(): Promise\<string> 6136 6137Obtains the key of this component. 6138 6139This API is deprecated since API version 9. You are advised to use [getId<sup>9+</sup>](#getid9) instead. 6140 6141**System capability**: SystemCapability.Test.UiTest 6142 6143**Return value** 6144 6145| Type | Description | 6146| ---------------- | ------------------------------ | 6147| Promise\<string> | Promise used to return the key value.| 6148 6149**Example** 6150 6151```ts 6152import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6153async function demo() { 6154 let driver: UiDriver = UiDriver.create(); 6155 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6156 let str_key = await button.getKey(); 6157} 6158``` 6159 6160### getText<sup>(deprecated)</sup> 6161 6162getText(): Promise\<string> 6163 6164Obtains the text information of this component. 6165 6166This API is deprecated since API version 9. You are advised to use [getText<sup>9+</sup>](#gettext9) instead. 6167 6168**System capability**: SystemCapability.Test.UiTest 6169 6170**Return value** 6171 6172| Type | Description | 6173| ---------------- | --------------------------------- | 6174| Promise\<string> | Promise used to return the original text information of the component.| 6175 6176**Example** 6177 6178```ts 6179import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6180async function demo() { 6181 let driver: UiDriver = UiDriver.create(); 6182 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6183 let text = await button.getText(); 6184} 6185``` 6186 6187### getType<sup>(deprecated)</sup> 6188 6189getType(): Promise\<string> 6190 6191Obtains the type of this component. 6192 6193This API is deprecated since API version 9. You are advised to use [getType<sup>9+</sup>](#gettype9) instead. 6194 6195**System capability**: SystemCapability.Test.UiTest 6196 6197**Return value** 6198 6199| Type | Description | 6200| ---------------- | ----------------------------- | 6201| Promise\<string> | Promise used to return the component type.| 6202 6203**Example** 6204 6205```ts 6206import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6207async function demo() { 6208 let driver: UiDriver = UiDriver.create(); 6209 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6210 let type = await button.getType(); 6211} 6212``` 6213 6214### isClickable<sup>(deprecated)</sup> 6215 6216isClickable(): Promise\<boolean> 6217 6218Obtains the clickable status of this component. 6219 6220This API is deprecated since API version 9. You are advised to use [isClickable<sup>9+</sup>](#isclickable9) instead. 6221 6222**System capability**: SystemCapability.Test.UiTest 6223 6224**Return value** 6225 6226| Type | Description | 6227| ----------------- | ------------------------------------------------------------ | 6228| Promise\<boolean> | Promise used to return whether the component is clickable. The value **true** indicates that the component is clickable, and **false** indicates the opposite.| 6229 6230**Example** 6231 6232```ts 6233import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6234async function demo() { 6235 let driver: UiDriver = UiDriver.create(); 6236 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6237 if (await button.isClickable()) { 6238 console.info('This button can be Clicked'); 6239 } else { 6240 console.info('This button can not be Clicked'); 6241 } 6242} 6243``` 6244 6245### isScrollable<sup>(deprecated)</sup> 6246 6247isScrollable(): Promise\<boolean> 6248 6249Obtains the scrollable status of this component. 6250 6251This API is deprecated since API version 9. You are advised to use [isScrollable<sup>9+</sup>](#isscrollable9) instead. 6252 6253**System capability**: SystemCapability.Test.UiTest 6254 6255**Return value** 6256 6257| Type | Description | 6258| ----------------- | ------------------------------------------------------------ | 6259| Promise\<boolean> | Promise used to return whether the component is scrollable. The value **true** indicates that the component is scrollable, and **false** indicates the opposite.| 6260 6261**Example** 6262 6263```ts 6264import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6265async function demo() { 6266 let driver: UiDriver = UiDriver.create(); 6267 let scrollBar: UiComponent = await driver.findComponent(BY.scrollable(true)); 6268 if (await scrollBar.isScrollable()) { 6269 console.info('This scrollBar can be operated'); 6270 } else { 6271 console.info('This scrollBar can not be operated'); 6272 } 6273} 6274``` 6275 6276 6277### isEnabled<sup>(deprecated)</sup> 6278 6279isEnabled(): Promise\<boolean> 6280 6281Obtains the enabled status of this component. 6282 6283This API is deprecated since API version 9. You are advised to use [isEnabled<sup>9+</sup>](#isenabled9) instead. 6284 6285**System capability**: SystemCapability.Test.UiTest 6286 6287**Return value** 6288 6289| Type | Description | 6290| ----------------- | ---------------------------------------------------------- | 6291| Promise\<boolean> | Promise used to return whether the component is enabled. The value **true** indicates that the component is enabled, and **false** indicates the opposite.| 6292 6293**Example** 6294 6295```ts 6296import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6297async function demo() { 6298 let driver: UiDriver = UiDriver.create(); 6299 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6300 if (await button.isEnabled()) { 6301 console.info('This button can be operated'); 6302 } else { 6303 console.info('This button can not be operated'); 6304 } 6305} 6306 6307``` 6308 6309### isFocused<sup>(deprecated)</sup> 6310 6311isFocused(): Promise\<boolean> 6312 6313Obtains the focused status of this component. 6314 6315This API is deprecated since API version 9. You are advised to use [isFocused<sup>9+</sup>](#isfocused9) instead. 6316 6317**System capability**: SystemCapability.Test.UiTest 6318 6319**Return value** 6320 6321| Type | Description | 6322| ----------------- | ------------------------------------------------------------ | 6323| Promise\<boolean> | Promise used to return whether the component is focused. The value **true** indicates that the window is focused, and **false** indicates the opposite.| 6324 6325**Example** 6326 6327```ts 6328import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6329async function demo() { 6330 let driver: UiDriver = UiDriver.create(); 6331 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6332 if (await button.isFocused()) { 6333 console.info('This button is focused'); 6334 } else { 6335 console.info('This button is not focused'); 6336 } 6337} 6338``` 6339 6340### isSelected<sup>(deprecated)</sup> 6341 6342isSelected(): Promise\<boolean> 6343 6344Obtains the selected status of this component. 6345 6346This API is deprecated since API version 9. You are advised to use [isSelected<sup>9+</sup>](#isselected9) instead. 6347 6348**System capability**: SystemCapability.Test.UiTest 6349 6350**Return value** 6351 6352| Type | Description | 6353| ----------------- | ----------------------------------------------------- | 6354| Promise\<boolean> | Promise used to return whether the component is selected. The value **true** indicates that the component is selected, and **false** indicates the opposite.| 6355 6356**Example** 6357 6358```ts 6359import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6360async function demo() { 6361 let driver: UiDriver = UiDriver.create(); 6362 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6363 if (await button.isSelected()) { 6364 console.info('This button is selected'); 6365 } else { 6366 console.info('This button is not selected'); 6367 } 6368} 6369``` 6370 6371### inputText<sup>(deprecated)</sup> 6372 6373inputText(text: string): Promise\<void> 6374 6375Inputs text into a component (applicable to text box components). 6376 6377This API is deprecated since API version 9. You are advised to use [inputText<sup>9+</sup>](#inputtext9) instead. 6378 6379**System capability**: SystemCapability.Test.UiTest 6380 6381**Parameters** 6382 6383| Name| Type | Mandatory| Description | 6384| ------ | ------ | ---- | ---------------- | 6385| text | string | Yes | Text to enter.| 6386 6387**Example** 6388 6389```ts 6390import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6391async function demo() { 6392 let driver: UiDriver = UiDriver.create(); 6393 let text: UiComponent = await driver.findComponent(BY.text('hello world')); 6394 await text.inputText('123'); 6395} 6396``` 6397 6398### scrollSearch<sup>(deprecated)</sup> 6399 6400scrollSearch(by: By): Promise\<UiComponent> 6401 6402Scrolls on this component to search for the target component (applicable to components that support scrolling, such as **List**). 6403 6404This API is deprecated since API version 9. You are advised to use [scrollSearch<sup>9+</sup>](#scrollsearch9) instead. 6405 6406**System capability**: SystemCapability.Test.UiTest 6407 6408**Parameters** 6409 6410| Name| Type | Mandatory| Description | 6411| ------ | ------------------- | ---- | -------------------- | 6412| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 6413 6414**Return value** 6415 6416| Type | Description | 6417| ----------------------------------------------- | ------------------------------------- | 6418| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise used to return the target component.| 6419 6420**Example** 6421 6422```ts 6423import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6424async function demo() { 6425 let driver: UiDriver = UiDriver.create(); 6426 let scrollBar: UiComponent = await driver.findComponent(BY.type('Scroll')); 6427 let button = await scrollBar.scrollSearch(BY.text('next page')); 6428} 6429``` 6430 6431## UiDriver<sup>(deprecated)</sup> 6432 6433The **UiDriver** class is the main entry to the UiTest framework. It provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. 6434All APIs provided by this class, except **UiDriver.create()**, use a promise to return the result and must be invoked using **await**. 6435 6436This class is deprecated since API version 9. You are advised to use [Driver<sup>9+</sup>](#driver9) instead. 6437 6438### create<sup>(deprecated)</sup> 6439 6440static create(): UiDriver 6441 6442Creates a **UiDriver** object and returns the object created. This API is a static API. 6443 6444This API is deprecated since API version 9. You are advised to use [create<sup>9+</sup>](#create9) instead. 6445 6446**System capability**: SystemCapability.Test.UiTest 6447 6448**Return value** 6449 6450| Type | Description | 6451| -------- | ------------------------ | 6452| UiDriver | **UiDriver** object created.| 6453 6454**Example** 6455 6456```ts 6457import { UiDriver } from '@kit.TestKit'; 6458async function demo() { 6459 let driver: UiDriver = UiDriver.create(); 6460} 6461``` 6462 6463### delayMs<sup>(deprecated)</sup> 6464 6465delayMs(duration: number): Promise\<void> 6466 6467Delays this **UiDriver** object within the specified duration. 6468 6469This API is deprecated since API version 9. You are advised to use [delayMs<sup>9+</sup>](#delayms9) instead. 6470 6471**System capability**: SystemCapability.Test.UiTest 6472 6473**Parameters** 6474 6475| Name | Type | Mandatory| Description | 6476| -------- | ------ | ---- | ------------ | 6477| duration | number | Yes | Duration of time.| 6478 6479**Example** 6480 6481```ts 6482import { UiDriver } from '@kit.TestKit'; 6483async function demo() { 6484 let driver: UiDriver = UiDriver.create(); 6485 await driver.delayMs(1000); 6486} 6487``` 6488 6489### findComponent<sup>(deprecated)</sup> 6490 6491findComponent(by: By): Promise\<UiComponent> 6492 6493Searches this **UiDriver** object for the target component that matches the given attributes. 6494 6495This API is deprecated since API version 9. You are advised to use [findComponent<sup>9+</sup>](#findcomponent9) instead. 6496 6497**System capability**: SystemCapability.Test.UiTest 6498 6499**Parameters** 6500 6501| Name| Type | Mandatory| Description | 6502| ------ | ------------------- | ---- | -------------------- | 6503| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 6504 6505**Return value** 6506 6507| Type | Description | 6508| ----------------------------------------------- | --------------------------------- | 6509| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise used to return the component.| 6510 6511**Example** 6512 6513```ts 6514import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6515async function demo() { 6516 let driver: UiDriver = UiDriver.create(); 6517 let button: UiComponent = await driver.findComponent(BY.text('next page')); 6518} 6519``` 6520 6521### findComponents<sup>(deprecated)</sup> 6522 6523findComponents(by: By): Promise\<Array\<UiComponent>> 6524 6525Searches this **UiDriver** object for all components that match the given attributes. 6526 6527This API is deprecated since API version 9. You are advised to use [findComponents<sup>9+</sup>](#findcomponents9) instead. 6528 6529**System capability**: SystemCapability.Test.UiTest 6530 6531**Parameters** 6532 6533| Name| Type | Mandatory| Description | 6534| ------ | ------------------- | ---- | -------------------- | 6535| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 6536 6537**Return value** 6538 6539| Type | Description | 6540| ------------------------------------------------------- | --------------------------------------- | 6541| Promise\<Array\<[UiComponent](#uicomponentdeprecated)>> | Promise used to return the list of components.| 6542 6543**Example** 6544 6545```ts 6546import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6547async function demo() { 6548 let driver: UiDriver = UiDriver.create(); 6549 let buttonList: Array<UiComponent> = await driver.findComponents(BY.text('next page')); 6550} 6551``` 6552 6553### assertComponentExist<sup>(deprecated)</sup> 6554 6555assertComponentExist(by: By): Promise\<void> 6556 6557Asserts that a component that matches the given attributes exists on the current page. If the component does not exist, the API throws a JS exception, causing the current test case to fail. 6558 6559This API is deprecated since API version 9. You are advised to use [assertComponentExist<sup>9+</sup>](#assertcomponentexist9) instead. 6560 6561**System capability**: SystemCapability.Test.UiTest 6562 6563**Parameters** 6564 6565| Name| Type | Mandatory| Description | 6566| ------ | ------------------- | ---- | -------------------- | 6567| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 6568 6569**Error codes** 6570 6571For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 6572 6573| ID| Error Message | 6574| -------- | ------------------------------------------------ | 6575| 401 | if the input parameters are invalid. | 6576| 17000002 | if the async function was not called with await. | 6577| 17000003 | if the assertion failed. | 6578 6579**Example** 6580 6581```ts 6582import { UiDriver, BY } from '@kit.TestKit'; 6583async function demo() { 6584 let driver: UiDriver = UiDriver.create(); 6585 await driver.assertComponentExist(BY.text('next page')); 6586} 6587``` 6588 6589### pressBack<sup>(deprecated)</sup> 6590 6591pressBack(): Promise\<void> 6592 6593Presses the Back button on this **UiDriver** object. 6594 6595This API is deprecated since API version 9. You are advised to use [pressBack<sup>9+</sup>](#pressback9) instead. 6596 6597**System capability**: SystemCapability.Test.UiTest 6598 6599**Example** 6600 6601```ts 6602import { UiDriver } from '@kit.TestKit'; 6603async function demo() { 6604 let driver: UiDriver = UiDriver.create(); 6605 await driver.pressBack(); 6606} 6607``` 6608 6609### triggerKey<sup>(deprecated)</sup> 6610 6611triggerKey(keyCode: number): Promise\<void> 6612 6613Triggers the key of this **UiDriver** object that matches the given key code. 6614 6615This API is deprecated since API version 9. You are advised to use [triggerKey<sup>9+</sup>](#triggerkey9) instead. 6616 6617**System capability**: SystemCapability.Test.UiTest 6618 6619**Parameters** 6620 6621| Name | Type | Mandatory| Description | 6622| ------- | ------ | ---- | ------------- | 6623| keyCode | number | Yes | Key value. The value is an integer greater than or equal to 0. For details, see [KeyCode](../apis-input-kit/js-apis-keycode.md#keycode).| 6624 6625**Example** 6626 6627```ts 6628import { Driver, UiDriver } from '@kit.TestKit'; 6629async function demo() { 6630 let driver: UiDriver = UiDriver.create(); 6631 await driver.triggerKey(123); 6632} 6633``` 6634 6635 6636### click<sup>(deprecated)</sup> 6637 6638click(x: number, y: number): Promise\<void> 6639 6640Clicks a specific point of this **UiDriver** object based on the given coordinates. 6641 6642This API is deprecated since API version 9. You are advised to use [click<sup>9+</sup>](#click9) instead. 6643 6644**System capability**: SystemCapability.Test.UiTest 6645 6646**Parameters** 6647 6648| Name| Type | Mandatory| Description | 6649| ------ | ------ | ---- | -------------------------------------- | 6650| x | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.| 6651| y | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.| 6652 6653**Example** 6654 6655```ts 6656import { UiDriver } from '@kit.TestKit'; 6657 6658async function demo() { 6659 let driver: UiDriver = UiDriver.create(); 6660 await driver.click(100, 100); 6661} 6662``` 6663 6664### doubleClick<sup>(deprecated)</sup> 6665 6666doubleClick(x: number, y: number): Promise\<void> 6667 6668Double-clicks a specific point of this **UiDriver** object based on the given coordinates. 6669 6670This API is deprecated since API version 9. You are advised to use [doubleClick<sup>9+</sup>](#doubleclick9) instead. 6671 6672**System capability**: SystemCapability.Test.UiTest 6673 6674**Parameters** 6675 6676| Name| Type | Mandatory| Description | 6677| ------ | ------ | ---- | -------------------------------------- | 6678| x | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.| 6679| y | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.| 6680 6681**Example** 6682 6683```ts 6684import { UiDriver } from '@kit.TestKit'; 6685 6686async function demo() { 6687 let driver: UiDriver = UiDriver.create(); 6688 await driver.doubleClick(100, 100); 6689} 6690``` 6691 6692### longClick<sup>(deprecated)</sup> 6693 6694longClick(x: number, y: number): Promise\<void> 6695 6696Long-clicks a specific point of this **UiDriver** object based on the given coordinates. 6697 6698This API is deprecated since API version 9. You are advised to use [longClick<sup>9+</sup>](#longclick9) instead. 6699 6700**System capability**: SystemCapability.Test.UiTest 6701 6702**Parameters** 6703 6704| Name| Type | Mandatory| Description | 6705| ------ | ------ | ---- | -------------------------------------- | 6706| x | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.| 6707| y | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.| 6708 6709**Example** 6710 6711```ts 6712import { UiDriver } from '@kit.TestKit'; 6713async function demo() { 6714 let driver: UiDriver = UiDriver.create(); 6715 await driver.longClick(100, 100); 6716} 6717``` 6718 6719### swipe<sup>(deprecated)</sup> 6720 6721swipe(startx: number, starty: number, endx: number, endy: number): Promise\<void> 6722 6723Swipes on this **UiDriver** object from the start point to the end point based on the given coordinates. 6724 6725This API is deprecated since API version 9. You are advised to use [swipe<sup>9+</sup>](#swipe9) instead. 6726 6727**System capability**: SystemCapability.Test.UiTest 6728 6729**Parameters** 6730 6731| Name| Type | Mandatory| Description | 6732| ------ | ------ | ---- | -------------------------------------- | 6733| startx | number | Yes | Number, which indicates the horizontal coordinate of the start point. The value is an integer greater than or equal to 0.| 6734| starty | number | Yes | Number, which indicates the vertical coordinate of the start point. The value is an integer greater than or equal to 0.| 6735| endx | number | Yes | Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.| 6736| endy | number | Yes | Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.| 6737 6738**Example** 6739 6740```ts 6741import { UiDriver } from '@kit.TestKit'; 6742 6743async function demo() { 6744 let driver: UiDriver = UiDriver.create(); 6745 await driver.swipe(100, 100, 200, 200); 6746} 6747``` 6748 6749### screenCap<sup>(deprecated)</sup> 6750 6751screenCap(savePath: string): Promise\<boolean> 6752 6753Captures the current screen of this **UiDriver** object and saves it as a PNG image to the given save path. 6754 6755This API is deprecated since API version 9. You are advised to use [screenCap<sup>9+</sup>](#screencap9) instead. 6756 6757**System capability**: SystemCapability.Test.UiTest 6758 6759**Parameters** 6760 6761| Name | Type | Mandatory| Description | 6762| -------- | ------ | ---- | -------------- | 6763| savePath | string | Yes | File save path.| 6764 6765**Return value** 6766 6767 6768| Type | Description | 6769| ----------------- |-----------------------------------------------| 6770| Promise\<boolean> | Promise used to return whether the screenshot operation is successful. The value **true** indicates the screenshot operation is successful, and **false** indicates the opposite.| 6771 6772**Example** 6773 6774```ts 6775import { UiDriver } from '@kit.TestKit'; 6776async function demo() { 6777 let driver: UiDriver = UiDriver.create(); 6778 await driver.screenCap('/data/storage/el2/base/cache/1.png'); 6779} 6780``` 6781
