@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:

• On⁹⁺: provides UI component feature description APIs for component filtering and matching.
• Component⁹⁺: represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection.
• Driver⁹⁺: works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot.
• UiWindow⁹⁺: works as the entry class and provides APIs for obtaining window attributes, dragging windows, and adjusting window sizes.
• By^(deprecated): provides UI component feature description APIs for component filtering and matching. This class is deprecated since API version 9. You are advised to use On⁹⁺ instead.
• UiComponent^(deprecated): represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. This class is deprecated since API version 9. You are advised to use Component⁹⁺ instead.
• UiDriver^(deprecated): works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. This class is deprecated since API version 9. You are advised to use Driver⁹⁺ instead.

NOTE

The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import {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.

ResizeDirection⁹⁺

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.

Point⁹⁺

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.

Rect⁹⁺

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.

WindowMode⁹⁺

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.

DisplayRotation⁹⁺

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.

WindowFilter⁹⁺

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.

UiDirection¹⁰⁺

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.

MouseButton¹⁰⁺

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.

UIElementInfo¹⁰⁺

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.

On⁹⁺

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 and ON.isAfter 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.

import { ON } from '@ohos.UiTest';
ON.text('123').type('button');

text⁹⁺

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	No	Match pattern. The default value is EQUALS.

Return value

Type	Description
On	On object that matches the text attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
let on = ON.text('123'); // Use the static constructor ON to create an On object and specify the text attribute of the target component.

id⁹⁺

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	On object that matches the ID attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
let on = ON.id('123'); // Use the static constructor ON to create an On object and specify the ID attribute of the target component.

type⁹⁺

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	On object that matches the type attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
let on = ON.type('button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component.

clickable⁹⁺

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	On object that matches the clickable status attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
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.

longClickable⁹⁺

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	On object that matches the long-clickable status attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
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.

scrollable⁹⁺

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	On object that matches the scrollable status attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
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.

enabled⁹⁺

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	On object that matches the enabled status attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
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.

focused⁹⁺

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	On object that matches the focused status attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
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.

selected⁹⁺

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	On object that matches the selected status attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
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.

checked⁹⁺

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	On object that matches the checked status attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
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.

checkable⁹⁺

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	On object that matches the checkable status attribute of the target component.

Example

import { ON } from '@ohos.UiTest';
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.

isBefore⁹⁺

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	Yes	Information about the attribute component.

Return value

Type	Description
On	On object.

Example

import { ON } from '@ohos.UiTest';
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.

isAfter⁹⁺

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	Yes	Information about the attribute component.

Return value

Type	Description
On	On object.

Example

import { ON } from '@ohos.UiTest';
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.

within¹⁰⁺

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	Yes	Information about the attribute component.

Return value

Type	Description
On	On object.

Example

import { ON } from '@ohos.UiTest';
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.

inWindow¹⁰⁺

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	On object.

Example

import { ON } from '@ohos.UiTest';
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.

Component⁹⁺

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.

click⁹⁺

click(): Promise<void>

Clicks this component.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.click();
}

doubleClick⁹⁺

doubleClick(): Promise<void>

Double-clicks this component.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.doubleClick();
}

longClick⁹⁺

longClick(): Promise<void>

Long-clicks this component.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.longClick();
}

getId⁹⁺

getId(): Promise<string>

Obtains the ID of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the ID of the component.

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let num = await button.getId();
}

getText⁹⁺

getText(): Promise<string>

Obtains the text information of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the text information of the component.

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let text = await button.getText();
}

getType⁹⁺

getType(): Promise<string>

Obtains the type of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the type of the component.

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let type = await button.getType();
}

getBounds⁹⁺

getBounds(): Promise<Rect>

Obtains the bounds of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Rect>	Promise used to return the bounds of the component.

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let rect = await button.getBounds();
}

getBoundsCenter⁹⁺

getBoundsCenter(): Promise<Point>

