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 API 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 API 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 API is deprecated since API version 9. You are advised to use [Driver<sup>9+</sup>](#driver9) instead. 14 15>**NOTE** 16> 17>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. 18 19 20## Modules to Import 21 22```js 23import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix} from '@ohos.UiTest'; 24``` 25 26## MatchPattern 27 28Enumerates the match patterns supported for component attributes. 29 30**System capability**: SystemCapability.Test.UiTest 31 32| Name | Value | Description | 33| ----------- | ---- | -------------- | 34| EQUALS | 0 | Equals the given value. | 35| CONTAINS | 1 | Contains the given value. | 36| STARTS_WITH | 2 | Starts with the given value.| 37| ENDS_WITH | 3 | Ends with the given value.| 38 39## ResizeDirection<sup>9+</sup> 40 41Enumerates the directions in which a window can be resized. 42 43**System capability**: SystemCapability.Test.UiTest 44 45| Name | Value | Description | 46| ---------- | ---- | -------- | 47| LEFT | 0 | Left. | 48| RIGHT | 1 | Right. | 49| UP | 2 | Up. | 50| DOWN | 3 | Down. | 51| LEFT_UP | 4 | Upper left.| 52| LEFT_DOWN | 5 | Lower left.| 53| RIGHT_UP | 6 | Upper right.| 54| RIGHT_DOWN | 7 | Lower right.| 55 56## Point<sup>9+</sup> 57 58Provides the coordinates of a point. 59 60**System capability**: SystemCapability.Test.UiTest 61 62| Name| Type | Readable| Writable| Description | 63| ---- | ------ | ---- | ---- | ---------------- | 64| x | number | Yes | No | X-coordinate of a point.| 65| y | number | Yes | No | Y-coordinate of a point.| 66 67## Rect<sup>9+</sup> 68 69Provides bounds information of a component. 70 71**System capability**: SystemCapability.Test.UiTest 72 73| Name | Type | Readable| Writable| Description | 74| ------ | ------ | ---- | ---- | ------------------------- | 75| left | number | Yes | No | X-coordinate of the upper left corner of the component bounds.| 76| top | number | Yes | No | Y-coordinate of the upper left corner of the component bounds.| 77| right | number | Yes | No | X-coordinate of the lower right corner of the component bounds.| 78| bottom | number | Yes | No | Y-coordinate of the lower right corner of the component bounds.| 79 80## WindowMode<sup>9+</sup> 81 82**System capability**: SystemCapability.Test.UiTest 83 84Enumerates the window modes. 85 86| Name | Value | Description | 87| ---------- | ---- | ---------- | 88| FULLSCREEN | 0 | Full-screen mode.| 89| PRIMARY | 1 | Primary window mode. | 90| SECONDARY | 2 | Secondary window mode.| 91| FLOATING | 3 | Floating window mode.| 92 93## DisplayRotation<sup>9+</sup> 94 95**System capability**: SystemCapability.Test.UiTest 96 97Describes the display rotation of the device. 98 99| Name | Value | Description | 100| ------------ | ---- | ---------------------------------------- | 101| ROTATION_0 | 0 | The device display is not rotated and is in its original vertical orientation. | 102| ROTATION_90 | 1 | The device display rotates 90° clockwise and is in landscape orientation. | 103| ROTATION_180 | 2 | The device display rotates 180° clockwise and is in reverse vertical orientation.| 104| ROTATION_270 | 3 | The device display rotates 270° clockwise and is in reverse landscape orientation.| 105 106## WindowFilter<sup>9+</sup> 107 108Provides the flag attributes of this window. 109 110**System capability**: SystemCapability.Test.UiTest 111 112| Name | Type | Readable| Writable| Description | 113| ---------- | ------- | ---- | ---- | -------------------------- | 114| bundleName | string | Yes | No | Bundle name of the application to which the window belongs. | 115| title | string | Yes | No | Title of the window. | 116| focused | boolean | Yes | No | Whether the window is in focused state. | 117| actived | boolean | Yes | No | Whether the window is interacting with the user.| 118 119## On<sup>9+</sup> 120 121Since 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. 122The API capabilities provided by the **On** class exhibit the following features: 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](#isbefore) and [ON.isAfter](#isafter) 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. 123 124```js 125ON.text('123').type('button'); 126``` 127 128### text<sup>9+</sup> 129 130text(txt: string, pattern?: MatchPattern): On 131 132Specifies the text attribute of the target component. Multiple match patterns are supported. 133 134**System capability**: SystemCapability.Test.UiTest 135 136**Parameters** 137 138| Name | Type | Mandatory| Description | 139| ------- | ----------------------------- | ---- | --------------------------------------------------- | 140| txt | string | Yes | Component text, used to match the target component. | 141| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 142 143**Return value** 144 145| Type | Description | 146| ---------- | ---------------------------------- | 147| [On](#on9) | **On** object that matches the text attribute of the target component.| 148 149**Example** 150 151```js 152let on = ON.text('123'); // Use the static constructor ON to create an On object and specify the text attribute of the target component. 153``` 154 155 156### id<sup>9+</sup> 157 158id(id: string): On 159 160Specifies the ID attribute of the target component. 161 162**System capability**: SystemCapability.Test.UiTest 163 164**Parameters** 165 166| Name| Type | Mandatory| Description | 167| ------ | ------ | ---- | ---------------- | 168| id | string | Yes | Component ID.| 169 170**Return value** 171 172| Type | Description | 173| ---------- | -------------------------------- | 174| [On](#on9) | **On** object that matches the ID attribute of the target component.| 175 176**Example** 177 178```js 179let on = ON.id('123'); // Use the static constructor ON to create an On object and specify the ID attribute of the target component. 180``` 181 182 183### type<sup>9+</sup> 184 185type(tp: string): On 186 187Specifies the type attribute of the target component. 188 189**System capability**: SystemCapability.Test.UiTest 190 191**Parameters** 192 193| Name| Type | Mandatory| Description | 194| ------ | ------ | ---- | -------------- | 195| tp | string | Yes | Component type.| 196 197**Return value** 198 199| Type | Description | 200| ---------- | ---------------------------------------- | 201| [On](#on9) | **On** object that matches the type attribute of the target component.| 202 203**Example** 204 205```js 206let on = ON.type('button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component. 207``` 208 209 210### clickable<sup>9+</sup> 211 212clickable(b?: boolean): On 213 214Specifies the clickable status attribute of the target component. 215 216**System capability**: SystemCapability.Test.UiTest 217 218**Parameters** 219 220| Name| Type | Mandatory| Description | 221| ------ | ------- | ---- | ------------------------------------------------------------ | 222| b | boolean | No | Clickable status of the target component.<br>**true**: clickable.<br>**false**: not clickable.<br>Default value: **true** | 223 224**Return value** 225 226| Type | Description | 227| ---------- | ------------------------------------------ | 228| [On](#on9) | **On** object that matches the clickable status attribute of the target component.| 229 230**Example** 231 232```js 233let on = ON.clickable(true); // Use the static constructor ON to create an On object and specify the clickable status attribute of the target component. 234``` 235 236### longClickable<sup>9+</sup> 237 238longClickable(b?: boolean): On 239 240Specifies the long-clickable status attribute of the target component. 241 242**System capability**: SystemCapability.Test.UiTest 243 244**Parameters** 245 246| Name| Type | Mandatory| Description | 247| ------ | ------- | ---- | ------------------------------------------------------------ | 248| b | boolean | No | Long-clickable status of the target component.<br>**true**: long-clickable.<br>**false**: not long-clickable.<br>Default value: **true** | 249 250**Return value** 251 252| Type | Description | 253| ---------- | ---------------------------------------------- | 254| [On](#on9) | **On** object that matches the long-clickable status attribute of the target component.| 255 256**Example** 257 258```js 259let on = ON.longClickable(true); // Use the static constructor ON to create an On object and specify the long-clickable status attribute of the target component. 260``` 261 262 263### scrollable<sup>9+</sup> 264 265scrollable(b?: boolean): On 266 267Specifies the scrollable status attribute of the target component. 268 269**System capability**: SystemCapability.Test.UiTest 270 271**Parameters** 272 273| Name| Type | Mandatory| Description | 274| ------ | ------- | ---- | ----------------------------------------------------------- | 275| b | boolean | No | Scrollable status of the target component.<br>**true**: scrollable.<br>**false**: not scrollable.<br>Default value: **true** | 276 277**Return value** 278 279| Type | Description | 280| ---------- | ------------------------------------------ | 281| [On](#on9) | **On** object that matches the scrollable status attribute of the target component.| 282 283**Example** 284 285```js 286let on = ON.scrollable(true); // Use the static constructor ON to create an On object and specify the scrollable status attribute of the target component. 287``` 288 289### enabled<sup>9+</sup> 290 291enabled(b?: boolean): On 292 293Specifies the enabled status attribute of the target component. 294 295**System capability**: SystemCapability.Test.UiTest 296 297**Parameters** 298 299| Name| Type | Mandatory| Description | 300| ------ | ------- | ---- | --------------------------------------------------------- | 301| b | boolean | No | Enabled status of the target component.<br>**true**: enabled.<br>**false**: not enabled.<br>Default value: **true** | 302 303**Return value** 304 305| Type | Description | 306| ---------- | ---------------------------------------- | 307| [On](#on9) | **On** object that matches the enabled status attribute of the target component.| 308 309**Example** 310 311```js 312let on = ON.enabled(true); // Use the static constructor ON to create an On object and specify the enabled status attribute of the target component. 313``` 314 315### focused<sup>9+</sup> 316 317focused(b?: boolean): On 318 319Specifies the focused status attribute of the target component. 320 321**System capability**: SystemCapability.Test.UiTest 322 323**Parameters** 324 325| Name| Type | Mandatory| Description | 326| ------ | ------- | ---- | ----------------------------------------------------- | 327| b | boolean | No | Focused status of the target component.<br>**true**: focused.<br>**false**: not focused.<br>Default value: **true** | 328 329**Return value** 330 331| Type | Description | 332| ---------- | ---------------------------------------- | 333| [On](#on9) | **On** object that matches the focused status attribute of the target component.| 334 335**Example** 336 337```js 338let on = ON.focused(true); // Use the static constructor ON to create an On object and specify the focused status attribute of the target component. 339``` 340 341### selected<sup>9+</sup> 342 343selected(b?: boolean): On 344 345Specifies the selected status attribute of the target component. 346 347**System capability**: SystemCapability.Test.UiTest 348 349**Parameters** 350 351| Name| Type | Mandatory| Description | 352| ------ | ------- | ---- | ------------------------------------------------------------ | 353| b | boolean | No | Selected status of the target component.<br>**true**: selected.<br>**false**: not selected.<br>Default value: **true** | 354 355**Return value** 356 357| Type | Description | 358| ---------- | ------------------------------------------ | 359| [On](#on9) | **On** object that matches the selected status attribute of the target component.| 360 361**Example** 362 363```js 364let on = ON.selected(true); // Use the static constructor ON to create an On object and specify the selected status attribute of the target component. 365``` 366 367### checked<sup>9+</sup> 368 369checked(b?: boolean): On 370 371Specifies the checked status attribute of the target component. 372 373**System capability**: SystemCapability.Test.UiTest 374 375**Parameters** 376 377| Name| Type | Mandatory| Description | 378| ------ | ------- | ---- | ------------------------------------------------------------ | 379| b | boolean | No | Checked status of the target component.<br>**true**: checked.<br>**false**: not checked.<br>Default value: **false** | 380 381**Return value** 382 383| Type | Description | 384| ---------- | ------------------------------------------ | 385| [On](#on9) | **On** object that matches the checked status attribute of the target component.| 386 387**Example** 388 389```js 390let on = ON.checked(true); // Use the static constructor ON to create an On object and specify the checked status attribute of the target component. 391``` 392 393### checkable<sup>9+</sup> 394 395checkable(b?: boolean): On 396 397Specifies the checkable status attribute of the target component. 398 399**System capability**: SystemCapability.Test.UiTest 400 401**Parameters** 402 403| Name| Type | Mandatory| Description | 404| ------ | ------- | ---- | ------------------------------------------------------------ | 405| b | boolean | No | Checkable status of the target component.<br>**true**: checkable.<br>**false**: not checkable.<br>Default value: **false** | 406 407**Return value** 408 409| Type | Description | 410| ---------- | -------------------------------------------- | 411| [On](#on9) | **On** object that matches the checkable status attribute of the target component.| 412 413**Example** 414 415```js 416let on = ON.checkable(true); // Use the static constructor ON to create an On object and specify the checkable status attribute of the target component. 417``` 418 419### isBefore<sup>9+</sup> 420 421isBefore(on: On): On 422 423Specifies the attributes of the component before which the target component is located. 424 425**System capability**: SystemCapability.Test.UiTest 426 427**Parameters** 428 429| Name| Type | Mandatory| Description | 430| ------ | ---------- | ---- | -------------------- | 431| on | [On](#on9) | Yes | Attributes of the component before which the target component is located.| 432 433**Return value** 434 435| Type | Description | 436| ---------- | ---------------------------------------------------- | 437| [On](#on9) | **On** object.| 438 439**Example** 440 441```js 442let on = ON.isBefore(ON.text('123')); // Use the static constructor ON to create an On object and specify the attributes of the component before which the target component is located. 443``` 444 445### isAfter<sup>9+</sup> 446 447isAfter(on: On): On 448 449Specifies the attributes of the component after which the target component is located. 450 451**System capability**: SystemCapability.Test.UiTest 452 453**Parameters** 454 455| Name| Type | Mandatory| Description | 456| ------ | ---------- | ---- | -------------------- | 457| on | [On](#on9) | Yes | Attributes of the component after which the target component is located.| 458 459**Return value** 460 461| Type | Description | 462| ---------- | ---------------------------------------------------- | 463| [On](#on9) | **On** object.| 464 465**Example** 466 467```js 468let on = ON.isAfter(ON.text('123')); // Use the static constructor ON to create an On object and specify the attributes of the component after which the target component is located. 469``` 470 471## Component<sup>9+</sup> 472 473In **UiTest** of API version 9, the **Component** 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. 474All APIs provided in this class use a promise to return the result and must be invoked using **await**. 475 476### click<sup>9+</sup> 477 478click(): Promise\<void> 479 480Clicks this component. 481 482**System capability**: SystemCapability.Test.UiTest 483 484**Error codes** 485 486For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 487 488| ID| Error Message | 489| -------- | ---------------------------------------- | 490| 17000002 | API does not allow calling concurrently. | 491| 17000004 | Component lost/UiWindow lost. | 492 493**Example** 494 495```js 496async function demo() { 497 let driver = Driver.create(); 498 let button = await driver.findComponent(ON.type('button')); 499 await button.click(); 500} 501``` 502 503### doubleClick<sup>9+</sup> 504 505doubleClick(): Promise\<void> 506 507Double-clicks this component. 508 509**System capability**: SystemCapability.Test.UiTest 510 511**Error codes** 512 513For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 514 515| ID| Error Message | 516| -------- | ---------------------------------------- | 517| 17000002 | API does not allow calling concurrently. | 518| 17000004 | Component lost/UiWindow lost. | 519 520**Example** 521 522```js 523async function demo() { 524 let driver = Driver.create(); 525 let button = await driver.findComponent(ON.type('button')); 526 await button.doubleClick(); 527} 528``` 529 530### longClick<sup>9+</sup> 531 532longClick(): Promise\<void> 533 534Long-clicks this component. 535 536**System capability**: SystemCapability.Test.UiTest 537 538**Error codes** 539 540For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 541 542| ID| Error Message | 543| -------- | ---------------------------------------- | 544| 17000002 | API does not allow calling concurrently. | 545| 17000004 | Component lost/UiWindow lost. | 546 547**Example** 548 549```js 550async function demo() { 551 let driver = Driver.create(); 552 let button = await driver.findComponent(ON.type('button')); 553 await button.longClick(); 554} 555``` 556 557### getId<sup>9+</sup> 558 559getId(): Promise\<string> 560 561Obtains the ID of this component. 562 563**System capability**: SystemCapability.Test.UiTest 564 565**Return value** 566 567| Type | Description | 568| ---------------- | ------------------------------- | 569| Promise\<string> | Promise used to return the ID of the component.| 570 571**Error codes** 572 573For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 574 575| ID| Error Message | 576| -------- | ---------------------------------------- | 577| 17000002 | API does not allow calling concurrently. | 578| 17000004 | Component lost/UiWindow lost. | 579 580**Example** 581 582```js 583async function demo() { 584 let driver = Driver.create(); 585 let button = await driver.findComponent(ON.type('button')); 586 let num = await button.getId(); 587} 588``` 589 590### getText<sup>9+</sup> 591 592getText(): Promise\<string> 593 594Obtains the text information of this component. 595 596**System capability**: SystemCapability.Test.UiTest 597 598**Return value** 599 600| Type | Description | 601| ---------------- | --------------------------------- | 602| Promise\<string> | Promise used to return the text information of the component.| 603 604**Error codes** 605 606For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 607 608| ID| Error Message | 609| -------- | ---------------------------------------- | 610| 17000002 | API does not allow calling concurrently. | 611| 17000004 | Component lost/UiWindow lost. | 612 613**Example** 614 615```js 616async function demo() { 617 let driver = Driver.create(); 618 let button = await driver.findComponent(ON.type('button')); 619 let text = await button.getText(); 620} 621``` 622 623### getType<sup>9+</sup> 624 625getType(): Promise\<string> 626 627Obtains the type of this component. 628 629**System capability**: SystemCapability.Test.UiTest 630 631**Return value** 632 633| Type | Description | 634| ---------------- | ----------------------------- | 635| Promise\<string> | Promise used to return the type of the component.| 636 637**Error codes** 638 639For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 640 641| ID| Error Message | 642| -------- | ---------------------------------------- | 643| 17000002 | API does not allow calling concurrently. | 644| 17000004 | Component lost/UiWindow lost. | 645 646**Example** 647 648```js 649async function demo() { 650 let driver = Driver.create(); 651 let button = await driver.findComponent(ON.type('button')); 652 let type = await button.getType(); 653} 654``` 655 656### getBounds<sup>9+</sup> 657 658getBounds(): Promise\<Rect> 659 660Obtains the bounds of this component. 661 662**System capability**: SystemCapability.Test.UiTest 663 664**Return value** 665 666| Type | Description | 667| ------------------------ | ------------------------------------- | 668| Promise\<[Rect](#rect9)> | Promise used to return the bounds of the component.| 669 670**Error codes** 671 672For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 673 674| ID| Error Message | 675| -------- | ---------------------------------------- | 676| 17000002 | API does not allow calling concurrently. | 677| 17000004 | Component lost/UiWindow lost. | 678 679**Example** 680 681```js 682async function demo() { 683 let driver = Driver.create(); 684 let button = await driver.findComponent(ON.type('button')); 685 let rect = await button.getBounds(); 686} 687``` 688 689### getBoundsCenter<sup>9+</sup> 690 691getBoundsCenter(): Promise\<Point> 692 693Obtains the information about the center of the bounding box around this component. 694 695**System capability**: SystemCapability.Test.UiTest 696 697**Return value** 698 699| Type | Description | 700| -------------------------- | ----------------------------------------------- | 701| Promise\<[Point](#point9)> | Promise used to return the information about the center of the bounding box around the component.| 702 703**Error codes** 704 705For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 706 707| ID| Error Message | 708| -------- | ---------------------------------------- | 709| 17000002 | API does not allow calling concurrently. | 710| 17000004 | Component lost/UiWindow lost. | 711 712**Example** 713 714```js 715async function demo() { 716 let driver = Driver.create(); 717 let button = await driver.findComponent(ON.type('button')); 718 let point = await button.getBoundsCenter(); 719} 720``` 721 722### isClickable<sup>9+</sup> 723 724isClickable(): Promise\<boolean> 725 726Obtains the clickable status of this component. 727 728**System capability**: SystemCapability.Test.UiTest 729 730**Return value** 731 732| Type | Description | 733| ----------------- | ------------------------------------------------------------ | 734| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is clickable, and **false** means the opposite.| 735 736**Error codes** 737 738For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 739 740| ID| Error Message | 741| -------- | ---------------------------------------- | 742| 17000002 | API does not allow calling concurrently. | 743| 17000004 | Component lost/UiWindow lost. | 744 745**Example** 746 747```js 748async function demo() { 749 let driver = Driver.create(); 750 let button = await driver.findComponent(ON.type('button')); 751 if(await button.isClickable()) { 752 console.info('This button can be Clicked'); 753 } else { 754 console.info('This button can not be Clicked'); 755 } 756} 757``` 758 759### isLongClickable<sup>9+</sup> 760 761isLongClickable(): Promise\<boolean> 762 763Obtains the long-clickable status of this component. 764 765**System capability**: SystemCapability.Test.UiTest 766 767**Return value** 768 769| Type | Description | 770| ----------------- | ------------------------------------------------------------ | 771| 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.| 772 773**Error codes** 774 775For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 776 777| ID| Error Message | 778| -------- | ---------------------------------------- | 779| 17000002 | API does not allow calling concurrently. | 780| 17000004 | Component lost/UiWindow lost. | 781 782**Example** 783 784```js 785async function demo() { 786 let driver = Driver.create(); 787 let button = await driver.findComponent(ON.type('button')); 788 if(await button.isLongClickable()) { 789 console.info('This button can longClick'); 790 } else { 791 console.info('This button can not longClick'); 792 } 793} 794``` 795 796### isChecked<sup>9+</sup> 797 798isChecked(): Promise\<boolean> 799 800Obtains the checked status of this component. 801 802**System capability**: SystemCapability.Test.UiTest 803 804**Return value** 805 806| Type | Description | 807| ----------------- | ------------------------------------------------------------ | 808| 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.| 809 810**Error codes** 811 812For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 813 814| ID| Error Message | 815| -------- | ---------------------------------------- | 816| 17000002 | API does not allow calling concurrently. | 817| 17000004 | Component lost/UiWindow lost. | 818 819**Example** 820 821```js 822async function demo() { 823 let driver = Driver.create(); 824 let checkBox = await driver.findComponent(ON.type('Checkbox')); 825 if(await checkBox.isChecked) { 826 console.info('This checkBox is checked'); 827 } else { 828 console.info('This checkBox is not checked'); 829 } 830} 831``` 832 833### isCheckable<sup>9+</sup> 834 835isCheckable(): Promise\<boolean> 836 837Obtains the checkable status of this component. 838 839**System capability**: SystemCapability.Test.UiTest 840 841**Return value** 842 843| Type | Description | 844| ----------------- | ------------------------------------------------------------ | 845| 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.| 846 847**Error codes** 848 849For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 850 851| ID| Error Message | 852| -------- | ---------------------------------------- | 853| 17000002 | API does not allow calling concurrently. | 854| 17000004 | Component lost/UiWindow lost. | 855 856**Example** 857 858```js 859async function demo() { 860 let driver = Driver.create(); 861 let checkBox = await driver.findComponent(ON.type('Checkbox')); 862 if(await checkBox.isCheckable) { 863 console.info('This checkBox is checkable'); 864 } else { 865 console.info('This checkBox is not checkable'); 866 } 867} 868``` 869 870### isScrollable<sup>9+</sup> 871 872isScrollable(): Promise\<boolean> 873 874Obtains the scrollable status of this component. 875 876**System capability**: SystemCapability.Test.UiTest 877 878**Return value** 879 880| Type | Description | 881| ----------------- | ------------------------------------------------------------ | 882| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is scrollable, and **false** means the opposite.| 883 884**Error codes** 885 886For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 887 888| ID| Error Message | 889| -------- | ---------------------------------------- | 890| 17000002 | API does not allow calling concurrently. | 891| 17000004 | Component lost/UiWindow lost. | 892 893**Example** 894 895```js 896async function demo() { 897 let driver = Driver.create(); 898 let scrollBar = await driver.findComponent(ON.scrollable(true)); 899 if(await scrollBar.isScrollable()) { 900 console.info('This scrollBar can be operated'); 901 } else { 902 console.info('This scrollBar can not be operated'); 903 } 904} 905``` 906 907 908### isEnabled<sup>9+</sup> 909 910isEnabled(): Promise\<boolean> 911 912Obtains the enabled status of this component. 913 914**System capability**: SystemCapability.Test.UiTest 915 916**Return value** 917 918| Type | Description | 919| ----------------- | ---------------------------------------------------------- | 920| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is enabled, and **false** means the opposite.| 921 922**Error codes** 923 924For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 925 926| ID| Error Message | 927| -------- | ---------------------------------------- | 928| 17000002 | API does not allow calling concurrently. | 929| 17000004 | Component lost/UiWindow lost. | 930 931**Example** 932 933```js 934async function demo() { 935 let driver = Driver.create(); 936 let button = await driver.findComponent(ON.type('button')); 937 if(await button.isEnabled()) { 938 console.info('This button can be operated'); 939 } else { 940 console.info('This button can not be operated'); 941 } 942} 943 944``` 945 946### isFocused<sup>9+</sup> 947 948isFocused(): Promise\<boolean> 949 950Obtains the focused status of this component. 951 952**System capability**: SystemCapability.Test.UiTest 953 954**Return value** 955 956| Type | Description | 957| ----------------- | ------------------------------------------------------------ | 958| 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.| 959 960**Error codes** 961 962For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 963 964| ID| Error Message | 965| -------- | ---------------------------------------- | 966| 17000002 | API does not allow calling concurrently. | 967| 17000004 | Component lost/UiWindow lost. | 968 969**Example** 970 971```js 972async function demo() { 973 let driver = Driver.create(); 974 let button = await driver.findComponent(ON.type('button')); 975 if(await button.isFocused()) { 976 console.info('This button is focused'); 977 } else { 978 console.info('This button is not focused'); 979 } 980} 981``` 982 983### isSelected<sup>9+</sup> 984 985isSelected(): Promise\<boolean> 986 987Obtains the selected status of this component. 988 989**System capability**: SystemCapability.Test.UiTest 990 991**Return value** 992 993| Type | Description | 994| ----------------- | --------------------------------------------------- | 995| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is selected, and **false** means the opposite.| 996 997**Error codes** 998 999For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1000 1001| ID| Error Message | 1002| -------- | ---------------------------------------- | 1003| 17000002 | API does not allow calling concurrently. | 1004| 17000004 | Component lost/UiWindow lost. | 1005 1006**Example** 1007 1008```js 1009async function demo() { 1010 let driver = Driver.create(); 1011 let button = await driver.findComponent(ON.type('button')); 1012 if(await button.isSelected()) { 1013 console.info('This button is selected'); 1014 } else { 1015 console.info('This button is not selected'); 1016 } 1017} 1018``` 1019 1020### inputText<sup>9+</sup> 1021 1022inputText(text: string): Promise\<void> 1023 1024Enters text into this component (available for text boxes). 1025 1026**System capability**: SystemCapability.Test.UiTest 1027 1028**Parameters** 1029 1030| Name| Type | Mandatory| Description | 1031| ------ | ------ | ---- | ---------------------------------------- | 1032| text | string | Yes | Text to enter, which can contain English and special characters.| 1033 1034**Error codes** 1035 1036For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1037 1038| ID| Error Message | 1039| -------- | ---------------------------------------- | 1040| 17000002 | API does not allow calling concurrently. | 1041| 17000004 | Component lost/UiWindow lost. | 1042 1043**Example** 1044 1045```js 1046async function demo() { 1047 let driver = Driver.create(); 1048 let text = await driver.findComponent(ON.text('hello world')); 1049 await text.inputText('123'); 1050} 1051``` 1052 1053### clearText<sup>9+</sup> 1054 1055clearText(): Promise\<void> 1056 1057Clears text in this component. This API is applicable to text boxes. 1058 1059**System capability**: SystemCapability.Test.UiTest 1060 1061**Error codes** 1062 1063| ID| Error Message | 1064| -------- | ---------------------------------------- | 1065| 17000002 | API does not allow calling concurrently. | 1066| 17000004 | Component lost/UiWindow lost. | 1067 1068**Example** 1069 1070```js 1071async function demo() { 1072 let driver = Driver.create(); 1073 let text = await driver.findComponent(ON.text('hello world')); 1074 await text.clearText(); 1075} 1076``` 1077 1078### scrollSearch<sup>9+</sup> 1079 1080scrollSearch(on: On): Promise\<Component> 1081 1082Scrolls on this component to search for the target component. This API is applicable to components that support scrolling. 1083 1084**System capability**: SystemCapability.Test.UiTest 1085 1086**Parameters** 1087 1088| Name| Type | Mandatory| Description | 1089| ------ | ---------- | ---- | -------------------- | 1090| on | [On](#on9) | Yes | Attributes of the target component.| 1091 1092**Return value** 1093 1094| Type | Description | 1095| ---------------------------------- | ------------------------------------- | 1096| Promise\<[Component](#component9)> | Promise used to return the target component.| 1097 1098**Error codes** 1099 1100For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1101 1102| ID| Error Message | 1103| -------- | ---------------------------------------- | 1104| 17000002 | API does not allow calling concurrently. | 1105| 17000004 | Component lost/UiWindow lost. | 1106 1107**Example** 1108 1109```js 1110async function demo() { 1111 let driver = Driver.create(); 1112 let button = await driver.findComponent(ON.type('Scroll')); 1113 let button = await scrollBar.scrollSearch(ON.text('next page')); 1114} 1115``` 1116 1117### scrollToTop<sup>9+</sup> 1118 1119scrollToTop(speed?: number): Promise\<void> 1120 1121Scrolls to the top of this component. This API is applicable to components that support scrolling. 1122 1123**System capability**: SystemCapability.Test.UiTest 1124 1125**Parameters** 1126 1127| Name| Type | Mandatory| Description | 1128| ------ | ------ | ---- | ------------------------------------------------------------ | 1129| speed | number | No | Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.| 1130 1131**Error codes** 1132 1133For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1134 1135| ID| Error Message | 1136| -------- | ---------------------------------------- | 1137| 17000002 | API does not allow calling concurrently. | 1138| 17000004 | Component lost/UiWindow lost. | 1139 1140**Example** 1141 1142```js 1143async function demo() { 1144 let driver = Driver.create(); 1145 let scrollBar = await driver.findComponent(ON.type('Scroll')); 1146 await scrollBar.scrollToTop(); 1147} 1148``` 1149 1150### scrollToBottom<sup>9+</sup> 1151 1152scrollToBottom(speed?: number): Promise\<void> 1153 1154Scrolls to the bottom of this component. This API is applicable to components that support scrolling. 1155 1156**System capability**: SystemCapability.Test.UiTest 1157 1158**Parameters** 1159 1160| Name| Type | Mandatory| Description | 1161| ------ | ------ | ---- | ------------------------------------------------------------ | 1162| speed | number | No | Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.| 1163 1164**Error codes** 1165 1166For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1167 1168| ID| Error Message | 1169| -------- | ---------------------------------------- | 1170| 17000002 | API does not allow calling concurrently. | 1171| 17000004 | Component lost/UiWindow lost. | 1172 1173**Example** 1174 1175```js 1176async function demo() { 1177 let driver = Driver.create(); 1178 let scrollBar = await driver.findComponent(ON.type('Scroll')); 1179 await scrollBar.scrollToBottom(); 1180} 1181``` 1182 1183### dragTo<sup>9+</sup> 1184 1185dragTo(target: Component): Promise\<void> 1186 1187Drags this component to the target component. 1188 1189**System capability**: SystemCapability.Test.UiTest 1190 1191**Parameters** 1192 1193| Name| Type | Mandatory| Description | 1194| ------ | ------------------------ | ---- | ---------- | 1195| target | [Component](#component9) | Yes | Target component.| 1196 1197**Error codes** 1198 1199For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1200 1201| ID| Error Message | 1202| -------- | ---------------------------------------- | 1203| 17000002 | API does not allow calling concurrently. | 1204| 17000004 | Component lost/UiWindow lost. | 1205 1206**Example** 1207 1208```js 1209async function demo() { 1210 let driver = Driver.create(); 1211 let button = await driver.findComponent(ON.type('button')); 1212 let text = await driver.findComponent(ON.text('hello world')); 1213 await button.dragTo(text); 1214 } 1215``` 1216 1217### pinchOut<sup>9+</sup> 1218 1219pinchOut(scale: number): Promise\<void> 1220 1221Pinches a component to scale it up to the specified ratio. 1222 1223**System capability**: SystemCapability.Test.UiTest 1224 1225**Parameters** 1226 1227| Name| Type | Mandatory| Description | 1228| ------ | ------ | ---- | ---------------- | 1229| scale | number | Yes | Scale factor.| 1230 1231**Error codes** 1232 1233For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1234 1235| ID| Error Message | 1236| -------- | ---------------------------------------- | 1237| 17000002 | API does not allow calling concurrently. | 1238| 17000004 | Component lost/UiWindow lost. | 1239 1240**Example** 1241 1242```js 1243async function demo() { 1244 let driver = Driver.create(); 1245 let image = await driver.findComponent(ON.type('image')); 1246 await image.pinchOut(1.5); 1247 } 1248``` 1249 1250### pinchIn<sup>9+</sup> 1251 1252pinchIn(scale: number): Promise\<void> 1253 1254Pinches a component to scale it down to the specified ratio. 1255 1256**System capability**: SystemCapability.Test.UiTest 1257 1258**Parameters** 1259 1260| Name| Type | Mandatory| Description | 1261| ------ | ------ | ---- | ---------------- | 1262| scale | number | Yes | Scale factor.| 1263 1264**Error codes** 1265 1266For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1267 1268| ID| Error Message | 1269| -------- | ---------------------------------------- | 1270| 17000002 | API does not allow calling concurrently. | 1271| 17000004 | Component lost/UiWindow lost. | 1272 1273**Example** 1274 1275```js 1276async function demo() { 1277 let driver = Driver.create(); 1278 let image = await driver.findComponent(ON.type('image')); 1279 await image.pinchIn(0.5); 1280 } 1281``` 1282 1283## Driver<sup>9+</sup> 1284 1285The **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. 1286All APIs provided by this class, except for **Driver.create()**, use a promise to return the result and must be invoked using **await**. 1287 1288### create<sup>9+</sup> 1289 1290static create(): Driver 1291 1292Creates a **Driver** object and returns the object created. This API is a static API. 1293 1294**System capability**: SystemCapability.Test.UiTest 1295 1296**Return value** 1297 1298| Type| Description | 1299| -------- | ---------------------- | 1300| Driver | **Driver** object created.| 1301 1302**Error codes** 1303 1304For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1305 1306| ID| Error Message | 1307| -------- | ------------------ | 1308| 17000001 | Initialize failed. | 1309 1310**Example** 1311 1312```js 1313async function demo() { 1314 let driver = Driver.create(); 1315} 1316``` 1317 1318### delayMs<sup>9+</sup> 1319 1320delayMs(duration: number): Promise\<void> 1321 1322Delays this **Driver** object within the specified duration. 1323 1324**System capability**: SystemCapability.Test.UiTest 1325 1326**Parameters** 1327 1328| Name | Type | Mandatory| Description | 1329| -------- | ------ | ---- | ---------------------- | 1330| duration | number | Yes | Duration of time, in ms.| 1331 1332**Error codes** 1333 1334For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1335 1336| ID| Error Message | 1337| -------- | ---------------------------------------- | 1338| 17000002 | API does not allow calling concurrently. | 1339 1340**Example** 1341 1342```js 1343async function demo() { 1344 let driver = Driver.create(); 1345 await driver.delayMs(1000); 1346} 1347``` 1348 1349### findComponent<sup>9+</sup> 1350 1351findComponent(on: On): Promise\<Component> 1352 1353Searches this **Driver** object for the target component that matches the given attributes. 1354 1355**System capability**: SystemCapability.Test.UiTest 1356 1357**Parameters** 1358 1359| Name| Type | Mandatory| Description | 1360| ------ | ---------- | ---- | -------------------- | 1361| on | [On](#on9) | Yes | Attributes of the target component.| 1362 1363**Return value** 1364 1365| Type | Description | 1366| ---------------------------------- | --------------------------------- | 1367| Promise\<[Component](#component9)> | Promise used to return the found component.| 1368 1369**Error codes** 1370 1371For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1372 1373| ID| Error Message | 1374| -------- | ---------------------------------------- | 1375| 17000002 | API does not allow calling concurrently. | 1376 1377**Example** 1378 1379```js 1380async function demo() { 1381 let driver = Driver.create(); 1382 let button = await driver.findComponent(ON.text('next page')); 1383} 1384``` 1385 1386### findComponents<sup>9+</sup> 1387 1388findComponents(on: On): Promise\<Array\<Component>> 1389 1390Searches this **Driver** object for all components that match the given attributes. 1391 1392**System capability**: SystemCapability.Test.UiTest 1393 1394**Parameters** 1395 1396| Name| Type | Mandatory| Description | 1397| ------ | ---------- | ---- | -------------------- | 1398| on | [On](#on9) | Yes | Attributes of the target component.| 1399 1400**Return value** 1401 1402| Type | Description | 1403| ------------------------------------------ | --------------------------------------- | 1404| Promise\<Array\<[Component](#component9)>> | Promise used to return a list of found components.| 1405 1406**Error codes** 1407 1408For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1409 1410| ID| Error Message | 1411| -------- | ---------------------------------------- | 1412| 17000002 | API does not allow calling concurrently. | 1413 1414**Example** 1415 1416```js 1417async function demo() { 1418 let driver = Driver.create(); 1419 let buttonList = await driver.findComponents(ON.text('next page')); 1420} 1421``` 1422 1423### findWindow<sup>9+</sup> 1424 1425findWindow(filter: WindowFilter): Promise\<UiWindow> 1426 1427Searches for the window that matches the specified attributes. 1428 1429**System capability**: SystemCapability.Test.UiTest 1430 1431**Parameters** 1432 1433| Name| Type | Mandatory| Description | 1434| ------ | ------------------------------ | ---- | ---------------- | 1435| filter | [WindowFilter](#windowfilter9) | Yes | Attributes of the target window.| 1436 1437**Return value** 1438 1439| Type | Description | 1440| -------------------------------- | ------------------------------------- | 1441| Promise\<[UiWindow](#uiwindow9)> | Promise used to return the target window.| 1442 1443**Error codes** 1444 1445For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1446 1447| ID| Error Message | 1448| -------- | ---------------------------------------- | 1449| 17000002 | API does not allow calling concurrently. | 1450 1451**Example** 1452 1453```js 1454async function demo() { 1455 let driver = Driver.create(); 1456 let window = await driver.findWindow({actived: true}); 1457} 1458``` 1459 1460### waitForComponent<sup>9+</sup> 1461 1462waitForComponent(on: On, time: number): Promise\<Component> 1463 1464Searches this **Driver** object for the target component that matches the given attributes within the specified duration. 1465 1466**System capability**: SystemCapability.Test.UiTest 1467 1468**Parameters** 1469 1470| Name| Type | Mandatory| Description | 1471| ------ | ---------- | ---- | -------------------------------- | 1472| On | [On](#on9) | Yes | Attributes of the target component. | 1473| time | number | Yes | Duration for searching for the target component, in ms.| 1474 1475**Return value** 1476 1477| Type | Description | 1478| --------------------------------- | --------------------------------- | 1479| Promise\<[Component](#component)> | Promise used to return the found component.| 1480 1481**Error codes** 1482 1483For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1484 1485| ID| Error Message | 1486| -------- | ---------------------------------------- | 1487| 17000002 | API does not allow calling concurrently. | 1488 1489**Example** 1490 1491```js 1492async function demo() { 1493 let driver = Driver.create(); 1494 let button = await driver.waitForComponent(ON.text('next page'),500); 1495} 1496``` 1497 1498### assertComponentExist<sup>9+</sup> 1499 1500assertComponentExist(on: On): Promise\<void> 1501 1502Asserts that a component that matches the given attributes exists on the current page. 1503 1504**System capability**: SystemCapability.Test.UiTest 1505 1506**Parameters** 1507 1508| Name| Type | Mandatory| Description | 1509| ------ | ---------- | ---- | -------------------- | 1510| on | [On](#on9) | Yes | Attributes of the target component.| 1511 1512**Error codes** 1513 1514For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1515 1516| ID| Error Message | 1517| -------- | ---------------------------------------- | 1518| 17000002 | API does not allow calling concurrently. | 1519| 17000003 | Component existence assertion failed. | 1520 1521**Example** 1522 1523```js 1524async function demo() { 1525 let driver = Driver.create(); 1526 await driver.assertComponentExist(ON.text('next page')); 1527} 1528``` 1529 1530### pressBack<sup>9+</sup> 1531 1532pressBack(): Promise\<void> 1533 1534Presses the Back button on this **Driver** object. 1535 1536**System capability**: SystemCapability.Test.UiTest 1537 1538**Error codes** 1539 1540For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1541 1542| ID| Error Message | 1543| -------- | ---------------------------------------- | 1544| 17000002 | API does not allow calling concurrently. | 1545 1546**Example** 1547 1548```js 1549async function demo() { 1550 let driver = Driver.create(); 1551 await driver.pressBack(); 1552} 1553``` 1554 1555### triggerKey<sup>9+</sup> 1556 1557triggerKey(keyCode: number): Promise\<void> 1558 1559Triggers the key of this **Driver** object that matches the given key code. 1560 1561**System capability**: SystemCapability.Test.UiTest 1562 1563**Parameters** 1564 1565| Name | Type | Mandatory| Description | 1566| ------- | ------ | ---- | ------------- | 1567| keyCode | number | Yes | Key code.| 1568 1569**Error codes** 1570 1571For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1572 1573| ID| Error Message | 1574| -------- | ---------------------------------------- | 1575| 17000002 | API does not allow calling concurrently. | 1576 1577**Example** 1578 1579```js 1580async function demo() { 1581 let driver = Driver.create(); 1582 await driver.triggerKey(123); 1583} 1584``` 1585 1586### triggerCombineKeys<sup>9+</sup> 1587 1588triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\<void> 1589 1590Triggers 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**. 1591 1592**System capability**: SystemCapability.Test.UiTest 1593 1594**Parameters** 1595 1596| Name| Type | Mandatory| Description | 1597| ------ | ------ | ---- | ------------------- | 1598| key0 | number | Yes | The first key value.| 1599| key1 | number | Yes | The second key value.| 1600| key2 | number | No | The third key value.| 1601 1602**Error codes** 1603 1604For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1605 1606| ID| Error Message | 1607| -------- | ---------------------------------------- | 1608| 17000002 | API does not allow calling concurrently. | 1609 1610**Example** 1611 1612```js 1613async function demo() { 1614 let driver = Driver.create(); 1615 await driver.triggerCombineKeys(2072, 2047, 2035); 1616} 1617``` 1618 1619 1620### click<sup>9+</sup> 1621 1622click(x: number, y: number): Promise\<void> 1623 1624Clicks a specific point of this **Driver** object based on the given coordinates. 1625 1626**System capability**: SystemCapability.Test.UiTest 1627 1628**Parameters** 1629 1630| Name| Type | Mandatory| Description | 1631| ------ | ------ | ---- | -------------------------------------- | 1632| x | number | Yes | X-coordinate of the target point.| 1633| y | number | Yes | Y-coordinate of the target point.| 1634 1635**Error codes** 1636 1637For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1638 1639| ID| Error Message | 1640| -------- | ---------------------------------------- | 1641| 17000002 | API does not allow calling concurrently. | 1642 1643**Example** 1644 1645```js 1646async function demo() { 1647 let driver = Driver.create(); 1648 await driver.click(100,100); 1649} 1650``` 1651 1652### doubleClick<sup>9+</sup> 1653 1654doubleClick(x: number, y: number): Promise\<void> 1655 1656Double-clicks a specific point of this **Driver** object based on the given coordinates. 1657 1658**System capability**: SystemCapability.Test.UiTest 1659 1660**Parameters** 1661 1662| Name| Type | Mandatory| Description | 1663| ------ | ------ | ---- | -------------------------------------- | 1664| x | number | Yes | X-coordinate of the target point.| 1665| y | number | Yes | Y-coordinate of the target point.| 1666 1667**Error codes** 1668 1669For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1670 1671| ID| Error Message | 1672| -------- | ---------------------------------------- | 1673| 17000002 | API does not allow calling concurrently. | 1674 1675**Example** 1676 1677```js 1678async function demo() { 1679 let driver = Driver.create(); 1680 await driver.doubleClick(100,100); 1681} 1682``` 1683 1684### longClick<sup>9+</sup> 1685 1686longClick(x: number, y: number): Promise\<void> 1687 1688Long-clicks a specific point of this **Driver** object based on the given coordinates. 1689 1690**System capability**: SystemCapability.Test.UiTest 1691 1692**Parameters** 1693 1694| Name| Type | Mandatory| Description | 1695| ------ | ------ | ---- | -------------------------------------- | 1696| x | number | Yes | X-coordinate of the target point.| 1697| y | number | Yes | Y-coordinate of the target point.| 1698 1699**Error codes** 1700 1701For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1702 1703| ID| Error Message | 1704| -------- | ---------------------------------------- | 1705| 17000002 | API does not allow calling concurrently. | 1706 1707**Example** 1708 1709```js 1710async function demo() { 1711 let driver = Driver.create(); 1712 await driver.longClick(100,100); 1713} 1714``` 1715 1716### swipe<sup>9+</sup> 1717 1718swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 1719 1720Swipes on this **Driver** object from the given start point to the given end point. 1721 1722**System capability**: SystemCapability.Test.UiTest 1723 1724**Parameters** 1725 1726| Name| Type | Mandatory| Description | 1727| ------ | ------ | ---- | ------------------------------------------------------------ | 1728| startx | number | Yes | X-coordinate of the start point. | 1729| starty | number | Yes | Y-coordinate of the start point. | 1730| endx | number | Yes | X-coordinate of the end point. | 1731| endy | number | Yes | Y-coordinate of the end point. | 1732| speed | number | No | Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.| 1733 1734**Error codes** 1735 1736For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1737 1738| ID| Error Message | 1739| -------- | ---------------------------------------- | 1740| 17000002 | API does not allow calling concurrently. | 1741 1742**Example** 1743 1744```js 1745async function demo() { 1746 let driver = Driver.create(); 1747 await driver.swipe(100,100,200,200,600); 1748} 1749``` 1750 1751### drag<sup>9+</sup> 1752 1753drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 1754 1755Drags this **Driver** object from the given start point to the given end point. 1756 1757**System capability**: SystemCapability.Test.UiTest 1758 1759**Parameters** 1760 1761| Name| Type | Mandatory| Description | 1762| ------ | ------ | ---- | ------------------------------------------------------------ | 1763| startx | number | Yes | X-coordinate of the start point. | 1764| starty | number | Yes | Y-coordinate of the start point. | 1765| endx | number | Yes | X-coordinate of the end point. | 1766| endy | number | Yes | Y-coordinate of the end point. | 1767| speed | number | No | Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.| 1768 1769**Error codes** 1770 1771For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1772 1773| ID| Error Message | 1774| -------- | ---------------------------------------- | 1775| 17000002 | API does not allow calling concurrently. | 1776 1777**Example** 1778 1779```js 1780async function demo() { 1781 let driver = Driver.create(); 1782 await driver.drag(100,100,200,200,600); 1783} 1784``` 1785 1786### screenCap<sup>9+</sup> 1787 1788screenCap(savePath: string): Promise\<boolean> 1789 1790Captures the current screen of this **Driver** object and saves it as a PNG image to the given save path. 1791 1792**System capability**: SystemCapability.Test.UiTest 1793 1794**Parameters** 1795 1796| Name | Type | Mandatory| Description | 1797| -------- | ------ | ---- | -------------- | 1798| savePath | string | Yes | File save path.| 1799 1800**Return value** 1801 1802| Type | Description | 1803| ----------------- | -------------------------------------- | 1804| Promise\<boolean> | Promise used to return the operation result. The value **true** means that the operation is successful.| 1805 1806**Error codes** 1807 1808For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1809 1810| ID| Error Message | 1811| -------- | ---------------------------------------- | 1812| 17000002 | API does not allow calling concurrently. | 1813 1814**Example** 1815 1816```js 1817async function demo() { 1818 let driver = Driver.create(); 1819 await driver.screenCap('/local/tmp/1.png'); 1820} 1821``` 1822 1823### setDisplayRotation<sup>9+</sup> 1824 1825setDisplayRotation(rotation: DisplayRotation): Promise\<void> 1826 1827Sets the display rotation of the device. 1828 1829**System capability**: SystemCapability.Test.UiTest 1830 1831**Parameters** 1832 1833| Name | Type | Mandatory| Description | 1834| -------- | ------------------------------------ | ---- | ---------------- | 1835| rotation | [DisplayRotation](#displayrotation9) | Yes | Display rotation of the device.| 1836 1837**Error codes** 1838 1839For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1840 1841| ID| Error Message | 1842| -------- | ---------------------------------------- | 1843| 17000002 | API does not allow calling concurrently. | 1844 1845**Example** 1846 1847```js 1848async function demo() { 1849 let driver = Driver.create(); 1850 await driver.setDisplayRotation(DisplayRotation.ROTATION_180); 1851} 1852``` 1853 1854### getDisplayRotation<sup>9+</sup> 1855 1856getDisplayRotation(): Promise\<DisplayRotation> 1857 1858Obtains the display rotation of the current device. 1859 1860**System capability**: SystemCapability.Test.UiTest 1861 1862**Return value** 1863 1864| Type | Description | 1865| ---------------------------------------------- | --------------------------------------- | 1866| Promise\<[DisplayRotation](#displayrotation9)> | Promise used to return the display rotation of the current device.| 1867 1868**Error codes** 1869 1870For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1871 1872| ID| Error Message | 1873| -------- | ---------------------------------------- | 1874| 17000002 | API does not allow calling concurrently. | 1875 1876**Example** 1877 1878```js 1879async function demo() { 1880 let driver = Driver.create(); 1881 let rotation = await driver.getDisplayRotation(); 1882} 1883``` 1884 1885### setDisplayRotationEnabled<sup>9+</sup> 1886 1887setDisplayRotationEnabled(enabled: boolean): Promise\<void> 1888 1889Enables or disables display rotation. 1890 1891**System capability**: SystemCapability.Test.UiTest 1892 1893**Parameters** 1894 1895| Name | Type | Mandatory| Description | 1896| ------- | ------- | ---- | ------------------------------------------------------- | 1897| enabled | boolean | Yes | Whether to enable display rotation. The value **true** means to enable display rotation, and **false** means the opposite.| 1898 1899**Error codes** 1900 1901For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1902 1903| ID| Error Message | 1904| -------- | ---------------------------------------- | 1905| 17000002 | API does not allow calling concurrently. | 1906 1907**Example** 1908 1909```js 1910async function demo() { 1911 let driver = Driver.create(); 1912 await driver.setDisplayRotationEnabled(false); 1913} 1914``` 1915 1916### getDisplaySize<sup>9+</sup> 1917 1918getDisplaySize(): Promise\<Point> 1919 1920Obtains the display size of the current device. 1921 1922**System capability**: SystemCapability.Test.UiTest 1923 1924**Return value** 1925 1926| Type | Description | 1927| -------------------------- | --------------------------------------- | 1928| Promise\<[Point](#point9)> | Promise used to return the display size of the current device.| 1929 1930**Error codes** 1931 1932For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1933 1934| ID| Error Message | 1935| -------- | ---------------------------------------- | 1936| 17000002 | API does not allow calling concurrently. | 1937 1938**Example** 1939 1940```js 1941async function demo() { 1942 let driver = Driver.create(); 1943 let size = await driver.getDisplaySize(); 1944} 1945``` 1946 1947### getDisplayDensity<sup>9+</sup> 1948 1949getDisplayDensity(): Promise\<Point> 1950 1951Obtains the display density of the current device. 1952 1953**System capability**: SystemCapability.Test.UiTest 1954 1955**Return value** 1956 1957| Type | Description | 1958| -------------------------- | ----------------------------------------- | 1959| Promise\<[Point](#point9)> | Promise used to return the display density of the current device.| 1960 1961**Error codes** 1962 1963For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1964 1965| ID| Error Message | 1966| -------- | ---------------------------------------- | 1967| 17000002 | API does not allow calling concurrently. | 1968 1969**Example** 1970 1971```js 1972async function demo() { 1973 let driver = Driver.create(); 1974 let density = await driver.getDisplayDensity(); 1975} 1976``` 1977 1978### wakeUpDisplay<sup>9+</sup> 1979 1980wakeUpDisplay(): Promise\<void> 1981 1982Wakes up the device display. 1983 1984**System capability**: SystemCapability.Test.UiTest 1985 1986**Error codes** 1987 1988For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 1989 1990| ID| Error Message | 1991| -------- | ---------------------------------------- | 1992| 17000002 | API does not allow calling concurrently. | 1993 1994**Example** 1995 1996```js 1997async function demo() { 1998 let driver = Driver.create(); 1999 await driver.wakeUpDisplay(); 2000} 2001``` 2002 2003### pressHome<sup>9+</sup> 2004 2005pressHome(): Promise\<void> 2006 2007Returns to the home screen. 2008 2009**System capability**: SystemCapability.Test.UiTest 2010 2011**Error codes** 2012 2013For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2014 2015| ID| Error Message | 2016| -------- | ---------------------------------------- | 2017| 17000002 | API does not allow calling concurrently. | 2018 2019**Example** 2020 2021```js 2022async function demo() { 2023 let driver = Driver.create(); 2024 await driver.pressHome(); 2025} 2026``` 2027 2028### waitForIdle<sup>9+</sup> 2029 2030waitForIdle(idleTime: number, timeout: number): Promise\<boolean> 2031 2032Checks whether all components on the current page are idle. 2033 2034**System capability**: SystemCapability.Test.UiTest 2035 2036**Parameters** 2037 2038| Name | Type | Mandatory| Description | 2039| -------- | ------ | ---- | ------------------------------------------------------------ | 2040| idleTime | number | Yes | Idle time threshold, in milliseconds. If the duration for which a component remains inactive reaches this threshold, it is considered as idle.| 2041| timeout | number | Yes | Maximum idle waiting time, in milliseconds. | 2042 2043**Return value** 2044 2045| Type | Description | 2046| ----------------- | --------------------------------------------------- | 2047| Promise\<boolean> | Promise used to return the result.| 2048 2049**Error codes** 2050 2051For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2052 2053| ID| Error Message | 2054| -------- | ---------------------------------------- | 2055| 17000002 | API does not allow calling concurrently. | 2056 2057**Example** 2058 2059```js 2060async function demo() { 2061 let driver = Driver.create(); 2062 let idled = await driver.waitForIdle(4000,5000); 2063} 2064``` 2065 2066### fling<sup>9+</sup> 2067 2068fling(from: Point, to: Point, stepLen: number, speed: number): Promise\<void> 2069 2070Simulates a fling operation on the screen. 2071 2072**System capability**: SystemCapability.Test.UiTest 2073 2074**Parameters** 2075 2076| Name | Type | Mandatory| Description | 2077| ------- | ---------------- | ---- | ------------------------------------------------------------ | 2078| from | [Point](#point9) | Yes | Coordinates of the point where the finger touches the screen. | 2079| to | [Point](#point9) | Yes | Coordinates of the point where the finger leaves the screen. | 2080| stepLen | number | Yes | Fling step length, in pixels. | 2081| speed | number | Yes | Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.| 2082 2083**Error codes** 2084 2085For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2086 2087| ID| Error Message | 2088| -------- | ---------------------------------------- | 2089| 17000002 | API does not allow calling concurrently. | 2090 2091**Example** 2092 2093```js 2094async function demo() { 2095 let driver = Driver.create(); 2096 await driver.fling({x: 500, Y: 480},{x: 450, Y: 480},5,600); 2097} 2098``` 2099 2100### injectMultiPointerAction<sup>9+</sup> 2101 2102injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\<boolean> 2103 2104Injects a multi-touch operation to the device. 2105 2106**System capability**: SystemCapability.Test.UiTest 2107 2108**Parameters** 2109 2110| Name | Type | Mandatory| Description | 2111| -------- | -------------------------------- | ---- | ------------------------------------------------------------ | 2112| pointers | [PointerMatrix](#pointermatrix9) | Yes | Scroll trajectory, including the number of fingers and an array of coordinates along the trajectory. | 2113| speed | number | No | Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.| 2114 2115**Return value** 2116 2117| Type | Description | 2118| ----------------- | ------------------------------------- | 2119| Promise\<boolean> | Promise used to return the result.| 2120 2121**Error codes** 2122 2123For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2124 2125| ID| Error Message | 2126| -------- | ---------------------------------------- | 2127| 17000002 | API does not allow calling concurrently. | 2128 2129**Example** 2130 2131```js 2132async function demo() { 2133 let driver = Driver.create(); 2134 let pointers = PointerMatrix.create(2,3); 2135 pointers.setPoint(0,0,{x:230,y:480}); 2136 pointers.setPoint(0,1,{x:250,y:380}); 2137 pointers.setPoint(0,2,{x:270,y:280}); 2138 pointers.setPoint(1,0,{x:230,y:680}); 2139 pointers.setPoint(1,1,{x:240,y:580}); 2140 pointers.setPoint(1,2,{x:250,y:480}); 2141 await driver.injectMultiPointerAction(pointers); 2142} 2143``` 2144 2145## PointerMatrix<sup>9+</sup> 2146 2147Implements a **PointerMatrix** object that stores coordinates and behaviors of each action of each finger in a multi-touch operation. 2148 2149### create<sup>9+</sup> 2150 2151static create(fingers: number, steps: number): PointerMatrix 2152 2153Creates a **PointerMatrix** object and returns the object created. This API is a static API. 2154 2155**System capability**: SystemCapability.Test.UiTest 2156 2157**Parameters** 2158 2159| Name | Type | Mandatory| Description | 2160| ------- | ------ | ---- | ------------------------------------------ | 2161| fingers | number | Yes | Number of fingers in the multi-touch operation. Value range: [1,10].| 2162| steps | number | Yes | Number of steps operated by each finger. Value range: [1,1000].| 2163 2164**Return value** 2165 2166| Type | Description | 2167| -------------------------------- | ----------------------------- | 2168| [PointerMatrix](#pointermatrix9) | **PointerMatrix** object created.| 2169 2170**Example** 2171 2172```js 2173async function demo() { 2174 let pointerMatrix = PointerMatrix.create(2,3); 2175} 2176``` 2177 2178### setPoint<sup>9+</sup> 2179 2180setPoint(finger: number, step: number, point: Point): void 2181 2182Sets the coordinates for the action corresponding to the specified finger and step in the **PointerMatrix** object. 2183 2184**System capability**: SystemCapability.Test.UiTest 2185 2186**Parameters** 2187 2188| Name| Type | Mandatory| Description | 2189| ------ | ---------------- | ---- | ---------------- | 2190| finger | number | Yes | Sequence number of the finger. | 2191| step | number | Yes | Sequence number of the step. | 2192| point | [Point](#point9) | Yes | Coordinates of the action.| 2193 2194**Example** 2195 2196```js 2197async function demo() { 2198 let pointers = PointerMatrix.create(2,3); 2199 pointers.setPoint(0,0,{x:230,y:480}); 2200 pointers.setPoint(0,1,{x:250,y:380}); 2201 pointers.setPoint(0,2,{x:270,y:280}); 2202 pointers.setPoint(1,0,{x:230,y:680}); 2203 pointers.setPoint(1,1,{x:240,y:580}); 2204 pointers.setPoint(1,2,{x:250,y:480}); 2205} 2206``` 2207 2208## UiWindow<sup>9+</sup> 2209 2210The **UiWindow** class represents a window on the UI and provides APIs for obtaining window attributes, dragging a window, and adjusting the window size. 2211All APIs provided in this class use a promise to return the result and must be invoked using **await**. 2212 2213### getBundleName<sup>9+</sup> 2214 2215getBundleName(): Promise\<string> 2216 2217Obtains the bundle name of the application to which this window belongs. 2218 2219**System capability**: SystemCapability.Test.UiTest 2220 2221**Return value** 2222 2223| Type | Description | 2224| ---------------- | ----------------------------------------- | 2225| Promise\<string> | Promise used to return the bundle name.| 2226 2227**Error codes** 2228 2229For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2230 2231| ID| Error Message | 2232| -------- | ---------------------------------------- | 2233| 17000002 | API does not allow calling concurrently. | 2234| 17000004 | Component lost/UiWindow lost. | 2235 2236**Example** 2237 2238```js 2239async function demo() { 2240 let driver = Driver.create(); 2241 let window = await driver.findWindow({actived: true}); 2242 let name = await window.getBundleName(); 2243} 2244``` 2245 2246### getBounds<sup>9+</sup> 2247 2248getBounds(): Promise\<Rect> 2249 2250Obtains the bounds information of this window. 2251 2252**System capability**: SystemCapability.Test.UiTest 2253 2254**Return value** 2255 2256| Type | Description | 2257| ------------------------ | --------------------------------- | 2258| Promise\<[Rect](#rect9)> | Promise used to return the bounds information of the window.| 2259 2260**Error codes** 2261 2262For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2263 2264| ID| Error Message | 2265| -------- | ---------------------------------------- | 2266| 17000002 | API does not allow calling concurrently. | 2267| 17000004 | Component lost/UiWindow lost. | 2268 2269**Example** 2270 2271```js 2272async function demo() { 2273 let driver = Driver.create(); 2274 let window = await driver.findWindow({actived: true}); 2275 let rect = await window.getBounds(); 2276} 2277``` 2278 2279### getTitle<sup>9+</sup> 2280 2281getTitle(): Promise\<string> 2282 2283Obtains the title of this window. 2284 2285**System capability**: SystemCapability.Test.UiTest 2286 2287**Return value** 2288 2289| Type | Description | 2290| ---------------- | --------------------------------- | 2291| Promise\<string> | Promise used to return the title of the window.| 2292 2293**Error codes** 2294 2295For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2296 2297| ID| Error Message | 2298| -------- | ---------------------------------------- | 2299| 17000002 | API does not allow calling concurrently. | 2300| 17000004 | Component lost/UiWindow lost. | 2301 2302**Example** 2303 2304```js 2305async function demo() { 2306 let driver = Driver.create(); 2307 let window = await driver.findWindow({actived: true}); 2308 let rect = await window.getTitle(); 2309} 2310``` 2311 2312### getWindowMode<sup>9+</sup> 2313 2314getWindowMode(): Promise\<WindowMode> 2315 2316Obtains the window mode of this window. 2317 2318**System capability**: SystemCapability.Test.UiTest 2319 2320**Return value** 2321 2322| Type | Description | 2323| ------------------------------------ | ------------------------------------- | 2324| Promise\<[WindowMode](#windowmode9)> | Promise used to return the window mode of the window.| 2325 2326**Error codes** 2327 2328For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2329 2330| ID| Error Message | 2331| -------- | ---------------------------------------- | 2332| 17000002 | API does not allow calling concurrently. | 2333| 17000004 | Component lost/UiWindow lost. | 2334 2335**Example** 2336 2337```js 2338async function demo() { 2339 let driver = Driver.create(); 2340 let window = await driver.findWindow({actived: true}); 2341 let mode = await window.getWindowMode(); 2342} 2343``` 2344 2345### isFocused<sup>9+</sup> 2346 2347isFocused(): Promise\<boolean> 2348 2349Checks whether this window is in focused state. 2350 2351**System capability**: SystemCapability.Test.UiTest 2352 2353**Return value** 2354 2355| Type | Description | 2356| ----------------- | ------------------------------------------------------------ | 2357| Promise\<boolean> | Promise used to return the result. The value **true** means that the window is in focused state, and **false** means the opposite.| 2358 2359**Error codes** 2360 2361For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2362 2363| ID| Error Message | 2364| -------- | ---------------------------------------- | 2365| 17000002 | API does not allow calling concurrently. | 2366| 17000004 | Component lost/UiWindow lost. | 2367 2368**Example** 2369 2370```js 2371async function demo() { 2372 let driver = Driver.create(); 2373 let window = await driver.findWindow({actived: true}); 2374 let focused = await window.isFocused(); 2375} 2376``` 2377 2378### isActived<sup>9+</sup> 2379 2380isActived(): Promise\<boolean> 2381 2382Checks whether this window is active. 2383 2384**System capability**: SystemCapability.Test.UiTest 2385 2386**Return value** 2387 2388| Type | Description | 2389| ----------------- | ------------------------------------------------------------ | 2390| Promise\<boolean> | Promise used to return the result. The value **true** means that the window is active, and **false** means the opposite.| 2391 2392**Error codes** 2393 2394For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2395 2396| ID| Error Message | 2397| -------- | ---------------------------------------- | 2398| 17000002 | API does not allow calling concurrently. | 2399| 17000004 | Component lost/UiWindow lost. | 2400 2401**Example** 2402 2403```js 2404async function demo() { 2405 let driver = Driver.create(); 2406 let window = await driver.findWindow({actived: true}); 2407 let focused = await window.isActived(); 2408} 2409``` 2410 2411### focus<sup>9+</sup> 2412 2413focus(): Promise\<void> 2414 2415Moves the focus to this window. 2416 2417**System capability**: SystemCapability.Test.UiTest 2418 2419**Error codes** 2420 2421For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2422 2423| ID| Error Message | 2424| -------- | ---------------------------------------- | 2425| 17000002 | API does not allow calling concurrently. | 2426| 17000004 | Component lost/UiWindow lost. | 2427 2428**Example** 2429 2430```js 2431async function demo() { 2432 let driver = Driver.create(); 2433 let window = await driver.findWindow({actived: true}); 2434 await window.focus(); 2435} 2436``` 2437 2438### moveTo<sup>9+</sup> 2439 2440moveTo(x: number, y: number): Promise\<void> 2441 2442Moves this window to the target point. This API is applicable to moveable windows. 2443 2444**System capability**: SystemCapability.Test.UiTest 2445 2446**Parameters** 2447 2448| Name| Type | Mandatory| Description | 2449| ------ | ------ | ---- | -------------------------------------- | 2450| x | number | Yes | X-coordinate of the target point.| 2451| y | number | Yes | Y-coordinate of the target point.| 2452 2453**Error codes** 2454 2455For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2456 2457| ID| Error Message | 2458| -------- | ---------------------------------------- | 2459| 17000002 | API does not allow calling concurrently. | 2460| 17000004 | Component lost/UiWindow lost. | 2461| 17000005 | This operation is not supported. | 2462 2463**Example** 2464 2465```js 2466async function demo() { 2467 let driver = Driver.create(); 2468 let window = await driver.findWindow({actived: true}); 2469 await window.moveTo(100, 100); 2470} 2471``` 2472 2473### resize<sup>9+</sup> 2474 2475resize(wide: number, height: number, direction: ResizeDirection): Promise\<void> 2476 2477Resizes this window based on the specified width, height, and resize direction. This API is applicable to resizable windows. 2478 2479**System capability**: SystemCapability.Test.UiTest 2480 2481**Parameters** 2482 2483| Name | Type | Mandatory| Description | 2484| --------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2485| wide | number | Yes | Target width. | 2486| height | number | Yes | Target height. | 2487| direction | [ResizeDirection](#resizedirection9) | Yes | Resize direction.| 2488 2489**Error codes** 2490 2491For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2492 2493| ID| Error Message | 2494| -------- | ---------------------------------------- | 2495| 17000002 | API does not allow calling concurrently. | 2496| 17000004 | Component lost/UiWindow lost. | 2497| 17000005 | This operation is not supported. | 2498 2499**Example** 2500 2501```js 2502async function demo() { 2503 let driver = Driver.create(); 2504 let window = await driver.findWindow({actived: true}); 2505 await window.resize(100, 100, ResizeDirection.LEFT); 2506} 2507``` 2508 2509### split<sup>9+</sup> 2510 2511split(): Promise\<void> 2512 2513Switches the window to split-screen mode. This API is applicable to windows that support screen splitting. 2514 2515**System capability**: SystemCapability.Test.UiTest 2516 2517**Error codes** 2518 2519For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2520 2521| ID| Error Message | 2522| -------- | ---------------------------------------- | 2523| 17000002 | API does not allow calling concurrently. | 2524| 17000004 | Component lost/UiWindow lost. | 2525| 17000005 | This operation is not supported. | 2526 2527**Example** 2528 2529```js 2530async function demo() { 2531 let driver = Driver.create(); 2532 let window = await driver.findWindow({actived: true}); 2533 await window.split(); 2534} 2535``` 2536 2537### maximize<sup>9+</sup> 2538 2539maximize(): Promise\<void> 2540 2541Maximizes this window. This API is applicable to windows that can be maximized. 2542 2543**System capability**: SystemCapability.Test.UiTest 2544 2545**Error codes** 2546 2547For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2548 2549| ID| Error Message | 2550| -------- | ---------------------------------------- | 2551| 17000002 | API does not allow calling concurrently. | 2552| 17000004 | Component lost/UiWindow lost. | 2553| 17000005 | This operation is not supported. | 2554 2555**Example** 2556 2557```js 2558async function demo() { 2559 let driver = Driver.create(); 2560 let window = await driver.findWindow({actived: true}); 2561 await window.maximize(); 2562} 2563``` 2564 2565### minimize<sup>9+</sup> 2566 2567minimize(): Promise\<void> 2568 2569Minimizes this window. This API is applicable to windows that can be minimized. 2570 2571**System capability**: SystemCapability.Test.UiTest 2572 2573**Error codes** 2574 2575For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2576 2577| ID| Error Message | 2578| -------- | ---------------------------------------- | 2579| 17000002 | API does not allow calling concurrently. | 2580| 17000004 | Component lost/UiWindow lost. | 2581| 17000005 | This operation is not supported. | 2582 2583**Example** 2584 2585```js 2586async function demo() { 2587 let driver = Driver.create(); 2588 let window = await driver.findWindow({actived: true}); 2589 await window.minimize(); 2590} 2591``` 2592 2593### resume<sup>9+</sup> 2594 2595resume(): Promise\<void> 2596 2597Restores this window to the previous window mode. 2598 2599**System capability**: SystemCapability.Test.UiTest 2600 2601**Error codes** 2602 2603For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2604 2605| ID| Error Message | 2606| -------- | ---------------------------------------- | 2607| 17000002 | API does not allow calling concurrently. | 2608| 17000004 | Component lost/UiWindow lost. | 2609| 17000005 | This operation is not supported. | 2610 2611**Example** 2612 2613```js 2614async function demo() { 2615 let driver = Driver.create(); 2616 let window = await driver.findWindow({actived: true}); 2617 await window.resume(); 2618} 2619``` 2620 2621### close<sup>9+</sup> 2622 2623close(): Promise\<void> 2624 2625Closes this window. 2626 2627**System capability**: SystemCapability.Test.UiTest 2628 2629**Error codes** 2630 2631For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). 2632 2633| ID| Error Message | 2634| -------- | ---------------------------------------- | 2635| 17000002 | API does not allow calling concurrently. | 2636| 17000004 | Component lost/UiWindow lost. | 2637| 17000005 | This operation is not supported. | 2638 2639**Example** 2640 2641```js 2642async function demo() { 2643 let driver = Driver.create(); 2644 let window = await driver.findWindow({actived: true}); 2645 await window.close(); 2646} 2647``` 2648 2649## By<sup>(deprecated)</sup> 2650 2651The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components. 2652The API capabilities 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. 2653 2654This API is deprecated since API version 9. You are advised to use [On<sup>9+</sup>](#on9) instead. 2655 2656```js 2657BY.text('123').type('button'); 2658``` 2659 2660### text<sup>(deprecated)</sup> 2661 2662text(txt: string, pattern?: MatchPattern): By 2663 2664Specifies the text attribute of the target component. Multiple match patterns are supported. 2665 2666This API is deprecated since API version 9. You are advised to use [text<sup>9+</sup>](#text9). 2667 2668**System capability**: SystemCapability.Test.UiTest 2669 2670**Parameters** 2671 2672| Name | Type | Mandatory| Description | 2673| ------- | ----------------------------- | ---- | --------------------------------------------------- | 2674| txt | string | Yes | Component text, used to match the target component. | 2675| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).| 2676 2677**Return value** 2678 2679| Type | Description | 2680| ------------------- | ---------------------------------- | 2681| [By](#bydeprecated) | **By** object that matches the text attribute of the target component.| 2682 2683**Example** 2684 2685```js 2686let by = BY.text('123'); // Use the static constructor BY to create a By object and specify the text attribute of the target component. 2687``` 2688 2689 2690### key<sup>(deprecated)</sup> 2691 2692key(key: string): By 2693 2694Specifies the key attribute of the target component. 2695 2696This API is deprecated since API version 9. You are advised to use [id<sup>9+</sup>](#id9). 2697 2698**System capability**: SystemCapability.Test.UiTest 2699 2700**Parameters** 2701 2702| Name| Type | Mandatory| Description | 2703| ------ | ------ | ---- | ----------------- | 2704| key | string | Yes | Component key.| 2705 2706**Return value** 2707 2708| Type | Description | 2709| ------------------- | ----------------------------------- | 2710| [By](#bydeprecated) | **By** object that matches the key attribute of the target component.| 2711 2712**Example** 2713 2714```js 2715let by = BY.key('123'); // Use the static constructor BY to create a By object and specify the key attribute of the target component. 2716``` 2717 2718 2719### id<sup>(deprecated)</sup> 2720 2721id(id: number): By 2722 2723Specifies the ID attribute of the target component. 2724 2725This API is deprecated since API version 9. 2726 2727**System capability**: SystemCapability.Test.UiTest 2728 2729**Parameters** 2730 2731| Name| Type | Mandatory| Description | 2732| ------ | ------ | ---- | ---------------- | 2733| id | number | Yes | Component ID.| 2734 2735**Return value** 2736 2737| Type | Description | 2738| ------------------- | -------------------------------- | 2739| [By](#bydeprecated) | **By** object that matches the ID attribute of the target component.| 2740 2741**Example** 2742 2743```js 2744let by = BY.id(123); // Use the static constructor BY to create a By object and specify the ID attribute of the target component. 2745``` 2746 2747 2748### type<sup>(deprecated)</sup> 2749 2750type(tp: string): By 2751 2752Specifies the type attribute of the target component. 2753 2754This API is deprecated since API version 9. You are advised to use [type<sup>9+</sup>](#type9). 2755 2756**System capability**: SystemCapability.Test.UiTest 2757 2758**Parameters** 2759 2760| Name| Type | Mandatory| Description | 2761| ------ | ------ | ---- | -------------- | 2762| tp | string | Yes | Component type.| 2763 2764**Return value** 2765 2766| Type | Description | 2767| ------------------- | ---------------------------------------- | 2768| [By](#bydeprecated) | **By** object that matches the type attribute of the target component.| 2769 2770**Example** 2771 2772```js 2773let by = BY.type('button'); // Use the static constructor BY to create a By object and specify the type attribute of the target component. 2774``` 2775 2776 2777### clickable<sup>(deprecated)</sup> 2778 2779clickable(b?: boolean): By 2780 2781Specifies the clickable status attribute of the target component. 2782 2783This API is deprecated since API version 9. You are advised to use [clickable<sup>9+</sup>](#clickable9). 2784 2785**System capability**: SystemCapability.Test.UiTest 2786 2787**Parameters** 2788 2789| Name| Type | Mandatory| Description | 2790| ------ | ------- | ---- | ------------------------------------------------------------ | 2791| b | boolean | No | Clickable status of the target component.<br>**true**: clickable.<br>**false**: not clickable.<br>Default value: **true** | 2792 2793**Return value** 2794 2795| Type | Description | 2796| ------------------- | ------------------------------------------ | 2797| [By](#bydeprecated) | **By** object that matches the clickable status attribute of the target component.| 2798 2799**Example** 2800 2801```js 2802let by = BY.clickable(true); // Use the static constructor BY to create a By object and specify the clickable status attribute of the target component. 2803``` 2804 2805 2806### scrollable<sup>(deprecated)</sup> 2807 2808scrollable(b?: boolean): By 2809 2810Specifies the scrollable status attribute of the target component. 2811 2812This API is deprecated since API version 9. You are advised to use [scrollable<sup>9+</sup>](#scrollable9). 2813 2814**System capability**: SystemCapability.Test.UiTest 2815 2816**Parameters** 2817 2818| Name| Type | Mandatory| Description | 2819| ------ | ------- | ---- | ----------------------------------------------------------- | 2820| b | boolean | No | Scrollable status of the target component.<br>**true**: scrollable.<br>**false**: not scrollable.<br>Default value: **true** | 2821 2822**Return value** 2823 2824| Type | Description | 2825| ------------------- | ------------------------------------------ | 2826| [By](#bydeprecated) | **By** object that matches the scrollable status attribute of the target component.| 2827 2828**Example** 2829 2830```js 2831let by = BY.scrollable(true); // Use the static constructor BY to create a By object and specify the scrollable status attribute of the target component. 2832``` 2833 2834### enabled<sup>(deprecated)</sup> 2835 2836enabled(b?: boolean): By 2837 2838Specifies the enabled status attribute of the target component. 2839 2840This API is deprecated since API version 9. You are advised to use [enabled<sup>9+</sup>](#enabled9). 2841 2842**System capability**: SystemCapability.Test.UiTest 2843 2844**Parameters** 2845 2846| Name| Type | Mandatory| Description | 2847| ------ | ------- | ---- | --------------------------------------------------------- | 2848| b | boolean | No | Enabled status of the target component.<br>**true**: enabled.<br>**false**: not enabled.<br>Default value: **true** | 2849 2850**Return value** 2851 2852| Type | Description | 2853| ------------------- | ---------------------------------------- | 2854| [By](#bydeprecated) | **By** object that matches the enabled status attribute of the target component.| 2855 2856**Example** 2857 2858```js 2859let by = BY.enabled(true); // Use the static constructor BY to create a By object and specify the enabled status attribute of the target component. 2860``` 2861 2862### focused<sup>(deprecated)</sup> 2863 2864focused(b?: boolean): By 2865 2866Specifies the focused status attribute of the target component. 2867 2868This API is deprecated since API version 9. You are advised to use [focused<sup>9+</sup>](#focused9). 2869 2870**System capability**: SystemCapability.Test.UiTest 2871 2872**Parameters** 2873 2874| Name| Type | Mandatory| Description | 2875| ------ | ------- | ---- | ----------------------------------------------------- | 2876| b | boolean | No | Focused status of the target component.<br>**true**: focused.<br>**false**: not focused.<br>Default value: **true** | 2877 2878**Return value** 2879 2880| Type | Description | 2881| ------------------- | ---------------------------------------- | 2882| [By](#bydeprecated) | **By** object that matches the focused status attribute of the target component.| 2883 2884**Example** 2885 2886```js 2887let by = BY.focused(true); // Use the static constructor BY to create a By object and specify the focused status attribute of the target component. 2888``` 2889 2890### selected<sup>(deprecated)</sup> 2891 2892selected(b?: boolean): By 2893 2894Specifies the selected status of the target component. 2895 2896This API is deprecated since API version 9. You are advised to use [selected<sup>9+</sup>](#selected9). 2897 2898**System capability**: SystemCapability.Test.UiTest 2899 2900**Parameters** 2901 2902| Name| Type | Mandatory| Description | 2903| ------ | ------- | ---- | ------------------------------------------------------------ | 2904| b | boolean | No | Selected status of the target component.<br>**true**: selected.<br>**false**: not selected.<br>Default value: **true** | 2905 2906**Return value** 2907 2908| Type | Description | 2909| ------------------- | ------------------------------------------ | 2910| [By](#bydeprecated) | **By** object that matches the selected status attribute of the target component.| 2911 2912**Example** 2913 2914```js 2915let by = BY.selected(true); // Use the static constructor BY to create a By object and specify the selected status attribute of the target component. 2916``` 2917 2918### isBefore<sup>(deprecated)</sup> 2919 2920isBefore(by: By): By 2921 2922Specifies the attributes of the component before which the target component is located. 2923 2924This API is deprecated since API version 9. You are advised to use [isBefore<sup>9+</sup>](#isbefore9). 2925 2926**System capability**: SystemCapability.Test.UiTest 2927 2928**Parameters** 2929 2930| Name| Type | Mandatory| Description | 2931| ------ | ------------------- | ---- | ---------------- | 2932| by | [By](#bydeprecated) | Yes | Attributes of the component before which the target component is located.| 2933 2934**Return value** 2935 2936| Type | Description | 2937| ------------------- | ---------------------------------------------------- | 2938| [By](#bydeprecated) | **By** object.| 2939 2940**Example** 2941 2942```js 2943let by = BY.isBefore(BY.text('123')); // Use the static constructor BY to create a By object and specify the attributes of the component before which the target component is located. 2944``` 2945 2946### isAfter<sup>(deprecated)</sup> 2947 2948isAfter(by: By): By 2949 2950Specifies the attributes of the component after which the target component is located. 2951 2952This API is deprecated since API version 9. You are advised to use [isAfter<sup>9+</sup>](#isafter9). 2953 2954**System capability**: SystemCapability.Test.UiTest 2955 2956**Parameters** 2957 2958| Name| Type | Mandatory| Description | 2959| ------ | ------------------- | ---- | ---------------- | 2960| by | [By](#bydeprecated) | Yes | Attributes of the component before which the target component is located.| 2961 2962**Return value** 2963 2964| Type | Description | 2965| ------------------- | ---------------------------------------------------- | 2966| [By](#bydeprecated) | **By** object.| 2967 2968**Example** 2969 2970```js 2971let by = BY.isAfter(BY.text('123')); // Use the static constructor BY to create a By object and specify the attributes of the component after which the target component is located. 2972``` 2973 2974## UiComponent<sup>(deprecated)</sup> 2975 2976In **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. 2977All APIs provided in this class use a promise to return the result and must be invoked using **await**. 2978 2979This API is deprecated since API version 9. You are advised to use [Component<sup>9+</sup>](#component9) instead. 2980 2981### click<sup>(deprecated)</sup> 2982 2983click(): Promise\<void> 2984 2985Clicks this component. 2986 2987This API is deprecated since API version 9. You are advised to use [click<sup>9+</sup>](#click9). 2988 2989**System capability**: SystemCapability.Test.UiTest 2990 2991**Example** 2992 2993```js 2994async function demo() { 2995 let driver = UiDriver.create(); 2996 let button = await driver.findComponent(BY.type('button')); 2997 await button.click(); 2998} 2999``` 3000 3001### doubleClick<sup>(deprecated)</sup> 3002 3003doubleClick(): Promise\<void> 3004 3005Double-clicks this component. 3006 3007This API is deprecated since API version 9. You are advised to use [doubleClick<sup>9+</sup>](#doubleclick9). 3008 3009**System capability**: SystemCapability.Test.UiTest 3010 3011**Example** 3012 3013```js 3014async function demo() { 3015 let driver = UiDriver.create(); 3016 let button = await driver.findComponent(BY.type('button')); 3017 await button.doubleClick(); 3018} 3019``` 3020 3021### longClick<sup>(deprecated)</sup> 3022 3023longClick(): Promise\<void> 3024 3025Long-clicks this component. 3026 3027This API is deprecated since API version 9. You are advised to use [longClick<sup>9+</sup>](#longclick9). 3028 3029**System capability**: SystemCapability.Test.UiTest 3030 3031**Example** 3032 3033```js 3034async function demo() { 3035 let driver = UiDriver.create(); 3036 let button = await driver.findComponent(BY.type('button')); 3037 await button.longClick(); 3038} 3039``` 3040 3041### getId<sup>(deprecated)</sup> 3042 3043getId(): Promise\<number> 3044 3045Obtains the ID of this component. 3046 3047This API is deprecated since API version 9. 3048 3049**System capability**: SystemCapability.Test.UiTest 3050 3051**Return value** 3052 3053| Type | Description | 3054| ---------------- | ------------------------------- | 3055| Promise\<number> | Promise used to return the ID of the component.| 3056 3057**Example** 3058 3059```js 3060async function demo() { 3061 let driver = UiDriver.create(); 3062 let button = await driver.findComponent(BY.type('button')); 3063 let num = await button.getId(); 3064} 3065``` 3066 3067### getKey<sup>(deprecated)</sup> 3068 3069getKey(): Promise\<string> 3070 3071Obtains the key of this component. 3072 3073This API is deprecated since API version 9. You are advised to use [getId<sup>9+</sup>](#getid9). 3074 3075**System capability**: SystemCapability.Test.UiTest 3076 3077**Return value** 3078 3079| Type | Description | 3080| ---------------- | ------------------------------ | 3081| Promise\<string> | Promise used to return the key of the component.| 3082 3083**Example** 3084 3085```js 3086async function demo() { 3087 let driver = UiDriver.create(); 3088 let button = await driver.findComponent(BY.type('button')); 3089 let str_key = await button.getKey(); 3090} 3091``` 3092 3093### getText<sup>(deprecated)</sup> 3094 3095getText(): Promise\<string> 3096 3097Obtains the text information of this component. 3098 3099This API is deprecated since API version 9. You are advised to use [getText<sup>9+</sup>](#gettext9). 3100 3101**System capability**: SystemCapability.Test.UiTest 3102 3103**Return value** 3104 3105| Type | Description | 3106| ---------------- | --------------------------------- | 3107| Promise\<string> | Promise used to return the text information of the component.| 3108 3109**Example** 3110 3111```js 3112async function demo() { 3113 let driver = UiDriver.create(); 3114 let button = await driver.findComponent(BY.type('button')); 3115 let text = await button.getText(); 3116} 3117``` 3118 3119### getType<sup>(deprecated)</sup> 3120 3121getType(): Promise\<string> 3122 3123Obtains the type of this component. 3124 3125This API is deprecated since API version 9. You are advised to use [getType<sup>9+</sup>](#gettype9). 3126 3127**System capability**: SystemCapability.Test.UiTest 3128 3129**Return value** 3130 3131| Type | Description | 3132| ---------------- | ----------------------------- | 3133| Promise\<string> | Promise used to return the type of the component.| 3134 3135**Example** 3136 3137```js 3138async function demo() { 3139 let driver = UiDriver.create(); 3140 let button = await driver.findComponent(BY.type('button')); 3141 let type = await button.getType(); 3142} 3143``` 3144 3145### isClickable<sup>(deprecated)</sup> 3146 3147isClickable(): Promise\<boolean> 3148 3149Obtains the clickable status of this component. 3150 3151This API is deprecated since API version 9. You are advised to use [isClickable<sup>9+</sup>](#isclickable9). 3152 3153**System capability**: SystemCapability.Test.UiTest 3154 3155**Return value** 3156 3157| Type | Description | 3158| ----------------- | ------------------------------------------------------------ | 3159| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is clickable, and **false** means the opposite.| 3160 3161**Example** 3162 3163```js 3164async function demo() { 3165 let driver = UiDriver.create(); 3166 let button = await driver.findComponent(BY.type('button')); 3167 if(await button.isClickable()) { 3168 console.info('This button can be Clicked'); 3169 } else { 3170 console.info('This button can not be Clicked'); 3171 } 3172} 3173``` 3174 3175### isScrollable<sup>(deprecated)</sup> 3176 3177isScrollable(): Promise\<boolean> 3178 3179Obtains the scrollable status of this component. 3180 3181This API is deprecated since API version 9. You are advised to use [isScrollable<sup>9+</sup>](#isscrollable9). 3182 3183**System capability**: SystemCapability.Test.UiTest 3184 3185**Return value** 3186 3187| Type | Description | 3188| ----------------- | ------------------------------------------------------------ | 3189| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is scrollable, and **false** means the opposite.| 3190 3191**Example** 3192 3193```js 3194async function demo() { 3195 let driver = UiDriver.create(); 3196 let scrollBar = await driver.findComponent(BY.scrollable(true)); 3197 if(await scrollBar.isScrollable()) { 3198 console.info('This scrollBar can be operated'); 3199 } else { 3200 console.info('This scrollBar can not be operated'); 3201 } 3202} 3203``` 3204 3205 3206### isEnabled<sup>(deprecated)</sup> 3207 3208isEnabled(): Promise\<boolean> 3209 3210Obtains the enabled status of this component. 3211 3212This API is deprecated since API version 9. You are advised to use [isEnabled<sup>9+</sup>](#isenabled9). 3213 3214**System capability**: SystemCapability.Test.UiTest 3215 3216**Return value** 3217 3218| Type | Description | 3219| ----------------- | ---------------------------------------------------------- | 3220| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is enabled, and **false** means the opposite.| 3221 3222**Example** 3223 3224```js 3225async function demo() { 3226 let driver = UiDriver.create(); 3227 let button = await driver.findComponent(BY.type('button')); 3228 if(await button.isEnabled()) { 3229 console.info('This button can be operated'); 3230 } else { 3231 console.info('This button can not be operated'); 3232 } 3233} 3234 3235``` 3236 3237### isFocused<sup>(deprecated)</sup> 3238 3239isFocused(): Promise\<boolean> 3240 3241Obtains the focused status of this component. 3242 3243This API is deprecated since API version 9. You are advised to use [isFocused<sup>9+</sup>](#isfocused9). 3244 3245**System capability**: SystemCapability.Test.UiTest 3246 3247**Return value** 3248 3249| Type | Description | 3250| ----------------- | ------------------------------------------------------------ | 3251| Promise\<boolean> | Promise used to return the result. The value **true** means that the target component is focused, and **false** means the opposite.| 3252 3253**Example** 3254 3255```js 3256async function demo() { 3257 let driver = UiDriver.create(); 3258 let button = await driver.findComponent(BY.type('button')); 3259 if(await button.isFocused()) { 3260 console.info('This button is focused'); 3261 } else { 3262 console.info('This button is not focused'); 3263 } 3264} 3265``` 3266 3267### isSelected<sup>(deprecated)</sup> 3268 3269isSelected(): Promise\<boolean> 3270 3271Obtains the selected status of this component. 3272 3273This API is deprecated since API version 9. You are advised to use [isSelected<sup>9+</sup>](#isselected9). 3274 3275**System capability**: SystemCapability.Test.UiTest 3276 3277**Return value** 3278 3279| Type | Description | 3280| ----------------- | ----------------------------------------------------- | 3281| Promise\<boolean> | Promise used to return the result. The value **true** means that the component is selected, and **false** means the opposite.| 3282 3283**Example** 3284 3285```js 3286async function demo() { 3287 let driver = UiDriver.create(); 3288 let button = await driver.findComponent(BY.type('button')); 3289 if(await button.isSelected()) { 3290 console.info('This button is selected'); 3291 } else { 3292 console.info('This button is not selected'); 3293 } 3294} 3295``` 3296 3297### inputText<sup>(deprecated)</sup> 3298 3299inputText(text: string): Promise\<void> 3300 3301Enters text into this component (available for text boxes). 3302 3303This API is deprecated since API version 9. You are advised to use [inputText<sup>9+</sup>](#inputtext9). 3304 3305**System capability**: SystemCapability.Test.UiTest 3306 3307**Parameters** 3308 3309| Name| Type | Mandatory| Description | 3310| ------ | ------ | ---- | ---------------- | 3311| text | string | Yes | Text to enter.| 3312 3313**Example** 3314 3315```js 3316async function demo() { 3317 let driver = UiDriver.create(); 3318 let text = await driver.findComponent(BY.text('hello world')); 3319 await text.inputText('123'); 3320} 3321``` 3322 3323### scrollSearch<sup>(deprecated)</sup> 3324 3325scrollSearch(by: By): Promise\<UiComponent> 3326 3327Scrolls on this component to search for the target component (applicable to components that support scrolling, such as **\<List>**). 3328 3329This API is deprecated since API version 9. You are advised to use [scrollSearch<sup>9+</sup>](#scrollsearch9). 3330 3331**System capability**: SystemCapability.Test.UiTest 3332 3333**Parameters** 3334 3335| Name| Type | Mandatory| Description | 3336| ------ | ------------------- | ---- | -------------------- | 3337| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 3338 3339**Return value** 3340 3341| Type | Description | 3342| ----------------------------------------------- | ------------------------------------- | 3343| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise used to return the target component.| 3344 3345**Example** 3346 3347```js 3348async function demo() { 3349 let driver = UiDriver.create(); 3350 let scrollBar = await driver.findComponent(BY.type('Scroll')); 3351 let button = await scrollBar.scrollSearch(BY.text('next page')); 3352} 3353``` 3354 3355## UiDriver<sup>(deprecated)</sup> 3356 3357The **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. 3358All APIs provided by this class, except for **UiDriver.create()**, use a promise to return the result and must be invoked using **await**. 3359 3360This API is deprecated since API version 9. You are advised to use [Driver<sup>9+</sup>](#driver9) instead. 3361 3362### create<sup>(deprecated)</sup> 3363 3364static create(): UiDriver 3365 3366Creates a **UiDriver** object and returns the object created. This API is a static API. 3367 3368This API is deprecated since API version 9. You are advised to use [create<sup>9+</sup>](#create9). 3369 3370**System capability**: SystemCapability.Test.UiTest 3371 3372**Return value** 3373 3374| Type | Description | 3375| -------- | ------------------------ | 3376| UiDriver | Returns the **UiDriver** object created.| 3377 3378**Example** 3379 3380```js 3381async function demo() { 3382 let driver = UiDriver.create(); 3383} 3384``` 3385 3386### delayMs<sup>(deprecated)</sup> 3387 3388delayMs(duration: number): Promise\<void> 3389 3390Delays this **UiDriver** object within the specified duration. 3391 3392This API is deprecated since API version 9. You are advised to use [delayMs<sup>9+</sup>](#delayms9). 3393 3394**System capability**: SystemCapability.Test.UiTest 3395 3396**Parameters** 3397 3398| Name | Type | Mandatory| Description | 3399| -------- | ------ | ---- | ------------ | 3400| duration | number | Yes | Duration of time.| 3401 3402**Example** 3403 3404```js 3405async function demo() { 3406 let driver = UiDriver.create(); 3407 await driver.delayMs(1000); 3408} 3409``` 3410 3411### findComponent<sup>(deprecated)</sup> 3412 3413findComponent(by: By): Promise\<UiComponent> 3414 3415Searches this **UiDriver** object for the target component that matches the given attributes. 3416 3417This API is deprecated since API version 9. You are advised to use [findComponent<sup>9+</sup>](#findcomponent9). 3418 3419**System capability**: SystemCapability.Test.UiTest 3420 3421**Parameters** 3422 3423| Name| Type | Mandatory| Description | 3424| ------ | ------------------- | ---- | -------------------- | 3425| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 3426 3427**Return value** 3428 3429| Type | Description | 3430| ----------------------------------------------- | --------------------------------- | 3431| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise used to return the found component.| 3432 3433**Example** 3434 3435```js 3436async function demo() { 3437 let driver = UiDriver.create(); 3438 let button = await driver.findComponent(BY.text('next page')); 3439} 3440``` 3441 3442### findComponents<sup>(deprecated)</sup> 3443 3444findComponents(by: By): Promise\<Array\<UiComponent>> 3445 3446Searches this **UiDriver** object for all components that match the given attributes. 3447 3448This API is deprecated since API version 9. You are advised to use [findComponents<sup>9+</sup>](#findcomponents9). 3449 3450**System capability**: SystemCapability.Test.UiTest 3451 3452**Parameters** 3453 3454| Name| Type | Mandatory| Description | 3455| ------ | ------------------- | ---- | -------------------- | 3456| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 3457 3458**Return value** 3459 3460| Type | Description | 3461| ------------------------------------------------------- | --------------------------------------- | 3462| Promise\<Array\<[UiComponent](#uicomponentdeprecated)>> | Promise used to return a list of found components.| 3463 3464**Example** 3465 3466```js 3467async function demo() { 3468 let driver = UiDriver.create(); 3469 let buttonList = await driver.findComponents(BY.text('next page')); 3470} 3471``` 3472 3473### assertComponentExist<sup>(deprecated)</sup> 3474 3475assertComponentExist(by: By): Promise\<void> 3476 3477Asserts 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. 3478 3479This API is deprecated since API version 9. You are advised to use [assertComponentExist<sup>9+</sup>](#assertcomponentexist9). 3480 3481**System capability**: SystemCapability.Test.UiTest 3482 3483**Parameters** 3484 3485| Name| Type | Mandatory| Description | 3486| ------ | ------------------- | ---- | -------------------- | 3487| by | [By](#bydeprecated) | Yes | Attributes of the target component.| 3488 3489**Example** 3490 3491```js 3492async function demo() { 3493 let driver = UiDriver.create(); 3494 await driver.assertComponentExist(BY.text('next page')); 3495} 3496``` 3497 3498### pressBack<sup>(deprecated)</sup> 3499 3500pressBack(): Promise\<void> 3501 3502Presses the Back button on this **UiDriver** object. 3503 3504This API is deprecated since API version 9. You are advised to use [pressBack<sup>9+</sup>](#pressback9). 3505 3506**System capability**: SystemCapability.Test.UiTest 3507 3508**Example** 3509 3510```js 3511async function demo() { 3512 let driver = UiDriver.create(); 3513 await driver.pressBack(); 3514} 3515``` 3516 3517### triggerKey<sup>(deprecated)</sup> 3518 3519triggerKey(keyCode: number): Promise\<void> 3520 3521Triggers the key of this **UiDriver** object that matches the given key code. 3522 3523This API is deprecated since API version 9. You are advised to use [triggerKey<sup>9+</sup>](#triggerkey9). 3524 3525**System capability**: SystemCapability.Test.UiTest 3526 3527**Parameters** 3528 3529| Name | Type | Mandatory| Description | 3530| ------- | ------ | ---- | ------------- | 3531| keyCode | number | Yes | Key code.| 3532 3533**Example** 3534 3535```js 3536async function demo() { 3537 let driver = UiDriver.create(); 3538 await driver.triggerKey(123); 3539} 3540``` 3541 3542 3543### click<sup>(deprecated)</sup> 3544 3545click(x: number, y: number): Promise\<void> 3546 3547Clicks a specific point of this **UiDriver** object based on the given coordinates. 3548 3549This API is deprecated since API version 9. You are advised to use [click<sup>9+</sup>](#click9). 3550 3551**System capability**: SystemCapability.Test.UiTest 3552 3553**Parameters** 3554 3555| Name| Type | Mandatory| Description | 3556| ------ | ------ | ---- | -------------------------------------- | 3557| x | number | Yes | X-coordinate of the target point.| 3558| y | number | Yes | Y-coordinate of the target point.| 3559 3560**Example** 3561 3562```js 3563async function demo() { 3564 let driver = UiDriver.create(); 3565 await driver.click(100,100); 3566} 3567``` 3568 3569### doubleClick<sup>(deprecated)</sup> 3570 3571doubleClick(x: number, y: number): Promise\<void> 3572 3573Double-clicks a specific point of this **UiDriver** object based on the given coordinates. 3574 3575This API is deprecated since API version 9. You are advised to use [doubleClick<sup>9+</sup>](#doubleclick9). 3576 3577**System capability**: SystemCapability.Test.UiTest 3578 3579**Parameters** 3580 3581| Name| Type | Mandatory| Description | 3582| ------ | ------ | ---- | -------------------------------------- | 3583| x | number | Yes | X-coordinate of the target point.| 3584| y | number | Yes | Y-coordinate of the target point.| 3585 3586**Example** 3587 3588```js 3589async function demo() { 3590 let driver = UiDriver.create(); 3591 await driver.doubleClick(100,100); 3592} 3593``` 3594 3595### longClick<sup>(deprecated)</sup> 3596 3597longClick(x: number, y: number): Promise\<void> 3598 3599Long-clicks a specific point of this **UiDriver** object based on the given coordinates. 3600 3601This API is deprecated since API version 9. You are advised to use [longClick<sup>9+</sup>](#longclick9). 3602 3603**System capability**: SystemCapability.Test.UiTest 3604 3605**Parameters** 3606 3607| Name| Type | Mandatory| Description | 3608| ------ | ------ | ---- | -------------------------------------- | 3609| x | number | Yes | X-coordinate of the target point.| 3610| y | number | Yes | Y-coordinate of the target point.| 3611 3612**Example** 3613 3614```js 3615async function demo() { 3616 let driver = UiDriver.create(); 3617 await driver.longClick(100,100); 3618} 3619``` 3620 3621### swipe<sup>(deprecated)</sup> 3622 3623swipe(startx: number, starty: number, endx: number, endy: number): Promise\<void> 3624 3625Swipes on this **UiDriver** object from the start point to the end point based on the given coordinates. 3626 3627This API is deprecated since API version 9. You are advised to use [swipe<sup>9+</sup>](#swipe9). 3628 3629**System capability**: SystemCapability.Test.UiTest 3630 3631**Parameters** 3632 3633| Name| Type | Mandatory| Description | 3634| ------ | ------ | ---- | -------------------------------------- | 3635| startx | number | Yes | X-coordinate of the start point.| 3636| starty | number | Yes | Y-coordinate of the start point.| 3637| endx | number | Yes | X-coordinate of the end point.| 3638| endy | number | Yes | Y-coordinate of the end point.| 3639 3640**Example** 3641 3642```js 3643async function demo() { 3644 let driver = UiDriver.create(); 3645 await driver.swipe(100,100,200,200); 3646} 3647``` 3648 3649### screenCap<sup>(deprecated)</sup> 3650 3651screenCap(savePath: string): Promise\<boolean> 3652 3653Captures the current screen of this **UiDriver** object and saves it as a PNG image to the given save path. 3654 3655This API is deprecated since API version 9. You are advised to use [screenCap<sup>9+</sup>](#screencap9). 3656 3657**System capability**: SystemCapability.Test.UiTest 3658 3659**Parameters** 3660 3661| Name | Type | Mandatory| Description | 3662| -------- | ------ | ---- | -------------- | 3663| savePath | string | Yes | File save path.| 3664 3665**Return value** 3666 3667| Type | Description | 3668| ----------------- | -------------------------------------- | 3669| Promise\<boolean> | Promise used to return the operation result. The value **true** means that the operation is successful.| 3670 3671**Example** 3672 3673```js 3674async function demo() { 3675 let driver = UiDriver.create(); 3676 await driver.screenCap('/local/tmp/1.png'); 3677} 3678``` 3679
