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