Obtains the information about the center of the bounding box around this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Point>	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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let point = await button.getBoundsCenter();
}

isClickable⁹⁺

isClickable(): Promise<boolean>

Obtains the clickable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
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');
    }
}

isLongClickable⁹⁺

isLongClickable(): Promise<boolean>

Obtains the long-clickable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the long-clickable status of the component. The value true means that the component is long-clickable, and false means the opposite.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
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');
    }
}

isChecked⁹⁺

isChecked(): Promise<boolean>

Obtains the checked status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the checked status of the component. The value true means that the component is checked, and false means the opposite.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
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');
    }
}

isCheckable⁹⁺

isCheckable(): Promise<boolean>

Obtains the checkable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the checkable status of the component. The value true means that the component is checkable, and false means the opposite.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
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');
    }
}

isScrollable⁹⁺

isScrollable(): Promise<boolean>

Obtains the scrollable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
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');
    }
}

isEnabled⁹⁺

isEnabled(): Promise<boolean>

Obtains the enabled status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
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');
    }
}

isFocused⁹⁺

isFocused(): Promise<boolean>

Obtains the focused status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the focused status of the component. The value true means that the component is focused, and false means the opposite.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
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');
	}
}

isSelected⁹⁺

isSelected(): Promise<boolean>

Obtains the selected status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
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');
    }
}

inputText⁹⁺

inputText(text: string): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let text = await driver.findComponent(ON.text('hello world'));
    await text.inputText('123');
}

clearText⁹⁺

clearText(): Promise<void>

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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let text = await driver.findComponent(ON.text('hello world'));
    await text.clearText();
}

scrollSearch⁹⁺

scrollSearch(on: On): Promise<Component>

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	Yes	Attributes of the target component.

Return value

Type	Description
Promise<Component>	Promise used to return the target component.

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let scrollBar = await driver.findComponent(ON.type('Scroll'));
    let button = await scrollBar.scrollSearch(ON.text('next page'));
}

scrollToTop⁹⁺

scrollToTop(speed?: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let scrollBar = await driver.findComponent(ON.type('Scroll'));
    await scrollBar.scrollToTop();
}

scrollToBottom⁹⁺

scrollToBottom(speed?: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let scrollBar = await driver.findComponent(ON.type('Scroll'));
    await scrollBar.scrollToBottom();
}

dragTo⁹⁺

dragTo(target: Component): Promise<void>

Drags this component to the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
target	Component	Yes	Target component.

Error codes

For details about the error codes, see 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

import { Driver, ON } from '@ohos.UiTest';
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);
    }

pinchOut⁹⁺

pinchOut(scale: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let image = await driver.findComponent(ON.type('image'));
    await image.pinchOut(1.5);
    }

pinchIn⁹⁺

pinchIn(scale: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let image = await driver.findComponent(ON.type('image'));
    await image.pinchIn(0.5);
    }

Driver⁹⁺

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.

create⁹⁺

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.

ID	Error Message
17000001	if the test framework failed to initialize.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
}

delayMs⁹⁺

delayMs(duration: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.delayMs(1000);
}

findComponent⁹⁺

findComponent(on: On): Promise<Component>

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	Yes	Attributes of the target component.

Return value

Type	Description
Promise<Component>	Promise used to return the found component.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.text('next page'));
}

findComponents⁹⁺

findComponents(on: On): Promise<Array<Component>>

Searches this Driver object for all components that match the given attributes.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
on	On	Yes	Attributes of the target component.

Return value

Type	Description
Promise<Array<Component>>	Promise used to return a list of found components.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let buttonList = await driver.findComponents(ON.text('next page'));
}

findWindow⁹⁺

findWindow(filter: WindowFilter): Promise<UiWindow>

Searches for the window that matches the specified attributes.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
filter	WindowFilter	Yes	Attributes of the target window.

Return value

Type	Description
Promise<UiWindow>	Promise used to return the target window.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
}

