# @ohos.UiTest
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:
- [On9+](#on9): provides UI component feature description APIs for component filtering and matching.
- [Component9+](#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.
- [Driver9+](#driver9): works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot.
- [UiWindow9+](#uiwindow9): works as the entry class and provides APIs for obtaining window attributes, dragging windows, and adjusting window sizes.
- [By(deprecated)](#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 [On9+](#on9) instead.
- [UiComponent(deprecated)](#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 [Component9+](#component9) instead.
- [UiDriver(deprecated)](#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 [Driver9+](#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
```js
import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton, UIElementInfo, UIEventObserver} from '@ohos.UiTest';
```
## MatchPattern
Enumerates the match patterns supported for component attributes.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ----------- | ---- | -------------- |
| EQUALS | 0 | Equals the given value. |
| CONTAINS | 1 | Contains the given value. |
| STARTS_WITH | 2 | Starts with the given value.|
| ENDS_WITH | 3 | Ends with the given value.|
## ResizeDirection9+
Enumerates the directions in which a window can be resized.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ---------- | ---- | -------- |
| LEFT | 0 | Left. |
| RIGHT | 1 | Right. |
| UP | 2 | Up. |
| DOWN | 3 | Down. |
| LEFT_UP | 4 | Upper left.|
| LEFT_DOWN | 5 | Lower left.|
| RIGHT_UP | 6 | Upper right.|
| RIGHT_DOWN | 7 | Lower right.|
## Point9+
Provides the coordinates of a point.
**System capability**: SystemCapability.Test.UiTest
| Name| Type | Readable| Writable| Description |
| ---- | ------ | ---- | ---- | ---------------- |
| x | number | Yes | No | X-coordinate of a point.|
| y | number | Yes | No | Y-coordinate of a point.|
## Rect9+
Provides bounds information of a component.
**System capability**: SystemCapability.Test.UiTest
| Name | Type | Readable| Writable| Description |
| ------ | ------ | ---- | ---- | ------------------------- |
| left | number | Yes | No | X-coordinate of the upper left corner of the component bounds.|
| top | number | Yes | No | Y-coordinate of the upper left corner of the component bounds.|
| right | number | Yes | No | X-coordinate of the lower right corner of the component bounds.|
| bottom | number | Yes | No | Y-coordinate of the lower right corner of the component bounds.|
## WindowMode9+
Enumerates the window modes.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ---------- | ---- | ---------- |
| FULLSCREEN | 0 | Full-screen mode.|
| PRIMARY | 1 | Primary window mode. |
| SECONDARY | 2 | Secondary window mode.|
| FLOATING | 3 | Floating window mode.|
## DisplayRotation9+
Describes the display rotation of the device.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ------------ | ---- | ---------------------------------------- |
| ROTATION_0 | 0 | The device display is not rotated and is in its original vertical orientation. |
| ROTATION_90 | 1 | The device display rotates 90° clockwise and is in landscape orientation. |
| ROTATION_180 | 2 | The device display rotates 180° clockwise and is in reverse vertical orientation.|
| ROTATION_270 | 3 | The device display rotates 270° clockwise and is in reverse landscape orientation.|
## WindowFilter9+
Provides the flag attributes of this window.
**System capability**: SystemCapability.Test.UiTest
| Name | Type | Readable| Writable| Description |
| ---------- | ------- | ---- | ---- | -------------------------- |
| 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.|
## UiDirection10+
Describes the direction of a UI operation such as fling.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ----- | ---- | ------ |
| LEFT | 0 | Leftward.|
| RIGHT | 1 | Rightward.|
| UP | 2 | Upward.|
| DOWN | 3 | Downward.|
## MouseButton10+
Describes the injected simulated mouse button.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ------------------- | ---- | ------------ |
| MOUSE_BUTTON_LEFT | 0 | Left button on the mouse. |
| MOUSE_BUTTON_RIGHT | 1 | Right button on the mouse. |
| MOUSE_BUTTON_MIDDLE | 2 | Middle button on the mouse.|
## UIElementInfo10+
Provides information about the UI event.
**System capability**: SystemCapability.Test.UiTest
| Name | Type | Readable| Writable| Description |
| ---------- | ------ | ---- | ---- | --------------------- |
| bundleName | string | Yes | No | Bundle name of the home application. |
| type | string | Yes | No | Component or window type. |
| text | string | Yes | No | Text information of the component or window.|
## On9+
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:
- 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.
- Provide multiple match patterns for component attributes.
- 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.
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
ON.text('123').type('button');
```
### text9+
text(txt: string, pattern?: MatchPattern): On
Specifies the text attribute of the target component. Multiple match patterns are supported.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ----------------------------- | ---- | --------------------------------------------------- |
| txt | string | Yes | Component text, used to match the target component. |
| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).|
**Return value**
| Type | Description |
| ---------- | ---------------------------------- |
| [On](#on9) | **On** object that matches the text attribute of the target component.|
**Example**
```js
let on = ON.text('123'); // Use the static constructor ON to create an On object and specify the text attribute of the target component.
```
### id9+
id(id: string): On
Specifies the ID attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------- |
| id | string | Yes | Component ID.|
**Return value**
| Type | Description |
| ---------- | -------------------------------- |
| [On](#on9) | **On** object that matches the ID attribute of the target component.|
**Example**
```js
let on = ON.id('123'); // Use the static constructor ON to create an On object and specify the ID attribute of the target component.
```
### type9+
type(tp: string): On
Specifies the type attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------- |
| tp | string | Yes | Component type.|
**Return value**
| Type | Description |
| ---------- | ---------------------------------------- |
| [On](#on9) | **On** object that matches the type attribute of the target component.|
**Example**
```js
let on = ON.type('button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component.
```
### clickable9+
clickable(b?: boolean): On
Specifies the clickable status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | No | Clickable status of the target component.
**true**: clickable.
**false**: not clickable.
Default value: **true**|
**Return value**
| Type | Description |
| ---------- | ------------------------------------------ |
| [On](#on9) | **On** object that matches the clickable status attribute of the target component.|
**Example**
```js
let on = ON.clickable(true); // Use the static constructor ON to create an On object and specify the clickable status attribute of the target component.
```
### longClickable9+
longClickable(b?: boolean): On
Specifies the long-clickable status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | No | Long-clickable status of the target component.
**true**: long-clickable.
**false**: not long-clickable.
Default value: **true**|
**Return value**
| Type | Description |
| ---------- | ---------------------------------------------- |
| [On](#on9) | **On** object that matches the long-clickable status attribute of the target component.|
**Example**
```js
let 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.
```
### scrollable9+
scrollable(b?: boolean): On
Specifies the scrollable status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ----------------------------------------------------------- |
| b | boolean | No | Scrollable status of the target component.
**true**: scrollable.
**false**: not scrollable.
Default value: **true**|
**Return value**
| Type | Description |
| ---------- | ------------------------------------------ |
| [On](#on9) | **On** object that matches the scrollable status attribute of the target component.|
**Example**
```js
let on = ON.scrollable(true); // Use the static constructor ON to create an On object and specify the scrollable status attribute of the target component.
```
### enabled9+
enabled(b?: boolean): On
Specifies the enabled status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | --------------------------------------------------------- |
| b | boolean | No | Enabled status of the target component.
**true**: enabled.
**false**: not enabled.
Default value: **true**|
**Return value**
| Type | Description |
| ---------- | ---------------------------------------- |
| [On](#on9) | **On** object that matches the enabled status attribute of the target component.|
**Example**
```js
let on = ON.enabled(true); // Use the static constructor ON to create an On object and specify the enabled status attribute of the target component.
```
### focused9+
focused(b?: boolean): On
Specifies the focused status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ----------------------------------------------------- |
| b | boolean | No | Focused status of the target component.
**true**: focused.
**false**: not focused.
Default value: **true**|
**Return value**
| Type | Description |
| ---------- | ---------------------------------------- |
| [On](#on9) | **On** object that matches the focused status attribute of the target component.|
**Example**
```js
let on = ON.focused(true); // Use the static constructor ON to create an On object and specify the focused status attribute of the target component.
```
### selected9+
selected(b?: boolean): On
Specifies the selected status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | No | Selected status of the target component.
**true**: selected.
**false**: not selected.
Default value: **true**|
**Return value**
| Type | Description |
| ---------- | ------------------------------------------ |
| [On](#on9) | **On** object that matches the selected status attribute of the target component.|
**Example**
```js
let on = ON.selected(true); // Use the static constructor ON to create an On object and specify the selected status attribute of the target component.
```
### checked9+
checked(b?: boolean): On
Specifies the checked status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | No | Checked status of the target component.
**true**: checked.
**false**: not checked.
Default value: **false**|
**Return value**
| Type | Description |
| ---------- | ------------------------------------------ |
| [On](#on9) | **On** object that matches the checked status attribute of the target component.|
**Example**
```js
let on = ON.checked(true); // Use the static constructor ON to create an On object and specify the checked status attribute of the target component.
```
### checkable9+
checkable(b?: boolean): On
Specifies the checkable status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | No | Checkable status of the target component.
**true**: checkable.
**false**: not checkable.
Default value: **false**|
**Return value**
| Type | Description |
| ---------- | -------------------------------------------- |
| [On](#on9) | **On** object that matches the checkable status attribute of the target component.|
**Example**
```js
let on = ON.checkable(true); // Use the static constructor ON to create an On object and specify the checkable status attribute of the target component.
```
### isBefore9+
isBefore(on: On): On
Specifies that the target component is located before the given attribute component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | Yes | Information about the attribute component.|
**Return value**
| Type | Description |
| ---------- | ---------------------------------------------------- |
| [On](#on9) | **On** object.|
**Example**
```js
let 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.
```
### isAfter9+
isAfter(on: On): On
Specifies that the target component is located after the given attribute component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | Yes | Information about the attribute component.|
**Return value**
| Type | Description |
| ---------- | ---------------------------------------------------- |
| [On](#on9) | **On** object.|
**Example**
```js
let 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.
```
### within10+
within(on: On): On
Specifies that the target component is located within the given attribute component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | Yes | Information about the attribute component.|
**Return value**
| Type | Description |
| ---------- | -------------------------------------------------- |
| [On](#on9) | **On** object.|
**Example**
```js
let 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.
```
### inWindow10+
inWindow(bundleName: string): On;
Specifies that the target component is located within the given application window.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------ | ---- | ---------------- |
| bundleName | string | Yes | Bundle name of the application window.|
**Return value**
| Type | Description |
| ---------- | ---------------------------------------------- |
| [On](#on9) | **On** object.|
**Example**
```js
let 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.
```
## 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.
All APIs provided in this class use a promise to return the result and must be invoked using **await**.
### click9+
click(): Promise\
Clicks this component.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
await button.click();
}
```
### doubleClick9+
doubleClick(): Promise\
Double-clicks this component.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
await button.doubleClick();
}
```
### longClick9+
longClick(): Promise\
Long-clicks this component.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
await button.longClick();
}
```
### getId9+
getId(): Promise\
Obtains the ID of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ------------------------------- |
| Promise\ | Promise used to return the ID of the component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
let num = await button.getId();
}
```
### getText9+
getText(): Promise\
Obtains the text information of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | --------------------------------- |
| Promise\ | Promise used to return the text information of the component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
let text = await button.getText();
}
```
### getType9+
getType(): Promise\
Obtains the type of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ----------------------------- |
| Promise\ | Promise used to return the type of the component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
let type = await button.getType();
}
```
### getBounds9+
getBounds(): Promise\
Obtains the bounds of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ------------------------ | ------------------------------------- |
| Promise\<[Rect](#rect9)> | Promise used to return the bounds of the component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
let rect = await button.getBounds();
}
```
### getBoundsCenter9+
getBoundsCenter(): Promise\
Obtains the information about the center of the bounding box around this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------------------- | ----------------------------------------------- |
| Promise\<[Point](#point9)> | Promise used to return the information about the center of the bounding box around the component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
let point = await button.getBoundsCenter();
}
```
### isClickable9+
isClickable(): Promise\
Obtains the clickable status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | Promise used to return the result. The value **true** means that the component is clickable, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
if(await button.isClickable()) {
console.info('This button can be Clicked');
} else {
console.info('This button can not be Clicked');
}
}
```
### isLongClickable9+
isLongClickable(): Promise\
Obtains the long-clickable status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
if(await button.isLongClickable()) {
console.info('This button can longClick');
} else {
console.info('This button can not longClick');
}
}
```
### isChecked9+
isChecked(): Promise\
Obtains the checked status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let checkBox = await driver.findComponent(ON.type('Checkbox'));
if(await checkBox.isChecked()) {
console.info('This checkBox is checked');
} else {
console.info('This checkBox is not checked');
}
}
```
### isCheckable9+
isCheckable(): Promise\
Obtains the checkable status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let checkBox = await driver.findComponent(ON.type('Checkbox'));
if(await checkBox.isCheckable()) {
console.info('This checkBox is checkable');
} else {
console.info('This checkBox is not checkable');
}
}
```
### isScrollable9+
isScrollable(): Promise\
Obtains the scrollable status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | Promise used to return the result. The value **true** means that the component is scrollable, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let scrollBar = await driver.findComponent(ON.scrollable(true));
if(await scrollBar.isScrollable()) {
console.info('This scrollBar can be operated');
} else {
console.info('This scrollBar can not be operated');
}
}
```
### isEnabled9+
isEnabled(): Promise\
Obtains the enabled status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ---------------------------------------------------------- |
| Promise\ | Promise used to return the result. The value **true** means that the component is enabled, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
if(await button.isEnabled()) {
console.info('This button can be operated');
} else {
console.info('This button can not be operated');
}
}
```
### isFocused9+
isFocused(): Promise\
Obtains the focused status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
if(await button.isFocused()) {
console.info('This button is focused');
} else {
console.info('This button is not focused');
}
}
```
### isSelected9+
isSelected(): Promise\
Obtains the selected status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | --------------------------------------------------- |
| Promise\ | Promise used to return the result. The value **true** means that the component is selected, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
if(await button.isSelected()) {
console.info('This button is selected');
} else {
console.info('This button is not selected');
}
}
```
### inputText9+
inputText(text: string): Promise\
Enters text into this component (available for text boxes).
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------------------------------- |
| text | string | Yes | Text to enter, which can contain English and special characters.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let text = await driver.findComponent(ON.text('hello world'));
await text.inputText('123');
}
```
### clearText9+
clearText(): Promise\
Clears text in this component. This API is applicable to text boxes.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let text = await driver.findComponent(ON.text('hello world'));
await text.clearText();
}
```
### scrollSearch9+
scrollSearch(on: On): Promise\
Scrolls on this component to search for the target component. This API is applicable to components that support scrolling.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | Yes | Attributes of the target component.|
**Return value**
| Type | Description |
| ---------------------------------- | ------------------------------------- |
| Promise\<[Component](#component9)> | Promise used to return the target component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let scrollBar = await driver.findComponent(ON.type('Scroll'));
let button = await scrollBar.scrollSearch(ON.text('next page'));
}
```
### scrollToTop9+
scrollToTop(speed?: number): Promise\
Scrolls to the top of this component. This API is applicable to components that support scrolling.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let scrollBar = await driver.findComponent(ON.type('Scroll'));
await scrollBar.scrollToTop();
}
```
### scrollToBottom9+
scrollToBottom(speed?: number): Promise\
Scrolls to the bottom of this component. This API is applicable to components that support scrolling.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let scrollBar = await driver.findComponent(ON.type('Scroll'));
await scrollBar.scrollToBottom();
}
```
### dragTo9+
dragTo(target: Component): Promise\
Drags this component to the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------ | ---- | ---------- |
| target | [Component](#component9) | Yes | Target component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.type('button'));
let text = await driver.findComponent(ON.text('hello world'));
await button.dragTo(text);
}
```
### pinchOut9+
pinchOut(scale: number): Promise\
Pinches a component to scale it up to the specified ratio.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------- |
| scale | number | Yes | Scale factor.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let image = await driver.findComponent(ON.type('image'));
await image.pinchOut(1.5);
}
```
### pinchIn9+
pinchIn(scale: number): Promise\
Pinches a component to scale it down to the specified ratio.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------- |
| scale | number | Yes | Scale factor.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the component is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let image = await driver.findComponent(ON.type('image'));
await image.pinchIn(0.5);
}
```
## Driver9+
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**.
### create9+
static create(): Driver
Creates a **Driver** object and returns the object created. This API is a static API.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type| Description |
| -------- | ---------------------- |
| Driver | **Driver** object created.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ------------------ |
| 17000001 | if the test framework failed to initialize. |
**Example**
```js
async function demo() {
let driver = Driver.create();
}
```
### delayMs9+
delayMs(duration: number): Promise\
Delays this **Driver** object within the specified duration.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ---------------------- |
| duration | number | Yes | Duration of time, in ms.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.delayMs(1000);
}
```
### findComponent9+
findComponent(on: On): Promise\
Searches this **Driver** object for the target component that matches the given attributes.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | Yes | Attributes of the target component.|
**Return value**
| Type | Description |
| ---------------------------------- | --------------------------------- |
| Promise\<[Component](#component9)> | Promise used to return the found component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.findComponent(ON.text('next page'));
}
```
### findComponents9+
findComponents(on: On): Promise\>
Searches this **Driver** object for all components that match the given attributes.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | Yes | Attributes of the target component.|
**Return value**
| Type | Description |
| ------------------------------------------ | --------------------------------------- |
| Promise\> | Promise used to return a list of found components.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let buttonList = await driver.findComponents(ON.text('next page'));
}
```
### findWindow9+
findWindow(filter: WindowFilter): Promise\
Searches for the window that matches the specified attributes.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------ | ---- | ---------------- |
| filter | [WindowFilter](#windowfilter9) | Yes | Attributes of the target window.|
**Return value**
| Type | Description |
| -------------------------------- | ------------------------------------- |
| Promise\<[UiWindow](#uiwindow9)> | Promise used to return the target window.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
}
```
### waitForComponent9+
waitForComponent(on: On, time: number): Promise\
Searches this **Driver** object for the target component that matches the given attributes within the specified duration.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- | ---- | -------------------------------- |
| On | [On](#on9) | Yes | Attributes of the target component. |
| time | number | Yes | Duration for searching for the target component, in ms.|
**Return value**
| Type | Description |
| --------------------------------- | --------------------------------- |
| Promise\<[Component](#component9)> | Promise used to return the found component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let button = await driver.waitForComponent(ON.text('next page'),500);
}
```
### assertComponentExist9+
assertComponentExist(on: On): Promise\
Asserts that a component that matches the given attributes exists on the current page.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | Yes | Attributes of the target component.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000003 | if the assertion failed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.assertComponentExist(ON.text('next page'));
}
```
### pressBack9+
pressBack(): Promise\
Presses the Back button on this **Driver** object.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.pressBack();
}
```
### triggerKey9+
triggerKey(keyCode: number): Promise\
Triggers the key of this **Driver** object that matches the given key code.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ------------- |
| keyCode | number | Yes | Key code.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.triggerKey(123);
}
```
### triggerCombineKeys9+
triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\
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**.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------- |
| key0 | number | Yes | The first key value.|
| key1 | number | Yes | The second key value.|
| key2 | number | No | The third key value.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.triggerCombineKeys(2072, 2047, 2035);
}
```
### click9+
click(x: number, y: number): Promise\
Clicks a specific point of this **Driver** object based on the given coordinates.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X-coordinate of the target point.|
| y | number | Yes | Y-coordinate of the target point.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.click(100,100);
}
```
### doubleClick9+
doubleClick(x: number, y: number): Promise\
Double-clicks a specific point of this **Driver** object based on the given coordinates.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X-coordinate of the target point.|
| y | number | Yes | Y-coordinate of the target point.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.doubleClick(100,100);
}
```
### longClick9+
longClick(x: number, y: number): Promise\
Long-clicks a specific point of this **Driver** object based on the given coordinates.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X-coordinate of the target point.|
| y | number | Yes | Y-coordinate of the target point.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.longClick(100,100);
}
```
### swipe9+
swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\
Swipes on this **Driver** object from the given start point to the given end point.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.swipe(100,100,200,200,600);
}
```
### drag9+
drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\
Drags this **Driver** object from the given start point to the given end point.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.drag(100,100,200,200,600);
}
```
### screenCap9+
screenCap(savePath: string): Promise\
Captures the current screen of this **Driver** object and saves it as a PNG image to the given save path.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | -------------- |
| savePath | string | Yes | File save path.|
**Return value**
| Type | Description |
| ----------------- | -------------------------------------- |
| Promise\ | Promise used to return the operation result. The value **true** means that the operation is successful.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.screenCap('/data/storage/el2/base/cache/1.png');
}
```
### setDisplayRotation9+
setDisplayRotation(rotation: DisplayRotation): Promise\
Sets the display rotation of the device.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------ | ---- | ---------------- |
| rotation | [DisplayRotation](#displayrotation9) | Yes | Display rotation of the device.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.setDisplayRotation(DisplayRotation.ROTATION_180);
}
```
### getDisplayRotation9+
getDisplayRotation(): Promise\
Obtains the display rotation of the current device.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------------------------------------- | --------------------------------------- |
| Promise\<[DisplayRotation](#displayrotation9)> | Promise used to return the display rotation of the current device.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let rotation = await driver.getDisplayRotation();
}
```
### setDisplayRotationEnabled9+
setDisplayRotationEnabled(enabled: boolean): Promise\
Enables or disables display rotation.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------- | ---- | ------------------------------------------------------- |
| 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.setDisplayRotationEnabled(false);
}
```
### getDisplaySize9+
getDisplaySize(): Promise\
Obtains the display size of the current device.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------------------- | --------------------------------------- |
| Promise\<[Point](#point9)> | Promise used to return the display size of the current device.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let size = await driver.getDisplaySize();
}
```
### getDisplayDensity9+
getDisplayDensity(): Promise\
Obtains the display density of the current device.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------------------- | ----------------------------------------- |
| Promise\<[Point](#point9)> | Promise used to return the display density of the current device.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let density = await driver.getDisplayDensity();
}
```
### wakeUpDisplay9+
wakeUpDisplay(): Promise\
Wakes up the device display.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.wakeUpDisplay();
}
```
### pressHome9+
pressHome(): Promise\
Returns to the home screen.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.pressHome();
}
```
### waitForIdle9+
waitForIdle(idleTime: number, timeout: number): Promise\
Checks whether all components on the current page are idle.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| 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. |
**Return value**
| Type | Description |
| ----------------- | --------------------------------------------------- |
| Promise\ | Promise used to return the result.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let idled = await driver.waitForIdle(4000,5000);
}
```
### fling9+
fling(from: Point, to: Point, stepLen: number, speed: number): Promise\
Simulates a fling operation on the screen.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ---------------- | ---- | ------------------------------------------------------------ |
| 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 | 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.fling({x: 500, y: 480},{x: 450, y: 480},5,600);
}
```
### injectMultiPointerAction9+
injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\
Injects a multi-touch operation to the device.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------- | ---- | ------------------------------------------------------------ |
| 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.|
**Return value**
| Type | Description |
| ----------------- | ------------------------------------- |
| Promise\ | Promise used to return the result.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let pointers = 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});
await driver.injectMultiPointerAction(pointers);
}
```
### fling10+
fling(direction: UiDirection, speed: number): Promise\;
Simulates a fling operation on the screen, in the specified direction and speed.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ----------------------------- | ---- | ------------------------------------------------------------ |
| direction | [UiDirection](#uidirection10) | Yes | Direction of the fling operation. |
| 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.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.fling(UiDirection.DOWN, 10000);
}
```
### screenCapture10+
screenCapture(savePath: string, rect?: Rect): Promise\;
Captures the specified area of the current screen and saves the captured screenshot as a PNG image to the specified path.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------- | ---- | ---------------------- |
| savePath | string | Yes | File save path. |
| rect | [Rect](#rect9) | No | Area of the screen to capture. The default value is the entire screen.|
**Return value**
| Type | Description |
| ----------------- | -------------------------------------- |
| Promise\ | Promise used to return the operation result. The value **true** means that the operation is successful.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.screenCapture('/data/storage/el2/base/cache/1.png', {left: 0, top: 0, right: 100, bottom: 100});
}
```
### mouseClick10+
mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\;
Injects 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.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------------------------- | ---- | ------------------- |
| p | [Point](#point9) | Yes | Coordinates of the mouse click. |
| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressed. |
| key1 | number | No | The first key value.|
| key2 | number | No | The second key value.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.mouseClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072);
}
```
### mouseScroll10+
mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): Promise\;
Injects 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.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------------- | ---- | --------------------------------------------------- |
| p | [Point](#point9) | Yes | Coordinates of the mouse click. |
| down | boolean | Yes | Whether the scroll wheel slides downward. |
| 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.|
| key1 | number | No | The first key value. |
| key2 | number | No | The second key value. |
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.mouseScroll({x:360, y:640}, true, 30, 2072)
}
```
### mouseMoveTo10+
mouseMoveTo(p: Point): Promise\;
Moves the cursor to the target point.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------------- | ---- | -------------- |
| p | [Point](#point9) | Yes | Coordinates of the target point.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
await driver.mouseMoveTo({x:100, y:100})
}
```
### createUIEventObserver10+
createUIEventObserver(): UIEventObserver;
Creates a UI event listener.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------------------------------------- | ------------------------------------- |
| Promise\<[UIEventObserver](#uieventobserver10)> | Promise used to return the target window.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let observer = await driver.createUIEventObserver()
}
```
## PointerMatrix9+
Implements a **PointerMatrix** object that stores coordinates and behaviors of each action of each finger in a multi-touch operation.
### create9+
static create(fingers: number, steps: number): PointerMatrix
Creates a **PointerMatrix** object and returns the object created. This API is a static API.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ------------------------------------------ |
| fingers | number | Yes | Number of fingers in the multi-touch operation. Value range: [1,10].|
| steps | number | Yes | Number of steps operated by each finger. Value range: [1,1000].|
**Return value**
| Type | Description |
| -------------------------------- | ----------------------------- |
| [PointerMatrix](#pointermatrix9) | **PointerMatrix** object created.|
**Example**
```js
async function demo() {
let pointerMatrix = PointerMatrix.create(2,3);
}
```
### setPoint9+
setPoint(finger: number, step: number, point: Point): void
Sets the coordinates for the action corresponding to the specified finger and step in the **PointerMatrix** object.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------------- | ---- | ---------------- |
| 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
async function demo() {
let pointers = 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});
}
```
## UiWindow9+
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**.
### getBundleName9+
getBundleName(): Promise\
Obtains the bundle name of the application to which this window belongs.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ----------------------------------------- |
| Promise\ | Promise used to return the bundle name.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
let name = await window.getBundleName();
}
```
### getBounds9+
getBounds(): Promise\
Obtains the bounds information of this window.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ------------------------ | --------------------------------- |
| Promise\<[Rect](#rect9)> | Promise used to return the bounds information of the window.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
let rect = await window.getBounds();
}
```
### getTitle9+
getTitle(): Promise\
Obtains the title of this window.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | --------------------------------- |
| Promise\ | Promise used to return the title of the window.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
let rect = await window.getTitle();
}
```
### getWindowMode9+
getWindowMode(): Promise\
Obtains the window mode of this window.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ------------------------------------ | ------------------------------------- |
| Promise\<[WindowMode](#windowmode9)> | Promise used to return the window mode of the window.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
let mode = await window.getWindowMode();
}
```
### isFocused9+
isFocused(): Promise\
Checks whether this window is in focused state.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 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).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
let focused = await window.isFocused();
}
```
### isActived9+
isActived(): Promise\
Checks whether this window is active.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | Promise used to return the result. The value **true** means that the window is active, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
let focused = await window.isActived();
}
```
### focus9+
focus(): Promise\
Moves the focus to this window.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
await window.focus();
}
```
### moveTo9+
moveTo(x: number, y: number): Promise\
Moves this window to the target point. This API is applicable to moveable windows.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X-coordinate of the target point.|
| y | number | Yes | Y-coordinate of the target point.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
| 17000005 | if the action is not supported on this window. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
await window.moveTo(100, 100);
}
```
### resize9+
resize(wide: number, height: number, direction: ResizeDirection): Promise\
Resizes this window based on the specified width, height, and resize direction. This API is applicable to resizable windows.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
| wide | number | Yes | Target width. |
| height | number | Yes | Target height. |
| direction | [ResizeDirection](#resizedirection9) | Yes | Resize direction.|
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
| 17000005 | if the action is not supported on this window. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
await window.resize(100, 100, ResizeDirection.LEFT);
}
```
### split9+
split(): Promise\
Switches the window to split-screen mode. This API is applicable to windows that support screen splitting.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
| 17000005 | if the action is not supported on this window. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
await window.split();
}
```
### maximize9+
maximize(): Promise\
Maximizes this window. This API is applicable to windows that can be maximized.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
| 17000005 | if the action is not supported on this window. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
await window.maximize();
}
```
### minimize9+
minimize(): Promise\
Minimizes this window. This API is applicable to windows that can be minimized.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
| 17000005 | if the action is not supported on this window. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
await window.minimize();
}
```
### resume9+
resume(): Promise\
Restores this window to the previous window mode.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
| 17000005 | if the action is not supported on this window. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
await window.resume();
}
```
### close9+
close(): Promise\
Closes this window.
**System capability**: SystemCapability.Test.UiTest
**Error codes**
For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md).
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17000002 | if the async function was not called with await. |
| 17000004 | if the window is invisible or destroyed. |
| 17000005 | if the action is not supported on this window. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let window = await driver.findWindow({actived: true});
await window.close();
}
```
## UIEventObserver10+
Implements a UI event listener.
### once('toastShow')
once(type: 'toastShow', callback: Callback\):void;
Subscribes to events of the toast component. This API uses a callback to return the result.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------- | ---- | --------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'toastShow'**.|
| callback | Callback\<[UIElementInfo](#uielementinfo10)> | Yes | Callback used to return the result. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let observer = await driver.createUIEventObserver()
let callback = (UIElementInfo)=>{
console.info(UIElementInfo.bundleName)
console.info(UIElementInfo.text)
console.info(UIElementInfo.type)
}
observer.once('toastShow', callback)
}
```
### once('dialogShow')
once(type: 'dialogShow', callback: Callback\): void;
Subscribes to events of the dialog component. This API uses a callback to return the result.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------- | ---- | ---------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'dialogShow'**.|
| callback | Callback\<[UIElementInfo](#uielementinfo10)> | Yes | Callback used to return the result. |
**Example**
```js
async function demo() {
let driver = Driver.create();
let observer = await driver.createUIEventObserver()
let callback = (UIElementInfo)=>{
console.info(UIElementInfo.bundleName)
console.info(UIElementInfo.text)
console.info(UIElementInfo.type)
}
observer.once('dialogShow', callback)
}
```
## By(deprecated)
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:
- 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.
- Provide multiple match patterns for component attributes.
- Support absolute positioning and relative positioning for components. APIs such as [By.isBefore(deprecated)](#isbeforedeprecated) and [By.isAfter(deprecated)](#isafterdeprecated) can be used to specify the features of adjacent components to assist positioning.
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 class is deprecated since API version 9. You are advised to use [On9+](#on9) instead.
```js
BY.text('123').type('button');
```
### text(deprecated)
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 [text9+](#text9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ----------------------------- | ---- | --------------------------------------------------- |
| txt | string | Yes | Component text, used to match the target component. |
| pattern | [MatchPattern](#matchpattern) | No | Match pattern. The default value is [EQUALS](#matchpattern).|
**Return value**
| Type | Description |
| ------------------- | ---------------------------------- |
| [By](#bydeprecated) | **By** object that matches the text attribute of the target component.|
**Example**
```js
let by = BY.text('123'); // Use the static constructor BY to create a By object and specify the text attribute of the target component.
```
### key(deprecated)
key(key: string): By
Specifies the key attribute of the target component.
This API is deprecated since API version 9. You are advised to use [id9+](#id9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ----------------- |
| key | string | Yes | Component key.|
**Return value**
| Type | Description |
| ------------------- | ----------------------------------- |
| [By](#bydeprecated) | **By** object that matches the key attribute of the target component.|
**Example**
```js
let by = BY.key('123'); // Use the static constructor BY to create a By object and specify the key attribute of the target component.
```
### id(deprecated)
id(id: number): By
Specifies the ID attribute of the target component.
This API is deprecated since API version 9.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------- |
| id | number | Yes | Component ID.|
**Return value**
| Type | Description |
| ------------------- | -------------------------------- |
| [By](#bydeprecated) | **By** object that matches the ID attribute of the target component.|
**Example**
```js
let by = BY.id(123); // Use the static constructor BY to create a By object and specify the ID attribute of the target component.
```
### type(deprecated)
type(tp: string): By
Specifies the type attribute of the target component.
This API is deprecated since API version 9. You are advised to use [type9+](#type9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------- |
| tp | string | Yes | Component type.|
**Return value**
| Type | Description |
| ------------------- | ---------------------------------------- |
| [By](#bydeprecated) | **By** object that matches the type attribute of the target component.|
**Example**
```js
let by = BY.type('button'); // Use the static constructor BY to create a By object and specify the type attribute of the target component.
```
### clickable(deprecated)
clickable(b?: boolean): By
Specifies the clickable status attribute of the target component.
This API is deprecated since API version 9. You are advised to use [clickable9+](#clickable9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | No | Clickable status of the target component.
**true**: clickable.
**false**: not clickable.
Default value: **true**|
**Return value**
| Type | Description |
| ------------------- | ------------------------------------------ |
| [By](#bydeprecated) | **By** object that matches the clickable status attribute of the target component.|
**Example**
```js
let by = BY.clickable(true); // Use the static constructor BY to create a By object and specify the clickable status attribute of the target component.
```
### scrollable(deprecated)
scrollable(b?: boolean): By
Specifies the scrollable status attribute of the target component.
This API is deprecated since API version 9. You are advised to use [scrollable9+](#scrollable9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ----------------------------------------------------------- |
| b | boolean | No | Scrollable status of the target component.
**true**: scrollable.
**false**: not scrollable.
Default value: **true**|
**Return value**
| Type | Description |
| ------------------- | ------------------------------------------ |
| [By](#bydeprecated) | **By** object that matches the scrollable status attribute of the target component.|
**Example**
```js
let by = BY.scrollable(true); // Use the static constructor BY to create a By object and specify the scrollable status attribute of the target component.
```
### enabled(deprecated)
enabled(b?: boolean): By
Specifies the enabled status attribute of the target component.
This API is deprecated since API version 9. You are advised to use [enabled9+](#enabled9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | --------------------------------------------------------- |
| b | boolean | No | Enabled status of the target component.
**true**: enabled.
**false**: not enabled.
Default value: **true**|
**Return value**
| Type | Description |
| ------------------- | ---------------------------------------- |
| [By](#bydeprecated) | **By** object that matches the enabled status attribute of the target component.|
**Example**
```js
let by = BY.enabled(true); // Use the static constructor BY to create a By object and specify the enabled status attribute of the target component.
```
### focused(deprecated)
focused(b?: boolean): By
Specifies the focused status attribute of the target component.
This API is deprecated since API version 9. You are advised to use [focused9+](#focused9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ----------------------------------------------------- |
| b | boolean | No | Focused status of the target component.
**true**: focused.
**false**: not focused.
Default value: **true**|
**Return value**
| Type | Description |
| ------------------- | ---------------------------------------- |
| [By](#bydeprecated) | **By** object that matches the focused status attribute of the target component.|
**Example**
```js
let by = BY.focused(true); // Use the static constructor BY to create a By object and specify the focused status attribute of the target component.
```
### selected(deprecated)
selected(b?: boolean): By
Specifies the selected status of the target component.
This API is deprecated since API version 9. You are advised to use [selected9+](#selected9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | No | Selected status of the target component.
**true**: selected.
**false**: not selected.
Default value: **true**|
**Return value**
| Type | Description |
| ------------------- | ------------------------------------------ |
| [By](#bydeprecated) | **By** object that matches the selected status attribute of the target component.|
**Example**
```js
let by = BY.selected(true); // Use the static constructor BY to create a By object and specify the selected status attribute of the target component.
```
### isBefore(deprecated)
isBefore(by: By): By
Specifies that the target component is located before the given attribute component.
This API is deprecated since API version 9. You are advised to use [isBefore9+](#isbefore9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------- | ---- | ---------------- |
| by | [By](#bydeprecated) | Yes | Information about the attribute component.|
**Return value**
| Type | Description |
| ------------------- | ---------------------------------------------------- |
| [By](#bydeprecated) | **By** object.|
**Example**
```js
let 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.
```
### isAfter(deprecated)
isAfter(by: By): By
Specifies that the target component is located after the given attribute component.
This API is deprecated since API version 9. You are advised to use [isAfter9+](#isafter9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------- | ---- | ---------------- |
| by | [By](#bydeprecated) | Yes | Information about the attribute component.|
**Return value**
| Type | Description |
| ------------------- | ---------------------------------------------------- |
| [By](#bydeprecated) | **By** object.|
**Example**
```js
let 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.
```
## UiComponent(deprecated)
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 class is deprecated since API version 9. You are advised to use [Component9+](#component9) instead.
### click(deprecated)
click(): Promise\
Clicks this component.
This API is deprecated since API version 9. You are advised to use [click9+](#click9) instead.
**System capability**: SystemCapability.Test.UiTest
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
await button.click();
}
```
### doubleClick(deprecated)
doubleClick(): Promise\
Double-clicks this component.
This API is deprecated since API version 9. You are advised to use [doubleClick9+](#doubleclick9) instead.
**System capability**: SystemCapability.Test.UiTest
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
await button.doubleClick();
}
```
### longClick(deprecated)
longClick(): Promise\
Long-clicks this component.
This API is deprecated since API version 9. You are advised to use [longClick9+](#longclick9) instead.
**System capability**: SystemCapability.Test.UiTest
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
await button.longClick();
}
```
### getId(deprecated)
getId(): Promise\
Obtains the ID of this component.
This API is deprecated since API version 9.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ------------------------------- |
| Promise\ | Promise used to return the ID of the component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
let num = await button.getId();
}
```
### getKey(deprecated)
getKey(): Promise\
Obtains the key of this component.
This API is deprecated since API version 9. You are advised to use [getId9+](#getid9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ------------------------------ |
| Promise\ | Promise used to return the key of the component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
let str_key = await button.getKey();
}
```
### getText(deprecated)
getText(): Promise\
Obtains the text information of this component.
This API is deprecated since API version 9. You are advised to use [getText9+](#gettext9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | --------------------------------- |
| Promise\ | Promise used to return the text information of the component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
let text = await button.getText();
}
```
### getType(deprecated)
getType(): Promise\
Obtains the type of this component.
This API is deprecated since API version 9. You are advised to use [getType9+](#gettype9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ----------------------------- |
| Promise\ | Promise used to return the type of the component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
let type = await button.getType();
}
```
### isClickable(deprecated)
isClickable(): Promise\
Obtains the clickable status of this component.
This API is deprecated since API version 9. You are advised to use [isClickable9+](#isclickable9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | Promise used to return the result. The value **true** means that the component is clickable, and **false** means the opposite.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
if(await button.isClickable()) {
console.info('This button can be Clicked');
} else {
console.info('This button can not be Clicked');
}
}
```
### isScrollable(deprecated)
isScrollable(): Promise\
Obtains the scrollable status of this component.
This API is deprecated since API version 9. You are advised to use [isScrollable9+](#isscrollable9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | Promise used to return the result. The value **true** means that the component is scrollable, and **false** means the opposite.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let scrollBar = await driver.findComponent(BY.scrollable(true));
if(await scrollBar.isScrollable()) {
console.info('This scrollBar can be operated');
} else {
console.info('This scrollBar can not be operated');
}
}
```
### isEnabled(deprecated)
isEnabled(): Promise\
Obtains the enabled status of this component.
This API is deprecated since API version 9. You are advised to use [isEnabled9+](#isenabled9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ---------------------------------------------------------- |
| Promise\ | Promise used to return the result. The value **true** means that the component is enabled, and **false** means the opposite.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
if(await button.isEnabled()) {
console.info('This button can be operated');
} else {
console.info('This button can not be operated');
}
}
```
### isFocused(deprecated)
isFocused(): Promise\
Obtains the focused status of this component.
This API is deprecated since API version 9. You are advised to use [isFocused9+](#isfocused9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | Promise used to return the result. The value **true** means that the target component is focused, and **false** means the opposite.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
if(await button.isFocused()) {
console.info('This button is focused');
} else {
console.info('This button is not focused');
}
}
```
### isSelected(deprecated)
isSelected(): Promise\
Obtains the selected status of this component.
This API is deprecated since API version 9. You are advised to use [isSelected9+](#isselected9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ----------------- | ----------------------------------------------------- |
| Promise\ | Promise used to return the result. The value **true** means that the component is selected, and **false** means the opposite.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.type('button'));
if(await button.isSelected()) {
console.info('This button is selected');
} else {
console.info('This button is not selected');
}
}
```
### inputText(deprecated)
inputText(text: string): Promise\
Enters text into this component (available for text boxes).
This API is deprecated since API version 9. You are advised to use [inputText9+](#inputtext9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------- |
| text | string | Yes | Text to enter.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let text = await driver.findComponent(BY.text('hello world'));
await text.inputText('123');
}
```
### scrollSearch(deprecated)
scrollSearch(by: By): Promise\
Scrolls on this component to search for the target component (applicable to components that support scrolling, such as **\**).
This API is deprecated since API version 9. You are advised to use [scrollSearch9+](#scrollsearch9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------- | ---- | -------------------- |
| by | [By](#bydeprecated) | Yes | Attributes of the target component.|
**Return value**
| Type | Description |
| ----------------------------------------------- | ------------------------------------- |
| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise used to return the target component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let scrollBar = await driver.findComponent(BY.type('Scroll'));
let button = await scrollBar.scrollSearch(BY.text('next page'));
}
```
## UiDriver(deprecated)
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 class is deprecated since API version 9. You are advised to use [Driver9+](#driver9) instead.
### create(deprecated)
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 [create9+](#create9) instead.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------- | ------------------------ |
| UiDriver | Returns the **UiDriver** object created.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
}
```
### delayMs(deprecated)
delayMs(duration: number): Promise\
Delays this **UiDriver** object within the specified duration.
This API is deprecated since API version 9. You are advised to use [delayMs9+](#delayms9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------ |
| duration | number | Yes | Duration of time.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.delayMs(1000);
}
```
### findComponent(deprecated)
findComponent(by: By): Promise\
Searches this **UiDriver** object for the target component that matches the given attributes.
This API is deprecated since API version 9. You are advised to use [findComponent9+](#findcomponent9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------- | ---- | -------------------- |
| by | [By](#bydeprecated) | Yes | Attributes of the target component.|
**Return value**
| Type | Description |
| ----------------------------------------------- | --------------------------------- |
| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise used to return the found component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let button = await driver.findComponent(BY.text('next page'));
}
```
### findComponents(deprecated)
findComponents(by: By): Promise\>
Searches this **UiDriver** object for all components that match the given attributes.
This API is deprecated since API version 9. You are advised to use [findComponents9+](#findcomponents9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------- | ---- | -------------------- |
| by | [By](#bydeprecated) | Yes | Attributes of the target component.|
**Return value**
| Type | Description |
| ------------------------------------------------------- | --------------------------------------- |
| Promise\> | Promise used to return a list of found components.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
let buttonList = await driver.findComponents(BY.text('next page'));
}
```
### assertComponentExist(deprecated)
assertComponentExist(by: By): Promise\
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 [assertComponentExist9+](#assertcomponentexist9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------- | ---- | -------------------- |
| by | [By](#bydeprecated) | Yes | Attributes of the target component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.assertComponentExist(BY.text('next page'));
}
```
### pressBack(deprecated)
pressBack(): Promise\
Presses the Back button on this **UiDriver** object.
This API is deprecated since API version 9. You are advised to use [pressBack9+](#pressback9) instead.
**System capability**: SystemCapability.Test.UiTest
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.pressBack();
}
```
### triggerKey(deprecated)
triggerKey(keyCode: number): Promise\
Triggers the key of this **UiDriver** object that matches the given key code.
This API is deprecated since API version 9. You are advised to use [triggerKey9+](#triggerkey9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ------------- |
| keyCode | number | Yes | Key code.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.triggerKey(123);
}
```
### click(deprecated)
click(x: number, y: number): Promise\
Clicks a specific point of this **UiDriver** object based on the given coordinates.
This API is deprecated since API version 9. You are advised to use [click9+](#click9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X-coordinate of the target point.|
| y | number | Yes | Y-coordinate of the target point.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.click(100,100);
}
```
### doubleClick(deprecated)
doubleClick(x: number, y: number): Promise\
Double-clicks a specific point of this **UiDriver** object based on the given coordinates.
This API is deprecated since API version 9. You are advised to use [doubleClick9+](#doubleclick9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X-coordinate of the target point.|
| y | number | Yes | Y-coordinate of the target point.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.doubleClick(100,100);
}
```
### longClick(deprecated)
longClick(x: number, y: number): Promise\
Long-clicks a specific point of this **UiDriver** object based on the given coordinates.
This API is deprecated since API version 9. You are advised to use [longClick9+](#longclick9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X-coordinate of the target point.|
| y | number | Yes | Y-coordinate of the target point.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.longClick(100,100);
}
```
### swipe(deprecated)
swipe(startx: number, starty: number, endx: number, endy: number): Promise\
Swipes on this **UiDriver** object from the start point to the end point based on the given coordinates.
This API is deprecated since API version 9. You are advised to use [swipe9+](#swipe9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| 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.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.swipe(100,100,200,200);
}
```
### screenCap(deprecated)
screenCap(savePath: string): Promise\
Captures the current screen of this **UiDriver** object and saves it as a PNG image to the given save path.
This API is deprecated since API version 9. You are advised to use [screenCap9+](#screencap9) instead.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | -------------- |
| savePath | string | Yes | File save path.|
**Return value**
| Type | Description |
| ----------------- | -------------------------------------- |
| Promise\ | Promise used to return the operation result. The value **true** means that the operation is successful.|
**Example**
```js
async function demo() {
let driver = UiDriver.create();
await driver.screenCap('/data/storage/el2/base/cache/1.png');
}
```