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