waitForComponent⁹⁺

waitForComponent(on: On, time: number): Promise<Component>

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	Yes	Attributes of the target component.
time	number	Yes	Duration for searching for the target component, in ms.

Return value

Type	Description
Promise<Component>	Promise used to return the found component.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.waitForComponent(ON.text('next page'),500);
}

assertComponentExist⁹⁺

assertComponentExist(on: On): Promise<void>

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	Yes	Attributes of the target component.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000003	if the assertion failed.

Example

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.assertComponentExist(ON.text('next page'));
}

pressBack⁹⁺

pressBack(): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.pressBack();
}

triggerKey⁹⁺

triggerKey(keyCode: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.triggerKey(123);
}

triggerCombineKeys⁹⁺

triggerCombineKeys(key0: number, key1: number, key2?: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.triggerCombineKeys(2072, 2047, 2035);
}

click⁹⁺

click(x: number, y: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.click(100,100);
}

doubleClick⁹⁺

doubleClick(x: number, y: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.doubleClick(100,100);
}

longClick⁹⁺

longClick(x: number, y: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.longClick(100,100);
}

swipe⁹⁺

swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.swipe(100,100,200,200,600);
}

drag⁹⁺

drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.drag(100,100,200,200,600);
}

screenCap⁹⁺

screenCap(savePath: string): Promise<boolean>

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<boolean>	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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.screenCap('/data/storage/el2/base/cache/1.png');
}

setDisplayRotation⁹⁺

setDisplayRotation(rotation: DisplayRotation): Promise<void>

Sets the display rotation of the device.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
rotation	DisplayRotation	Yes	Display rotation of the device.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver, DisplayRotation } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.setDisplayRotation(DisplayRotation.ROTATION_180);
}

getDisplayRotation⁹⁺

getDisplayRotation(): Promise<DisplayRotation>

Obtains the display rotation of the current device.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<DisplayRotation>	Promise used to return the display rotation of the current device.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let rotation = await driver.getDisplayRotation();
}

setDisplayRotationEnabled⁹⁺

setDisplayRotationEnabled(enabled: boolean): Promise<void>

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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.setDisplayRotationEnabled(false);
}

getDisplaySize⁹⁺

getDisplaySize(): Promise<Point>

Obtains the display size of the current device.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Point>	Promise used to return the display size of the current device.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let size = await driver.getDisplaySize();
}

getDisplayDensity⁹⁺

getDisplayDensity(): Promise<Point>

Obtains the display density of the current device.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Point>	Promise used to return the display density of the current device.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let density = await driver.getDisplayDensity();
}

wakeUpDisplay⁹⁺

wakeUpDisplay(): Promise<void>

Wakes up the device display.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.wakeUpDisplay();
}

pressHome⁹⁺

pressHome(): Promise<void>

Returns to the home screen.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.pressHome();
}

waitForIdle⁹⁺

waitForIdle(idleTime: number, timeout: number): Promise<boolean>

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<boolean>	Promise used to return the result.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let idled = await driver.waitForIdle(4000,5000);
}

fling⁹⁺

fling(from: Point, to: Point, stepLen: number, speed: number): Promise<void>

Simulates a fling operation on the screen.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Coordinates of the point where the finger touches the screen.
to	Point	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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.fling({x: 500, y: 480},{x: 450, y: 480},5,600);
}

injectMultiPointerAction⁹⁺

injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise<boolean>

Injects a multi-touch operation to the device.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
pointers	PointerMatrix	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<boolean>	Promise used to return the result.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver, PointerMatrix } from '@ohos.UiTest';
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);
}

fling¹⁰⁺

fling(direction: UiDirection, speed: number): Promise<void>;

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	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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver, UiDirection } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.fling(UiDirection.DOWN, 10000);
}

screenCapture¹⁰⁺

