1# 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- [By](#by): provides UI component feature description APIs for component filtering and matching. 8- [UiComponent](#uicomponent): 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- [UiDriver](#uidriver): works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. 10 11>**NOTE** 12> 13>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. 14 15 16## Modules to Import 17 18``` 19import {UiDriver,BY,MatchPattern} from '@ohos.uitest' 20``` 21 22## MatchPattern 23 24Enumerates the match patterns supported for component attributes. 25 26**System capability**: SystemCapability.Test.UiTest 27 28| Name | Value | Description | 29| ----------- | ---- | -------------- | 30| EQUALS | 0 | Equal to the given value. | 31| CONTAINS | 1 | Contains the given value. | 32| STARTS_WITH | 2 | Starts with the given value.| 33| ENDS_WITH | 3 | Ends with the given value.| 34 35 36## By 37 38The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components. 39The API capabilities provided by the **By** class exhibit the following features: <br>1. Allow one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component. <br>2. Provide multiple match patterns for component attributes. <br>3. Support absolute positioning and relative positioning for components. APIs such as [By.isBefore](#byisbefore) and [By.isAfter](#byisafter) can be used to specify the features of adjacent components to assist positioning. <br>All APIs provided in the **By** class are synchronous. You are advised to use the static constructor **BY** to create a **By** object in chain mode. 40 41```js 42BY.text('123').type('button') 43``` 44 45### text 46 47text(txt: string, pattern?: MatchPattern): By 48 49Specifies the text attribute of the target component. Multiple match patterns are supported. 50 51**System capability**: SystemCapability.Test.UiTest 52 53**Parameters** 54 55| Name | Type | Mandatory| Description | 56| ------- | ------------ | ---- | ------------------------------------------------- | 57| txt | string | Yes | Component text, used to match the target component. | 58| pattern | MatchPattern | No | Match pattern. The default value is [EQUALS](#matchpattern).| 59 60**Return value** 61 62| Type| Description | 63| ---- | -------------- | 64| By | Returns the **By** object itself.| 65 66**Example** 67 68```js 69let by = BY.text('123') // Use the static constructor BY to create a By object and specify the text attribute of the target component. 70``` 71 72 73### By.key 74 75key(key: string): By 76 77Specifies the key attribute of the target component. 78 79**System capability**: SystemCapability.Test.UiTest 80 81**Parameters** 82 83| Name| Type | Mandatory| Description | 84| ------ | ------ | ---- | ----------------- | 85| key | string | Yes | Component key.| 86 87**Return value** 88 89| Type| Description | 90| ---- | ---------------- | 91| By | Returns the **By** object itself.| 92 93**Example** 94 95```js 96let by = BY.key('123') // Use the static constructor BY to create a By object and specify the key attribute of the target component. 97``` 98 99 100### By.id 101 102id(id: number): By 103 104Specifies the ID attribute of the target component. 105 106**System capability**: SystemCapability.Test.UiTest 107 108**Parameters** 109 110| Name| Type | Mandatory| Description | 111| ------ | ------ | ---- | ---------------- | 112| id | number | Yes | Component ID.| 113 114**Return value** 115 116| Type| Description | 117| ---- | ---------------- | 118| By | Returns the **By** object itself.| 119 120**Example** 121 122```js 123let by = BY.id(123) // Use the static constructor BY to create a By object and specify the id attribute of the target component. 124``` 125 126 127### By.type 128 129type(tp: string): By 130 131Specifies the type attribute of the target component. 132 133**System capability**: SystemCapability.Test.UiTest 134 135**Parameters** 136 137| Name| Type | Mandatory| Description | 138| ------ | ------ | ---- | -------------- | 139| tp | string | Yes | Component type.| 140 141**Return value** 142 143| Type| Description | 144| ---- | ---------------- | 145| By | Returns the **By** object itself.| 146 147**Example** 148 149```js 150let by = BY.type('button') // Use the static constructor BY to create a By object and specify the type attribute of the target component. 151``` 152 153 154### clickable 155 156clickable(b?: bool): By 157 158Specifies the clickable status of the target component. 159 160**System capability**: SystemCapability.Test.UiTest 161 162**Parameters** 163 164| Name| Type| Mandatory| Description | 165| ------ | ---- | ---- | -------------------------------- | 166| b | bool | No | Clickable status of the target component. The default value is **true**.| 167 168**Return value** 169 170| Type| Description | 171| ---- | ---------------- | 172| By | Returns the **By** object itself.| 173 174**Example** 175 176```js 177let by = BY.clickable(true) // Use the static constructor BY to create a By object and specify the clickable status of the target component. 178``` 179 180 181### By.scrollable 182 183scrollable(b?: bool): By 184 185Specifies the scrollable status of the target component. 186 187**System capability**: SystemCapability.Test.UiTest 188 189**Parameters** 190 191| Name| Type| Mandatory| Description | 192| ------ | ---- | ---- | ---------------------------- | 193| b | bool | No | Scrollable status of the target component. The default value is **true**.| 194 195**Return value** 196 197| Type| Description | 198| ---- | ---------------- | 199| By | Returns the **By** object itself.| 200 201**Example** 202 203```js 204let by = BY.scrollable(true) // Use the static constructor BY to create a By object and specify the scrollable status of the target component. 205``` 206 207### By.enabled 208 209enabled(b?: bool): By 210 211Specifies the enabled status of the target component. 212 213**System capability**: SystemCapability.Test.UiTest 214 215**Parameters** 216 217| Name| Type| Mandatory| Description | 218| ------ | ---- | ---- | ------------------------------ | 219| b | bool | No | Enabled status of the target component. The default value is **true**.| 220 221**Return value** 222 223| Type| Description | 224| ---- | ---------------- | 225| By | Returns the **By** object itself.| 226 227**Example** 228 229```js 230let by = BY.enabled(true) // Use the static constructor BY to create a By object and specify the enabled status of the target component. 231``` 232 233### By.focused 234 235focused(b?: bool): By 236 237Specifies the focused status of the target component. 238 239**System capability**: SystemCapability.Test.UiTest 240 241**Parameters** 242 243| Name| Type| Mandatory| Description | 244| ------ | ---- | ---- | -------------------------- | 245| b | bool | No | Focused status of the target component. The default value is **true**.| 246 247**Return value** 248 249| Type| Description | 250| ---- | ---------------- | 251| By | Returns the **By** object itself.| 252 253**Example** 254 255```js 256let by = BY.focused(true) // Use the static constructor BY to create a By object and specify the focused status of the target component. 257``` 258 259### By.selected 260 261selected(b?: bool): By 262 263Specifies the selected status of the target component. 264 265**System capability**: SystemCapability.Test.UiTest 266 267**Parameters** 268 269| Name| Type| Mandatory| Description | 270| ------ | ---- | ---- | -------------------------------- | 271| b | bool | No | Selected status of the target component. The default value is **true**.| 272 273**Return value** 274 275| Type| Description | 276| ---- | ---------------- | 277| By | Returns the **By** object itself.| 278 279**Example** 280 281```js 282let by = BY.selected(true) // Use the static constructor BY to create a By object and specify the selected status of the target component. 283``` 284 285### By.isBefore 286 287isBefore(by: By): By 288 289Specifies the attributes of the component before which the target component is located. 290 291**System capability**: SystemCapability.Test.UiTest 292 293**Parameters** 294 295| Name| Type| Mandatory| Description | 296| ------ | ---- | ---- | ---------------- | 297| by | By | Yes | Attributes of the component before which the target component is located.| 298 299**Return value** 300 301| Type| Description | 302| ---- | ---------------- | 303| By | Returns the **By** object itself.| 304 305**Example** 306 307```js 308let by = BY.isBefore(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes of the component before which the target component is located. 309``` 310 311### By.isAfter 312 313isAfter(by: By): By 314 315Specifies the attributes of the component after which the target component is located. 316 317**System capability**: SystemCapability.Test.UiTest 318 319**Parameters** 320 321| Name| Type| Mandatory| Description | 322| ------ | ---- | ---- | ---------------- | 323| by | By | Yes | Attributes of the component before which the target component is located.| 324 325**Return value** 326 327| Type| Description | 328| ---- | ---------------- | 329| By | Returns the **By** object itself.| 330 331**Example** 332 333```js 334let by = BY.isAfter(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes of the component after which the target component is located. 335``` 336 337## UiComponent 338 339In **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. 340All APIs provided in this class use a promise to return the result and must be invoked using **await**. 341 342 343### UiComponent.click 344 345click(): Promise\<void> 346 347Clicks this component. 348 349**System capability**: SystemCapability.Test.UiTest 350 351**Example** 352 353```js 354async function demo() { 355 let driver = UiDriver.create() 356 let button = await driver.findComponent(BY.type('button')) 357 await button.click() 358} 359``` 360 361### UiComponent.doubleClick 362 363doubleClick(): Promise\<void> 364 365Double-clicks this component. 366 367**System capability**: SystemCapability.Test.UiTest 368 369**Example** 370 371```js 372async function demo() { 373 let driver = UiDriver.create() 374 let button = await driver.findComponent(BY.type('button')) 375 await button.doubleClick() 376} 377``` 378 379### UiComponent.longClick 380 381longClick(): Promise\<void> 382 383Long-clicks this component. 384 385**System capability**: SystemCapability.Test.UiTest 386 387**Example** 388 389```js 390async function demo() { 391 let driver = UiDriver.create() 392 let button = await driver.findComponent(BY.type('button')) 393 await button.longClick() 394} 395``` 396 397### UiComponent.getId 398 399getId(): Promise\<number> 400 401Obtains the ID of this component. 402 403**System capability**: SystemCapability.Test.UiTest 404 405**Return value** 406 407| Type | Description | 408| ---------------- | ------------------------------- | 409| Promise\<number> | Promise used to return the ID of the component.| 410 411**Example** 412 413```js 414async function demo() { 415 let driver = UiDriver.create() 416 let button = await driver.findComponent(BY.type('button')) 417 let num = await button.getId() 418} 419``` 420 421### UiComponent.getKey 422 423getKey(): Promise\<string> 424 425Obtains the key of this component. 426 427**System capability**: SystemCapability.Test.UiTest 428 429**Return value** 430 431| Type | Description | 432| ---------------- | ------------------------------ | 433| Promise\<string> | Promise used to return the key of the component.| 434 435**Example** 436 437```js 438async function demo() { 439 let driver = UiDriver.create() 440 let button = await driver.findComponent(BY.type('button')) 441 let str_key = await button.getKey() 442} 443``` 444 445### UiComponent.getText 446 447getText(): Promise\<string> 448 449Obtains the text information of this component. 450 451**System capability**: SystemCapability.Test.UiTest 452 453**Return value** 454 455| Type | Description | 456| ---------------- | --------------------------------- | 457| Promise\<string> | Promise used to return the text information of the component.| 458 459**Example** 460 461```js 462async function demo() { 463 let driver = UiDriver.create() 464 let button = await driver.findComponent(BY.type('button')) 465 let text = await button.getText() 466} 467``` 468 469### UiComponent.getType 470 471getType(): Promise\<string> 472 473Obtains the type of this component. 474 475**System capability**: SystemCapability.Test.UiTest 476 477**Return value** 478 479| Type | Description | 480| ---------------- | ----------------------------- | 481| Promise\<string> | Promise used to return the type of the component.| 482 483**Example** 484 485```js 486async function demo() { 487 let driver = UiDriver.create() 488 let button = await driver.findComponent(BY.type('button')) 489 let type = await button.getType() 490} 491``` 492 493### UiComponent.isClickable 494 495isClickable(): Promise\<bool> 496 497Obtains the clickable status of this component. 498 499**System capability**: SystemCapability.Test.UiTest 500 501**Return value** 502 503| Type | Description | 504| -------------- | ------------------------------------- | 505| Promise\<bool> | Promise used to return the clickable status of the component.| 506 507**Example** 508 509```js 510async function demo() { 511 let driver = UiDriver.create() 512 let button = await driver.findComponent(BY.type('button')) 513 if(await button.isClickable()) { 514 console.info('This button can be Clicked') 515 } 516 else{ 517 console.info('This button can not be Clicked') 518 } 519} 520``` 521 522### UiComponent.isScrollable 523 524isScrollable(): Promise\<bool> 525 526Obtains the scrollable status of this component. 527 528**System capability**: SystemCapability.Test.UiTest 529 530**Return value** 531 532| Type | Description | 533| -------------- | ------------------------------------- | 534| Promise\<bool> | Promise used to return the scrollable status of the component.| 535 536**Example** 537 538```js 539async function demo() { 540 let driver = UiDriver.create() 541 let scrollBar = await driver.findComponent(BY.scrollable(true)) 542 if(await scrollBar.isScrollable()) { 543 console.info('This scrollBar can be operated') 544 } 545 else{ 546 console.info('This scrollBar can not be operated') 547 } 548} 549``` 550 551 552### UiComponent.isEnabled 553 554isEnabled(): Promise\<bool> 555 556Obtains the enabled status of this component. 557 558**System capability**: SystemCapability.Test.UiTest 559 560**Return value** 561 562| Type | Description | 563| -------------- | ------------------------------- | 564| Promise\<bool> | Promise used to return the enabled status of the component.| 565 566**Example** 567 568```js 569async function demo() { 570 let driver = UiDriver.create() 571 let button = await driver.findComponent(BY.type('button')) 572 if(await button.isEnabled()) { 573 console.info('This button can be operated') 574 } 575 else{ 576 console.info('This button can not be operated') 577 } 578} 579 580``` 581 582### UiComponent.isFocused 583 584isFocused(): Promise\<bool> 585 586Obtains the focused status of this component. 587 588**System capability**: SystemCapability.Test.UiTest 589 590**Return value** 591 592| Type | Description | 593| -------------- | ----------------------------------- | 594| Promise\<bool> | Promise used to return the focused status of the component.| 595 596**Example** 597 598```js 599async function demo() { 600 let driver = UiDriver.create() 601 let button = await driver.findComponent(BY.type('button')) 602 if(await button.isFocused()) { 603 console.info('This button is focused') 604 } 605 else{ 606 console.info('This button is not focused') 607 } 608} 609``` 610 611### UiComponent.isSelected 612 613isSelected(): Promise\<bool> 614 615Obtains the selected status of this component. 616 617**System capability**: SystemCapability.Test.UiTest 618 619**Return value** 620 621| Type | Description | 622| -------------- | -------------------- | 623| Promise\<bool> | Promise used to return the selected status of the component.| 624 625**Example** 626 627```js 628async function demo() { 629 let driver = UiDriver.create() 630 let button = await driver.findComponent(BY.type('button')) 631 if(await button.isSelected()) { 632 console.info('This button is selected') 633 } 634 else{ 635 console.info('This button is not selected') 636 } 637} 638``` 639 640### UiComponent.inputText 641 642inputText(text: string): Promise\<void> 643 644Enters text into this component (available for text boxes). 645 646**System capability**: SystemCapability.Test.UiTest 647 648**Parameters** 649 650| Name| Type | Mandatory| Description | 651| ------ | ------ | ---- | ---------------- | 652| text | string | Yes | Text to enter.| 653 654**Example** 655 656```js 657async function demo() { 658 let driver = UiDriver.create() 659 let text = await driver.findComponent(BY.text('hello world')) 660 await text.inputText('123') 661} 662``` 663 664### UiComponent.scrollSearch 665 666scrollSearch(by:By): Promise\<UiComponent> 667 668Scrolls on this component to search for the target component (applicable to component that support scrolling, such as **\<List>**). 669 670**System capability**: SystemCapability.Test.UiTest 671 672**Parameters** 673 674| Name| Type| Mandatory| Description | 675| ------ | ---- | ---- | -------------------- | 676| by | By | Yes | Attributes of the target component.| 677 678**Return value** 679 680| Type | Description | 681| --------------------- | ------------------------------------- | 682| Promise\<UiComponent> | Promise used to return the target component.| 683 684**Example** 685 686```js 687async function demo() { 688 let driver = UiDriver.create() 689 let scrollBar = await driver.findComponent(BY.type('Scroll')) 690 let button = await scrollBar.scrollSearch(BY.text('next page')) 691} 692``` 693 694 695 696## UiDriver 697 698The **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. 699All APIs provided by this class, except for **UiDriver.create()**, use a promise to return the result and must be invoked using **await**. 700 701### create 702 703static create(): UiDriver 704 705Creates a **UiDriver** object and returns the object created. This API is a static API. 706 707**System capability**: SystemCapability.Test.UiTest 708 709**Return value** 710 711| Type | Description | 712| ------- | ------------------------ | 713| UiDrive | Returns the **UiDriver** object created.| 714 715**Example** 716 717```js 718async function demo() { 719 let driver = UiDriver.create() 720} 721``` 722 723### UiDriver.delayMs 724 725delayMs(duration: number): Promise\<void> 726 727Delays this **UiDriver** object within the specified duration. 728 729**System capability**: SystemCapability.Test.UiTest 730 731**Parameters** 732 733| Name | Type | Mandatory| Description | 734| -------- | ------ | ---- | ------------ | 735| duration | number | Yes | Duration of time.| 736 737**Example** 738 739```js 740async function demo() { 741 let driver = UiDriver.create() 742 await driver.delayMs(1000) 743} 744``` 745 746### UiDriver.findComponent 747 748findComponent(by: By): Promise\<UiComponent> 749 750Searches this **UiDriver** object for the target component that matches the given attributes. 751 752**System capability**: SystemCapability.Test.UiTest 753 754**Parameters** 755 756| Name| Type| Mandatory| Description | 757| ------ | ---- | ---- | -------------------- | 758| by | By | Yes | Attributes of the target component.| 759 760**Return value** 761 762| Type | Description | 763| --------------------- | --------------------------------- | 764| Promise\<UiComponent> | Promise used to return the found component.| 765 766**Example** 767 768```js 769async function demo() { 770 let driver = UiDriver.create() 771 let button = await driver.findComponent(BY.text('next page')) 772} 773``` 774 775### findComponents 776 777findComponents(by: By): Promise\<Array\<UiComponent>> 778 779Searches this **UiDriver** object for all components that match the given attributes. 780 781**System capability**: SystemCapability.Test.UiTest 782 783**Parameters** 784 785| Name| Type| Mandatory| Description | 786| ------ | ---- | ---- | -------------------- | 787| by | By | Yes | Attributes of the target component.| 788 789**Return value** 790 791| Type | Description | 792| ----------------------------- | --------------------------------------- | 793| Promise\<Array\<UiComponent>> | Promise used to return a list of found components.| 794 795**Example** 796 797```js 798async function demo() { 799 let driver = UiDriver.create() 800 let buttonList = await driver.findComponents(BY.text('next page')) 801} 802``` 803 804### UiDriver.assertComponentExist 805 806assertComponentExist(by: By): Promise\<void> 807 808Asserts 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. 809 810**System capability**: SystemCapability.Test.UiTest 811 812**Parameters** 813 814| Name| Type| Mandatory| Description | 815| ------ | ---- | ---- | -------------------- | 816| by | By | Yes | Attributes of the target component.| 817 818**Example** 819 820```js 821async function demo() { 822 let driver = UiDriver.create() 823 await driver.assertComponentExist(BY.text('next page')) 824} 825``` 826 827### UiDriver.pressBack 828 829pressBack(): Promise\<void> 830 831Presses the Back button on this **UiDriver** object. 832 833**System capability**: SystemCapability.Test.UiTest 834 835**Example** 836 837```js 838async function demo() { 839 let driver = UiDriver.create() 840 await driver.pressBack() 841} 842``` 843 844### UiDriver.triggerKey 845 846triggerKey(keyCode: number): Promise\<void> 847 848Triggers the key of this **UiDriver** object that matches the given key code. 849 850**System capability**: SystemCapability.Test.UiTest 851 852**Parameters** 853 854| Name | Type | Mandatory| Description | 855| ------- | ------ | ---- | ------------- | 856| keyCode | number | Yes | Key code.| 857 858**Example** 859 860```js 861async function demo() { 862 let driver = UiDriver.create() 863 await driver.triggerKey(123) 864} 865``` 866 867### UiDriver.click 868 869click(x: number, y: number): Promise\<void> 870 871Clicks a specific point of this **UiDriver** object based on the given coordinates. 872 873**System capability**: SystemCapability.Test.UiTest 874 875**Parameters** 876 877| Name| Type | Mandatory| Description | 878| ------ | ------ | ---- | -------------------------------------- | 879| x | number | Yes | X-coordinate of the target point.| 880| y | number | Yes | Y-coordinate of the target point.| 881 882**Example** 883 884```js 885async function demo() { 886 let driver = UiDriver.create() 887 await driver.click(100,100) 888} 889``` 890 891### UiDriver.doubleClick 892 893doubleClick(x: number, y: number): Promise\<void> 894 895Double-clicks a specific point of this **UiDriver** object based on the given coordinates. 896 897**System capability**: SystemCapability.Test.UiTest 898 899**Parameters** 900 901| Name| Type | Mandatory| Description | 902| ------ | ------ | ---- | -------------------------------------- | 903| x | number | Yes | X-coordinate of the target point.| 904| y | number | Yes | Y-coordinate of the target point.| 905 906**Example** 907 908```js 909async function demo() { 910 let driver = UiDriver.create() 911 await driver.doubleClick(100,100) 912} 913``` 914 915### longClick 916 917longClick(x: number, y: number): Promise\<void> 918 919Long-clicks a specific point of this **UiDriver** object based on the given coordinates. 920 921**System capability**: SystemCapability.Test.UiTest 922 923**Parameters** 924 925| Name| Type | Mandatory| Description | 926| ------ | ------ | ---- | -------------------------------------- | 927| x | number | Yes | X-coordinate of the target point.| 928| y | number | Yes | Y-coordinate of the target point.| 929 930**Example** 931 932```js 933async function demo() { 934 let driver = UiDriver.create() 935 await driver.longClick(100,100) 936} 937``` 938 939### UiDriver.swipe 940 941swipe(startx: number, starty: number, endx: number, endy: number, speed: number): Promise\<void> 942 943Swipes on this **UiDriver** object from the start point to the end point based on the given coordinates. 944 945**System capability**: SystemCapability.Test.UiTest 946 947**Parameters** 948 949| Name| Type | Mandatory| Description | 950| ------ | ------ | ---- | ---------------------------------------- | 951| startx | number | Yes | X-coordinate of the start point. | 952| starty | number | Yes | Y-coordinate of the start point. | 953| endx | number | Yes | X-coordinate of the end point. | 954| endy | number | Yes | Y-coordinate of the end point. | 955| speed | number | No | Scroll speed, in pixels/s. The default value is **600**.| 956 957**Example** 958 959```js 960async function demo() { 961 let driver = UiDriver.create() 962 await driver.swipe(100,100,200,200) 963} 964``` 965 966### UiDriver.screenCap 967 968screenCap(savePath: string): Promise\<bool> 969 970Captures the current screen of this **UiDriver** object and saves it as a PNG image to the given save path. 971 972**System capability**: SystemCapability.Test.UiTest 973 974**Parameters** 975 976| Name | Type | Mandatory| Description | 977| -------- | ------ | ---- | -------------- | 978| savePath | string | Yes | File save path.| 979 980**Return value** 981 982| Type | Description | 983| -------------- | -------------------------------------- | 984| Promise\<bool> | Promise used to return the operation result. The value **true** means that the operation is successful.| 985 986**Example** 987 988```js 989async function demo() { 990 let driver = UiDriver.create() 991 await driver.screenCap('/local/tmp/') 992} 993``` 994 995