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 can be used on mobile phones, tablets, 2-in-1 devices, and smart wearable devices. 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**Atomic service API**: This API can be used in atomic services since API version 11. 66 67**System capability**: SystemCapability.Test.UiTest 68 69| Name| Type | Readable| Writable| Description | 70| ---- | ------ | ---- | ---- | ---------------- | 71| x | number | Yes | No | X coordinate of a point.| 72| y | number | Yes | No | Y coordinate of a point.| 73 74## Rect<sup>9+</sup> 75 76Provides bounds information of a component. 77 78**Atomic service API**: This API can be used in atomic services since API version 11. 79 80**System capability**: SystemCapability.Test.UiTest 81 82| Name | Type | Readable| Writable| Description | 83| ------ | ------ | ---- | ---- | ------------------------- | 84| left | number | Yes | No | X coordinate of the upper left corner of the component bounds.| 85| top | number | Yes | No | Y coordinate of the upper left corner of the component bounds.| 86| right | number | Yes | No | X coordinate of the lower right corner of the component bounds.| 87| bottom | number | Yes | No | Y coordinate of the lower right corner of the component bounds.| 88 89## WindowMode<sup>9+</sup> 90 91Enumerates the window modes. 92 93**Atomic service API**: This API can be used in atomic services since API version 11. 94 95**System capability**: SystemCapability.Test.UiTest 96 97| Name | Value | Description | 98| ---------- | ---- | ---------- | 99| FULLSCREEN | 0 | Full-screen mode.| 100| PRIMARY | 1 | Primary window mode. | 101| SECONDARY | 2 | Secondary window mode.| 102| FLOATING | 3 | Floating window mode.| 103 104## DisplayRotation<sup>9+</sup> 105 106Describes the display rotation of the device. 107 108**Atomic service API**: This API can be used in atomic services since API version 11. 109 110**System capability**: SystemCapability.Test.UiTest 111 112| Name | Value | Description | 113| ------------ | ---- | ---------------------------------------- | 114| ROTATION_0 | 0 | The device display is not rotated and is in its original vertical orientation. | 115| ROTATION_90 | 1 | The device display rotates 90° clockwise and is in landscape orientation. | 116| ROTATION_180 | 2 | The device display rotates 180° clockwise and is in reverse vertical orientation.| 117| ROTATION_270 | 3 | The device display rotates 270° clockwise and is in reverse landscape orientation.| 118 119## WindowFilter<sup>9+</sup> 120 121Provides the flag attributes of this window. 122 123**System capability**: SystemCapability.Test.UiTest 124 125| Name | Type | Readable| Writable| Description | 126| -------------------- | ------- | ---- | ---- | ------------------------------------------------------------ | 127| bundleName | string | Yes | No | Bundle name of the application to which the window belongs.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 128| title | string | Yes | No | Title of the window.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 129| focused | boolean | Yes | No | Whether the window is in focused state.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 130| actived(deprecated) | boolean | Yes | No | Whether the window is interacting with the user.<br>Since API version 11, this parameter is renamed **active**.| 131| active<sup>11+</sup> | boolean | Yes | No | Whether the window is interacting with the user.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 132 133## UiDirection<sup>10+</sup> 134 135Describes the direction of a UI operation such as fling. 136 137**Atomic service API**: This API can be used in atomic services since API version 11. 138 139**System capability**: SystemCapability.Test.UiTest 140 141| Name | Value | Description | 142| ----- | ---- | ------ | 143| LEFT | 0 | Leftward.| 144| RIGHT | 1 | Rightward.| 145| UP | 2 | Upward.| 146| DOWN | 3 | Downward.| 147 148## MouseButton<sup>10+</sup> 149 150Describes the injected simulated mouse button. 151 152**Atomic service API**: This API can be used in atomic services since API version 11. 153 154**System capability**: SystemCapability.Test.UiTest 155 156| Name | Value | Description | 157| ------------------- | ---- | ------------ | 158| MOUSE_BUTTON_LEFT | 0 | Left button on the mouse. | 159| MOUSE_BUTTON_RIGHT | 1 | Right button on the mouse. | 160| MOUSE_BUTTON_MIDDLE | 2 | Middle button on the mouse.| 161 162## UIElementInfo<sup>10+</sup> 163 164Provides information about the UI event. 165 166**Atomic service API**: This API can be used in atomic services since API version 11. 167 168**System capability**: SystemCapability.Test.UiTest 169 170| Name | Type | Readable| Writable| Description | 171| ---------- | ------ | ---- | ---- | --------------------- | 172| bundleName | string | Yes | No | Bundle name of the home application. | 173| type | string | Yes | No | Component or window type. | 174| text | string | Yes | No | Text information of the component or window.| 175 176 177## TouchPadSwipeOptions<sup>18+</sup> 178 179Describes information about the touchpad swipe gesture option. 180 181**Atomic service API**: This API can be used in atomic services since API version 18. 182 183**System capability**: SystemCapability.Test.UiTest 184 185| Name | Type | Readable| Writable| Description | 186| ---------- | ------ |----|----|----------------------------------------------------------| 187| stay | boolean | No | Yes | Whether to hold fingers on the touchpad for 1s after swiping. The default value is **false**. | 188| speed | number | No | Yes | Swipe speed, in px/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value **2000** is used.| 189 190## On<sup>9+</sup> 191 192Since 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> 193The 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. 194 195```ts 196import { ON } from '@kit.TestKit'; 197 198ON.text('123').type('Button'); 199``` 200 201### text<sup>9+</sup> 202 203text(txt: string, pattern?: MatchPattern): On 204 205Specifies the text attribute of the target component. Multiple match patterns are supported. 206 207**Atomic service API**: This API can be used in atomic services since API version 11. 208 209**System capability**: SystemCapability.Test.UiTest 210 211**Parameters** 212 213| Name | Type | Mandatory| Description | 214| ------- | ----------------------------- | ---- | --------------------------------------------------- | 215| txt | string | Yes | Component text, used to match the target component. | 216| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 217 218**Return value** 219 220| Type | Description | 221| ---------- | ---------------------------------- | 222| [On](#on9) | **On** object that matches the text attribute of the target component.| 223 224**Error codes** 225 226For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 227 228| ID| Error Message | 229| -------- | ------------------------------------------------------------ | 230| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 231 232**Example** 233 234```ts 235import { On, ON } from '@kit.TestKit'; 236let on:On = ON.text('123'); // Use the static constructor ON to create an On object and specify the text attribute of the target component. 237``` 238 239### id<sup>9+</sup> 240 241id(id: string): On 242 243Specifies the ID attribute of the target component. 244 245**Atomic service API**: This API can be used in atomic services since API version 11. 246 247**System capability**: SystemCapability.Test.UiTest 248 249**Parameters** 250 251| Name| Type | Mandatory| Description | 252| ------ | ------ | ---- | ---------------- | 253| id | string | Yes | Component ID.| 254 255**Return value** 256 257| Type | Description | 258| ---------- | -------------------------------- | 259| [On](#on9) | **On** object that matches the ID attribute of the target component.| 260 261**Error codes** 262 263For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 264 265| ID| Error Message | 266| -------- | ------------------------------------------------------------ | 267| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 268 269**Example** 270 271```ts 272import { On, ON } from '@kit.TestKit'; 273 274let on:On = ON.id('123'); // Use the static constructor ON to create an On object and specify the id attribute of the target component. 275``` 276 277### id<sup>18+</sup> 278 279id(id: string, pattern?: MatchPattern): On 280 281Specifies the ID attribute of the target component. 282 283**Atomic service API**: This API can be used in atomic services since API version 18. 284 285**System capability**: SystemCapability.Test.UiTest 286 287**Parameters** 288 289| Name | Type | Mandatory| Description | 290|-----------------------| ------ |----|---------------------------------------| 291| id | string | Yes | Component ID. | 292| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 293 294**Return value** 295 296| Type | Description | 297| ---------- | -------------------------------- | 298| [On](#on9) | **On** object that matches the ID attribute of the target component.| 299 300**Error codes** 301 302For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 303 304| ID| Error Message | 305| -------- | ------------------------------------------------------------ | 306| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 307 308**Example** 309 310```ts 311import { MatchPattern, On, ON } from '@kit.TestKit'; 312let on:On = ON.id('id', MatchPattern.REG_EXP_ICASE) // Use case-insensitive regular expression to match the ID attribute value of the component. 313``` 314 315### type<sup>9+</sup> 316 317type(tp: string): On 318 319Specifies the type attribute of the target component. 320 321>**NOTE** 322> 323>You can define the type of the component. In addition, you can use [DevEco Testing](https://developer.huawei.com/consumer/cn/download) to query the type information of the component. 324 325**Atomic service API**: This API can be used in atomic services since API version 11. 326 327**System capability**: SystemCapability.Test.UiTest 328 329**Parameters** 330 331| Name| Type | Mandatory| Description | 332| ------ | ------ | ---- | -------------- | 333| tp | string | Yes | Component type.| 334 335**Return value** 336 337| Type | Description | 338| ---------- | ---------------------------------------- | 339| [On](#on9) | **On** object that matches the type attribute of the target component.| 340 341**Error codes** 342 343For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 344 345| ID| Error Message | 346| -------- | ------------------------------------------------------------ | 347| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 348 349**Example** 350 351```ts 352import { On, ON } from '@kit.TestKit'; 353let on:On = ON.type('Button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component. 354``` 355 356### type<sup>18+</sup> 357 358type(tp: string, pattern?: MatchPattern): On 359 360Specifies the type attribute of the target component. 361 362>**NOTE** 363> 364>You can define the type of the component. In addition, you can use [DevEco Testing](https://developer.huawei.com/consumer/cn/download) to query the type information of the component. 365 366**Atomic service API**: This API can be used in atomic services since API version 18. 367 368**System capability**: SystemCapability.Test.UiTest 369 370**Parameters** 371 372| Name | Type | Mandatory| Description | 373|-----------------------| ------ | ---- |---------------------------------------| 374| tp | string | Yes | Component type. | 375| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 376 377**Return value** 378 379| Type | Description | 380| ---------- | ---------------------------------------- | 381| [On](#on9) | **On** object that matches the type attribute of the target component.| 382 383**Error codes** 384 385For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 386 387| ID| Error Message | 388| -------- | ------------------------------------------------------------ | 389| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 390 391**Example** 392 393```ts 394import { On, ON } from '@kit.TestKit'; 395let on:On = ON.type('Button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component. 396``` 397 398### clickable<sup>9+</sup> 399 400clickable(b?: boolean): On 401 402Specifies the clickable attribute of the target component. 403 404**Atomic service API**: This API can be used in atomic services since API version 11. 405 406**System capability**: SystemCapability.Test.UiTest 407 408**Parameters** 409 410| Name| Type | Mandatory| Description | 411| ------ | ------- | ---- | ------------------------------------------------------------ | 412| b | boolean | No | Clickable status of the target component.<br>**true**: clickable.<br>**false**: not clickable.<br> Default value: **true**| 413 414**Return value** 415 416| Type | Description | 417| ---------- | ------------------------------------------ | 418| [On](#on9) | **On** object that matches the clickable attribute of the target component.| 419 420**Error codes** 421 422For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 423 424| ID| Error Message | 425| -------- | ------------------------------------------------------------ | 426| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 427 428**Example** 429 430```ts 431import { On, ON } from '@kit.TestKit'; 432let on:On = ON.clickable(true); // Use the static constructor ON to create an On object and specify the clickable attribute of the target component. 433``` 434 435### longClickable<sup>9+</sup> 436 437longClickable(b?: boolean): On 438 439Specifies the long-clickable attribute of the target component. 440 441**Atomic service API**: This API can be used in atomic services since API version 11. 442 443**System capability**: SystemCapability.Test.UiTest 444 445**Parameters** 446 447| Name| Type | Mandatory| Description | 448| ------ | ------- | ---- | ------------------------------------------------------------ | 449| b | boolean | No | Long-clickable status of the target component.<br>**true**: long-clickable.<br>**false**: not long-clickable.<br> Default value: **true**| 450 451**Return value** 452 453| Type | Description | 454| ---------- | ---------------------------------------------- | 455| [On](#on9) | **On** object that matches the long-clickable attribute of the target component.| 456 457**Error codes** 458 459For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 460 461| ID| Error Message | 462| -------- | ------------------------------------------------------------ | 463| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 464 465**Example** 466 467```ts 468import { On, ON } from '@kit.TestKit'; 469let on:On = ON.longClickable(true); // Use the static constructor ON to create an On object and specify the longClickable attribute of the target component. 470``` 471 472 473### scrollable<sup>9+</sup> 474 475scrollable(b?: boolean): On 476 477Specifies the scrollable attribute of the target component. 478 479**Atomic service API**: This API can be used in atomic services since API version 11. 480 481**System capability**: SystemCapability.Test.UiTest 482 483**Parameters** 484 485| Name| Type | Mandatory| Description | 486| ------ | ------- | ---- | ----------------------------------------------------------- | 487| b | boolean | No | Scrollable status of the target component.<br>**true**: scrollable.<br>**false**: not scrollable.<br> Default value: **true**| 488 489**Return value** 490 491| Type | Description | 492| ---------- | ------------------------------------------ | 493| [On](#on9) | **On** object that matches the scrollable attribute of the target component.| 494 495**Error codes** 496 497For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 498 499| ID| Error Message | 500| -------- | ------------------------------------------------------------ | 501| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 502 503**Example** 504 505```ts 506import { On, ON } from '@kit.TestKit'; 507let on:On = ON.scrollable(true); // Use the static constructor ON to create an On object and specify the scrollable attribute of the target component. 508``` 509 510### enabled<sup>9+</sup> 511 512enabled(b?: boolean): On 513 514Specifies the enabled attribute of the target component. 515 516**Atomic service API**: This API can be used in atomic services since API version 11. 517 518**System capability**: SystemCapability.Test.UiTest 519 520**Parameters** 521 522| Name| Type | Mandatory| Description | 523| ------ | ------- | ---- | --------------------------------------------------------- | 524| b | boolean | No | Enabled status of the target component.<br>**true**: enabled.<br>**false**: not enabled.<br> Default value: **true**| 525 526**Return value** 527 528| Type | Description | 529| ---------- | ---------------------------------------- | 530| [On](#on9) | **On** object that matches the enabled attribute of the target component.| 531 532**Error codes** 533 534For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 535 536| ID| Error Message | 537| -------- | ------------------------------------------------------------ | 538| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 539 540**Example** 541 542```ts 543import { On, ON } from '@kit.TestKit'; 544let on:On = ON.enabled(true); // Use the static constructor ON to create an On object and specify the enabled attribute of the target component. 545``` 546 547### focused<sup>9+</sup> 548 549focused(b?: boolean): On 550 551Specifies the focused attribute of the target component. 552 553**Atomic service API**: This API can be used in atomic services since API version 11. 554 555**System capability**: SystemCapability.Test.UiTest 556 557**Parameters** 558 559| Name| Type | Mandatory| Description | 560| ------ | ------- | ---- | ----------------------------------------------------- | 561| b | boolean | No | Focused status of the target component.<br>**true**: focused.<br>**false**: not focused.<br> Default value: **true**| 562 563**Return value** 564 565| Type | Description | 566| ---------- | ---------------------------------------- | 567| [On](#on9) | **On** object that matches the focused attribute of the target component.| 568 569**Error codes** 570 571For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 572 573| ID| Error Message | 574| -------- | ------------------------------------------------------------ | 575| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 576 577**Example** 578 579```ts 580import { On, ON } from '@kit.TestKit'; 581let on:On = ON.focused(true); // Use the static constructor ON to create an On object and specify the focused attribute of the target component. 582``` 583 584### selected<sup>9+</sup> 585 586selected(b?: boolean): On 587 588Specifies the selected attribute of the target component. 589 590**Atomic service API**: This API can be used in atomic services since API version 11. 591 592**System capability**: SystemCapability.Test.UiTest 593 594**Parameters** 595 596| Name| Type | Mandatory| Description | 597| ------ | ------- | ---- | ------------------------------------------------------------ | 598| b | boolean | No | Selected status of the target component.<br>**true**: selected.<br>**false**: not selected.<br> Default value: **true**| 599 600**Return value** 601 602| Type | Description | 603| ---------- | ------------------------------------------ | 604| [On](#on9) | **On** object that matches the selected attribute of the target component.| 605 606**Error codes** 607 608For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 609 610| ID| Error Message | 611| -------- | ------------------------------------------------------------ | 612| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 613 614**Example** 615 616```ts 617import { On, ON } from '@kit.TestKit'; 618let on:On = ON.selected(true); // Use the static constructor ON to create an On object and specify the selected attribute of the target component. 619``` 620 621### checked<sup>9+</sup> 622 623checked(b?: boolean): On 624 625Specifies the checked attribute of the target component. 626 627**Atomic service API**: This API can be used in atomic services since API version 11. 628 629**System capability**: SystemCapability.Test.UiTest 630 631**Parameters** 632 633| Name| Type | Mandatory| Description | 634| ------ | ------- | ---- | ------------------------------------------------------------ | 635| b | boolean | No | Checked status of the target component.<br>**true**: checked.<br>**false**: not checked.<br> Default value: **false**| 636 637**Return value** 638 639| Type | Description | 640| ---------- | ------------------------------------------ | 641| [On](#on9) | **On** object that matches the checked attribute of the target component.| 642 643**Error codes** 644 645For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 646 647| ID| Error Message | 648| -------- | ------------------------------------------------------------ | 649| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 650 651**Example** 652 653```ts 654import { On, ON } from '@kit.TestKit'; 655let on:On = ON.checked(true); // Use the static constructor ON to create an On object and specify the checked attribute of the target component. 656``` 657 658### checkable<sup>9+</sup> 659 660checkable(b?: boolean): On 661 662Specifies the checkable attribute of the target component. 663 664**Atomic service API**: This API can be used in atomic services since API version 11. 665 666**System capability**: SystemCapability.Test.UiTest 667 668**Parameters** 669 670| Name| Type | Mandatory| Description | 671| ------ | ------- | ---- | ------------------------------------------------------------ | 672| b | boolean | No | Checkable status of the target component.<br>**true**: checkable.<br>**false**: not checkable.<br> Default value: **false**| 673 674**Return value** 675 676| Type | Description | 677| ---------- | -------------------------------------------- | 678| [On](#on9) | **On** object that matches the checkable attribute of the target component.| 679 680**Error codes** 681 682For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 683 684| ID| Error Message | 685| -------- | ------------------------------------------------------------ | 686| 401 | Parameter error. 1. Incorrect parameter types; 2. Parameter verification failed. | 687 688**Example** 689 690```ts 691import { On, ON } from '@kit.TestKit'; 692let on:On = ON.checkable(true); // Use the static constructor ON to create an On object and specify the checkable attribute of the target component. 693``` 694 695### isBefore<sup>9+</sup> 696 697isBefore(on: On): On 698 699Specifies that the target component is located before the given attribute component. 700 701**Atomic service API**: This API can be used in atomic services since API version 11. 702 703**System capability**: SystemCapability.Test.UiTest 704 705**Parameters** 706 707| Name| Type | Mandatory| Description | 708| ------ | ---------- | ---- | -------------------- | 709| on | [On](#on9) | Yes | Information about the attribute component.| 710 711**Return value** 712 713| Type | Description | 714| ---------- | ---------------------------------------------------- | 715| [On](#on9) | **On** object.| 716 717**Error codes** 718 719For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 720 721| ID| Error Message | 722| -------- | ------------------------------------------------------------ | 723| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 724 725**Example** 726 727```ts 728import { On, ON } from '@kit.TestKit'; 729 730// Use the static constructor ON to create an On object and specify that the target component is located before the given attribute component. 731let on:On = ON.type('Button').isBefore(ON.text('123')); // Search for the first <Button> component located before the component whose text is 123. 732``` 733 734### isAfter<sup>9+</sup> 735 736isAfter(on: On): On 737 738Specifies that the target component is located after the given attribute component. 739 740**Atomic service API**: This API can be used in atomic services since API version 11. 741 742**System capability**: SystemCapability.Test.UiTest 743 744**Parameters** 745 746| Name| Type | Mandatory| Description | 747| ------ | ---------- | ---- | -------------------- | 748| on | [On](#on9) | Yes | Information about the attribute component.| 749 750**Return value** 751 752| Type | Description | 753| ---------- | ---------------------------------------------------- | 754| [On](#on9) | **On** object.| 755 756**Error codes** 757 758For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 759 760| ID| Error Message | 761| -------- | ------------------------------------------------------------ | 762| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 763 764**Example** 765 766```ts 767import { On, ON } from '@kit.TestKit'; 768 769// Use the static constructor ON to create an On object and specify that the target component is located after the given attribute component. 770let on:On = ON.type('Text').isAfter(ON.text('123')) // Search for the first <Text> component located after the component whose text is 123. 771``` 772 773### within<sup>10+</sup> 774 775within(on: On): On 776 777Specifies that the target component is located within the given attribute component. 778 779**Atomic service API**: This API can be used in atomic services since API version 11. 780 781**System capability**: SystemCapability.Test.UiTest 782 783**Parameters** 784 785| Name| Type | Mandatory| Description | 786| ------ | ---------- | ---- | -------------------- | 787| on | [On](#on9) | Yes | Information about the attribute component.| 788 789**Return value** 790 791| Type | Description | 792| ---------- | -------------------------------------------------- | 793| [On](#on9) | **On** object.| 794 795**Error codes** 796 797For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 798 799| ID| Error Message | 800| -------- | ------------------------------------------------------------ | 801| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 802 803**Example** 804 805```ts 806import { On, ON } from '@kit.TestKit'; 807// Use the static constructor ON to create an On object and specify that the target component is located within the given attribute component. 808let on:On = ON.text('java').within(ON.type('Scroll')); // Search for the child component whose text is java within the <Scroller> component. 809``` 810 811### inWindow<sup>10+</sup> 812 813inWindow(bundleName: string): On; 814 815Specifies that the target component is located within the given application window. 816 817**Atomic service API**: This API can be used in atomic services since API version 11. 818 819**System capability**: SystemCapability.Test.UiTest 820 821**Parameters** 822 823| Name | Type | Mandatory| Description | 824| ---------- | ------ | ---- | ---------------- | 825| bundleName | string | Yes | Bundle name of the application window.| 826 827**Return value** 828 829| Type | Description | 830| ---------- | ---------------------------------------------- | 831| [On](#on9) | **On** object.| 832 833**Error codes** 834 835For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 836 837| ID| Error Message | 838| -------- | ------------------------------------------------------------ | 839| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 840 841**Example** 842 843```ts 844import { On, ON } from '@kit.TestKit'; 845let 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. 846``` 847 848### description<sup>11+</sup> 849 850description(val: string, pattern?: MatchPattern): On 851 852Specifies the description of the target component. Multiple match patterns are supported. 853 854**Atomic service API**: This API can be used in atomic services since API version 11. 855 856**System capability**: SystemCapability.Test.UiTest 857 858**Parameters** 859 860| Name | Type | Mandatory| Description | 861| ------- | ----------------------------- | ---- | --------------------------------------------------- | 862| val | string | Yes | Description of the component. | 863| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 864 865**Return value** 866 867| Type | Description | 868| ---------- | ----------------------------------------- | 869| [On](#on9) | **On** object.| 870 871**Error codes** 872 873For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 874 875| ID| Error Message | 876| -------- | ------------------------------------------------------------ | 877| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 878 879**Example** 880 881```ts 882import { On, ON } from '@kit.TestKit'; 883let on:On = ON.description('123'); // Use the static constructor ON to create an On object and specify the description attribute of the target component. 884``` 885 886### hint<sup>18+</sup> 887 888hint(val: string, pattern?: MatchPattern): On 889 890Obtains the component object of the specified hint text and returns the **On** object. 891 892**Atomic service API**: This API can be used in atomic services since API version 18. 893 894**System capability**: SystemCapability.Test.UiTest 895 896**Parameters** 897 898| Name| Type | Mandatory| Description | 899| ------ | ------ |----|---------------------------------------| 900| val | string | Yes | The specified hint text of the component. | 901| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 902 903**Return value** 904 905| Type | Description | 906| ---------- | ---------------------------------------- | 907| [On](#on9) | The **On** object of the specified hint text component.| 908 909**Error codes** 910 911For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 912 913| ID| Error Message | 914| -------- | ------------------------------------------------------------ | 915| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 916 917**Example** 918 919```ts 920 import { MatchPattern, On, ON } from '@kit.TestKit'; 921 922 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. 923``` 924 925## Component<sup>9+</sup> 926 927Represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. 928All APIs provided in this class use a promise to return the result and must be invoked using **await**. 929 930### click<sup>9+</sup> 931 932click(): Promise\<void> 933 934Clicks this component. 935 936**Atomic service API**: This API can be used in atomic services since API version 11. 937 938**System capability**: SystemCapability.Test.UiTest 939 940**Error codes** 941 942For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 943 944| ID| Error Message | 945| -------- | ---------------------------------------- | 946| 17000002 | The async function is not called with await. | 947| 17000004 | The window or component is invisible or destroyed. | 948 949**Example** 950 951```ts 952import { Driver, ON, Component } from '@kit.TestKit'; 953async function demo() { 954 let driver:Driver = Driver.create(); 955 let button: Component = await driver.findComponent(ON.type('Button')); 956 await button.click(); 957} 958``` 959 960### doubleClick<sup>9+</sup> 961 962doubleClick(): Promise\<void> 963 964Double-clicks this component. 965 966**Atomic service API**: This API can be used in atomic services since API version 11. 967 968**System capability**: SystemCapability.Test.UiTest 969 970**Error codes** 971 972For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 973 974| ID| Error Message | 975| -------- | ---------------------------------------- | 976| 17000002 | The async function is not called with await. | 977| 17000004 | The window or component is invisible or destroyed. | 978 979**Example** 980 981```ts 982import {Component, Driver, ON } from '@kit.TestKit'; 983async function demo() { 984 let driver: Driver = Driver.create(); 985 let button: Component = await driver.findComponent(ON.type('Button')); 986 await button.doubleClick(); 987} 988``` 989 990### longClick<sup>9+</sup> 991 992longClick(): Promise\<void> 993 994Long-clicks this component. 995 996**Atomic service API**: This API can be used in atomic services since API version 11. 997 998**System capability**: SystemCapability.Test.UiTest 999 1000**Error codes** 1001 1002For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1003 1004| ID| Error Message | 1005| -------- | ---------------------------------------- | 1006| 17000002 | The async function is not called with await. | 1007| 17000004 | The window or component is invisible or destroyed. | 1008 1009**Example** 1010 1011```ts 1012import { Component, Driver, ON } from '@kit.TestKit'; 1013async function demo() { 1014 let driver: Driver = Driver.create(); 1015 let button: Component = await driver.findComponent(ON.type('Button')); 1016 await button.longClick(); 1017} 1018``` 1019 1020### getId<sup>9+</sup> 1021 1022getId(): Promise\<string> 1023 1024Obtains the ID of this component. 1025 1026**Atomic service API**: This API can be used in atomic services since API version 11. 1027 1028**System capability**: SystemCapability.Test.UiTest 1029 1030**Return value** 1031 1032| Type | Description | 1033| ---------------- | ------------------------------- | 1034| Promise\<string> | Promise used to return the ID of the component.| 1035 1036**Error codes** 1037 1038For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1039 1040| ID| Error Message | 1041| -------- | ---------------------------------------- | 1042| 17000002 | The async function is not called with await. | 1043| 17000004 | The window or component is invisible or destroyed. | 1044 1045**Example** 1046 1047```ts 1048import { Component, Driver, ON } from '@kit.TestKit'; 1049async function demo() { 1050 let driver: Driver = Driver.create(); 1051 let button: Component = await driver.findComponent(ON.type('Button')); 1052 let id = await button.getId(); 1053} 1054``` 1055 1056### getText<sup>9+</sup> 1057 1058getText(): Promise\<string> 1059 1060Obtains the text information of this component. 1061 1062**Atomic service API**: This API can be used in atomic services since API version 11. 1063 1064**System capability**: SystemCapability.Test.UiTest 1065 1066**Return value** 1067 1068| Type | Description | 1069| ---------------- | --------------------------------- | 1070| Promise\<string> | Promise used to return the text information of the component.| 1071 1072**Error codes** 1073 1074For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1075 1076| ID| Error Message | 1077| -------- | ---------------------------------------- | 1078| 17000002 | The async function is not called with await. | 1079| 17000004 | The window or component is invisible or destroyed. | 1080 1081**Example** 1082 1083```ts 1084import { Component, Driver, ON } from '@kit.TestKit'; 1085async function demo() { 1086 let driver: Driver = Driver.create(); 1087 let button: Component = await driver.findComponent(ON.type('Button')); 1088 let text = await button.getText(); 1089} 1090``` 1091 1092### getType<sup>9+</sup> 1093 1094getType(): Promise\<string> 1095 1096Obtains the type of this component. 1097 1098**Atomic service API**: This API can be used in atomic services since API version 11. 1099 1100**System capability**: SystemCapability.Test.UiTest 1101 1102**Return value** 1103 1104| Type | Description | 1105| ---------------- | ----------------------------- | 1106| Promise\<string> | Promise used to return the type of the component.| 1107 1108**Error codes** 1109 1110For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1111 1112| ID| Error Message | 1113| -------- | ---------------------------------------- | 1114| 17000002 | The async function is not called with await. | 1115| 17000004 | The window or component is invisible or destroyed. | 1116 1117**Example** 1118 1119```ts 1120import { Component, Driver, ON } from '@kit.TestKit'; 1121async function demo() { 1122 let driver: Driver = Driver.create(); 1123 let button: Component = await driver.findComponent(ON.type('Button')); 1124 let type = await button.getType(); 1125} 1126``` 1127 1128### getBounds<sup>9+</sup> 1129 1130getBounds(): Promise\<Rect> 1131 1132Obtains the bounds of this component. 1133 1134**Atomic service API**: This API can be used in atomic services since API version 11. 1135 1136**System capability**: SystemCapability.Test.UiTest 1137 1138**Return value** 1139 1140| Type | Description | 1141| ------------------------ | ------------------------------------- | 1142| Promise\<[Rect](#rect9)> | Promise used to return the bounds of the component.| 1143 1144**Error codes** 1145 1146For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1147 1148| ID| Error Message | 1149| -------- | ---------------------------------------- | 1150| 17000002 | The async function is not called with await. | 1151| 17000004 | The window or component is invisible or destroyed. | 1152 1153**Example** 1154 1155```ts 1156import { Component, Driver, ON } from '@kit.TestKit'; 1157async function demo() { 1158 let driver: Driver = Driver.create(); 1159 let button: Component = await driver.findComponent(ON.type('Button')); 1160 let rect = await button.getBounds(); 1161} 1162``` 1163 1164### getBoundsCenter<sup>9+</sup> 1165 1166getBoundsCenter(): Promise\<Point> 1167 1168Obtains the information about the center of the bounding box around this component. 1169 1170**Atomic service API**: This API can be used in atomic services since API version 11. 1171 1172**System capability**: SystemCapability.Test.UiTest 1173 1174**Return value** 1175 1176| Type | Description | 1177| -------------------------- | ----------------------------------------------- | 1178| Promise\<[Point](#point9)> | Promise used to return the information about the center of the bounding box around the component.| 1179 1180**Error codes** 1181 1182For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1183 1184| ID| Error Message | 1185| -------- | ---------------------------------------- | 1186| 17000002 | The async function is not called with await. | 1187| 17000004 | The window or component is invisible or destroyed. | 1188 1189**Example** 1190 1191```ts 1192import { Component, Driver, ON } from '@kit.TestKit'; 1193async function demo() { 1194 let driver: Driver = Driver.create(); 1195 let button: Component = await driver.findComponent(ON.type('Button')); 1196 let point = await button.getBoundsCenter(); 1197} 1198``` 1199 1200### isClickable<sup>9+</sup> 1201 1202isClickable(): Promise\<boolean> 1203 1204Obtains the clickable status of this component. 1205 1206**Atomic service API**: This API can be used in atomic services since API version 11. 1207 1208**System capability**: SystemCapability.Test.UiTest 1209 1210**Return value** 1211 1212| Type | Description | 1213| ----------------- | ------------------------------------------------------------ | 1214| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is clickable, and **false** means the opposite.| 1215 1216**Error codes** 1217 1218For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1219 1220| ID| Error Message | 1221| -------- | ---------------------------------------- | 1222| 17000002 | The async function is not called with await. | 1223| 17000004 | The window or component is invisible or destroyed. | 1224 1225**Example** 1226 1227```ts 1228import { Component, Driver, ON } from '@kit.TestKit'; 1229async function demo() { 1230 let driver: Driver = Driver.create(); 1231 let button: Component = await driver.findComponent(ON.type('Button')); 1232 if(await button.isClickable()) { 1233 console.info('This button can be Clicked'); 1234 } else { 1235 console.info('This button can not be Clicked'); 1236 } 1237} 1238``` 1239 1240### isLongClickable<sup>9+</sup> 1241 1242isLongClickable(): Promise\<boolean> 1243 1244Obtains the long-clickable status of this component. 1245 1246**Atomic service API**: This API can be used in atomic services since API version 11. 1247 1248**System capability**: SystemCapability.Test.UiTest 1249 1250**Return value** 1251 1252| Type | Description | 1253| ----------------- |--------------------------------------------------| 1254| Promise\<boolean> | Promise used to return the long-clickable status of the component. The value **true** means that the component is long-clickable, and **false** means the opposite.| 1255 1256**Error codes** 1257 1258For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1259 1260| ID| Error Message | 1261| -------- | ---------------------------------------- | 1262| 17000002 | The async function is not called with await. | 1263| 17000004 | The window or component is invisible or destroyed. | 1264 1265**Example** 1266 1267```ts 1268import { Component, Driver, ON } from '@kit.TestKit'; 1269async function demo() { 1270 let driver: Driver = Driver.create(); 1271 let button: Component = await driver.findComponent(ON.type('Button')); 1272 if(await button.isLongClickable()) { 1273 console.info('This button can longClick'); 1274 } else { 1275 console.info('This button can not longClick'); 1276 } 1277} 1278``` 1279 1280### isChecked<sup>9+</sup> 1281 1282isChecked(): Promise\<boolean> 1283 1284Obtains the checked status of this component. 1285 1286**Atomic service API**: This API can be used in atomic services since API version 11. 1287 1288**System capability**: SystemCapability.Test.UiTest 1289 1290**Return value** 1291 1292| Type | Description | 1293| ----------------- | ------------------------------------------------------------ | 1294| Promise\<boolean> | Promise used to return the checked status of the component. The value **true** means that the component is checked, and **false** means the opposite.| 1295 1296**Error codes** 1297 1298For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1299 1300| ID| Error Message | 1301| -------- | ---------------------------------------- | 1302| 17000002 | The async function is not called with await. | 1303| 17000004 | The window or component is invisible or destroyed. | 1304 1305**Example** 1306 1307```ts 1308import { Component, Driver, ON } from '@kit.TestKit'; 1309async function demo() { 1310 let driver: Driver = Driver.create(); 1311 let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); 1312 if(await checkBox.isChecked()) { 1313 console.info('This checkBox is checked'); 1314 } else { 1315 console.info('This checkBox is not checked'); 1316 } 1317} 1318``` 1319 1320### isCheckable<sup>9+</sup> 1321 1322isCheckable(): Promise\<boolean> 1323 1324Obtains the checkable status of this component. 1325 1326**Atomic service API**: This API can be used in atomic services since API version 11. 1327 1328**System capability**: SystemCapability.Test.UiTest 1329 1330**Return value** 1331 1332| Type | Description | 1333| ----------------- | ------------------------------------------------------------ | 1334| Promise\<boolean> | Promise used to return the checkable status of the component. The value **true** means that the component is checkable, and **false** means the opposite.| 1335 1336**Error codes** 1337 1338For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1339 1340| ID| Error Message | 1341| -------- | ---------------------------------------- | 1342| 17000002 | The async function is not called with await. | 1343| 17000004 | The window or component is invisible or destroyed. | 1344 1345**Example** 1346 1347```ts 1348import { Component, Driver, ON } from '@kit.TestKit'; 1349async function demo() { 1350 let driver: Driver = Driver.create(); 1351 let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); 1352 if(await checkBox.isCheckable()) { 1353 console.info('This checkBox is checkable'); 1354 } else { 1355 console.info('This checkBox is not checkable'); 1356 } 1357} 1358``` 1359 1360### isScrollable<sup>9+</sup> 1361 1362isScrollable(): Promise\<boolean> 1363 1364Obtains the scrollable status of this component. 1365 1366**Atomic service API**: This API can be used in atomic services since API version 11. 1367 1368**System capability**: SystemCapability.Test.UiTest 1369 1370**Return value** 1371 1372| Type | Description | 1373| ----------------- | ------------------------------------------------------------ | 1374| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is scrollable, and **false** means the opposite.| 1375 1376**Error codes** 1377 1378For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1379 1380| ID| Error Message | 1381| -------- | ---------------------------------------- | 1382| 17000002 | The async function is not called with await. | 1383| 17000004 | The window or component is invisible or destroyed. | 1384 1385**Example** 1386 1387```ts 1388import { Component, Driver, ON } from '@kit.TestKit'; 1389async function demo() { 1390 let driver: Driver = Driver.create(); 1391 let scrollBar: Component = await driver.findComponent(ON.scrollable(true)); 1392 if(await scrollBar.isScrollable()) { 1393 console.info('This scrollBar can be operated'); 1394 } else { 1395 console.info('This scrollBar can not be operated'); 1396 } 1397} 1398``` 1399 1400 1401### isEnabled<sup>9+</sup> 1402 1403isEnabled(): Promise\<boolean> 1404 1405Obtains the enabled status of this component. 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 result. The value **true** means that the component is enabled, and **false** means 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 button: Component = await driver.findComponent(ON.type('Button')); 1433 if(await button.isEnabled()) { 1434 console.info('This button can be operated'); 1435 } else { 1436 console.info('This button can not be operated'); 1437 } 1438} 1439``` 1440 1441### isFocused<sup>9+</sup> 1442 1443isFocused(): Promise\<boolean> 1444 1445Obtains the focused status of this component. 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 the focused status of the component. The value **true** means that the component is focused, and **false** means 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 button: Component = await driver.findComponent(ON.type('Button')); 1473 if(await button.isFocused()) { 1474 console.info('This button is focused'); 1475 } else { 1476 console.info('This button is not focused'); 1477 } 1478} 1479``` 1480 1481### isSelected<sup>9+</sup> 1482 1483isSelected(): Promise\<boolean> 1484 1485Obtains the selected status of this component. 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 the selected status of the component. The value **true** means that the component is selected, and **false** means 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 button: Component = await driver.findComponent(ON.type('Button')); 1513 if(await button.isSelected()) { 1514 console.info('This button is selected'); 1515 } else { 1516 console.info('This button is not selected'); 1517 } 1518} 1519``` 1520 1521### inputText<sup>9+</sup> 1522 1523inputText(text: string): Promise\<void> 1524 1525Inputs text to a component after the original text in the component is cleared. This API is applicable to text box components. 1526 1527**Atomic service API**: This API can be used in atomic services since API version 11. 1528 1529**System capability**: SystemCapability.Test.UiTest 1530 1531**Parameters** 1532 1533| Name| Type | Mandatory| Description | 1534| ------ | ------ | ---- | ---------------------------------------- | 1535| text | string | Yes | Input text. Currently, English, Chinese, and special characters are supported.<br> **Note**: For wearables, this API does not support Chinese characters.| 1536 1537**Error codes** 1538 1539For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1540 1541| ID| Error Message | 1542| -------- | ---------------------------------------- | 1543| 17000002 | The async function is not called with await. | 1544| 17000004 | The window or component is invisible or destroyed. | 1545| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1546 1547**Example** 1548 1549```ts 1550import { Component, Driver, ON } from '@kit.TestKit'; 1551async function demo() { 1552 let driver: Driver = Driver.create(); 1553 let text: Component = await driver.findComponent(ON.text('hello world')); 1554 await text.inputText('123'); 1555} 1556``` 1557 1558### clearText<sup>9+</sup> 1559 1560clearText(): Promise\<void> 1561 1562Clears text in this component. This API is applicable to text boxes. 1563 1564**Atomic service API**: This API can be used in atomic services since API version 11. 1565 1566**System capability**: SystemCapability.Test.UiTest 1567 1568**Error codes** 1569For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1570 1571| ID| Error Message | 1572| -------- | ---------------------------------------- | 1573| 17000002 | The async function is not called with await. | 1574| 17000004 | The window or component is invisible or destroyed. | 1575 1576**Example** 1577 1578```ts 1579import { Component, Driver, ON } from '@kit.TestKit'; 1580async function demo() { 1581 let driver: Driver = Driver.create(); 1582 let text: Component = await driver.findComponent(ON.text('hello world')); 1583 await text.clearText(); 1584} 1585``` 1586 1587### scrollSearch<sup>9+</sup> 1588 1589scrollSearch(on: On): Promise\<Component> 1590 1591Scrolls 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. 1592 1593**Atomic service API**: This API can be used in atomic services since API version 11. 1594 1595**System capability**: SystemCapability.Test.UiTest 1596 1597**Parameters** 1598 1599| Name| Type | Mandatory| Description | 1600| ------ | ---------- | ---- | -------------------- | 1601| on | [On](#on9) | Yes | Attributes of the target component.| 1602 1603**Return value** 1604 1605| Type | Description | 1606| ---------------------------------- | ------------------------------------- | 1607| Promise\<[Component](#component9)> | Promise used to return the target component.| 1608 1609**Error codes** 1610 1611For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1612 1613| ID| Error Message | 1614| -------- | ---------------------------------------- | 1615| 17000002 | The async function is not called with await. | 1616| 17000004 | The window or component is invisible or destroyed. | 1617| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1618 1619**Example** 1620 1621```ts 1622import { Component, Driver, ON } from '@kit.TestKit'; 1623 1624async function demo() { 1625 let driver: Driver = Driver.create(); 1626 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1627 let button = await scrollBar.scrollSearch(ON.text('next page')); 1628} 1629``` 1630 1631### scrollSearch<sup>18+</sup> 1632 1633scrollSearch(on: On, vertical?: boolean, offset?: number): Promise\<Component> 1634 1635Scrolls 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. 1636 1637**Atomic service API**: This API can be used in atomic services since API version 18. 1638 1639**System capability**: SystemCapability.Test.UiTest 1640 1641**Parameters** 1642 1643| Name | Type | Mandatory| Description | 1644|------------------------| ---------- | ---- |-----------------------------------| 1645| on | [On](#on9) | Yes | Attributes of the target component. | 1646| 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.| 1647| offset | number| No| Offset from the scrolling start point or end point to the component border, in pixels. The default value is **80**. | 1648 1649**Return value** 1650 1651| Type | Description | 1652| ---------------------------------- | ------------------------------------- | 1653| Promise\<[Component](#component9)> | Promise used to return the target component.| 1654 1655**Error codes** 1656 1657For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 1658 1659| ID| Error Message | 1660| -------- | ---------------------------------------- | 1661| 17000002 | The async function is not called with await. | 1662| 17000004 | The window or component is invisible or destroyed. | 1663| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1664 1665**Example** 1666 1667```ts 1668import { Component, Driver, ON } from '@kit.TestKit'; 1669async function demo() { 1670 let driver: Driver = Driver.create(); 1671 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1672 let button = await scrollBar.scrollSearch(ON.text('next page')); 1673} 1674``` 1675 1676### scrollToTop<sup>9+</sup> 1677 1678scrollToTop(speed?: number): Promise\<void> 1679 1680Scrolls to the top of this component. This API is applicable to components that support scrolling. 1681 1682**Atomic service API**: This API can be used in atomic services since API version 11. 1683 1684**System capability**: SystemCapability.Test.UiTest 1685 1686**Parameters** 1687 1688| Name| Type | Mandatory| Description | 1689| ------ | ------ | ---- |--------------------------------------------------------| 1690| 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.| 1691 1692**Error codes** 1693 1694For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1695 1696| ID| Error Message | 1697| -------- | ---------------------------------------- | 1698| 17000002 | The async function is not called with await. | 1699| 17000004 | The window or component is invisible or destroyed. | 1700| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 1701 1702**Example** 1703 1704```ts 1705import { Component, Driver, ON } from '@kit.TestKit'; 1706async function demo() { 1707 let driver: Driver = Driver.create(); 1708 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1709 await scrollBar.scrollToTop(); 1710} 1711``` 1712 1713### scrollToBottom<sup>9+</sup> 1714 1715scrollToBottom(speed?: number): Promise\<void> 1716 1717Scrolls to the bottom of this component. This API is applicable to components that support scrolling. 1718 1719**Atomic service API**: This API can be used in atomic services since API version 11. 1720 1721**System capability**: SystemCapability.Test.UiTest 1722 1723**Parameters** 1724 1725| Name| Type | Mandatory| Description | 1726| ------ | ------ | ---- |--------------------------------------------------------| 1727| 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.| 1728 1729**Error codes** 1730 1731For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1732 1733| ID| Error Message | 1734| -------- | ---------------------------------------- | 1735| 17000002 | The async function is not called with await. | 1736| 17000004 | The window or component is invisible or destroyed. | 1737| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 1738 1739**Example** 1740 1741```ts 1742import { Component, Driver, ON } from '@kit.TestKit'; 1743async function demo() { 1744 let driver: Driver = Driver.create(); 1745 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1746 await scrollBar.scrollToBottom(); 1747} 1748``` 1749 1750### dragTo<sup>9+</sup> 1751 1752dragTo(target: Component): Promise\<void> 1753 1754Drags this component to the target component. 1755 1756> **NOTE** 1757> 1758> This API takes effect only on phones, tablets, and 2-in-1 devices. 1759 1760**Atomic service API**: This API can be used in atomic services since API version 11. 1761 1762**System capability**: SystemCapability.Test.UiTest 1763 1764**Parameters** 1765 1766| Name| Type | Mandatory| Description | 1767| ------ | ------------------------ | ---- | ---------- | 1768| target | [Component](#component9) | Yes | Target component.| 1769 1770**Error codes** 1771 1772For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1773 1774| ID| Error Message | 1775| -------- | ---------------------------------------- | 1776| 17000002 | The async function is not called with await. | 1777| 17000004 | The window or component is invisible or destroyed. | 1778| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1779 1780**Example** 1781 1782```ts 1783import { Component, Driver, ON } from '@kit.TestKit'; 1784async function demo() { 1785 let driver: Driver = Driver.create(); 1786 let button: Component = await driver.findComponent(ON.type('Button')); 1787 let text: Component = await driver.findComponent(ON.text('hello world')); 1788 await button.dragTo(text); 1789} 1790``` 1791 1792### pinchOut<sup>9+</sup> 1793 1794pinchOut(scale: number): Promise\<void> 1795 1796Pinches a component to scale it up to the specified ratio. 1797 1798**Atomic service API**: This API can be used in atomic services since API version 11. 1799 1800**System capability**: SystemCapability.Test.UiTest 1801 1802**Parameters** 1803 1804| Name| Type | Mandatory| Description | 1805| ------ | ------ | ---- | ------------------------------- | 1806| scale | number | Yes | Scale factor, which is a value greater than 1.| 1807 1808**Error codes** 1809 1810For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1811 1812| ID| Error Message | 1813| -------- | ---------------------------------------- | 1814| 17000002 | The async function is not called with await. | 1815| 17000004 | The window or component is invisible or destroyed. | 1816| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1817 1818**Example** 1819 1820```ts 1821import { Component, Driver, ON } from '@kit.TestKit'; 1822async function demo() { 1823 let driver: Driver = Driver.create(); 1824 let image: Component = await driver.findComponent(ON.type('Image')); 1825 await image.pinchOut(1.5); 1826} 1827``` 1828 1829### pinchIn<sup>9+</sup> 1830 1831pinchIn(scale: number): Promise\<void> 1832 1833Pinches a component to scale it down to the specified ratio. 1834 1835**Atomic service API**: This API can be used in atomic services since API version 11. 1836 1837**System capability**: SystemCapability.Test.UiTest 1838 1839**Parameters** 1840 1841| Name| Type | Mandatory| Description | 1842| ------ | ------ | ---- | ------------------------------- | 1843| scale | number | Yes | Scale factor, which is a value ranging from 0 to 1.| 1844 1845**Error codes** 1846 1847For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1848 1849| ID| Error Message | 1850| -------- | ---------------------------------------- | 1851| 17000002 | The async function is not called with await. | 1852| 17000004 | The window or component is invisible or destroyed. | 1853| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1854 1855**Example** 1856 1857```ts 1858import { Component, Driver, ON } from '@kit.TestKit'; 1859async function demo() { 1860 let driver: Driver = Driver.create(); 1861 let image: Component = await driver.findComponent(ON.type('Image')); 1862 await image.pinchIn(0.5); 1863} 1864``` 1865 1866### getDescription<sup>11+</sup> 1867 1868getDescription(): Promise\<string> 1869 1870Obtains the description of this component. This API uses a promise to return the result. 1871 1872**Atomic service API**: This API can be used in atomic services since API version 11. 1873 1874**System capability**: SystemCapability.Test.UiTest 1875 1876**Return value** 1877 1878| Type | Description | 1879| ---------------- | --------------------------------- | 1880| Promise\<string> | Promise used to return the description of the component.| 1881 1882**Error codes** 1883 1884For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1885 1886| ID| Error Message | 1887| -------- | ------------------------------------------------------------ | 1888| 17000002 | The async function is not called with await. | 1889| 17000004 | The window or component is invisible or destroyed. | 1890 1891**Example** 1892 1893```ts 1894import { Component, Driver, ON } from '@kit.TestKit'; 1895async function demo() { 1896 let driver: Driver = Driver.create(); 1897 let button: Component = await driver.findComponent(ON.type('Button')); 1898 let description = await button.getDescription(); 1899} 1900``` 1901### getHint<sup>18+</sup> 1902 1903getHint(): Promise\<string> 1904 1905Obtains the hint text of a component object. This API uses a promise to return the result. 1906 1907**Atomic service API**: This API can be used in atomic services since API version 18. 1908 1909**System capability**: SystemCapability.Test.UiTest 1910 1911**Return value** 1912 1913| Type | Description | 1914| ---------------- |----------------------| 1915| Promise\<string> | Promise used to return the hint text of the component.| 1916 1917**Error codes** 1918 1919For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1920 1921| ID| Error Message | 1922| -------- | ---------------------------------------- | 1923| 17000002 | The async function is not called with await. | 1924| 17000004 | The window or component is invisible or destroyed. | 1925 1926**Example** 1927 1928```ts 1929import { Component, Driver, ON } from '@kit.TestKit'; 1930async function demo() { 1931 let driver: Driver = Driver.create(); 1932 let button: Component = await driver.findComponent(ON.type('TextInput')); 1933 let hints = await button.getHint(); 1934} 1935``` 1936 1937## Driver<sup>9+</sup> 1938 1939The **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. 1940All APIs provided by this class, except **Driver.create()**, use a promise to return the result and must be invoked using **await**. 1941 1942### create<sup>9+</sup> 1943 1944static create(): Driver 1945 1946Creates a **Driver** object and returns the object created. This API is a static API. 1947 1948**Atomic service API**: This API can be used in atomic services since API version 11. 1949 1950**System capability**: SystemCapability.Test.UiTest 1951 1952**Return value** 1953 1954| Type| Description | 1955| -------- | ---------------------- | 1956| Driver | **Driver** object created.| 1957 1958**Error codes** 1959 1960For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 1961 1962| ID| Error Message | 1963| -------- | ---------------------- | 1964| 17000001 | Initialization failed. | 1965 1966**Example** 1967 1968```ts 1969import { Driver } from '@kit.TestKit'; 1970async function demo() { 1971 let driver: Driver = Driver.create(); 1972} 1973``` 1974 1975### delayMs<sup>9+</sup> 1976 1977delayMs(duration: number): Promise\<void> 1978 1979Delays this **Driver** object within the specified duration. 1980 1981**Atomic service API**: This API can be used in atomic services since API version 11. 1982 1983**System capability**: SystemCapability.Test.UiTest 1984 1985**Parameters** 1986 1987| Name | Type | Mandatory| Description | 1988| -------- | ------ | ---- | ------------------------------- | 1989| duration | number | Yes | Duration of time, in ms. The value must be greater than or equal to 0.| 1990 1991**Error codes** 1992 1993For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1994 1995| ID| Error Message | 1996| -------- | ---------------------------------------- | 1997| 17000002 | The async function is not called with await. | 1998| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1999 2000**Example** 2001 2002```ts 2003import { Driver } from '@kit.TestKit'; 2004async function demo() { 2005 let driver: Driver = Driver.create(); 2006 await driver.delayMs(1000); 2007} 2008``` 2009 2010### findComponent<sup>9+</sup> 2011 2012findComponent(on: On): Promise\<Component> 2013 2014Searches this **Driver** object for the target component that matches the given attributes. 2015 2016**Atomic service API**: This API can be used in atomic services since API version 11. 2017 2018**System capability**: SystemCapability.Test.UiTest 2019 2020**Parameters** 2021 2022| Name| Type | Mandatory| Description | 2023| ------ | ---------- | ---- | -------------------- | 2024| on | [On](#on9) | Yes | Attributes of the target component.| 2025 2026**Return value** 2027 2028| Type | Description | 2029| ---------------------------------- | --------------------------------- | 2030| Promise\<[Component](#component9)> | Promise used to return the found component.| 2031 2032**Error codes** 2033 2034For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2035 2036| ID| Error Message | 2037| -------- | ---------------------------------------- | 2038| 17000002 | The async function is not called with await. | 2039| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2040 2041**Example** 2042 2043```ts 2044import { Component, Driver, ON } from '@kit.TestKit'; 2045async function demo() { 2046 let driver: Driver = Driver.create(); 2047 let button: Component = await driver.findComponent(ON.text('next page')); 2048} 2049``` 2050 2051### findComponents<sup>9+</sup> 2052 2053findComponents(on: On): Promise\<Array\<Component>> 2054 2055Searches this **Driver** object for all components that match the given attributes. 2056 2057**Atomic service API**: This API can be used in atomic services since API version 11. 2058 2059**System capability**: SystemCapability.Test.UiTest 2060 2061**Parameters** 2062 2063| Name| Type | Mandatory| Description | 2064| ------ | ---------- | ---- | -------------------- | 2065| on | [On](#on9) | Yes | Attributes of the target component.| 2066 2067**Return value** 2068 2069| Type | Description | 2070| ------------------------------------------ | --------------------------------------- | 2071| Promise\<Array\<[Component](#component9)>> | Promise used to return a list of found components.| 2072 2073**Error codes** 2074 2075For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2076 2077| ID| Error Message | 2078| -------- | ---------------------------------------- | 2079| 17000002 | The async function is not called with await. | 2080| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2081 2082**Example** 2083 2084```ts 2085import { Component, Driver, ON } from '@kit.TestKit'; 2086async function demo() { 2087 let driver: Driver = Driver.create(); 2088 let buttonList: Array<Component> = await driver.findComponents(ON.text('next page')); 2089} 2090``` 2091 2092### findWindow<sup>9+</sup> 2093 2094findWindow(filter: WindowFilter): Promise\<UiWindow> 2095 2096Searches for the window that matches the specified attributes. 2097 2098**Atomic service API**: This API can be used in atomic services since API version 11. 2099 2100**System capability**: SystemCapability.Test.UiTest 2101 2102**Parameters** 2103 2104| Name| Type | Mandatory| Description | 2105| ------ | ------------------------------ | ---- | ---------------- | 2106| filter | [WindowFilter](#windowfilter9) | Yes | Attributes of the target window.| 2107 2108**Return value** 2109 2110| Type | Description | 2111| -------------------------------- | ------------------------------------- | 2112| Promise\<[UiWindow](#uiwindow9)> | Promise used to return the target window.| 2113 2114**Error codes** 2115 2116For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2117 2118| ID| Error Message | 2119| -------- | ---------------------------------------- | 2120| 17000002 | The async function is not called with await. | 2121| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2122 2123**Example** 2124 2125```ts 2126import { Driver, UiWindow } from '@kit.TestKit'; 2127async function demo() { 2128 let driver: Driver = Driver.create(); 2129 let window: UiWindow = await driver.findWindow({actived: true}); 2130} 2131``` 2132 2133### waitForComponent<sup>9+</sup> 2134 2135waitForComponent(on: On, time: number): Promise\<Component> 2136 2137Searches this **Driver** object for the target component that matches the given attributes within the specified duration. 2138 2139**Atomic service API**: This API can be used in atomic services since API version 11. 2140 2141**System capability**: SystemCapability.Test.UiTest 2142 2143**Parameters** 2144 2145| Name| Type | Mandatory| Description | 2146| ------ | ---------- | ---- | ----------------------------------------- | 2147| on | [On](#on9) | Yes | Attributes of the target component. | 2148| time | number | Yes | Duration for searching for the target component, in ms. The value must be greater than or equal to 0.| 2149 2150**Return value** 2151 2152| Type | Description | 2153| --------------------------------- | --------------------------------- | 2154| Promise\<[Component](#component9)> | Promise used to return the found component.| 2155 2156**Error codes** 2157 2158For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2159 2160| ID| Error Message | 2161| -------- | ---------------------------------------- | 2162| 17000002 | The async function is not called with await. | 2163| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2164 2165**Example** 2166 2167```ts 2168import { Component, Driver, ON } from '@kit.TestKit'; 2169async function demo() { 2170 let driver: Driver = Driver.create(); 2171 let button: Component = await driver.waitForComponent(ON.text('next page'),500); 2172} 2173``` 2174 2175### assertComponentExist<sup>9+</sup> 2176 2177assertComponentExist(on: On): Promise\<void> 2178 2179Asserts that a component that matches the given attributes exists on the current page. 2180 2181**Atomic service API**: This API can be used in atomic services since API version 11. 2182 2183**System capability**: SystemCapability.Test.UiTest 2184 2185**Parameters** 2186 2187| Name| Type | Mandatory| Description | 2188| ------ | ---------- | ---- | -------------------- | 2189| on | [On](#on9) | Yes | Attributes of the target component.| 2190 2191**Error codes** 2192 2193For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2194 2195| ID| Error Message | 2196| -------- | ---------------------------------------- | 2197| 17000002 | The async function is not called with await. | 2198| 17000003 | Assertion failed. | 2199| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2200 2201**Example** 2202 2203```ts 2204import { Driver, ON } from '@kit.TestKit'; 2205async function demo() { 2206 let driver: Driver = Driver.create(); 2207 await driver.assertComponentExist(ON.text('next page')); 2208} 2209``` 2210 2211### pressBack<sup>9+</sup> 2212 2213pressBack(): Promise\<void> 2214 2215Presses the Back button on this **Driver** object. 2216 2217**Atomic service API**: This API can be used in atomic services since API version 11. 2218 2219**System capability**: SystemCapability.Test.UiTest 2220 2221**Error codes** 2222 2223For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2224 2225| ID| Error Message | 2226| -------- | ---------------------------------------- | 2227| 17000002 | The async function is not called with await. | 2228 2229**Example** 2230 2231```ts 2232import { Driver } from '@kit.TestKit'; 2233async function demo() { 2234 let driver: Driver = Driver.create(); 2235 await driver.pressBack(); 2236} 2237``` 2238 2239### triggerKey<sup>9+</sup> 2240 2241triggerKey(keyCode: number): Promise\<void> 2242 2243Triggers the key of this **Driver** object that matches the given key code. 2244 2245**Atomic service API**: This API can be used in atomic services since API version 11. 2246 2247**System capability**: SystemCapability.Test.UiTest 2248 2249**Parameters** 2250 2251| Name | Type | Mandatory| Description | 2252| ------- | ------ | ---- | ------------- | 2253| keyCode | number | Yes | Key code.| 2254 2255**Error codes** 2256 2257For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2258 2259| ID| Error Message | 2260| -------- | ---------------------------------------- | 2261| 17000002 | The async function is not called with await. | 2262| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2263 2264**Example** 2265 2266```ts 2267import { Driver } from '@kit.TestKit'; 2268async function demo() { 2269 let driver: Driver = Driver.create(); 2270 await driver.triggerKey(123); 2271} 2272``` 2273 2274### triggerCombineKeys<sup>9+</sup> 2275 2276triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\<void> 2277 2278Triggers a key combination based on the specified key values. For example, if the value of **Key** is (2072, 2019), the **Driver** object finds and clicks the key combination that matches the value, for example, **Ctrl+C**. 2279 2280**Atomic service API**: This API can be used in atomic services since API version 11. 2281 2282**System capability**: SystemCapability.Test.UiTest 2283 2284**Parameters** 2285 2286| Name| Type | Mandatory| Description | 2287| ------ | ------ | ---- | ------------------------------ | 2288| key0 | number | Yes | The first key value. | 2289| key1 | number | Yes | The second key value. | 2290| key2 | number | No | The third key value. The default value is **0**.| 2291 2292**Error codes** 2293 2294For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2295 2296| ID| Error Message | 2297| -------- | ---------------------------------------- | 2298| 17000002 | The async function is not called with await. | 2299| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2300 2301**Example** 2302 2303```ts 2304import { Driver } from '@kit.TestKit'; 2305async function demo() { 2306 let driver: Driver = Driver.create(); 2307 await driver.triggerCombineKeys(2072, 2047, 2035); 2308} 2309``` 2310 2311 2312### click<sup>9+</sup> 2313 2314click(x: number, y: number): Promise\<void> 2315 2316Clicks a specific point of this **Driver** object based on the given coordinates. 2317 2318**Atomic service API**: This API can be used in atomic services since API version 11. 2319 2320**System capability**: SystemCapability.Test.UiTest 2321 2322**Parameters** 2323 2324| Name| Type | Mandatory| Description | 2325| ------ | ------ | ---- | ----------------------------------------------- | 2326| x | number | Yes | X coordinate of the end point. The value must be greater than or equal to 0.| 2327| y | number | Yes | Y coordinate of the end point. The value must be greater than or equal to 0.| 2328 2329**Error codes** 2330 2331For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2332 2333| ID| Error Message | 2334| -------- | ---------------------------------------- | 2335| 17000002 | The async function is not called with await. | 2336| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2337 2338**Example** 2339 2340```ts 2341import { Driver } from '@kit.TestKit'; 2342async function demo() { 2343 let driver: Driver = Driver.create(); 2344 await driver.click(100,100); 2345} 2346``` 2347 2348### doubleClick<sup>9+</sup> 2349 2350doubleClick(x: number, y: number): Promise\<void> 2351 2352Double-clicks a specific point of this **Driver** object based on the given coordinates. 2353 2354**Atomic service API**: This API can be used in atomic services since API version 11. 2355 2356**System capability**: SystemCapability.Test.UiTest 2357 2358**Parameters** 2359 2360| Name| Type | Mandatory| Description | 2361| ------ | ------ | ---- | ----------------------------------------------- | 2362| x | number | Yes | X coordinate of the end point. The value must be greater than or equal to 0.| 2363| y | number | Yes | Y coordinate of the end point. The value must be greater than or equal to 0.| 2364 2365**Error codes** 2366 2367For details about the error codes, see [Universal Error Codes](../errorcode-universal.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 { Driver } from '@kit.TestKit'; 2378async function demo() { 2379 let driver: Driver = Driver.create(); 2380 await driver.doubleClick(100,100); 2381} 2382``` 2383 2384### longClick<sup>9+</sup> 2385 2386longClick(x: number, y: number): Promise\<void> 2387 2388Long-clicks a specific point of this **Driver** object based on the given coordinates. 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| x | number | Yes | X coordinate of the end point. The value must be greater than or equal to 0.| 2399| y | number | Yes | Y coordinate of the end point. The value must be greater than or equal to 0.| 2400 2401**Error codes** 2402 2403For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2404 2405| ID| Error Message | 2406| -------- | ---------------------------------------- | 2407| 17000002 | The async function is not called with await. | 2408| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2409 2410**Example** 2411 2412```ts 2413import { Driver } from '@kit.TestKit'; 2414async function demo() { 2415 let driver: Driver = Driver.create(); 2416 await driver.longClick(100,100); 2417} 2418``` 2419 2420### swipe<sup>9+</sup> 2421 2422swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 2423 2424Swipes on this **Driver** object from the given start point to the given end point. 2425 2426**Atomic service API**: This API can be used in atomic services since API version 11. 2427 2428**System capability**: SystemCapability.Test.UiTest 2429 2430**Parameters** 2431 2432| Name| Type | Mandatory| Description | 2433| ------ | ------ | ---- |------------------------------------------------------| 2434| startx | number | Yes | X coordinate of the start point. The value must be greater than or equal to 0. | 2435| starty | number | Yes | Y coordinate of the start point. The value must be greater than or equal to 0. | 2436| endx | number | Yes | X coordinate of the end point. The value must be greater than or equal to 0. | 2437| endy | number | Yes | Y coordinate of the end point. The value must be greater than or equal to 0. | 2438| 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.| 2439 2440**Error codes** 2441 2442For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2443 2444| ID| Error Message | 2445| -------- | ---------------------------------------- | 2446| 17000002 | The async function is not called with await. | 2447| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2448 2449**Example** 2450 2451```ts 2452import { Driver } from '@kit.TestKit'; 2453async function demo() { 2454 let driver: Driver = Driver.create(); 2455 await driver.swipe(100,100,200,200,600); 2456} 2457``` 2458 2459### drag<sup>9+</sup> 2460 2461drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 2462 2463Drags this **Driver** object from the given start point to the given end point. 2464 2465> **NOTE** 2466> 2467> This API takes effect only on phones, tablets, and 2-in-1 devices. 2468 2469**Atomic service API**: This API can be used in atomic services since API version 11. 2470 2471**System capability**: SystemCapability.Test.UiTest 2472 2473**Parameters** 2474 2475| Name| Type | Mandatory| Description | 2476| ------ | ------ | ---- |--------------------------------------------------------| 2477| startx | number | Yes | X coordinate of the start point. The value must be greater than or equal to 0. | 2478| starty | number | Yes | Y coordinate of the start point. The value must be greater than or equal to 0. | 2479| endx | number | Yes | X coordinate of the end point. The value must be greater than or equal to 0. | 2480| endy | number | Yes | Y coordinate of the end point. The value must be greater than or equal to 0. | 2481| 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.| 2482 2483**Error codes** 2484 2485For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2486 2487| ID| Error Message | 2488| -------- | ---------------------------------------- | 2489| 17000002 | The async function is not called with await. | 2490| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2491 2492**Example** 2493 2494```ts 2495import { Driver } from '@kit.TestKit'; 2496async function demo() { 2497 let driver: Driver = Driver.create(); 2498 await driver.drag(100,100,200,200,600); 2499} 2500``` 2501 2502### screenCap<sup>9+</sup> 2503 2504screenCap(savePath: string): Promise\<boolean> 2505 2506Captures the current screen of this **Driver** object and saves it as a PNG image to the given save path. This API can be used in scenarios where screenshots are supported. 2507 2508**Atomic service API**: This API can be used in atomic services since API version 11. 2509 2510**System capability**: SystemCapability.Test.UiTest 2511 2512**Parameters** 2513 2514| Name | Type | Mandatory| Description | 2515| -------- | ------ | ---- | ------------------------------------------ | 2516| savePath | string | Yes | File save path. The path must be the sandbox path of the current application.| 2517 2518**Return value** 2519 2520| Type | Description | 2521| ----------------- | -------------------------------------- | 2522| Promise\<boolean> | Promise used to return the result. The value **true** means that the operation is successful.| 2523 2524**Error codes** 2525 2526For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2527 2528| ID| Error Message | 2529| -------- | ---------------------------------------- | 2530| 17000002 | The async function is not called with await. | 2531| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2532 2533**Example** 2534 2535```ts 2536import { Driver } from '@kit.TestKit'; 2537async function demo() { 2538 let driver: Driver = Driver.create(); 2539 await driver.screenCap('/data/storage/el2/base/cache/1.png'); 2540} 2541``` 2542 2543### setDisplayRotation<sup>9+</sup> 2544 2545setDisplayRotation(rotation: DisplayRotation): Promise\<void> 2546 2547Sets the display rotation of the current scene. It applies to rotatable scenarios. 2548 2549> **NOTE** 2550> 2551> This API takes effect only on phones, tablets, and 2-in-1 devices. 2552 2553**Atomic service API**: This API can be used in atomic services since API version 11. 2554 2555**System capability**: SystemCapability.Test.UiTest 2556 2557**Parameters** 2558 2559| Name | Type | Mandatory| Description | 2560| -------- | ------------------------------------ | ---- | ---------------- | 2561| rotation | [DisplayRotation](#displayrotation9) | Yes | Display rotation of the device.| 2562 2563**Error codes** 2564 2565For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2566 2567| ID| Error Message | 2568| -------- | ---------------------------------------- | 2569| 17000002 | The async function is not called with await. | 2570| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2571 2572**Example** 2573 2574```ts 2575import { Driver, DisplayRotation } from '@kit.TestKit'; 2576async function demo() { 2577 let driver: Driver = Driver.create(); 2578 await driver.setDisplayRotation(DisplayRotation.ROTATION_180); 2579} 2580``` 2581 2582### getDisplayRotation<sup>9+</sup> 2583 2584getDisplayRotation(): Promise\<DisplayRotation> 2585 2586Obtains the display rotation of the current device. 2587 2588**Atomic service API**: This API can be used in atomic services since API version 11. 2589 2590**System capability**: SystemCapability.Test.UiTest 2591 2592**Return value** 2593 2594| Type | Description | 2595| ---------------------------------------------- | --------------------------------------- | 2596| Promise\<[DisplayRotation](#displayrotation9)> | Promise used to return the display rotation of the current device.| 2597 2598**Error codes** 2599 2600For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2601 2602| ID| Error Message | 2603| -------- | ---------------------------------------- | 2604| 17000002 | The async function is not called with await. | 2605 2606**Example** 2607 2608```ts 2609import { DisplayRotation, Driver } from '@kit.TestKit'; 2610async function demo() { 2611 let driver: Driver = Driver.create(); 2612 let rotation: DisplayRotation = await driver.getDisplayRotation(); 2613} 2614``` 2615 2616### setDisplayRotationEnabled<sup>9+</sup> 2617 2618setDisplayRotationEnabled(enabled: boolean): Promise\<void> 2619 2620Enables or disables display rotation. 2621 2622> **NOTE** 2623> 2624> This API takes effect only on phones, tablets, and 2-in-1 devices. 2625 2626**Atomic service API**: This API can be used in atomic services since API version 11. 2627 2628**System capability**: SystemCapability.Test.UiTest 2629 2630**Parameters** 2631 2632| Name | Type | Mandatory| Description | 2633| ------- | ------- | ---- | ------------------------------------------------------- | 2634| enabled | boolean | Yes | Whether to enable display rotation. The value **true** means to enable display rotation, and **false** means the opposite.| 2635 2636**Error codes** 2637 2638For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2639 2640| ID| Error Message | 2641| -------- | ---------------------------------------- | 2642| 17000002 | The async function is not called with await. | 2643| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2644 2645**Example** 2646 2647```ts 2648import { Driver } from '@kit.TestKit'; 2649async function demo() { 2650 let driver: Driver = Driver.create(); 2651 await driver.setDisplayRotationEnabled(false); 2652} 2653``` 2654 2655### getDisplaySize<sup>9+</sup> 2656 2657getDisplaySize(): Promise\<Point> 2658 2659Obtains the display size of the current device. 2660 2661**Atomic service API**: This API can be used in atomic services since API version 11. 2662 2663**System capability**: SystemCapability.Test.UiTest 2664 2665**Return value** 2666 2667| Type | Description | 2668| -------------------------- | --------------------------------------- | 2669| Promise\<[Point](#point9)> | Promise used to return the display size of the current device.| 2670 2671**Error codes** 2672 2673For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2674 2675| ID| Error Message | 2676| -------- | ---------------------------------------- | 2677| 17000002 | The async function is not called with await. | 2678 2679**Example** 2680 2681```ts 2682import { Driver, } from '@kit.TestKit'; 2683 2684async function demo() { 2685 let driver: Driver = Driver.create(); 2686 let size = await driver.getDisplaySize(); 2687} 2688``` 2689 2690### getDisplayDensity<sup>9+</sup> 2691 2692getDisplayDensity(): Promise\<Point> 2693 2694Obtains the display density of the current device. 2695 2696**Atomic service API**: This API can be used in atomic services since API version 11. 2697 2698**System capability**: SystemCapability.Test.UiTest 2699 2700**Return value** 2701 2702| Type | Description | 2703| -------------------------- | ----------------------------------------- | 2704| Promise\<[Point](#point9)> | Promise used to return the display density of the current device.| 2705 2706**Error codes** 2707 2708For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2709 2710| ID| Error Message | 2711| -------- | ---------------------------------------- | 2712| 17000002 | The async function is not called with await. | 2713 2714**Example** 2715 2716```ts 2717import { Driver } from '@kit.TestKit'; 2718async function demo() { 2719 let driver: Driver = Driver.create(); 2720 let density = await driver.getDisplayDensity(); 2721} 2722``` 2723 2724### wakeUpDisplay<sup>9+</sup> 2725 2726wakeUpDisplay(): Promise\<void> 2727 2728Wakes up the device display. 2729 2730**Atomic service API**: This API can be used in atomic services since API version 11. 2731 2732**System capability**: SystemCapability.Test.UiTest 2733 2734**Error codes** 2735 2736For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2737 2738| ID| Error Message | 2739| -------- | ---------------------------------------- | 2740| 17000002 | The async function is not called with await. | 2741 2742**Example** 2743 2744```ts 2745import { Driver } from '@kit.TestKit'; 2746async function demo() { 2747 let driver: Driver = Driver.create(); 2748 await driver.wakeUpDisplay(); 2749} 2750``` 2751 2752### pressHome<sup>9+</sup> 2753 2754pressHome(): Promise\<void> 2755 2756Returns to the home screen. 2757 2758> **NOTE** 2759> 2760> This API takes effect only on phones, tablets, and 2-in-1 devices. 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**Error codes** 2767 2768For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 2769 2770| ID| Error Message | 2771| -------- | ---------------------------------------- | 2772| 17000002 | The async function is not called with await. | 2773 2774**Example** 2775 2776```ts 2777import { Driver } from '@kit.TestKit'; 2778async function demo() { 2779 let driver: Driver = Driver.create(); 2780 await driver.pressHome(); 2781} 2782``` 2783 2784### waitForIdle<sup>9+</sup> 2785 2786waitForIdle(idleTime: number, timeout: number): Promise\<boolean> 2787 2788Checks whether all components on the current page are idle. 2789 2790**Atomic service API**: This API can be used in atomic services since API version 11. 2791 2792**System capability**: SystemCapability.Test.UiTest 2793 2794**Parameters** 2795 2796| Name | Type | Mandatory| Description | 2797| -------- | ------ | ---- | ------------------------------------------------------------ | 2798| 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 greater than or equal to 0.| 2799| timeout | number | Yes | Maximum idle waiting time, in ms. The value must be greater than or equal to 0. | 2800 2801**Return value** 2802 2803| Type | Description | 2804| ----------------- | --------------------------------------------------- | 2805| Promise\<boolean> | Promise used to return the result.| 2806 2807**Error codes** 2808 2809For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2810 2811| ID| Error Message | 2812| -------- | ---------------------------------------- | 2813| 17000002 | The async function is not called with await. | 2814| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2815 2816**Example** 2817 2818```ts 2819import { Driver } from '@kit.TestKit'; 2820async function demo() { 2821 let driver: Driver = Driver.create(); 2822 let idled:boolean = await driver.waitForIdle(4000,5000); 2823} 2824``` 2825 2826### fling<sup>9+</sup> 2827 2828fling(from: Point, to: Point, stepLen: number, speed: number): Promise\<void> 2829 2830Simulates a fling operation on the screen. 2831 2832**Atomic service API**: This API can be used in atomic services since API version 11. 2833 2834**System capability**: SystemCapability.Test.UiTest 2835 2836**Parameters** 2837 2838| Name | Type | Mandatory| Description | 2839| ------- | ---------------- | ---- |------------------------------------------------------| 2840| from | [Point](#point9) | Yes | Coordinates of the point where the finger touches the screen. | 2841| to | [Point](#point9) | Yes | Coordinates of the point where the finger leaves the screen. | 2842| stepLen | number | Yes | Step length, in pixels. | 2843| 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.| 2844 2845**Error codes** 2846 2847For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2848 2849| ID| Error Message | 2850| -------- | ---------------------------------------- | 2851| 17000002 | The async function is not called with await. | 2852| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2853 2854**Example** 2855 2856```ts 2857import { Driver } from '@kit.TestKit'; 2858async function demo() { 2859 let driver: Driver = Driver.create(); 2860 await driver.fling({x: 500, y: 480},{x: 450, y: 480},5,600); 2861} 2862``` 2863 2864### injectMultiPointerAction<sup>9+</sup> 2865 2866injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\<boolean> 2867 2868Injects a multi-touch operation to the device. 2869 2870**Atomic service API**: This API can be used in atomic services since API version 11. 2871 2872**System capability**: SystemCapability.Test.UiTest 2873 2874**Parameters** 2875 2876| Name | Type | Mandatory| Description | 2877| -------- | -------------------------------- | ---- |--------------------------------------------------------| 2878| pointers | [PointerMatrix](#pointermatrix9) | Yes | Scroll trajectory, including the number of fingers and an array of coordinates along the trajectory. | 2879| speed | number | No | Inject 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.| 2880 2881**Return value** 2882 2883| Type | Description | 2884| ----------------- | ------------------------------------- | 2885| Promise\<boolean> | Promise used to return the result.| 2886 2887**Error codes** 2888 2889For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2890 2891| ID| Error Message | 2892| -------- | ---------------------------------------- | 2893| 17000002 | The async function is not called with await. | 2894| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2895 2896**Example** 2897 2898```ts 2899import { Driver, PointerMatrix } from '@kit.TestKit'; 2900async function demo() { 2901 let driver: Driver = Driver.create(); 2902 let pointers: PointerMatrix = PointerMatrix.create(2,5); 2903 pointers.setPoint(0,0,{x:250,y:480}); 2904 pointers.setPoint(0,1,{x:250,y:440}); 2905 pointers.setPoint(0,2,{x:250,y:400}); 2906 pointers.setPoint(0,3,{x:250,y:360}); 2907 pointers.setPoint(0,4,{x:250,y:320}); 2908 pointers.setPoint(1,0,{x:250,y:480}); 2909 pointers.setPoint(1,1,{x:250,y:440}); 2910 pointers.setPoint(1,2,{x:250,y:400}); 2911 pointers.setPoint(1,3,{x:250,y:360}); 2912 pointers.setPoint(1,4,{x:250,y:320}); 2913 await driver.injectMultiPointerAction(pointers); 2914} 2915``` 2916 2917### fling<sup>10+</sup> 2918 2919fling(direction: UiDirection, speed: number): Promise\<void>; 2920 2921Simulates a fling operation on the screen, in the specified direction and speed. 2922 2923**Atomic service API**: This API can be used in atomic services since API version 11. 2924 2925**System capability**: SystemCapability.Test.UiTest 2926 2927**Parameters** 2928 2929| Name | Type | Mandatory| Description | 2930| --------- | ----------------------------- | ---- |--------------------------------------------------------| 2931| direction | [UiDirection](#uidirection10) | Yes | Direction of the fling operation. | 2932| 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.| 2933 2934**Error codes** 2935 2936For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2937 2938| ID| Error Message | 2939| -------- | ------------------------------------------------------------ | 2940| 17000002 | The async function is not called with await. | 2941| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2942 2943**Example** 2944 2945```ts 2946import { Driver, UiDirection } from '@kit.TestKit'; 2947async function demo() { 2948 let driver: Driver = Driver.create(); 2949 await driver.fling(UiDirection.DOWN, 10000); 2950} 2951``` 2952 2953### screenCapture<sup>10+</sup> 2954 2955screenCapture(savePath: string, rect?: Rect): Promise\<boolean>; 2956 2957Captures the specified area of the current screen and saves the captured screenshot as a PNG image to the specified path. This API can be used in scenarios where screenshots are supported. 2958 2959**Atomic service API**: This API can be used in atomic services since API version 11. 2960 2961**System capability**: SystemCapability.Test.UiTest 2962 2963**Parameters** 2964 2965| Name | Type | Mandatory| Description | 2966| -------- | -------------- | ---- | ------------------------------------------ | 2967| savePath | string | Yes | File save path. The path must be the sandbox path of the current application.| 2968| rect | [Rect](#rect9) | No | Area of the screen to capture. The default value is the entire screen. | 2969 2970**Return value** 2971 2972| Type | Description | 2973| ----------------- | -------------------------------------- | 2974| Promise\<boolean> | Promise used to return the result. The value **true** means that the operation is successful.| 2975 2976**Error codes** 2977 2978For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2979 2980| ID| Error Message | 2981| -------- | ------------------------------------------------------------ | 2982| 17000002 | The async function is not called with await. | 2983| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2984 2985**Example** 2986 2987```ts 2988import { Driver } from '@kit.TestKit'; 2989async function demo() { 2990 let driver: Driver = Driver.create(); 2991 await driver.screenCapture('/data/storage/el2/base/cache/1.png', {left: 0, top: 0, right: 100, bottom: 100}); 2992} 2993``` 2994 2995### mouseClick<sup>10+</sup> 2996 2997mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void>; 2998 2999Injects a mouse click at the specified coordinates, with the optional key or key combination. For example, if the value of **key1** is **2072**, the **Ctrl** button is pressed with the mouse click. 3000 3001**Atomic service API**: This API can be used in atomic services since API version 11. 3002 3003**System capability**: SystemCapability.Test.UiTest 3004 3005**Parameters** 3006 3007| Name| Type | Mandatory| Description | 3008| ------ | ----------------------------- | ---- | ------------------------------ | 3009| p | [Point](#point9) | Yes | Coordinates of the mouse click. | 3010| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressed. | 3011| key1 | number | No | The first key value. The default value is **0**.| 3012| key2 | number | No | The second key value. The default value is **0**.| 3013 3014**Error codes** 3015 3016For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3017 3018| ID| Error Message | 3019| -------- | ------------------------------------------------------------ | 3020| 17000002 | The async function is not called with await. | 3021| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3022 3023**Example** 3024 3025```ts 3026import { Driver,MouseButton } from '@kit.TestKit'; 3027async function demo() { 3028 let driver: Driver = Driver.create(); 3029 await driver.mouseClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 3030} 3031``` 3032 3033### mouseScroll<sup>10+</sup> 3034 3035mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): Promise\<void>; 3036 3037Injects a mouse scroll action at the specified coordinates, with the optional key or key combination. For example, if the value of **key1** is **2072**, the **Ctrl** button is pressed with mouse scrolling. 3038 3039**Atomic service API**: This API can be used in atomic services since API version 11. 3040 3041**System capability**: SystemCapability.Test.UiTest 3042 3043**Parameters** 3044 3045| Name| Type | Mandatory| Description | 3046| ------ | ---------------- | ---- | ----------------------------------------------------------- | 3047| p | [Point](#point9) | Yes | Coordinates of the mouse click. | 3048| down | boolean | Yes | Whether the mouse wheel scrolls downward.<br>**true**: The mouse wheel scrolls downward.<br>**false**: The mouse wheel scrolls upward.| 3049| d | number | Yes | Number of notches by which the mouse wheel scrolls. Scrolling by one notch means a 120-pixel offset of the target point. | 3050| key1 | number | No | The first key value. The default value is **0**. | 3051| key2 | number | No | The second key value. The default value is **0**. | 3052 3053**Error codes** 3054 3055For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3056 3057| ID| Error Message | 3058| -------- | ------------------------------------------------------------ | 3059| 17000002 | The async function is not called with await. | 3060| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3061 3062**Example** 3063 3064```ts 3065import { Driver } from '@kit.TestKit'; 3066async function demo() { 3067 let driver: Driver = Driver.create(); 3068 await driver.mouseScroll({x:360, y:640}, true, 30, 2072) 3069} 3070``` 3071 3072### mouseMoveTo<sup>10+</sup> 3073 3074mouseMoveTo(p: Point): Promise\<void>; 3075 3076Moves the cursor to the end point. 3077 3078**System capability**: SystemCapability.Test.UiTest 3079 3080**Atomic service API**: This API can be used in atomic services since API version 11. 3081 3082**Parameters** 3083 3084| Name| Type | Mandatory| Description | 3085| ------ | ---------------- | ---- | -------------- | 3086| p | [Point](#point9) | Yes | Coordinates of the end point.| 3087 3088**Error codes** 3089 3090For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3091 3092| ID| Error Message | 3093| -------- | ------------------------------------------------------------ | 3094| 17000002 | The async function is not called with await. | 3095| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3096 3097**Example** 3098 3099```ts 3100import { Driver } from '@kit.TestKit'; 3101async function demo() { 3102 let driver: Driver = Driver.create(); 3103 await driver.mouseMoveTo({x:100, y:100}) 3104} 3105``` 3106 3107### createUIEventObserver<sup>10+</sup> 3108 3109createUIEventObserver(): UIEventObserver; 3110 3111Creates a UI event listener. 3112 3113**Atomic service API**: This API can be used in atomic services since API version 11. 3114 3115**System capability**: SystemCapability.Test.UiTest 3116 3117**Return value** 3118 3119| Type | Description | 3120| ------------------------------------ | ------------------------------------- | 3121|[UIEventObserver](#uieventobserver10) | UI event listener.| 3122 3123**Error codes** 3124 3125For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3126 3127| ID| Error Message | 3128| -------- | ---------------------------------------- | 3129| 17000002 | The async function is not called with await. | 3130 3131**Example** 3132 3133```ts 3134import { Driver, UIEventObserver } from '@kit.TestKit'; 3135async function demo() { 3136 let driver: Driver = Driver.create(); 3137 let observer: UIEventObserver = await driver.createUIEventObserver() 3138} 3139``` 3140 3141### mouseScroll<sup>11+</sup> 3142 3143mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number, speed?: number): Promise\<void> 3144 3145Injects a mouse scroll action at the specified coordinates. You can specify the key or key combination to work with the action, as well as the scroll speed. 3146 3147**Atomic service API**: This API can be used in atomic services since API version 11. 3148 3149**System capability**: SystemCapability.Test.UiTest 3150 3151**Parameters** 3152 3153| Name| Type | Mandatory| Description | 3154| ------ | ---------------- | ---- | ------------------------------------------------------------ | 3155| p | [Point](#point9) | Yes | Coordinates of the mouse click. | 3156| down | boolean | Yes | Whether the mouse wheel scrolls downward.<br>**true**: The mouse wheel scrolls downward.<br>**false**: The mouse wheel scrolls upward. | 3157| d | number | Yes | Number of notches by which the mouse wheel scrolls. Scrolling by one notch means a 120-pixel offset of the target point. | 3158| key1 | number | No | The first key value. The default value is **0**. | 3159| key2 | number | No | The second key value. The default value is **0**. | 3160| speed | number | No | Scroll speed of the mouse wheel, in cells/second.<br>Value range: 1 to 500<br>If the value is not within the range, the default value **20** will be used.| 3161 3162**Error codes** 3163 3164For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3165 3166| ID| Error Message | 3167| -------- | ------------------------------------------------------------ | 3168| 17000002 | The async function is not called with await. | 3169| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3170 3171**Example** 3172 3173```ts 3174import { Driver } from '@kit.TestKit'; 3175async function demo() { 3176 let driver: Driver = Driver.create(); 3177 await driver.mouseScroll({x:360, y:640}, true, 30, 2072,20) 3178} 3179``` 3180 3181### mouseDoubleClick<sup>11+</sup> 3182 3183mouseDoubleClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void> 3184 3185Injects a double-click action at the specified coordinates, with the optional key or key combination. For example, if the value of **key** is **2072**, the **Ctrl** button is pressed with the double-click. 3186 3187**Atomic service API**: This API can be used in atomic services since API version 11. 3188 3189**System capability**: SystemCapability.Test.UiTest 3190 3191**Parameters** 3192 3193| Name| Type | Mandatory| Description | 3194| ------ | ----------------------------- | ---- | ------------------------------ | 3195| p | [Point](#point9) | Yes | Coordinates of the double-click. | 3196| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressed. | 3197| key1 | number | No | The first key value. The default value is **0**.| 3198| key2 | number | No | The second key value. The default value is **0**.| 3199 3200**Error codes** 3201 3202For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3203 3204| ID| Error Message | 3205| -------- | ------------------------------------------------------------ | 3206| 17000002 | The async function is not called with await. | 3207| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3208 3209**Example** 3210 3211```ts 3212import { Driver,MouseButton } from '@kit.TestKit'; 3213async function demo() { 3214 let driver: Driver = Driver.create(); 3215 await driver.mouseDoubleClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 3216} 3217``` 3218 3219### mouseLongClick<sup>11+</sup> 3220 3221mouseLongClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void> 3222 3223Injects a long-click action of the mouse device at the specified coordinates, with the optional key or key combination. For example, if the value of **Key** is **2072**, the **Ctrl** button is long-clicked with the mouse device. 3224 3225**Atomic service API**: This API can be used in atomic services since API version 11. 3226 3227**System capability**: SystemCapability.Test.UiTest 3228 3229**Parameters** 3230 3231| Name| Type | Mandatory| Description | 3232| ------ | ----------------------------- | ---- | ------------------------------ | 3233| p | [Point](#point9) | Yes | Coordinates of the long-click of the mouse device. | 3234| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressed. | 3235| key1 | number | No | The first key value. The default value is **0**.| 3236| key2 | number | No | The second key value. The default value is **0**.| 3237 3238**Error codes** 3239 3240For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3241 3242| ID| Error Message | 3243| -------- | ------------------------------------------------------------ | 3244| 17000002 | The async function is not called with await. | 3245| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3246 3247**Example** 3248 3249```ts 3250import { Driver,MouseButton } from '@kit.TestKit'; 3251async function demo() { 3252 let driver:Driver = Driver.create(); 3253 await driver.mouseLongClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 3254} 3255``` 3256 3257### mouseMoveWithTrack<sup>11+</sup> 3258 3259mouseMoveWithTrack(from: Point, to: Point, speed?: number): Promise\<void> 3260 3261Moves the mouse pointer from the start point to the end point. 3262 3263**Atomic service API**: This API can be used in atomic services since API version 11. 3264 3265**System capability**: SystemCapability.Test.UiTest 3266 3267**Parameters** 3268 3269| Name| Type | Mandatory| Description | 3270| ------ | ---------------- | ---- |--------------------------------------------------------| 3271| from | [Point](#point9) | Yes | Coordinates of the start point. | 3272| to | [Point](#point9) | Yes | Coordinates of the end point. | 3273| speed | number | No | Move 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.| 3274 3275**Error codes** 3276 3277For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3278 3279| ID| Error Message | 3280| -------- | ------------------------------------------------------------ | 3281| 17000002 | The async function is not called with await. | 3282| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3283 3284**Example** 3285 3286```ts 3287import { Driver } from '@kit.TestKit'; 3288async function demo() { 3289 let driver: Driver = Driver.create(); 3290 await driver.mouseMoveWithTrack({x:100, y:100},{x:200, y:200},600); 3291} 3292``` 3293 3294### mouseDrag<sup>11+</sup> 3295 3296mouseDrag(from: Point, to: Point, speed?: number): Promise\<void> 3297 3298Drags the mouse pointer from the start point to the end point. 3299 3300> **NOTE** 3301> 3302> This API takes effect only on phones, tablets, and 2-in-1 devices. 3303 3304**Atomic service API**: This API can be used in atomic services since API version 11. 3305 3306**System capability**: SystemCapability.Test.UiTest 3307 3308**Parameters** 3309 3310| Name| Type | Mandatory| Description | 3311| ------ | ---------------- | ---- |--------------------------------------------------------| 3312| from | [Point](#point9) | Yes | Coordinates of the start point. | 3313| to | [Point](#point9) | Yes | Coordinates of the end point. | 3314| 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.| 3315 3316**Error codes** 3317 3318For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3319 3320| ID| Error Message | 3321| -------- | ------------------------------------------------------------ | 3322| 17000002 | The async function is not called with await. | 3323| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3324 3325**Example** 3326 3327```ts 3328import { Driver } from '@kit.TestKit'; 3329async function demo() { 3330 let driver: Driver = Driver.create(); 3331 await driver.mouseDrag({x:100, y:100},{x:200, y:200},600); 3332} 3333``` 3334 3335### inputText<sup>11+</sup> 3336 3337inputText(p: Point, text: string): Promise\<void> 3338 3339Inputs text at a specified coordinate without clearing the original text in the component. 3340 3341**Atomic service API**: This API can be used in atomic services since API version 11. 3342 3343**System capability**: SystemCapability.Test.UiTest 3344 3345**Parameters** 3346 3347| Name| Type | Mandatory| Description | 3348| ------ | ---------------- | ---- | ------------------ | 3349| p | [Point](#point9) | Yes | Coordinates of the end point.| 3350| text | string | Yes |Input text. Currently, English, Chinese, and special characters are supported.<br> **Note**: For wearables, this API does not support Chinese characters.| 3351 3352**Error codes** 3353 3354For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3355 3356| ID| Error Message | 3357| -------- | ------------------------------------------------------------ | 3358| 17000002 | The async function is not called with await. | 3359| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3360 3361**Example** 3362 3363```ts 3364import { Component, Driver, ON } from '@kit.TestKit'; 3365async function demo() { 3366 let driver:Driver = Driver.create(); 3367 let text: Component = await driver.findComponent(ON.type('TextInput')); 3368 let point = await text.getBoundsCenter(); 3369 await driver.inputText(point, '123'); 3370} 3371``` 3372 3373### touchPadMultiFingerSwipe<sup>18+</sup> 3374 3375touchPadMultiFingerSwipe(fingers: number, direction: UiDirection, options?: TouchPadSwipeOptions): Promise\<void> 3376 3377Simulates a multi-finger swipe gesture on the touchpad. This API uses a promise to return the result. 3378 3379> **NOTE** 3380> 3381> This API takes effect only on 2-in-1 devices. 3382 3383**Atomic service API**: This API can be used in atomic services since API version 18. 3384 3385**System capability**: SystemCapability.Test.UiTest 3386 3387**Parameters** 3388 3389| Name| Type | Mandatory| Description | 3390| ------ |-----------------------------------------------|----|-----------------------| 3391| fingers | number | Yes | Number of fingers. The value ranges from 3 to 4.| 3392| direction | [UiDirection](#uidirection10) | Yes | Swipe direction. | 3393| options | [TouchPadSwipeOptions](#touchpadswipeoptions18) | No | Additional options. | 3394 3395**Return value** 3396 3397| Type | Description | 3398|----------------|-----------------| 3399| Promise\<void> | Promise that returns no value.| 3400 3401**Error codes** 3402 3403For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3404 3405| ID| Error Message | 3406| -------- | ------------------------------------------------------------ | 3407| 17000002 | The async function is not called with await. | 3408| 17000005 | This operation is not supported. | 3409| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3410 3411**Example** 3412 3413```ts 3414import { Driver, UiDirection } from '@kit.TestKit'; 3415async function demo() { 3416 let driver:Driver = Driver.create(); 3417 await driver.touchPadMultiFingerSwipe(3, UiDirection.UP); 3418} 3419``` 3420 3421### penClick<sup>18+</sup> 3422 3423penClick(point: Point): Promise\<void> 3424 3425Simulates a pen click. This API uses a promise to return the result. 3426 3427**Atomic service API**: This API can be used in atomic services since API version 18. 3428 3429**System capability**: SystemCapability.Test.UiTest 3430 3431**Parameters** 3432 3433| Name| Type | Mandatory| Description | 3434| ------ |-----------------------------------------------|----|---------| 3435| point | [Point](#point9) | Yes | Coordinates of the clicked point.| 3436 3437**Return value** 3438 3439| Type | Description | 3440|----------------|-----------------| 3441| Promise\<void> | Promise that returns no value.| 3442 3443**Error codes** 3444 3445For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3446 3447| ID| Error Message | 3448| -------- | ------------------------------------------------------------ | 3449| 17000002 | The async function is not called with await. | 3450| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3451 3452**Example** 3453 3454```ts 3455import { Driver } from '@kit.TestKit'; 3456async function demo() { 3457 let driver: Driver = Driver.create(); 3458 await driver.penClick({x: 100, y: 100}); 3459} 3460``` 3461 3462### penLongClick<sup>18+</sup> 3463 3464penLongClick(point: Point, pressure?: number): Promise\<void> 3465 3466Simulates a pen long-click. This API uses a promise to return the result. 3467 3468**Atomic service API**: This API can be used in atomic services since API version 18. 3469 3470**System capability**: SystemCapability.Test.UiTest 3471 3472**Parameters** 3473 3474| Name| Type | Mandatory| Description | 3475| ------ |-----------------------------------------------|----|-------------------------------| 3476| point | [Point](#point9) | Yes | Coordinates of the long-clicked point. | 3477| pressure | number | No | Swipe pressure of the pen. The value ranges from 0.0 to 1.0. The default value is **1.0**.| 3478 3479**Return value** 3480 3481| Type | Description | 3482|----------------|-----------------| 3483| Promise\<void> | Promise that returns no value.| 3484 3485**Error codes** 3486 3487For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3488 3489| ID| Error Message | 3490| -------- | ------------------------------------------------------------ | 3491| 17000002 | The async function is not called with await. | 3492| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3493 3494**Example** 3495 3496```ts 3497import { Driver } from '@kit.TestKit'; 3498async function demo() { 3499 let driver: Driver = Driver.create(); 3500 await driver.penLongClick({x: 100, y: 100}, 0.5); 3501} 3502``` 3503 3504### penDoubleClick<sup>18+</sup> 3505 3506penDoubleClick(point: Point): Promise\<void> 3507 3508Simulates a pen double-click. This API uses a promise to return the result. 3509 3510**Atomic service API**: This API can be used in atomic services since API version 18. 3511 3512**System capability**: SystemCapability.Test.UiTest 3513 3514**Parameters** 3515 3516| Name| Type | Mandatory| Description | 3517| ------ |-----------------------------------------------|----|---------| 3518| point | [Point](#point9) | Yes | Coordinates of the double-clicked point.| 3519 3520 3521**Return value** 3522 3523| Type | Description | 3524|----------------|-----------------| 3525| Promise\<void> | Promise that returns no value.| 3526 3527**Error codes** 3528 3529For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3530 3531| ID| Error Message | 3532| -------- | ------------------------------------------------------------ | 3533| 17000002 | The async function is not called with await. | 3534| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3535 3536**Example** 3537 3538```ts 3539import { Driver } from '@kit.TestKit'; 3540async function demo() { 3541 let driver: Driver = Driver.create(); 3542 await driver.penDoubleClick({x: 100, y: 100}); 3543} 3544``` 3545 3546### penSwipe<sup>18+</sup> 3547 3548penSwipe(startPoint: Point, endPoint: Point, speed?: number, pressure?: number): Promise\<void> 3549 3550Simulates a pen swipe. This API uses a promise to return the result. 3551 3552**Atomic service API**: This API can be used in atomic services since API version 18. 3553 3554**System capability**: SystemCapability.Test.UiTest 3555 3556**Parameters** 3557 3558| Name| Type | Mandatory| Description | 3559| ------ |-----------------------------------------------|----|--------------------------------------------------------| 3560| startPoint | [Point](#point9) | Yes | Coordinates of the start point. | 3561| endPoint | [Point](#point9) | Yes | Coordinates of the end point. | 3562| speed | number | No | Inject 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.| 3563| pressure | number | No | Swipe pressure of the pen. The value ranges from 0.0 to 1.0. The default value is **1.0**. | 3564 3565**Return value** 3566 3567| Type | Description | 3568|----------------|-----------------| 3569| Promise\<void> | Promise that returns no value.| 3570 3571**Error codes** 3572 3573For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3574 3575| ID| Error Message | 3576| -------- | ------------------------------------------------------------ | 3577| 17000002 | The async function is not called with await. | 3578| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3579 3580**Example** 3581 3582```ts 3583 import { Driver } from '@kit.TestKit'; 3584async function demo() { 3585 let driver: Driver = Driver.create(); 3586 await driver.penSwipe({x: 100, y: 100}, {x: 100, y: 500}, 600, 0.5); 3587} 3588``` 3589 3590### injectPenPointerAction<sup>18+</sup> 3591 3592injectPenPointerAction(pointers: PointerMatrix, speed?: number, pressure?: number): Promise\<void> 3593 3594Simulates a continuous multi-point pen injection. This API uses a promise to return the result. 3595 3596**Atomic service API**: This API can be used in atomic services since API version 18. 3597 3598**System capability**: SystemCapability.Test.UiTest 3599 3600**Parameters** 3601 3602| Name| Type | Mandatory| Description | 3603| ------ |-----------------------------------------------|----|-------------------------------------------------------------------| 3604| 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.| 3605| speed | number| No | Inject 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. | 3606| pressure | number | No | Injection pressure. The value ranges from 0.0 to 1.0. The default value is **1.0**. | 3607 3608 3609**Return value** 3610 3611| Type | Description | 3612|----------------|-----------------| 3613| Promise\<void> | Promise that returns no value.| 3614 3615**Error codes** 3616 3617For details about the following error codes, see [Universal Error Codes](../errorcode-universal.md) and [Uitest Error Codes](errorcode-uitest.md). 3618 3619| ID| Error Message | 3620| -------- | ------------------------------------------------------------ | 3621| 17000002 | The async function is not called with await. | 3622| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3623 3624**Example** 3625 3626```ts 3627import { Driver, PointerMatrix } from '@kit.TestKit'; 3628async function demo() { 3629 let driver: Driver = Driver.create(); 3630 let pointer = PointerMatrix.create(1,8); 3631 for (let step = 0; step < 8; step++) { 3632 pointer.setPoint(0, step, {x: 500, y: 1100 - 100 *step}); 3633 } 3634 await driver.injectPenPointerAction(pointer, 600, 0.5); 3635} 3636``` 3637 3638## PointerMatrix<sup>9+</sup> 3639 3640Implements a **PointerMatrix** object that stores coordinates and behaviors of each action of each finger in a multi-touch operation. 3641 3642### create<sup>9+</sup> 3643 3644static create(fingers: number, steps: number): PointerMatrix 3645 3646Creates a **PointerMatrix** object and returns the object created. This API is a static API. 3647 3648**Atomic service API**: This API can be used in atomic services since API version 11. 3649 3650**System capability**: SystemCapability.Test.UiTest 3651 3652**Parameters** 3653 3654| Name | Type | Mandatory| Description | 3655| ------- | ------ | ---- | ------------------------------------------ | 3656| fingers | number | Yes | Number of fingers in the multi-touch operation. Value range: [1,10].| 3657| steps | number | Yes | Number of steps operated by each finger. Value range: [1,1000].| 3658 3659**Return value** 3660 3661| Type | Description | 3662| -------------------------------- | ----------------------------- | 3663| [PointerMatrix](#pointermatrix9) | **PointerMatrix** object created.| 3664 3665**Error codes** 3666 3667For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3668 3669| ID| Error Message | 3670| -------- | ------------------------------------------------------------ | 3671| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3672 3673**Example** 3674 3675```ts 3676import { PointerMatrix } from '@kit.TestKit'; 3677async function demo() { 3678 let pointerMatrix: PointerMatrix = PointerMatrix.create(2,3); 3679} 3680``` 3681 3682### setPoint<sup>9+</sup> 3683 3684setPoint(finger: number, step: number, point: Point): void 3685 3686Sets the coordinates for the action corresponding to the specified finger and step in the **PointerMatrix** object. 3687 3688**Atomic service API**: This API can be used in atomic services since API version 11. 3689 3690**System capability**: SystemCapability.Test.UiTest 3691 3692**Parameters** 3693 3694| Name| Type | Mandatory| Description | 3695| ------ | ---------------- | ---- | ---------------------------------------------------------- | 3696| finger | number | Yes | Sequence number of the finger. | 3697| step | number | Yes | Sequence number of the step. | 3698| 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.| 3699 3700**Error codes** 3701 3702For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3703 3704| ID| Error Message | 3705| -------- | ------------------------------------------------------------ | 3706| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3707 3708**Example** 3709 3710```ts 3711import { PointerMatrix } from '@kit.TestKit'; 3712async function demo() { 3713 let pointers: PointerMatrix = PointerMatrix.create(2,5); 3714 pointers.setPoint(0,0,{x:250,y:480}); 3715 pointers.setPoint(0,1,{x:250,y:440}); 3716 pointers.setPoint(0,2,{x:250,y:400}); 3717 pointers.setPoint(0,3,{x:250,y:360}); 3718 pointers.setPoint(0,4,{x:250,y:320}); 3719 pointers.setPoint(1,0,{x:250,y:480}); 3720 pointers.setPoint(1,1,{x:250,y:440}); 3721 pointers.setPoint(1,2,{x:250,y:400}); 3722 pointers.setPoint(1,3,{x:250,y:360}); 3723 pointers.setPoint(1,4,{x:250,y:320}); 3724} 3725``` 3726 3727## UiWindow<sup>9+</sup> 3728 3729The **UiWindow** class represents a window on the UI and provides APIs for obtaining window attributes, dragging a window, and adjusting the window size. 3730All APIs provided in this class use a promise to return the result and must be invoked using **await**. 3731 3732### getBundleName<sup>9+</sup> 3733 3734getBundleName(): Promise\<string> 3735 3736Obtains the bundle name of the application to which this window belongs. 3737 3738**Atomic service API**: This API can be used in atomic services since API version 11. 3739 3740**System capability**: SystemCapability.Test.UiTest 3741 3742**Return value** 3743 3744| Type | Description | 3745| ---------------- | ----------------------------------------- | 3746| Promise\<string> | Promise used to return the bundle name.| 3747 3748**Error codes** 3749 3750For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3751 3752| ID| Error Message | 3753| -------- | ---------------------------------------- | 3754| 17000002 | The async function is not called with await. | 3755| 17000004 | The window or component is invisible or destroyed. | 3756 3757**Example** 3758 3759```ts 3760import { Driver, UiWindow } from '@kit.TestKit'; 3761 3762async function demo() { 3763 let driver: Driver = Driver.create(); 3764 let window: UiWindow = await driver.findWindow({actived: true}); 3765 let name: string = await window.getBundleName(); 3766} 3767``` 3768 3769### getBounds<sup>9+</sup> 3770 3771getBounds(): Promise\<Rect> 3772 3773Obtains the bounds information of this window. 3774 3775**Atomic service API**: This API can be used in atomic services since API version 11. 3776 3777**System capability**: SystemCapability.Test.UiTest 3778 3779**Return value** 3780 3781| Type | Description | 3782| ------------------------ | --------------------------------- | 3783| Promise\<[Rect](#rect9)> | Promise used to return the bounds information of the window.| 3784 3785**Error codes** 3786 3787For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3788 3789| ID| Error Message | 3790| -------- | ---------------------------------------- | 3791| 17000002 | The async function is not called with await. | 3792| 17000004 | The window or component is invisible or destroyed. | 3793 3794**Example** 3795 3796```ts 3797import { Driver, UiWindow } from '@kit.TestKit'; 3798async function demo() { 3799 let driver: Driver = Driver.create(); 3800 let window: UiWindow = await driver.findWindow({actived: true}); 3801 let rect = await window.getBounds(); 3802} 3803``` 3804 3805### getTitle<sup>9+</sup> 3806 3807getTitle(): Promise\<string> 3808 3809Obtains the title of this window. 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**Return value** 3816 3817| Type | Description | 3818| ---------------- | --------------------------------- | 3819| Promise\<string> | Promise used to return the title of the window.| 3820 3821**Error codes** 3822 3823For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3824 3825| ID| Error Message | 3826| -------- | ---------------------------------------- | 3827| 17000002 | The async function is not called with await. | 3828| 17000004 | The window or component is invisible or destroyed. | 3829 3830**Example** 3831 3832```ts 3833import { Driver, UiWindow } from '@kit.TestKit'; 3834async function demo() { 3835 let driver: Driver = Driver.create(); 3836 let window: UiWindow = await driver.findWindow({actived: true}); 3837 let rect = await window.getTitle(); 3838} 3839``` 3840 3841### getWindowMode<sup>9+</sup> 3842 3843getWindowMode(): Promise\<WindowMode> 3844 3845Obtains the window mode of this window. 3846 3847**Atomic service API**: This API can be used in atomic services since API version 11. 3848 3849**System capability**: SystemCapability.Test.UiTest 3850 3851**Return value** 3852 3853| Type | Description | 3854| ------------------------------------ | ------------------------------------- | 3855| Promise\<[WindowMode](#windowmode9)> | Promise used to return the window mode of the window.| 3856 3857**Error codes** 3858 3859For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3860 3861| ID| Error Message | 3862| -------- | ---------------------------------------- | 3863| 17000002 | The async function is not called with await. | 3864| 17000004 | The window or component is invisible or destroyed. | 3865 3866**Example** 3867 3868```ts 3869import { Driver, UiWindow } from '@kit.TestKit'; 3870async function demo() { 3871 let driver: Driver = Driver.create(); 3872 let window: UiWindow = await driver.findWindow({actived: true}); 3873 let mode = await window.getWindowMode(); 3874} 3875``` 3876 3877### isFocused<sup>9+</sup> 3878 3879isFocused(): Promise\<boolean> 3880 3881Checks whether this window is in focused state. 3882 3883**Atomic service API**: This API can be used in atomic services since API version 11. 3884 3885**System capability**: SystemCapability.Test.UiTest 3886 3887**Return value** 3888 3889| Type | Description | 3890| ----------------- | ------------------------------------------------------------ | 3891| Promise\<boolean> | Promise used to return the result. The value **true** means that the window is in focused state, and **false** means the opposite.| 3892 3893**Error codes** 3894 3895For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3896 3897| ID| Error Message | 3898| -------- | ---------------------------------------- | 3899| 17000002 | The async function is not called with await. | 3900| 17000004 | The window or component is invisible or destroyed. | 3901 3902**Example** 3903 3904```ts 3905import { Driver, UiWindow } from '@kit.TestKit'; 3906async function demo() { 3907 let driver: Driver = Driver.create(); 3908 let window: UiWindow = await driver.findWindow({actived: true}); 3909 let focused = await window.isFocused(); 3910} 3911``` 3912 3913### isActived<sup>(deprecated)</sup> 3914 3915isActived(): Promise\<boolean> 3916 3917Checks whether this window is active. This API uses a promise to return the result. 3918 3919This API is supported since API version 9 and deprecated since API version 11. You are advised to use [isActive<sup>11+</sup>](#isactive11) instead. 3920 3921**System capability**: SystemCapability.Test.UiTest 3922 3923**Return value** 3924 3925| Type | Description | 3926| ----------------- | ------------------------------------------------------------ | 3927| Promise\<boolean> | Promise used to return the result. The value **true** means that the window is active, and **false** means the opposite.| 3928 3929**Error codes** 3930 3931For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3932 3933| ID| Error Message | 3934| -------- | ---------------------------------------- | 3935| 17000002 | The async function is not called with await. | 3936| 17000004 | The window or component is invisible or destroyed. | 3937 3938**Example** 3939 3940```ts 3941import { Driver, UiWindow } from '@kit.TestKit'; 3942async function demo() { 3943 let driver: Driver = Driver.create(); 3944 let window: UiWindow = await driver.findWindow({actived: true}); 3945 let focused = await window.isActived(); 3946} 3947``` 3948 3949### focus<sup>9+</sup> 3950 3951focus(): Promise\<void> 3952 3953Moves the focus to this window. 3954 3955**Atomic service API**: This API can be used in atomic services since API version 11. 3956 3957**System capability**: SystemCapability.Test.UiTest 3958 3959**Error codes** 3960 3961For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 3962 3963| ID| Error Message | 3964| -------- | ---------------------------------------- | 3965| 17000002 | The async function is not called with await. | 3966| 17000004 | The window or component is invisible or destroyed. | 3967 3968**Example** 3969 3970```ts 3971import { Driver, UiWindow } from '@kit.TestKit'; 3972async function demo() { 3973 let driver: Driver = Driver.create(); 3974 let window: UiWindow = await driver.findWindow({actived: true}); 3975 await window.focus(); 3976} 3977``` 3978 3979### moveTo<sup>9+</sup> 3980 3981moveTo(x: number, y: number): Promise\<void> 3982 3983Moves this window to the end point. This API is applicable to moveable windows. 3984 3985**Atomic service API**: This API can be used in atomic services since API version 11. 3986 3987**System capability**: SystemCapability.Test.UiTest 3988 3989**Parameters** 3990 3991| Name| Type | Mandatory| Description | 3992| ------ | ------ | ---- | ----------------------------------------------- | 3993| x | number | Yes | X coordinate of the end point. The value must be greater than or equal to 0.| 3994| y | number | Yes | Y coordinate of the end point. The value must be greater than or equal to 0.| 3995 3996**Error codes** 3997 3998For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3999 4000| ID| Error Message | 4001| -------- | ---------------------------------------- | 4002| 17000002 | The async function is not called with await. | 4003| 17000004 | The window or component is invisible or destroyed. | 4004| 17000005 | This operation is not supported. | 4005| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4006 4007**Example** 4008 4009```ts 4010import { Driver, UiWindow } from '@kit.TestKit'; 4011async function demo() { 4012 let driver: Driver = Driver.create(); 4013 let window: UiWindow = await driver.findWindow({actived: true}); 4014 await window.moveTo(100, 100); 4015} 4016``` 4017 4018### resize<sup>9+</sup> 4019 4020resize(wide: number, height: number, direction: ResizeDirection): Promise\<void> 4021 4022Resizes this window based on the specified width, height, and resize direction. This API is applicable to resizable windows. 4023 4024**Atomic service API**: This API can be used in atomic services since API version 11. 4025 4026**System capability**: SystemCapability.Test.UiTest 4027 4028**Parameters** 4029 4030| Name | Type | Mandatory| Description | 4031| --------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 4032| wide | number | Yes | Target width. | 4033| height | number | Yes | Target height. | 4034| direction | [ResizeDirection](#resizedirection9) | Yes | Resize direction.| 4035 4036**Error codes** 4037 4038For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4039 4040| ID| Error Message | 4041| -------- | ---------------------------------------- | 4042| 17000002 | The async function is not called with await. | 4043| 17000004 | The window or component is invisible or destroyed. | 4044| 17000005 | This operation is not supported. | 4045| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4046 4047**Example** 4048 4049```ts 4050import { Driver, ResizeDirection, UiWindow } from '@kit.TestKit'; 4051async function demo() { 4052 let driver: Driver = Driver.create(); 4053 let window: UiWindow = await driver.findWindow({actived: true}); 4054 await window.resize(100, 100, ResizeDirection.LEFT); 4055} 4056``` 4057 4058### split<sup>9+</sup> 4059 4060split(): Promise\<void> 4061 4062Switches the window to split-screen mode. This API is applicable to windows that support screen splitting. 4063 4064**Atomic service API**: This API can be used in atomic services since API version 11. 4065 4066**System capability**: SystemCapability.Test.UiTest 4067 4068**Error codes** 4069 4070For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 4071 4072| ID| Error Message | 4073| -------- | ---------------------------------------- | 4074| 17000002 | The async function is not called with await. | 4075| 17000004 | The window or component is invisible or destroyed. | 4076| 17000005 | This operation is not supported. | 4077 4078**Example** 4079 4080```ts 4081import { Driver, UiWindow } from '@kit.TestKit'; 4082async function demo() { 4083 let driver: Driver = Driver.create(); 4084 let window: UiWindow = await driver.findWindow({actived: true}); 4085 await window.split(); 4086} 4087``` 4088 4089### maximize<sup>9+</sup> 4090 4091maximize(): Promise\<void> 4092 4093Maximizes this window. This API is applicable to windows that can be maximized. 4094 4095**Atomic service API**: This API can be used in atomic services since API version 11. 4096 4097**System capability**: SystemCapability.Test.UiTest 4098 4099**Error codes** 4100 4101For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 4102 4103| ID| Error Message | 4104| -------- | ---------------------------------------- | 4105| 17000002 | The async function is not called with await. | 4106| 17000004 | The window or component is invisible or destroyed. | 4107| 17000005 | This operation is not supported. | 4108 4109**Example** 4110 4111```ts 4112import { Driver, UiWindow } from '@kit.TestKit'; 4113async function demo() { 4114 let driver: Driver = Driver.create(); 4115 let window: UiWindow = await driver.findWindow({actived: true}); 4116 await window.maximize(); 4117} 4118``` 4119 4120### minimize<sup>9+</sup> 4121 4122minimize(): Promise\<void> 4123 4124Minimizes this window. This API is applicable to windows that can be minimized. 4125 4126**Atomic service API**: This API can be used in atomic services since API version 11. 4127 4128**System capability**: SystemCapability.Test.UiTest 4129 4130**Error codes** 4131 4132For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 4133 4134| ID| Error Message | 4135| -------- | ---------------------------------------- | 4136| 17000002 | The async function is not called with await. | 4137| 17000004 | The window or component is invisible or destroyed. | 4138| 17000005 | This operation is not supported. | 4139 4140**Example** 4141 4142```ts 4143import { Driver, UiWindow } from '@kit.TestKit'; 4144async function demo() { 4145 let driver: Driver = Driver.create(); 4146 let window: UiWindow = await driver.findWindow({actived: true}); 4147 await window.minimize(); 4148} 4149``` 4150 4151### resume<sup>9+</sup> 4152 4153resume(): Promise\<void> 4154 4155Restores this window to the previous window mode. 4156 4157**Atomic service API**: This API can be used in atomic services since API version 11. 4158 4159**System capability**: SystemCapability.Test.UiTest 4160 4161**Error codes** 4162 4163For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 4164 4165| ID| Error Message | 4166| -------- | ---------------------------------------- | 4167| 17000002 | The async function is not called with await. | 4168| 17000004 | The window or component is invisible or destroyed. | 4169| 17000005 | This operation is not supported. | 4170 4171**Example** 4172 4173```ts 4174import { Driver, UiWindow } from '@kit.TestKit'; 4175async function demo() { 4176 let driver: Driver = Driver.create(); 4177 let window: UiWindow = await driver.findWindow({actived: true}); 4178 await window.resume(); 4179} 4180``` 4181 4182### close<sup>9+</sup> 4183 4184close(): Promise\<void> 4185 4186Closes this window. 4187 4188**Atomic service API**: This API can be used in atomic services since API version 11. 4189 4190**System capability**: SystemCapability.Test.UiTest 4191 4192**Error codes** 4193 4194For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 4195 4196| ID| Error Message | 4197| -------- | ---------------------------------------- | 4198| 17000002 | The async function is not called with await. | 4199| 17000004 | The window or component is invisible or destroyed. | 4200| 17000005 | This operation is not supported. | 4201 4202**Example** 4203 4204```ts 4205import { Driver, UiWindow } from '@kit.TestKit'; 4206async function demo() { 4207 let driver:Driver = Driver.create(); 4208 let window: UiWindow = await driver.findWindow({actived: true}); 4209 await window.close(); 4210} 4211``` 4212 4213### isActive<sup>11+</sup> 4214 4215isActive(): Promise\<boolean> 4216 4217Checks whether this window is active. 4218 4219**Atomic service API**: This API can be used in atomic services since API version 11. 4220 4221**System capability**: SystemCapability.Test.UiTest 4222 4223**Return value** 4224 4225| Type | Description | 4226| ----------------- | ------------------------------------------------------------ | 4227| Promise\<boolean> | Promise used to return the result. The value **true** means that the window is active, and **false** means the opposite.| 4228 4229**Error codes** 4230 4231For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 4232 4233| ID| Error Message | 4234| -------- | ------------------------------------------------ | 4235| 17000002 | The async function is not called with await. | 4236| 17000004 | The window or component is invisible or destroyed. | 4237 4238**Example** 4239 4240```ts 4241import { Driver, UiWindow } from '@kit.TestKit'; 4242async function demo() { 4243 let driver: Driver = Driver.create(); 4244 let window: UiWindow = await driver.findWindow({active: true}); 4245 let focused = await window.isActive(); 4246} 4247``` 4248 4249## UIEventObserver<sup>10+</sup> 4250 4251UI event listener. 4252 4253### once('toastShow') 4254 4255once(type: 'toastShow', callback: Callback\<UIElementInfo>): void; 4256 4257Subscribes to events of the toast component. This API uses a callback to return the result. 4258 4259**Atomic service API**: This API can be used in atomic services since API version 11. 4260 4261**System capability**: SystemCapability.Test.UiTest 4262 4263**Parameters** 4264 4265| Name | Type | Mandatory| Description | 4266| -------- | -------------------------------------------- | ---- | --------------------------------- | 4267| type | string | Yes | Event type. The value is fixed at **'toastShow'**.| 4268| callback | Callback\<[UIElementInfo](#uielementinfo10)> | Yes | Callback used to return the result. | 4269 4270**Error codes** 4271 4272For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4273 4274| ID| Error Message | 4275| -------- | ------------------------------------------------------------ | 4276| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4277 4278**Example** 4279 4280```ts 4281import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit'; 4282async function demo() { 4283 let driver: Driver = Driver.create(); 4284 let observer: UIEventObserver = await driver.createUIEventObserver() 4285 let callback = (UIElementInfo: UIElementInfo)=>{ 4286 console.info(UIElementInfo.bundleName) 4287 console.info(UIElementInfo.text) 4288 console.info(UIElementInfo.type) 4289 } 4290 observer.once('toastShow', callback) 4291} 4292``` 4293 4294### once('dialogShow') 4295 4296once(type: 'dialogShow', callback: Callback\<UIElementInfo>): void; 4297 4298Subscribes to events of the dialog component. This API uses a callback to return the result. 4299 4300**Atomic service API**: This API can be used in atomic services since API version 11. 4301 4302**System capability**: SystemCapability.Test.UiTest 4303 4304**Parameters** 4305 4306| Name | Type | Mandatory| Description | 4307| -------- | -------------------------------------------- | ---- | ---------------------------------- | 4308| type | string | Yes | Event type. The value is fixed at **'dialogShow'**.| 4309| callback | Callback\<[UIElementInfo](#uielementinfo10)> | Yes | Callback used to return the result. | 4310 4311**Error codes** 4312 4313For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4314 4315| ID| Error Message | 4316| -------- | ------------------------------------------------------------ | 4317| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4318 4319**Example** 4320 4321```ts 4322import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit'; 4323async function demo() { 4324 let driver: Driver = Driver.create(); 4325 let observer: UIEventObserver = await driver.createUIEventObserver() 4326 let callback = (UIElementInfo: UIElementInfo)=>{ 4327 console.info(UIElementInfo.bundleName) 4328 console.info(UIElementInfo.text) 4329 console.info(UIElementInfo.type) 4330 } 4331 observer.once('dialogShow', callback) 4332} 4333``` 4334 4335## By<sup>(deprecated)</sup> 4336 4337The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components.<br> 4338The 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. 4339 4340This class is deprecated since API version 9. You are advised to use [On<sup>9+</sup>](#on9) instead. 4341 4342```ts 4343import { BY } from '@kit.TestKit'; 4344BY.text('123').type('Button'); 4345``` 4346 4347### text<sup>(deprecated)</sup> 4348 4349text(txt: string, pattern?: MatchPattern): By 4350 4351Specifies the text attribute of the target component. Multiple match patterns are supported. 4352 4353This API is deprecated since API version 9. You are advised to use [text<sup>9+</sup>](#text9) instead. 4354 4355**System capability**: SystemCapability.Test.UiTest 4356 4357**Parameters** 4358 4359| Name | Type | Mandatory| Description | 4360| ------- | ----------------------------- | ---- | --------------------------------------------------- | 4361| txt | string | Yes | Component text, used to match the target component. | 4362| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 4363 4364**Return value** 4365 4366| Type | Description | 4367| ------------------- | ---------------------------------- | 4368| [By](#bydeprecated) | **By** object that matches the text attribute of the target component.| 4369 4370**Example** 4371 4372```ts 4373import { BY, By } from '@kit.TestKit'; 4374let by: By = BY.text('123'); // Use the static constructor BY to create a By object and specify the text attribute of the target component. 4375``` 4376 4377 4378### key<sup>(deprecated)</sup> 4379 4380key(key: string): By 4381 4382Specifies the key attribute of the target component. 4383 4384This API is deprecated since API version 9. You are advised to use [id<sup>9+</sup>](#id9) instead. 4385 4386**System capability**: SystemCapability.Test.UiTest 4387 4388**Parameters** 4389 4390| Name| Type | Mandatory| Description | 4391| ------ | ------ | ---- | ----------------- | 4392| key | string | Yes | Component key.| 4393 4394**Return value** 4395 4396| Type | Description | 4397| ------------------- | ----------------------------------- | 4398| [By](#bydeprecated) | **By** object that matches the key attribute of the target component.| 4399 4400**Example** 4401 4402```ts 4403import { By, BY } from '@kit.TestKit'; 4404let by: By = BY.key('123'); // Use the static constructor BY to create a By object and specify the key attribute of the target component. 4405``` 4406 4407 4408### id<sup>(deprecated)</sup> 4409 4410id(id: number): By 4411 4412Specifies the ID attribute of the target component. 4413 4414This API is deprecated since API version 9. 4415 4416**System capability**: SystemCapability.Test.UiTest 4417 4418**Parameters** 4419 4420| Name| Type | Mandatory| Description | 4421| ------ | ------ | ---- | ---------------- | 4422| id | number | Yes | Component ID.| 4423 4424**Return value** 4425 4426| Type | Description | 4427| ------------------- | -------------------------------- | 4428| [By](#bydeprecated) | **By** object that matches the ID attribute of the target component.| 4429 4430**Example** 4431 4432```ts 4433import { By, BY } from '@kit.TestKit'; 4434let by: By = BY.id(123); // Use the static constructor BY to create a By object and specify the id attribute of the target component. 4435``` 4436 4437 4438### type<sup>(deprecated)</sup> 4439 4440type(tp: string): By 4441 4442Specifies the type attribute of the target component. 4443 4444This API is deprecated since API version 9. You are advised to use [type<sup>9+</sup>](#type9) instead. 4445 4446**System capability**: SystemCapability.Test.UiTest 4447 4448**Parameters** 4449 4450| Name| Type | Mandatory| Description | 4451| ------ | ------ | ---- | -------------- | 4452| tp | string | Yes | Component type.| 4453 4454**Return value** 4455 4456| Type | Description | 4457| ------------------- | ---------------------------------------- | 4458| [By](#bydeprecated) | **By** object that matches the type attribute of the target component.| 4459 4460**Example** 4461 4462```ts 4463import { By, BY } from '@kit.TestKit'; 4464let by: By = BY.type('Button'); // Use the static constructor BY to create a By object and specify the type attribute of the target component. 4465``` 4466 4467 4468### clickable<sup>(deprecated)</sup> 4469 4470clickable(b?: boolean): By 4471 4472Specifies the clickable attribute of the target component. 4473 4474This API is deprecated since API version 9. You are advised to use [clickable<sup>9+</sup>](#clickable9) instead. 4475 4476**System capability**: SystemCapability.Test.UiTest 4477 4478**Parameters** 4479 4480| Name| Type | Mandatory| Description | 4481| ------ | ------- | ---- | ------------------------------------------------------------ | 4482| b | boolean | No | Clickable status of the target component.<br>**true**: clickable.<br>**false**: not clickable.<br> Default value: **true**| 4483 4484**Return value** 4485 4486| Type | Description | 4487| ------------------- | ------------------------------------------ | 4488| [By](#bydeprecated) | **By** object that matches the clickable attribute of the target component.| 4489 4490**Example** 4491 4492```ts 4493import { By, BY } from '@kit.TestKit'; 4494let by: By = BY.clickable(true); // Use the static constructor BY to create a By object and specify the clickable attribute of the target component. 4495``` 4496 4497 4498### scrollable<sup>(deprecated)</sup> 4499 4500scrollable(b?: boolean): By 4501 4502Specifies the scrollable attribute of the target component. 4503 4504This API is deprecated since API version 9. You are advised to use [scrollable<sup>9+</sup>](#scrollable9) instead. 4505 4506**System capability**: SystemCapability.Test.UiTest 4507 4508**Parameters** 4509 4510| Name| Type | Mandatory| Description | 4511| ------ | ------- | ---- | ----------------------------------------------------------- | 4512| b | boolean | No | Scrollable status of the target component.<br>**true**: scrollable.<br>**false**: not scrollable.<br> Default value: **true**| 4513 4514**Return value** 4515 4516| Type | Description | 4517| ------------------- | ------------------------------------------ | 4518| [By](#bydeprecated) | **By** object that matches the scrollable attribute of the target component.| 4519 4520**Example** 4521 4522```ts 4523import { By, BY } from '@kit.TestKit'; 4524let by: By = BY.scrollable(true); // Use the static constructor BY to create a By object and specify the scrollable attribute of the target component. 4525``` 4526 4527### enabled<sup>(deprecated)</sup> 4528 4529enabled(b?: boolean): By 4530 4531Specifies the enabled attribute of the target component. 4532 4533This API is deprecated since API version 9. You are advised to use [enabled<sup>9+</sup>](#enabled9) instead. 4534 4535**System capability**: SystemCapability.Test.UiTest 4536 4537**Parameters** 4538 4539| Name| Type | Mandatory| Description | 4540| ------ | ------- | ---- | --------------------------------------------------------- | 4541| b | boolean | No | Enabled status of the target component.<br>**true**: enabled.<br>**false**: not enabled.<br> Default value: **true**| 4542 4543**Return value** 4544 4545| Type | Description | 4546| ------------------- | ---------------------------------------- | 4547| [By](#bydeprecated) | **By** object that matches the enabled attribute of the target component.| 4548 4549**Example** 4550 4551```ts 4552import { By, BY } from '@kit.TestKit'; 4553let by: By = BY.enabled(true); // Use the static constructor BY to create a By object and specify the enabled attribute of the target component. 4554``` 4555 4556### focused<sup>(deprecated)</sup> 4557 4558focused(b?: boolean): By 4559 4560Specifies the focused attribute of the target component. 4561 4562This API is deprecated since API version 9. You are advised to use [focused<sup>9+</sup>](#focused9) instead. 4563 4564**System capability**: SystemCapability.Test.UiTest 4565 4566**Parameters** 4567 4568| Name| Type | Mandatory| Description | 4569| ------ | ------- | ---- | ----------------------------------------------------- | 4570| b | boolean | No | Focused status of the target component.<br>**true**: focused.<br>**false**: not focused.<br> Default value: **true**| 4571 4572**Return value** 4573 4574| Type | Description | 4575| ------------------- | ---------------------------------------- | 4576| [By](#bydeprecated) | **By** object that matches the focused attribute of the target component.| 4577 4578**Example** 4579 4580```ts 4581import { By, BY } from '@kit.TestKit'; 4582let by: By = BY.focused(true); // Use the static constructor BY to create a By object and specify the focused attribute of the target component. 4583``` 4584 4585### selected<sup>(deprecated)</sup> 4586 4587selected(b?: boolean): By 4588 4589Specifies the selected status of the target component. 4590 4591This API is deprecated since API version 9. You are advised to use [selected<sup>9+</sup>](#selected9) instead. 4592 4593**System capability**: SystemCapability.Test.UiTest 4594 4595**Parameters** 4596 4597| Name| Type | Mandatory| Description | 4598| ------ | ------- | ---- | ------------------------------------------------------------ | 4599| b | boolean | No | Selected status of the target component.<br>**true**: selected.<br>**false**: not selected.<br> Default value: **true**| 4600 4601**Return value** 4602 4603| Type | Description | 4604| ------------------- | ------------------------------------------ | 4605| [By](#bydeprecated) | **By** object that matches the selected attribute of the target component.| 4606 4607**Example** 4608 4609```ts 4610import { By, BY } from '@kit.TestKit'; 4611let by: By = BY.selected(true); // Use the static constructor BY to create a By object and specify the selected attribute of the target component. 4612``` 4613 4614### isBefore<sup>(deprecated)</sup> 4615 4616isBefore(by: By): By 4617 4618Specifies that the target component is located before the given attribute component. 4619 4620This API is deprecated since API version 9. You are advised to use [isBefore<sup>9+</sup>](#isbefore9) instead. 4621 4622**System capability**: SystemCapability.Test.UiTest 4623 4624**Parameters** 4625 4626| Name| Type | Mandatory| Description | 4627| ------ | ------------------- | ---- | ---------------- | 4628| by | [By](#bydeprecated) | Yes | Information about the attribute component.| 4629 4630**Return value** 4631 4632| Type | Description | 4633| ------------------- | ---------------------------------------------------- | 4634| [By](#bydeprecated) | **By** object.| 4635 4636**Example** 4637 4638```ts 4639import { By, BY } from '@kit.TestKit'; 4640 4641// Use the static constructor BY to create a by object and specify that the target component is located before the given attribute component. 4642let by: By = BY.type('Button').isBefore(BY.text('123')); // Search for the first <Button> component located before the component whose text is 123. 4643``` 4644 4645### isAfter<sup>(deprecated)</sup> 4646 4647isAfter(by: By): By 4648 4649Specifies that the target component is located after the given attribute component. 4650 4651This API is deprecated since API version 9. You are advised to use [isAfter<sup>9+</sup>](#isafter9) instead. 4652 4653**System capability**: SystemCapability.Test.UiTest 4654 4655**Parameters** 4656 4657| Name| Type | Mandatory| Description | 4658| ------ | ------------------- | ---- | ---------------- | 4659| by | [By](#bydeprecated) | Yes | Information about the attribute component.| 4660 4661**Return value** 4662 4663| Type | Description | 4664| ------------------- | ---------------------------------------------------- | 4665| [By](#bydeprecated) | **By** object.| 4666 4667**Example** 4668 4669```ts 4670import { By, BY } from '@kit.TestKit'; 4671 4672// Use the static constructor BY to create a by object and specify that the target component is located after the given attribute component. 4673let by: By = BY.type('Text').isAfter(BY.text('123')); // Search for the first <Text> component located after the component whose text is 123. 4674``` 4675 4676## UiComponent<sup>(deprecated)</sup> 4677 4678In **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. 4679All APIs provided in this class use a promise to return the result and must be invoked using **await**. 4680 4681This class is deprecated since API version 9. You are advised to use [Component<sup>9+</sup>](#component9) instead. 4682 4683### click<sup>(deprecated)</sup> 4684 4685click(): Promise\<void> 4686 4687Clicks this component. 4688 4689This API is deprecated since API version 9. You are advised to use [click<sup>9+</sup>](#click9) instead. 4690 4691**System capability**: SystemCapability.Test.UiTest 4692 4693**Example** 4694 4695```ts 4696import { UiDriver, BY, Driver, UiComponent } from '@kit.TestKit'; 4697async function demo() { 4698 let driver: UiDriver = UiDriver.create(); 4699 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4700 await button.click(); 4701} 4702``` 4703 4704### doubleClick<sup>(deprecated)</sup> 4705 4706doubleClick(): Promise\<void> 4707 4708Double-clicks this component. 4709 4710This API is deprecated since API version 9. You are advised to use [doubleClick<sup>9+</sup>](#doubleclick9) instead. 4711 4712**System capability**: SystemCapability.Test.UiTest 4713 4714**Example** 4715 4716```ts 4717import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4718async function demo() { 4719 let driver: UiDriver = UiDriver.create(); 4720 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4721 await button.doubleClick(); 4722} 4723``` 4724 4725### longClick<sup>(deprecated)</sup> 4726 4727longClick(): Promise\<void> 4728 4729Long-clicks this component. 4730 4731This API is deprecated since API version 9. You are advised to use [longClick<sup>9+</sup>](#longclick9) instead. 4732 4733**System capability**: SystemCapability.Test.UiTest 4734 4735**Example** 4736 4737```ts 4738import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4739async function demo() { 4740 let driver: UiDriver = UiDriver.create(); 4741 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4742 await button.longClick(); 4743} 4744``` 4745 4746### getId<sup>(deprecated)</sup> 4747 4748getId(): Promise\<number> 4749 4750Obtains the ID of this component. 4751 4752This API is deprecated since API version 9. 4753 4754**System capability**: SystemCapability.Test.UiTest 4755 4756**Return value** 4757 4758| Type | Description | 4759| ---------------- | ------------------------------- | 4760| Promise\<number> | Promise used to return the ID of the component.| 4761 4762**Example** 4763 4764```ts 4765import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4766async function demo() { 4767 let driver: UiDriver = UiDriver.create(); 4768 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4769 let id = await button.getId(); 4770} 4771``` 4772 4773### getKey<sup>(deprecated)</sup> 4774 4775getKey(): Promise\<string> 4776 4777Obtains the key of this component. 4778 4779This API is deprecated since API version 9. You are advised to use [getId<sup>9+</sup>](#getid9) instead. 4780 4781**System capability**: SystemCapability.Test.UiTest 4782 4783**Return value** 4784 4785| Type | Description | 4786| ---------------- | ------------------------------ | 4787| Promise\<string> | Promise used to return the key of the component.| 4788 4789**Example** 4790 4791```ts 4792import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4793async function demo() { 4794 let driver: UiDriver = UiDriver.create(); 4795 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4796 let str_key = await button.getKey(); 4797} 4798``` 4799 4800### getText<sup>(deprecated)</sup> 4801 4802getText(): Promise\<string> 4803 4804Obtains the text information of this component. 4805 4806This API is deprecated since API version 9. You are advised to use [getText<sup>9+</sup>](#gettext9) instead. 4807 4808**System capability**: SystemCapability.Test.UiTest 4809 4810**Return value** 4811 4812| Type | Description | 4813| ---------------- | --------------------------------- | 4814| Promise\<string> | Promise used to return the text information of the component.| 4815 4816**Example** 4817 4818```ts 4819import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4820async function demo() { 4821 let driver: UiDriver = UiDriver.create(); 4822 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4823 let text = await button.getText(); 4824} 4825``` 4826 4827### getType<sup>(deprecated)</sup> 4828 4829getType(): Promise\<string> 4830 4831Obtains the type of this component. 4832 4833This API is deprecated since API version 9. You are advised to use [getType<sup>9+</sup>](#gettype9) instead. 4834 4835**System capability**: SystemCapability.Test.UiTest 4836 4837**Return value** 4838 4839| Type | Description | 4840| ---------------- | ----------------------------- | 4841| Promise\<string> | Promise used to return the type of the component.| 4842 4843**Example** 4844 4845```ts 4846import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4847async function demo() { 4848 let driver: UiDriver = UiDriver.create(); 4849 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4850 let type = await button.getType(); 4851} 4852``` 4853 4854### isClickable<sup>(deprecated)</sup> 4855 4856isClickable(): Promise\<boolean> 4857 4858Obtains the clickable status of this component. 4859 4860This API is deprecated since API version 9. You are advised to use [isClickable<sup>9+</sup>](#isclickable9) instead. 4861 4862**System capability**: SystemCapability.Test.UiTest 4863 4864**Return value** 4865 4866| Type | Description | 4867| ----------------- | ------------------------------------------------------------ | 4868| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is clickable, and **false** means the opposite.| 4869 4870**Example** 4871 4872```ts 4873import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4874async function demo() { 4875 let driver: UiDriver = UiDriver.create(); 4876 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4877 if(await button.isClickable()) { 4878 console.info('This button can be Clicked'); 4879 } else { 4880 console.info('This button can not be Clicked'); 4881 } 4882} 4883``` 4884 4885### isScrollable<sup>(deprecated)</sup> 4886 4887isScrollable(): Promise\<boolean> 4888 4889Obtains the scrollable status of this component. 4890 4891This API is deprecated since API version 9. You are advised to use [isScrollable<sup>9+</sup>](#isscrollable9) instead. 4892 4893**System capability**: SystemCapability.Test.UiTest 4894 4895**Return value** 4896 4897| Type | Description | 4898| ----------------- | ------------------------------------------------------------ | 4899| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is scrollable, and **false** means the opposite.| 4900 4901**Example** 4902 4903```ts 4904import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4905async function demo() { 4906 let driver: UiDriver = UiDriver.create(); 4907 let scrollBar: UiComponent = await driver.findComponent(BY.scrollable(true)); 4908 if(await scrollBar.isScrollable()) { 4909 console.info('This scrollBar can be operated'); 4910 } else { 4911 console.info('This scrollBar can not be operated'); 4912 } 4913} 4914``` 4915 4916 4917### isEnabled<sup>(deprecated)</sup> 4918 4919isEnabled(): Promise\<boolean> 4920 4921Obtains the enabled status of this component. 4922 4923This API is deprecated since API version 9. You are advised to use [isEnabled<sup>9+</sup>](#isenabled9) instead. 4924 4925**System capability**: SystemCapability.Test.UiTest 4926 4927**Return value** 4928 4929| Type | Description | 4930| ----------------- | ---------------------------------------------------------- | 4931| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is enabled, and **false** means the opposite.| 4932 4933**Example** 4934 4935```ts 4936import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4937async function demo() { 4938 let driver: UiDriver = UiDriver.create(); 4939 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4940 if(await button.isEnabled()) { 4941 console.info('This button can be operated'); 4942 } else { 4943 console.info('This button can not be operated'); 4944 } 4945} 4946 4947``` 4948 4949### isFocused<sup>(deprecated)</sup> 4950 4951isFocused(): Promise\<boolean> 4952 4953Obtains the focused status of this component. 4954 4955This API is deprecated since API version 9. You are advised to use [isFocused<sup>9+</sup>](#isfocused9) instead. 4956 4957**System capability**: SystemCapability.Test.UiTest 4958 4959**Return value** 4960 4961| Type | Description | 4962| ----------------- | ------------------------------------------------------------ | 4963| Promise\<boolean> | Promise used to return the result. The value **true** means that the target component is focused, and **false** means the opposite.| 4964 4965**Example** 4966 4967```ts 4968import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 4969async function demo() { 4970 let driver: UiDriver = UiDriver.create(); 4971 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4972 if(await button.isFocused()) { 4973 console.info('This button is focused'); 4974 } else { 4975 console.info('This button is not focused'); 4976 } 4977} 4978``` 4979 4980### isSelected<sup>(deprecated)</sup> 4981 4982isSelected(): Promise\<boolean> 4983 4984Obtains the selected status of this component. 4985 4986This API is deprecated since API version 9. You are advised to use [isSelected<sup>9+</sup>](#isselected9) instead. 4987 4988**System capability**: SystemCapability.Test.UiTest 4989 4990**Return value** 4991 4992| Type | Description | 4993| ----------------- | ----------------------------------------------------- | 4994| Promise\<boolean> | Promise used to return the selected status of the component. The value **true** means that the component is selected, and **false** means the opposite.| 4995 4996**Example** 4997 4998```ts 4999import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 5000async function demo() { 5001 let driver: UiDriver = UiDriver.create(); 5002 let button: UiComponent = await driver.findComponent(BY.type('Button')); 5003 if(await button.isSelected()) { 5004 console.info('This button is selected'); 5005 } else { 5006 console.info('This button is not selected'); 5007 } 5008} 5009``` 5010 5011### inputText<sup>(deprecated)</sup> 5012 5013inputText(text: string): Promise\<void> 5014 5015Inputs text into a component. This API is applicable to text box components. 5016 5017This API is deprecated since API version 9. You are advised to use [inputText<sup>9+</sup>](#inputtext9) instead. 5018 5019**System capability**: SystemCapability.Test.UiTest 5020 5021**Parameters** 5022 5023| Name| Type | Mandatory| Description | 5024| ------ | ------ | ---- | ---------------- | 5025| text | string | Yes | Text to enter.| 5026 5027**Example** 5028 5029```ts 5030import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 5031async function demo() { 5032 let driver: UiDriver = UiDriver.create(); 5033 let text: UiComponent = await driver.findComponent(BY.text('hello world')); 5034 await text.inputText('123'); 5035} 5036``` 5037 5038### scrollSearch<sup>(deprecated)</sup> 5039 5040scrollSearch(by: By): Promise\<UiComponent> 5041 5042Scrolls on this component to search for the target component (applicable to components that support scrolling, such as **List**). 5043 5044This API is deprecated since API version 9. You are advised to use [scrollSearch<sup>9+</sup>](#scrollsearch9) instead. 5045 5046**System capability**: SystemCapability.Test.UiTest 5047 5048**Parameters** 5049 5050| Name| Type | Mandatory| Description | 5051| ------ | ------------------- | ---- | -------------------- | 5052| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 5053 5054**Return value** 5055 5056| Type | Description | 5057| ----------------------------------------------- | ------------------------------------- | 5058| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise used to return the target component.| 5059 5060**Example** 5061 5062```ts 5063import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 5064async function demo() { 5065 let driver: UiDriver = UiDriver.create(); 5066 let scrollBar: UiComponent = await driver.findComponent(BY.type('Scroll')); 5067 let button = await scrollBar.scrollSearch(BY.text('next page')); 5068} 5069``` 5070 5071## UiDriver<sup>(deprecated)</sup> 5072 5073The **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. 5074All APIs provided by this class, except **UiDriver.create()**, use a promise to return the result and must be invoked using **await**. 5075 5076This class is deprecated since API version 9. You are advised to use [Driver<sup>9+</sup>](#driver9) instead. 5077 5078### create<sup>(deprecated)</sup> 5079 5080static create(): UiDriver 5081 5082Creates a **UiDriver** object and returns the object created. This API is a static API. 5083 5084This API is deprecated since API version 9. You are advised to use [create<sup>9+</sup>](#create9) instead. 5085 5086**System capability**: SystemCapability.Test.UiTest 5087 5088**Return value** 5089 5090| Type | Description | 5091| -------- | ------------------------ | 5092| UiDriver | **UiDriver** object created.| 5093 5094**Example** 5095 5096```ts 5097import { UiDriver } from '@kit.TestKit'; 5098async function demo() { 5099 let driver: UiDriver = UiDriver.create(); 5100} 5101``` 5102 5103### delayMs<sup>(deprecated)</sup> 5104 5105delayMs(duration: number): Promise\<void> 5106 5107Delays this **UiDriver** object within the specified duration. 5108 5109This API is deprecated since API version 9. You are advised to use [delayMs<sup>9+</sup>](#delayms9) instead. 5110 5111**System capability**: SystemCapability.Test.UiTest 5112 5113**Parameters** 5114 5115| Name | Type | Mandatory| Description | 5116| -------- | ------ | ---- | ------------ | 5117| duration | number | Yes | Duration of time.| 5118 5119**Example** 5120 5121```ts 5122import { UiDriver } from '@kit.TestKit'; 5123async function demo() { 5124 let driver: UiDriver = UiDriver.create(); 5125 await driver.delayMs(1000); 5126} 5127``` 5128 5129### findComponent<sup>(deprecated)</sup> 5130 5131findComponent(by: By): Promise\<UiComponent> 5132 5133Searches this **UiDriver** object for the target component that matches the given attributes. 5134 5135This API is deprecated since API version 9. You are advised to use [findComponent<sup>9+</sup>](#findcomponent9) instead. 5136 5137**System capability**: SystemCapability.Test.UiTest 5138 5139**Parameters** 5140 5141| Name| Type | Mandatory| Description | 5142| ------ | ------------------- | ---- | -------------------- | 5143| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 5144 5145**Return value** 5146 5147| Type | Description | 5148| ----------------------------------------------- | --------------------------------- | 5149| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise used to return the found component.| 5150 5151**Example** 5152 5153```ts 5154import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 5155async function demo() { 5156 let driver: UiDriver = UiDriver.create(); 5157 let button: UiComponent = await driver.findComponent(BY.text('next page')); 5158} 5159``` 5160 5161### findComponents<sup>(deprecated)</sup> 5162 5163findComponents(by: By): Promise\<Array\<UiComponent>> 5164 5165Searches this **UiDriver** object for all components that match the given attributes. 5166 5167This API is deprecated since API version 9. You are advised to use [findComponents<sup>9+</sup>](#findcomponents9) instead. 5168 5169**System capability**: SystemCapability.Test.UiTest 5170 5171**Parameters** 5172 5173| Name| Type | Mandatory| Description | 5174| ------ | ------------------- | ---- | -------------------- | 5175| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 5176 5177**Return value** 5178 5179| Type | Description | 5180| ------------------------------------------------------- | --------------------------------------- | 5181| Promise\<Array\<[UiComponent](#uicomponentdeprecated)>> | Promise used to return a list of found components.| 5182 5183**Example** 5184 5185```ts 5186import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 5187async function demo() { 5188 let driver: UiDriver = UiDriver.create(); 5189 let buttonList: Array<UiComponent> = await driver.findComponents(BY.text('next page')); 5190} 5191``` 5192 5193### assertComponentExist<sup>(deprecated)</sup> 5194 5195assertComponentExist(by: By): Promise\<void> 5196 5197Asserts 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. 5198 5199This API is deprecated since API version 9. You are advised to use [assertComponentExist<sup>9+</sup>](#assertcomponentexist9) instead. 5200 5201**System capability**: SystemCapability.Test.UiTest 5202 5203**Parameters** 5204 5205| Name| Type | Mandatory| Description | 5206| ------ | ------------------- | ---- | -------------------- | 5207| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 5208 5209**Error codes** 5210 5211For details about the error codes, see [UiTest Error Codes](errorcode-uitest.md). 5212 5213| ID| Error Message | 5214| -------- | ------------------------------------------------ | 5215| 401 | if the input parameters are invalid. | 5216| 17000002 | if the async function was not called with await. | 5217| 17000003 | if the assertion failed. | 5218 5219**Example** 5220 5221```ts 5222import { UiDriver, BY } from '@kit.TestKit'; 5223async function demo() { 5224 let driver: UiDriver = UiDriver.create(); 5225 await driver.assertComponentExist(BY.text('next page')); 5226} 5227``` 5228 5229### pressBack<sup>(deprecated)</sup> 5230 5231pressBack(): Promise\<void> 5232 5233Presses the Back button on this **UiDriver** object. 5234 5235This API is deprecated since API version 9. You are advised to use [pressBack<sup>9+</sup>](#pressback9) instead. 5236 5237**System capability**: SystemCapability.Test.UiTest 5238 5239**Example** 5240 5241```ts 5242import { UiDriver } from '@kit.TestKit'; 5243async function demo() { 5244 let driver: UiDriver = UiDriver.create(); 5245 await driver.pressBack(); 5246} 5247``` 5248 5249### triggerKey<sup>(deprecated)</sup> 5250 5251triggerKey(keyCode: number): Promise\<void> 5252 5253Triggers the key of this **UiDriver** object that matches the given key code. 5254 5255This API is deprecated since API version 9. You are advised to use [triggerKey<sup>9+</sup>](#triggerkey9) instead. 5256 5257**System capability**: SystemCapability.Test.UiTest 5258 5259**Parameters** 5260 5261| Name | Type | Mandatory| Description | 5262| ------- | ------ | ---- | ------------- | 5263| keyCode | number | Yes | Key code.| 5264 5265**Example** 5266 5267```ts 5268import { Driver, UiDriver } from '@kit.TestKit'; 5269async function demo() { 5270 let driver: UiDriver = UiDriver.create(); 5271 await driver.triggerKey(123); 5272} 5273``` 5274 5275 5276### click<sup>(deprecated)</sup> 5277 5278click(x: number, y: number): Promise\<void> 5279 5280Clicks a specific point of this **UiDriver** object based on the given coordinates. 5281 5282This API is deprecated since API version 9. You are advised to use [click<sup>9+</sup>](#click9) instead. 5283 5284**System capability**: SystemCapability.Test.UiTest 5285 5286**Parameters** 5287 5288| Name| Type | Mandatory| Description | 5289| ------ | ------ | ---- | -------------------------------------- | 5290| x | number | Yes | X coordinate of the end point.| 5291| y | number | Yes | Y coordinate of the end point.| 5292 5293**Example** 5294 5295```ts 5296import { UiDriver } from '@kit.TestKit'; 5297async function demo() { 5298 let driver: UiDriver = UiDriver.create(); 5299 await driver.click(100,100); 5300} 5301``` 5302 5303### doubleClick<sup>(deprecated)</sup> 5304 5305doubleClick(x: number, y: number): Promise\<void> 5306 5307Double-clicks a specific point of this **UiDriver** object based on the given coordinates. 5308 5309This API is deprecated since API version 9. You are advised to use [doubleClick<sup>9+</sup>](#doubleclick9) instead. 5310 5311**System capability**: SystemCapability.Test.UiTest 5312 5313**Parameters** 5314 5315| Name| Type | Mandatory| Description | 5316| ------ | ------ | ---- | -------------------------------------- | 5317| x | number | Yes | X coordinate of the end point.| 5318| y | number | Yes | Y coordinate of the end point.| 5319 5320**Example** 5321 5322```ts 5323import { UiDriver } from '@kit.TestKit'; 5324async function demo() { 5325 let driver: UiDriver = UiDriver.create(); 5326 await driver.doubleClick(100,100); 5327} 5328``` 5329 5330### longClick<sup>(deprecated)</sup> 5331 5332longClick(x: number, y: number): Promise\<void> 5333 5334Long-clicks a specific point of this **UiDriver** object based on the given coordinates. 5335 5336This API is deprecated since API version 9. You are advised to use [longClick<sup>9+</sup>](#longclick9) instead. 5337 5338**System capability**: SystemCapability.Test.UiTest 5339 5340**Parameters** 5341 5342| Name| Type | Mandatory| Description | 5343| ------ | ------ | ---- | -------------------------------------- | 5344| x | number | Yes | X coordinate of the end point.| 5345| y | number | Yes | Y coordinate of the end point.| 5346 5347**Example** 5348 5349```ts 5350import { UiDriver } from '@kit.TestKit'; 5351async function demo() { 5352 let driver: UiDriver = UiDriver.create(); 5353 await driver.longClick(100,100); 5354} 5355``` 5356 5357### swipe<sup>(deprecated)</sup> 5358 5359swipe(startx: number, starty: number, endx: number, endy: number): Promise\<void> 5360 5361Swipes on this **UiDriver** object from the start point to the end point based on the given coordinates. 5362 5363This API is deprecated since API version 9. You are advised to use [swipe<sup>9+</sup>](#swipe9) instead. 5364 5365**System capability**: SystemCapability.Test.UiTest 5366 5367**Parameters** 5368 5369| Name| Type | Mandatory| Description | 5370| ------ | ------ | ---- | -------------------------------------- | 5371| startx | number | Yes | X coordinate of the start point.| 5372| starty | number | Yes | Y coordinate of the start point.| 5373| endx | number | Yes | X coordinate of the end point.| 5374| endy | number | Yes | Y coordinate of the end point.| 5375 5376**Example** 5377 5378```ts 5379import { UiDriver } from '@kit.TestKit'; 5380async function demo() { 5381 let driver: UiDriver = UiDriver.create(); 5382 await driver.swipe(100,100,200,200); 5383} 5384``` 5385 5386### screenCap<sup>(deprecated)</sup> 5387 5388screenCap(savePath: string): Promise\<boolean> 5389 5390Captures the current screen of this **UiDriver** object and saves it as a PNG image to the given save path. 5391 5392This API is deprecated since API version 9. You are advised to use [screenCap<sup>9+</sup>](#screencap9) instead. 5393 5394**System capability**: SystemCapability.Test.UiTest 5395 5396**Parameters** 5397 5398| Name | Type | Mandatory| Description | 5399| -------- | ------ | ---- | -------------- | 5400| savePath | string | Yes | File save path.| 5401 5402**Return value** 5403 5404| Type | Description | 5405| ----------------- | -------------------------------------- | 5406| Promise\<boolean> | Promise used to return the result. The value **true** means that the operation is successful.| 5407 5408**Example** 5409 5410```ts 5411import { UiDriver } from '@kit.TestKit'; 5412async function demo() { 5413 let driver: UiDriver = UiDriver.create(); 5414 await driver.screenCap('/data/storage/el2/base/cache/1.png'); 5415} 5416``` 5417