screenCapture(savePath: string, rect?: Rect): Promise<boolean>;

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	No	Area of the screen to capture. The default value is the entire screen.

Return value

Type	Description
Promise<boolean>	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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
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});
}

mouseClick¹⁰⁺

mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise<void>;

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	Yes	Coordinates of the mouse click.
btnId	MouseButton	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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver,MouseButton } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.mouseClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072);
}

mouseScroll¹⁰⁺

mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): Promise<void>;

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	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.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.mouseScroll({x:360, y:640}, true, 30, 2072)
}

mouseMoveTo¹⁰⁺

mouseMoveTo(p: Point): Promise<void>;

Moves the cursor to the target point.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
p	Point	Yes	Coordinates of the target point.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    await driver.mouseMoveTo({x:100, y:100})
}

createUIEventObserver¹⁰⁺

createUIEventObserver(): UIEventObserver;

Creates a UI event listener.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<UIEventObserver>	Promise used to return the target window.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let observer = await driver.createUIEventObserver()
}

PointerMatrix⁹⁺

Implements a PointerMatrix object that stores coordinates and behaviors of each action of each finger in a multi-touch operation.

create⁹⁺

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	PointerMatrix object created.

Example

import { PointerMatrix } from '@ohos.UiTest';
async function demo() {
    let pointerMatrix = PointerMatrix.create(2,3);
}

setPoint⁹⁺

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	Yes	Coordinates of the action.

Example

import { PointerMatrix } from '@ohos.UiTest';
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});
}

UiWindow⁹⁺

The UiWindow class represents a window on the UI and provides APIs for obtaining window attributes, dragging a window, and adjusting the window size.

All APIs provided in this class use a promise to return the result and must be invoked using await.

getBundleName⁹⁺

getBundleName(): Promise<string>

Obtains the bundle name of the application to which this window belongs.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the bundle name.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let name = await window.getBundleName();
}

getBounds⁹⁺

getBounds(): Promise<Rect>

Obtains the bounds information of this window.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Rect>	Promise used to return the bounds information of the window.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let rect = await window.getBounds();
}

getTitle⁹⁺

getTitle(): Promise<string>

Obtains the title of this window.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the title of the window.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let rect = await window.getTitle();
}

getWindowMode⁹⁺

getWindowMode(): Promise<WindowMode>

Obtains the window mode of this window.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<WindowMode>	Promise used to return the window mode of the window.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let mode = await window.getWindowMode();
}

isFocused⁹⁺

isFocused(): Promise<boolean>

Checks whether this window is in focused state.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the window is in focused state, and false means the opposite.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let focused = await window.isFocused();
}

isActived⁹⁺

isActived(): Promise<boolean>

Checks whether this window is active.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	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.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let focused = await window.isActived();
}

focus⁹⁺

focus(): Promise<void>

Moves the focus to this window.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.focus();
}

moveTo⁹⁺

moveTo(x: number, y: number): Promise<void>

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.

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

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.moveTo(100, 100);
}

resize⁹⁺

resize(wide: number, height: number, direction: ResizeDirection): Promise<void>

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	Yes	Resize direction.

Error codes

For details about the error codes, see UiTest Error Codes.

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

import { Driver, ResizeDirection } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.resize(100, 100, ResizeDirection.LEFT);
}

split⁹⁺

split(): Promise<void>

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.

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

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.split();
}

maximize⁹⁺

maximize(): Promise<void>

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.

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

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.maximize();
}

minimize⁹⁺

minimize(): Promise<void>

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.

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

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.minimize();
}

resume⁹⁺

resume(): Promise<void>

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.

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

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.resume();
}

close⁹⁺

close(): Promise<void>

Closes this window.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

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

import { Driver } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.close();
}

UIEventObserver¹⁰⁺

Implements a UI event listener.

once('toastShow')

once(type: 'toastShow', callback: Callback<UIElementInfo>):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>	Yes	Callback used to return the result.

Example

