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