>**NOTE**<br>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.
The **UiTest** module provides APIs that you can use to simulate UI actions during testing, such as clicks, double-clicks, long-clicks, and swipes.
This module provides the following functions:
-[On<sup>9+</sup>](#on9): provides UI component feature description APIs for component filtering and matching.
-[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.
-[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.
-[UiWindow<sup>9+</sup>](#uiwindow9): works as the entry class and provides APIs for obtaining window attributes, dragging windows, and adjusting window sizes.
-[By<sup>(deprecated)</sup>](#bydeprecated): provides UI component feature description APIs for component filtering and matching. This API is deprecated since API version 9. You are advised to use [On<sup>9+</sup>](#on9) instead.
-[UiComponent<sup>(deprecated)</sup>](#uicomponentdeprecated): represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. This API is deprecated since API version 9. You are advised to use [Component<sup>9+</sup>](#component9) instead.
-[UiDriver<sup>(deprecated)</sup>](#uidriverdeprecated): works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. This API is deprecated since API version 9. You are advised to use [Driver<sup>9+</sup>](#driver9) instead.
>**NOTE**
>
>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.
## Modules to Import
```
import {UiDriver,BY,MatchPattern} from '@ohos.uitest'
The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components.<br>
The 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.
Enumerates the match patterns supported for component attributes.
| bundleName | string | Yes | No | Bundle name of the application to which the window belongs. |
| title | string | Yes | No | Title of the window. |
| focused | boolean | Yes | No | Whether the window is in focused state. |
| actived | boolean | Yes | No | Whether the window is interacting with the user.|
## On<sup>9+</sup>
Since 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.
The API capabilities provided by the **On** class exhibit the following features: 1. Allow one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component. <br>2. Provide multiple match patterns for component attributes. <br>3. Support absolute positioning and relative positioning for components. APIs such as [ON.isBefore](#isbefore) and [ON.isAfter](#isafter) can be used to specify the features of adjacent components to assist positioning. <br>All APIs provided in the **On** class are synchronous. You are advised to use the static constructor **ON** to create an **On** object in chain mode.
```js
letby=BY.text('123')// Use the static constructor BY to create a By object and specify the text attribute of the target component.
ON.text('123').type('button');
```
### text<sup>9+</sup>
### By.key
key(key: string): By
text(txt: string, pattern?: MatchPattern): On
Specifies the key attribute of the target component.
Specifies the text attribute of the target component. Multiple match patterns are supported.
| b | boolean | No | Long-clickable status of the target component.<br>**true**: long-clickable.<br>**false**: not long-clickable.<br> Default value: **true**|
| [On](#on9) | **On** object that matches the long-clickable status attribute of the target component.|
**Example**
```js
letby=BY.longClickable(true)// Use the static constructor BY to create a By object and specify the long-clickable status attribute of the target component.
leton=ON.longClickable(true);// Use the static constructor ON to create an On object and specify the long-clickable status attribute of the target component.
```
### By.scrollable
### scrollable<sup>9+</sup>
scrollable(b?: bool): By
scrollable(b?: boolean): On
Specifies the scrollable status attribute of the target component.
...
...
@@ -191,25 +270,25 @@ Specifies the scrollable status attribute of the target component.
letby=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.
leton=ON.isBefore(ON.text('123'));// Use the static constructor ON to create an On object and specify the attributes of the component before which the target component is located.
```
### By.isAfter
### isAfter<sup>9+</sup>
isAfter(by: By): By
isAfter(on: On): On
Specifies the attributes of the component after which the target component is located.
...
...
@@ -373,41 +452,28 @@ Specifies the attributes of the component after which the target component is lo
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ---------------- |
| by | By | Yes | Attributes of the component before which the target component is located.|
letby=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.
leton=ON.isAfter(ON.text('123'));// Use the static constructor ON to create an On object and specify the attributes of the component after which the target component is located.
```
## UiComponent
## Component<sup>9+</sup>
In **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.
In **UiTest** of API version 9, the **Component** class represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection.
All APIs provided in this class use a promise to return the result and must be invoked using **await**.
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
The **UiDriver** class is the main entry to the **uitest** test framework. It provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot.
All APIs provided by this class, except for **UiDriver.create()**, use a promise to return the result and must be invoked using **await**.
pinchOut(scale: number): Promise\<void>
### UiDriver.create
Pinches a component to scale it up to the specified ratio.
The **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.
All APIs provided by this class, except for **Driver.create()**, use a promise to return the result and must be invoked using **await**.
Searches this **UiDriver** object for the target component that matches the given attributes.
Asserts 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.
Searches this **Driver** object for all components that match the given attributes.
Triggers 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**.
| startx | number | Yes | X-coordinate of the start point. |
| starty | number | Yes | Y-coordinate of the start point. |
| endx | number | Yes | X-coordinate of the end point. |
| endy | number | Yes | Y-coordinate of the end point. |
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| startx | number | Yes | X-coordinate of the start point. |
| starty | number | Yes | Y-coordinate of the start point. |
| endx | number | Yes | X-coordinate of the end point. |
| endy | number | Yes | Y-coordinate of the end point. |
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| enabled | boolean | Yes | Whether to enable display rotation. The value **true** means to enable display rotation, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| 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.|
| timeout | number | Yes | Maximum idle waiting time, in milliseconds. |
| from | [Point](#point9) | Yes | Coordinates of the point where the finger touches the screen. |
| to | [Point](#point9) | Yes | Coordinates of the point where the finger leaves the screen. |
| stepLen | number | Yes | Fling step length, in pixels. |
| speed | number | Yes | Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| pointers | [PointerMatrix](#pointermatrix9) | Yes | Scroll trajectory, including the number of fingers and an array of coordinates along the trajectory. |
| 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.|
| finger | number | Yes | Sequence number of the finger. |
| step | number | Yes | Sequence number of the step. |
| point | [Point](#point9) | Yes | Coordinates of the action.|
**Example**
```js
asyncfunctiondemo(){
letpointers=PointerMatrix.create(2,3);
pointers.setPoint(0,0,{X:230,Y:480});
pointers.setPoint(0,1,{X:250,Y:380});
pointers.setPoint(0,2,{X:270,Y:280});
pointers.setPoint(1,0,{X:230,Y:680});
pointers.setPoint(1,1,{X:240,Y:580});
pointers.setPoint(1,2,{X:250,Y:480});
}
```
## UiWindow<sup>9+</sup>
The **UiWindow** class represents a window on the UI and provides APIs for obtaining window attributes, dragging a window, and adjusting the window size.
All APIs provided in this class use a promise to return the result and must be invoked using **await**.
### getBundleName<sup>9+</sup>
getBundleName(): Promise\<string>
Obtains the bundle name of the application to which this window belongs.
| Promise\<boolean> | Promise used to return the result. The value **true** means that the window is in focused state, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**Example**
```js
asyncfunctiondemo(){
letdriver=Driver.create();
letwindow=awaitdriver.findWindow({actived:true});
awaitwindow.close();
}
```
## By<sup>(deprecated)</sup>
The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components.
The API capabilities provided by the **By** class exhibit the following features: <br>1. Allow one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component. <br>2. Provide multiple match patterns for component attributes. <br>3. Support absolute positioning and relative positioning for components. APIs such as [By.isBefore<sup>(deprecated)</sup>](#isbeforedeprecated) and [By.isAfter<sup>(deprecated)</sup>](#isafterdeprecated) can be used to specify the features of adjacent components to assist positioning. <br>All APIs provided in the **By** class are synchronous. You are advised to use the static constructor **BY** to create a **By** object in chain mode.
This API is deprecated since API version 9. You are advised to use [On<sup>9+</sup>](#on9) instead.
```js
BY.text('123').type('button');
```
### text<sup>(deprecated)</sup>
text(txt: string, pattern?: MatchPattern): By
Specifies the text attribute of the target component. Multiple match patterns are supported.
This API is deprecated since API version 9. You are advised to use [text<sup>9+</sup>](#text9).
letby=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.
```
### isAfter<sup>(deprecated)</sup>
isAfter(by: By): By
Specifies the attributes of the component after which the target component is located.
This API is deprecated since API version 9. You are advised to use [isAfter<sup>9+</sup>](#isafter9).
letby=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.
```
## UiComponent<sup>(deprecated)</sup>
In **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.
All APIs provided in this class use a promise to return the result and must be invoked using **await**.
This API is deprecated since API version 9. You are advised to use [Component<sup>9+</sup>](#component9) instead.
### click<sup>(deprecated)</sup>
click(): Promise\<void>
Clicks this component.
This API is deprecated since API version 9. You are advised to use [click<sup>9+</sup>](#click9).
| Promise\<boolean> | Promise used to return the result. The value **true** means that the target component is focused, and **false** means the opposite.|
The **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.
All APIs provided by this class, except for **UiDriver.create()**, use a promise to return the result and must be invoked using **await**.
This API is deprecated since API version 9. You are advised to use [Driver<sup>9+</sup>](#driver9) instead.
### create<sup>(deprecated)</sup>
static create(): UiDriver
Creates a **UiDriver** object and returns the object created. This API is a static API.
This API is deprecated since API version 9. You are advised to use [create<sup>9+</sup>](#create9).
Asserts 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.
This API is deprecated since API version 9. You are advised to use [assertComponentExist<sup>9+</sup>](#assertcomponentexist9).