import { Driver, UIElementInfo } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let observer = await driver.createUIEventObserver()
    let  callback = (UIElementInfo: UIElementInfo)=>{
        console.info(UIElementInfo.bundleName)
        console.info(UIElementInfo.text)
        console.info(UIElementInfo.type)
     }
    observer.once('toastShow', callback)
}

once('dialogShow')

once(type: 'dialogShow', callback: Callback<UIElementInfo>): 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>	Yes	Callback used to return the result.

Example

import { Driver, UIElementInfo } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let observer = await driver.createUIEventObserver()
    let  callback = (UIElementInfo: 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) and By.isAfter^(deprecated) 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 On⁹⁺ instead.

import { BY } from '@ohos.UiTest';
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 text⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
txt	string	Yes	Component text, used to match the target component.
pattern	MatchPattern	No	Match pattern. The default value is EQUALS.

Return value

Type	Description
By	By object that matches the text attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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 id⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Component key.

Return value

Type	Description
By	By object that matches the key attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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	By object that matches the ID attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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 type⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
tp	string	Yes	Component type.

Return value

Type	Description
By	By object that matches the type attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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 clickable⁹⁺ 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	By object that matches the clickable status attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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 scrollable⁹⁺ 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	By object that matches the scrollable status attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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 enabled⁹⁺ 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	By object that matches the enabled status attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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 focused⁹⁺ 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	By object that matches the focused status attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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 selected⁹⁺ 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	By object that matches the selected status attribute of the target component.

Example

import { BY } from '@ohos.UiTest';
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 isBefore⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
by	By	Yes	Information about the attribute component.

Return value

Type	Description
By	By object.

Example

import { BY } from '@ohos.UiTest';
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 isAfter⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
by	By	Yes	Information about the attribute component.

Return value

Type	Description
By	By object.

Example

import { BY } from '@ohos.UiTest';
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 Component⁹⁺ instead.

click^(deprecated)

click(): Promise<void>

Clicks this component.

This API is deprecated since API version 9. You are advised to use click⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.click();
}

doubleClick^(deprecated)

doubleClick(): Promise<void>

Double-clicks this component.

This API is deprecated since API version 9. You are advised to use doubleClick⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.doubleClick();
}

longClick^(deprecated)

longClick(): Promise<void>

Long-clicks this component.

This API is deprecated since API version 9. You are advised to use longClick⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.longClick();
}

getId^(deprecated)

getId(): Promise<number>

Obtains the ID of this component.

This API is deprecated since API version 9.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<number>	Promise used to return the ID of the component.

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let num = await button.getId();
}

getKey^(deprecated)

getKey(): Promise<string>

Obtains the key of this component.

This API is deprecated since API version 9. You are advised to use getId⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the key of the component.

Example

import { UiDriver, BY } from '@ohos.UiTest';
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<string>

Obtains the text information of this component.

This API is deprecated since API version 9. You are advised to use getText⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the text information of the component.

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let text = await button.getText();
}

getType^(deprecated)

getType(): Promise<string>

Obtains the type of this component.

This API is deprecated since API version 9. You are advised to use getType⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the type of the component.

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let type = await button.getType();
}

isClickable^(deprecated)

isClickable(): Promise<boolean>

Obtains the clickable status of this component.

This API is deprecated since API version 9. You are advised to use isClickable⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the component is clickable, and false means the opposite.

Example

import { UiDriver, BY } from '@ohos.UiTest';
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<boolean>

Obtains the scrollable status of this component.

This API is deprecated since API version 9. You are advised to use isScrollable⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the component is scrollable, and false means the opposite.

Example

import { UiDriver, BY } from '@ohos.UiTest';
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<boolean>

Obtains the enabled status of this component.

This API is deprecated since API version 9. You are advised to use isEnabled⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the component is enabled, and false means the opposite.

Example

import { UiDriver, BY } from '@ohos.UiTest';
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<boolean>

Obtains the focused status of this component.

This API is deprecated since API version 9. You are advised to use isFocused⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the target component is focused, and false means the opposite.

Example

import { UiDriver, BY } from '@ohos.UiTest';
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<boolean>

Obtains the selected status of this component.

This API is deprecated since API version 9. You are advised to use isSelected⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the component is selected, and false means the opposite.

Example

import { UiDriver, BY } from '@ohos.UiTest';
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<void>

Enters text into this component (available for text boxes).

This API is deprecated since API version 9. You are advised to use inputText⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Text to enter.

Example

import { UiDriver, BY } from '@ohos.UiTest';
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<UiComponent>

Scrolls on this component to search for the target component (applicable to components that support scrolling, such as <List>).

This API is deprecated since API version 9. You are advised to use scrollSearch⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
by	By	Yes	Attributes of the target component.

Return value

Type	Description
Promise<UiComponent>	Promise used to return the target component.

Example

import { UiDriver, BY } from '@ohos.UiTest';
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 Driver⁹⁺ 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 create⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
UiDriver	Returns the UiDriver object created.

Example

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
}

delayMs^(deprecated)

delayMs(duration: number): Promise<void>

Delays this UiDriver object within the specified duration.

This API is deprecated since API version 9. You are advised to use delayMs⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
duration	number	Yes	Duration of time.

Example

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.delayMs(1000);
}

findComponent^(deprecated)

findComponent(by: By): Promise<UiComponent>

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 findComponent⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
by	By	Yes	Attributes of the target component.

Return value

Type	Description
Promise<UiComponent>	Promise used to return the found component.

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.text('next page'));
}

findComponents^(deprecated)

findComponents(by: By): Promise<Array<UiComponent>>

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 findComponents⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
by	By	Yes	Attributes of the target component.

Return value

Type	Description
Promise<Array<UiComponent>>	Promise used to return a list of found components.

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let buttonList = await driver.findComponents(BY.text('next page'));
}

assertComponentExist^(deprecated)

assertComponentExist(by: By): Promise<void>

Asserts that a component that matches the given attributes exists on the current page. If the component does not exist, the API throws a JS exception, causing the current test case to fail.

This API is deprecated since API version 9. You are advised to use assertComponentExist⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
by	By	Yes	Attributes of the target component.

Error codes

For details about the error codes, see UiTest Error Codes.

ID	Error Message
17000002	if the async function was not called with await.
17000003	if the assertion failed.

Example

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.assertComponentExist(BY.text('next page'));
}

pressBack^(deprecated)

pressBack(): Promise<void>

Presses the Back button on this UiDriver object.

This API is deprecated since API version 9. You are advised to use pressBack⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Example

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.pressBack();
}

triggerKey^(deprecated)

triggerKey(keyCode: number): Promise<void>

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 triggerKey⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
keyCode	number	Yes	Key code.

Example

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.triggerKey(123);
}

click^(deprecated)

click(x: number, y: number): Promise<void>

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 click⁹⁺ 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

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.click(100,100);
}

doubleClick^(deprecated)

doubleClick(x: number, y: number): Promise<void>

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 doubleClick⁹⁺ 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

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.doubleClick(100,100);
}

longClick^(deprecated)

longClick(x: number, y: number): Promise<void>

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 longClick⁹⁺ 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

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.longClick(100,100);
}

swipe^(deprecated)

swipe(startx: number, starty: number, endx: number, endy: number): Promise<void>

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 swipe⁹⁺ 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

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.swipe(100,100,200,200);
}

screenCap^(deprecated)

screenCap(savePath: string): Promise<boolean>

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 screenCap⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
savePath	string	Yes	File save path.

Return value

Type	Description
Promise<boolean>	Promise used to return the operation result. The value true means that the operation is successful.

Example

import { UiDriver } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    await driver.screenCap('/data/storage/el2/base/cache/1.png');
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)