@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 API is supported since API version 8 and 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 API is supported since API version 8 and 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 API is supported since API version 8 and 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.
• The APIs of this module can be used only in UITest.
• The APIs of this module do not support concurrent calls.

Modules to Import

import { Component, Driver, UiWindow, ON, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton, UIElementInfo, UIEventObserver, UiComponent, UiDriver, BY, KeyOptions, TouchOptions } from '@kit.TestKit';

MatchPattern

Enumerates the match patterns supported for component attributes.

System capability: SystemCapability.Test.UiTest

Name	Value	Description
EQUALS	0	Equals the given value. Atomic service API: This API can be used in atomic services since API version 11.
CONTAINS	1	Contains the given value. Atomic service API: This API can be used in atomic services since API version 11.
STARTS_WITH	2	Starts with the given value. Atomic service API: This API can be used in atomic services since API version 11.
ENDS_WITH	3	Ends with the given value. Atomic service API: This API can be used in atomic services since API version 11.
REG_EXP18+	4	Uses regular expression matching. Atomic service API: This API can be used in atomic services since API version 18.
REG_EXP_ICASE18+	5	Uses case-insensitive regular expression matching. Atomic service API: This API can be used in atomic services since API version 18.

ResizeDirection⁹⁺

Enumerates the directions in which a window can be resized.

Atomic service API: This API can be used in atomic services since API version 11.

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	Read-Only	Optional	Description
x	number	No	No	Horizontal coordinate of a coordinate point. The value is an integer greater than 0. Note: Since API version 20, this attribute is no longer read-only. Atomic service API: This API can be used in atomic services since API version 11.
y	number	No	No	Vertical coordinate of a coordinate point. The value is an integer greater than 0. Note: Since API version 20, this attribute is no longer read-only. Atomic service API: This API can be used in atomic services since API version 11.
displayId20+	number	No	Yes	ID of the display to which the coordinate point belongs. The value is an integer greater than or equal to 0. The default value is the default screen ID of the device. Atomic service API: This API can be used in atomic services since API version 20.

Rect⁹⁺

Provides bounds information of a component.

System capability: SystemCapability.Test.UiTest

Name	Type	Read-Only	Optional	Description
left	number	No	No	X coordinate of the upper left corner of the component border. The value is an integer greater than 0. Note: Since API version 20, this attribute is no longer read-only. Atomic service API: This API can be used in atomic services since API version 11.
top	number	No	No	Y coordinate of the upper left corner of the component border. The value is an integer greater than 0. Note: Since API version 20, this attribute is no longer read-only. Atomic service API: This API can be used in atomic services since API version 11.
right	number	No	No	X coordinate of the lower right corner of the component border. The value is an integer greater than 0. Note: Since API version 20, this attribute is no longer read-only. Atomic service API: This API can be used in atomic services since API version 11.
bottom	number	No	No	Y coordinate of the lower right corner of the component border. The value is an integer greater than 0. Note: Since API version 20, this attribute is no longer read-only. Atomic service API: This API can be used in atomic services since API version 11.
displayId20+	number	No	Yes	ID of the display to which the component border belongs. The value is an integer greater than or equal to 0. The default value is the default screen ID of the device. Atomic service API: This API can be used in atomic services since API version 20.

WindowMode⁹⁺

Enumerates the window modes.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Atomic service API: This API can be used in atomic services since API version 11.

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	Read-Only	Optional	Description
bundleName	string	No	Yes	Bundle name of the application to which the window belongs. The default value is empty. Atomic service API: This API can be used in atomic services since API version 11.
title	string	No	Yes	Title of the window. The default value is empty. Atomic service API: This API can be used in atomic services since API version 11.
focused	boolean	No	Yes	Whether the window is focused. The value true indicates that the window is focused, and false indicates the opposite. The default value is false. Atomic service API: This API can be used in atomic services since API version 11.
actived(deprecated)	boolean	No	Yes	Whether the window is interacting with the user. The value true indicates that the window is interacting with the user, and false indicates the opposite. This API is deprecated since API version 11. You are advised to use the active API instead.
active11+	boolean	No	Yes	Whether the window is interacting with the user. The value true indicates that the window is interacting with the user, and false indicates the opposite. Atomic service API: This API can be used in atomic services since API version 11.
displayId20+	number	No	Yes	ID of the display to which the window belongs. The value is an integer greater than or equal to 0. The default value is the default screen ID of the device. Atomic service API: This API can be used in atomic services since API version 20.

UiDirection¹⁰⁺

Describes the direction of a UI operation such as fling.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Atomic service API: This API can be used in atomic services since API version 11.

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.

WindowChangeType²²⁺

Enumerates the window change event types that can be listened for.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Name	Value	Description
WINDOW_UNDEFINED	0	Non-window change event. Note: This value can only be used as a return value. If it is passed in an API, an exception will be thrown.
WINDOW_ADDED	1	Window adding event.
WINDOW_REMOVED	2	Window removing event.
WINDOW_BOUNDS_CHANGED	3	Window bounds change event.

ComponentEventType²²⁺

Enumerates the component operation event types that can be listened for.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Name	Value	Description
COMPONENT_UNDEFINED	0	Non-component operation event. Note: This value can only be used as a return value. If it is passed in an API, an exception will be thrown.
COMPONENT_CLICKED	1	Component clicked event.
COMPONENT_LONG_CLICKED	2	Component long-clicked event.
COMPONENT_SCROLL_START	3	Component scroll start event.
COMPONENT_SCROLL_END	4	Component scroll end event.
COMPONENT_TEXT_CHANGED	5	Text change event of the text input component.

WindowChangeOptions²²⁺

Describes the extended configuration of window change event listening, which is used to specify the listening process configuration and event filtering conditions.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Name	Type	Read-Only	Optional	Description
timeout	number	No	Yes	Listening timeout interval, in milliseconds. The default value is 10000.
bundleName	string	No	Yes	Bundle name of the window to be listened for. By default, all windows are listened for.

ComponentEventOptions²²⁺

Describes the extended configuration of component operation event listening, which is used to specify the listening process configuration and event filtering conditions.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Name	Type	Read-Only	Optional	Description
timeout	number	No	Yes	Listening timeout interval, in milliseconds. The default value is 10000.
on	On	No	Yes	Attribute requirements of the target component to listen for. By default, all components are listened for. Note: Only components with specified attributes can be listened for. Components with relative positions such as On.isBefore, On.isAfter, and On.within cannot be listened for.

UIElementInfo¹⁰⁺

Provides information about the UI event.

System capability: SystemCapability.Test.UiTest

Name	Type	Read-Only	Optional	Description
bundleName	string	Yes	No	Bundle name of the application. Atomic service API: This API can be used in atomic services since API version 11.
type	string	Yes	No	Component or window type. Atomic service API: This API can be used in atomic services since API version 11.
text	string	Yes	No	Text information of the component or window. Atomic service API: This API can be used in atomic services since API version 11.
windowChangeType22+	WindowChangeType	Yes	Yes	Window change event type. If the event is not a window change event, WindowChangeType.WINDOW_UNDEFINED is returned. Atomic service API: This API can be used in atomic services since API version 22.
componentEventType22+	ComponentEventType	Yes	Yes	Component operation event type. If it is not a component operation event, ComponentEventType.COMPONENT_UNDEFINED is returned. Atomic service API: This API can be used in atomic services since API version 22.
windowId22+	number	Yes	Yes	ID of the window where the component belongs. Atomic service API: This API can be used in atomic services since API version 22.
componentId22+	string	Yes	Yes	Component ID. If it is not a component operation event, an empty string is returned. Atomic service API: This API can be used in atomic services since API version 22.
componentRect22+	Rect	Yes	Yes	Component border information. If it is not a component operation event, a Rect object with all attribute values being 0 is returned. Atomic service API: This API can be used in atomic services since API version 22.

TouchPadSwipeOptions¹⁸⁺

Describes information about the touchpad swipe gesture option.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Name	Type	Read-Only	Optional	Description
stay	boolean	No	Yes	Whether the swipe gesture stays on the touchpad for 1s before it is lifted. The value true indicates that the swipe gesture stays on the touchpad for 1s, and false indicates the opposite. The default value is false.
speed	number	No	Yes	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 2000. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 2000 is used. If the value is a negative number, an error code indicating a parameter error is returned.

InputTextMode²⁰⁺

Describes the text input mode.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Name	Type	Read-Only	Optional	Description
paste	boolean	No	Yes	Whether to copy and paste text. The value true means to copy and paste text, and false means to type text. Default value: false Note: If the input text contains Chinese characters, special characters, or the text length exceeds 200 characters, the text is copied and pasted regardless of the value of this parameter.
addition	boolean	No	Yes	Whether to input text in addition mode. The value true means to input text in addition mode, and false means the opposite. Default value: false

KeyOptions

Describes key options.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Test.UiTest

Name	Type	Read-Only	Optional	Description
key1	number	No	Yes	First key value injected during the operation. For details about the value range, see KeyCode. If this parameter is not set, no key event is injected.
key2	number	No	Yes	Second key value injected during the operation. For details about the value range, see KeyCode. If this parameter is not set, no key event is injected. Note: If only key2 is set, the 17000007 parameter verification failure error will be thrown.

TouchOptions

Describes common touch options.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Test.UiTest

Name	Type	Read-Only	Optional	Description
speed	number	No	Yes	Operation speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number beyond the value range or is null/undefined, the default value 600 is used. If the value is a negative number, the error code 17000007 is thrown.
duration	number	No	Yes	Operation duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500. If the value is less than 1500, the 17000007 error code is thrown. If the value is null or undefined, the default value is used.
pressure	number	No	Yes	Pressure value of the touch. The value ranges from 0 to 1. The default value is 0. If the value is null or undefined, the default value is used. If the value is out of the value range, the 17000007 error code is thrown.

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 APIs provided by the On class exhibit the following features:
1. Allow one or more attributes as the match conditions. For example, you can specify both the text and id attributes to find the target component.
2. Provide multiple match patterns for component attributes.
3. 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.

// xxx.test.ets
import { ON } from '@kit.TestKit';

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.

NOTE

If the accessibilityLevel of a component is set to no or no-hide-descendants, this API cannot be used to specify the text attribute of the target component for searching for the component. In this case, you can use the On.originalText() API.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: 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.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.id('123'); // Use the static constructor ON to create an On object and specify the ID attribute of the target component.

id¹⁸⁺

id(id: string, pattern: MatchPattern): On

Specifies the id attribute and match pattern of the target component.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
id	string	Yes	Component ID.
pattern	MatchPattern	Yes	Text matching pattern.

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { MatchPattern, On, ON } from '@kit.TestKit';

let on: On = ON.id('id', MatchPattern.REG_EXP_ICASE); // Use case-insensitive regular expression to match the ID attribute value of the component.

type⁹⁺

type(tp: string): On

Specifies the type attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.type('Button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component.

type¹⁸⁺

type(tp: string, pattern: MatchPattern): On

Specifies the type attribute and match pattern of the target component.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
tp	string	Yes	Component type.
pattern	MatchPattern	Yes	Text matching pattern.

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON, MatchPattern } from '@kit.TestKit';

let on: On = ON.type('Button', MatchPattern.EQUALS); // 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 attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
b	boolean	No	Clickable status of the component. The value true indicates that the component is clickable, and false indicates the opposite. Default value: true

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.clickable(true); // Use the static constructor ON to create an On object and specify the clickable attribute of the target component.

longClickable⁹⁺

longClickable(b?: boolean): On

Specifies the long-clickable attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
b	boolean	No	Long-clickable status of the component. The value true indicates that the component is long-clickable, and false indicates the opposite. Default value: true

Return value

Type	Description
On	On object that matches the long-clickable attribute of the target component.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.longClickable(true); // Use the static constructor ON to create an On object and specify the longClickable attribute of the target component.

scrollable⁹⁺

scrollable(b?: boolean): On

Specifies the scrollable attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
b	boolean	No	Scrollable status of the component. The value true indicates that the component is scrollable, and false indicates the opposite. Default value: true

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.scrollable(true); // Use the static constructor ON to create an On object and specify the scrollable attribute of the target component.

enabled⁹⁺

enabled(b?: boolean): On

Specifies the enabled attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
b	boolean	No	Enabled status of the component. The value true indicates that the component is enabled, and false indicates the opposite. Default value: true

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.enabled(true); // Use the static constructor ON to create an On object and specify the enabled attribute of the target component.

focused⁹⁺

focused(b?: boolean): On

Specifies the focused attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
b	boolean	No	Focused status of the component. The value true indicates that the component is focused, and false indicates the opposite. Default value: true

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.focused(true); // Use the static constructor ON to create an On object and specify the focused attribute of the target component.

selected⁹⁺

selected(b?: boolean): On

Specifies the selected attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
b	boolean	No	Selected status of the component. The value true indicates that the component is selected, and false indicates the opposite. Default value: true

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.selected(true); // Use the static constructor ON to create an On object and specify the selected attribute of the target component.

checked⁹⁺

checked(b?: boolean): On

Specifies the checked attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
b	boolean	No	Checked status of the component. The value true indicates that the component is checked, and false indicates the opposite. Default value: true

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.checked(true); // Use the static constructor ON to create an On object and specify the checked attribute of the target component.

checkable⁹⁺

checkable(b?: boolean): On

Specifies the checkable attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
b	boolean	No	Checkable status of the component. The value true indicates that the component is checkable, and false indicates the opposite. Default value: true

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.checkable(true); // Use the static constructor ON to create an On object and specify the checkable attribute of the target component.

isBefore⁹⁺

isBefore(on: On): On

Specifies that the target component is located before the given attribute component.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

// Use the static constructor ON to create an On object and specify that the target component is located before the given attribute component.
let on: On = ON.type('Button').isBefore(ON.text('123')); // Search for the first Button component located before the component whose text is 123.

isAfter⁹⁺

isAfter(on: On): On

Specifies that the target component is located after the given attribute component.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

// Use the static constructor ON to create an On object and specify that the target component is located after the given attribute component.
let on: On = ON.type('Text').isAfter(ON.text('123')); // Search for the first Text component located after the component whose text is 123.

within¹⁰⁺

within(on: On): On

Specifies that the target component is located within the given attribute component.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

// Use the static constructor ON to create an On object and specify that the target component is located within the given attribute component.
let on: On = ON.text('java').within(ON.type('Scroll')); // Search for the child component whose text is java within the Scroller component.

inWindow¹⁰⁺

inWindow(bundleName: string): On

Specifies that the target component is located within the given application window.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.inWindow('com.uitestScene.acts'); // Use the static constructor ON to create an On object and specify that the target component is located within the given application window.

description¹¹⁺

description(val: string, pattern?: MatchPattern): On

Specifies the description of the target component. Multiple match patterns are supported.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
val	string	Yes	Description of the component.
pattern	MatchPattern	No	Match pattern. The default value is EQUALS.

Return value

Type	Description
On	On object.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.description('123'); // Use the static constructor ON to create an On object and specify the description attribute of the target component.

hint¹⁸⁺

hint(val: string, pattern?: MatchPattern): On

Obtains the component object of the specified hint text and returns the On object.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
val	string	Yes	The specified hint text of the component.
pattern	MatchPattern	No	Match pattern. The default value is EQUALS.

Return value

Type	Description
On	The On object of the specified hint text component.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { MatchPattern, On, ON } from '@kit.TestKit';

let on: On = ON.hint('welcome', MatchPattern.EQUALS); // Use the static constructor ON to create an On object with the hint text attribute of the target component specified.

belongingDisplay²⁰⁺

belongingDisplay(displayId: number): On

Obtains the component object on the specified display.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	ID of the display to which the component belongs. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported. You can use getAllDisplays to obtain all current display objects and use them to obtain the corresponding display IDs.

Return value

Type	Description
On	The On object of the display to which the specified component belongs.

Error codes

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

ID	Error Message
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.belongingDisplay(0); // Use the static constructor ON to create an On object and specify the ID of the display to which the target component belongs.

originalText²⁰⁺

originalText(text: string, pattern?: MatchPattern): On

Specifies the text content and text matching pattern of the component.

NOTE

If the accessibilityLevel of a component is set to no or no-hide-descendants, this API can be used to specify the text attribute of the target component for searching for the component. In this case, the On.text() API does not take effect.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
text	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.

Error codes

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

ID	Error Message
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { On, ON } from '@kit.TestKit';

let on: On = ON.originalText('123'); // Use the static constructor ON to create an On object and specify the originalText attribute of the target component.

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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, ON, Component } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  await button.click();
}

doubleClick⁹⁺

doubleClick(): Promise<void>

Double-clicks this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  await button.doubleClick();
}

longClick⁹⁺

longClick(): Promise<void>

Long-clicks this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  await button.longClick();
}

getId⁹⁺

getId(): Promise<string>

Obtains the ID of this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let id = await button.getId();
}

getText⁹⁺

getText(): Promise<string>

Obtains the text information of this component. This API uses a promise to return the result.

NOTE

If the accessibilityLevel attribute of the component is set to no or no-hide-descendants, this API cannot be used to obtain the text information of the component. In this case, you can use Component.getOriginalText () instead.

Atomic service API: This API can be used in atomic services since API version 11.

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	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let text = await button.getText();
}

getType⁹⁺

getType(): Promise<string>

Obtains the type of this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let type = await button.getType();
}

getBounds⁹⁺

getBounds(): Promise<Rect>

Obtains the bounds information of this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Rect>	Promise used to return the bound information of the component object.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let rect = await button.getBounds();
}

getBoundsCenter⁹⁺

getBoundsCenter(): Promise<Point>

Obtains the center point of the area occupied by this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Point>	Promise used to return the center point of the area occupied by the component object.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let point = await button.getBoundsCenter();
}

isClickable⁹⁺

isClickable(): Promise<boolean>

Obtains the clickable status of this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = 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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  if (await button.isLongClickable()) {
    console.info('This button supports long click');
  } else {
    console.info('This button can not support long click');
  }
}

isChecked⁹⁺

isChecked(): Promise<boolean>

Obtains the checked status of this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let checkBox: Component = 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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return whether the component object is checkable. The value true indicates that the component is checkable, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let checkBox: Component = 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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = 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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = 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>

Checks whether a component is focused. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = 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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = 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>

Clears the original text in a component and inputs the specified text. This API takes effect only for editable text components. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Input text. Currently, English, Chinese, and special characters are supported.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let text: Component = await driver.findComponent(ON.text('hello world'));
  await text.inputText('123');
}

inputText²⁰⁺

inputText(text: string, mode: InputTextMode): Promise<void>

Inputs text to a component in a specified text input mode. This API takes effect only for editable text components. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Input text. Currently, English, Chinese, and special characters are supported.
mode	InputTextMode	Yes	Text input mode. For details, see InputTextMode. Note: If InputTextMode.addition is set to true, the specified text is added to the end of the existing text in the component. Otherwise, the specified text overwrites the existing text of the component.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported, function can not work correctly due to limited device capabilities.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function mode_demo() {
  let driver: Driver = Driver.create();
  let text: Component = await driver.findComponent(ON.text('hello world'));
  await text.inputText('123', { paste: true, addition: false });
}

clearText⁹⁺

clearText(): Promise<void>

Clears the text information of a component. This API takes effect only for editable text components. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let text: Component = 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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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 Universal Error Codes and UiTest Error Codes.

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = await driver.findComponent(ON.type('Scroll'));
  let button = await scrollBar.scrollSearch(ON.text('next page'));
}

scrollSearch¹⁸⁺

scrollSearch(on: On, vertical?: boolean, offset?: number): Promise<Component>

Scrolls on this component to search for the target component. This API is applicable to components that support scrolling. You can specify the scrolling direction and the offset between the scrolling start and end points and the component border. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
on	On	Yes	Attributes of the target component.
vertical	boolean	No	Whether the search direction is vertical. The default value true indicates that the search direction is vertical. false indicates that the search direction is horizontal.
offset	number	No	Offset from the scrolling start/end point to the component border, in pixels. The default value is 80. The value is an integer greater than or equal to 0.

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = 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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = 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. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = await driver.findComponent(ON.type('Scroll'));
  await scrollBar.scrollToBottom();
}

dragTo⁹⁺

dragTo(target: Component): Promise<void>

Drags a component to the target component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
target	Component	Yes	Target component.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let text: Component = await driver.findComponent(ON.text('hello world'));
  await button.dragTo(text);
}

pinchOut⁹⁺

pinchOut(scale: number): Promise<void>

Pinches out a component at the specified scale. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
scale	number	Yes	Scale factor, which is a value greater than 1.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let image: Component = await driver.findComponent(ON.type('Image'));
  await image.pinchOut(1.5);
}

pinchIn⁹⁺

pinchIn(scale: number): Promise<void>

Pinches in a component at the specified scale. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
scale	number	Yes	Scale factor, which is a value ranging from 0 to 1.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let image: Component = await driver.findComponent(ON.type('Image'));
  await image.pinchIn(0.5);
}

getDescription¹¹⁺

getDescription(): Promise<string>

Obtains the description of this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let description = await button.getDescription();
}

getHint¹⁸⁺

getHint(): Promise<string>

Obtains the hint text of a component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('TextInput'));
  let hints = await button.getHint();
}

getDisplayId²⁰⁺

getDisplayId(): Promise<number>

Obtains the ID of the display to which the component belongs. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('TextInput'));
  let displayId = await button.getDisplayId();
}

getOriginalText²⁰⁺

getOriginalText(): Promise<string>

Obtains the text information of this component. This API uses a promise to return the result. If the accessibilityLevel attribute of the component is set to no or no-hide-descendants, this API can be used to obtain the text information of the component, but Component.getText() cannot.

Atomic service API: This API can be used in atomic services since API version 20.

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	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let text = await button.getOriginalText();
}

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 Driver.create() and Driver.createUIEventObserver(), 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.

Atomic service API: This API can be used in atomic services since API version 11.

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

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
}

delayMs⁹⁺

delayMs(duration: number): Promise<void>

Delays execution for the specified duration. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
duration	number	Yes	Specified time, in ms. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.delayMs(1000);
}

findComponent⁹⁺

findComponent(on: On): Promise<Component>

Searches for the target component based on the specified attributes. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.text('next page'));
}

findComponents⁹⁺

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

Searches for all matched components based on the specified attributes and saves them in a list. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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 the list of components.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let buttonList: Array<Component> = await driver.findComponents(ON.text('next page'));
}

findWindow⁹⁺

findWindow(filter: WindowFilter): Promise<UiWindow>

Searches for a window based on the specified attributes. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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 Universal Error Codes and UiTest Error Codes.

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
}

waitForComponent⁹⁺

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

Searches for the target component based on the attributes within a specified time. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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. The value is an integer greater than or equal to 0.

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.waitForComponent(ON.text('next page'), 500);
}

assertComponentExist⁹⁺

assertComponentExist(on: On): Promise<void>

Asserts whether a component matches the specified attributes exists on the current page. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000003	Assertion failed.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.assertComponentExist(ON.text('next page'));
}

pressBack⁹⁺

pressBack(): Promise<void>

Presses the Back button. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.pressBack();
}

pressBack²⁰⁺

pressBack(displayId: number): Promise<void>

Presses the Back button on the specified screen. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.pressBack(0);
}

triggerKey⁹⁺

triggerKey(keyCode: number): Promise<void>

Triggers a key event by passing the key value. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
keyCode	number	Yes	Key value. For details about the value range, see KeyCode.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';
import { KeyCode } from '@kit.InputKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.triggerKey(KeyCode.KEYCODE_BACK); // Back button
}

triggerKey²⁰⁺

triggerKey(keyCode: number, displayId: number): Promise<void>

Triggers a key event by passing the key value on the specified screen. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
keyCode	number	Yes	Key value. For details about the value range, see KeyCode.
displayId	number	Yes	Display ID. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';
import { KeyCode } from '@kit.InputKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.triggerKey(KeyCode.KEYCODE_BACK, 0); // Back button
}

triggerCombineKeys⁹⁺

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

Triggers a combination key event based on the specified key values. This API uses a promise to return the result. For example, if the value of Key is (2072, 2019), the combination key Ctrl+C that matches the value is found and clicked.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
key0	number	Yes	First key value. For details about the value range, see KeyCode.
key1	number	Yes	Second key value. For details about the value range, see KeyCode.
key2	number	No	Third key value. For details about the value range, see KeyCode. The default value is 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.triggerCombineKeys(2072, 2047, 2035);
}

triggerCombineKeys²⁰⁺

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

Triggers a combination key event based on the specified key values on the specified screen. This API uses a promise to return the result. For example, if the value of Key is (2072, 2019), the combination key Ctrl+C that matches the value is found and clicked.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
key0	number	Yes	First key value. For details about the value range, see KeyCode.
key1	number	Yes	Second key value. For details about the value range, see KeyCode.
key2	number	No	Third key value. For details about the value range, see KeyCode. The default value is 0.
displayId	number	No	Display ID. The value is an integer greater than or equal to 0. The default value is the default display ID of the device.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.triggerCombineKeys(2072, 2047, 2035, 0);
}

click⁹⁺

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

Clicks the target coordinate point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
y	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.click(100, 100);
}

clickAt²⁰⁺

clickAt(point: Point): Promise<void>

Clicks the target coordinate point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Point object, which is used to transfer the target point information.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.clickAt({ x: 100, y: 100, displayId: 0 });
}

clickAt

clickAt(point: Point, options?: TouchOptions): Promise<void>

Clicks the target coordinate point. Touch options can be specified. This API uses a promise to return the result.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Point object, which is used to transfer the target point information.
options	TouchOptions	No	Touch options. Only the pressure property in TouchOptions can be set. If other properties are set, the 17000007 parameter verification failure error is thrown. The default values are inherited from the default values of the properties in TouchOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, TouchOptions } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let options: TouchOptions = {
    pressure: 0.5
  };
  // Clicks the target coordinate point and specifies the touch pressure.
  await driver.clickAt({ x: 100, y: 100, displayId: 0 }, options);
}

doubleClick⁹⁺

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

Double-clicks the target coordinate point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
y	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.doubleClick(100, 100);
}

doubleClickAt²⁰⁺

doubleClickAt(point: Point): Promise<void>

Double-clicks the target coordinate point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Point object, which is used to transfer the target point information.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.doubleClickAt({ x: 100, y: 100, displayId: 0 });
}

longClick⁹⁺

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

Long-clicks the target coordinate point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
y	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.longClick(100, 100);
}

longClickAt²⁰⁺

longClickAt(point: Point, duration?: number): Promise<void>

Long-clicks the target coordinate point for a specified duration. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Point object, which is used to transfer the target point information.
duration	number	No	Long-click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.longClickAt({ x: 100, y: 100, displayId: 0 }, 1500);
}

longClickAt

longClickAt(point: Point, options?: TouchOptions): Promise<void>

Long-clicks the target coordinate point. Touch options can be specified. This API uses a promise to return the result.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Point object, which is used to transfer the target point information.
options	TouchOptions	No	Touch options. Only the duration and pressure properties in TouchOptions can be set. If other properties are set, the 17000007 parameter verification failure error is thrown. The default values are inherited from the default values of the properties in TouchOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, TouchOptions } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let options: TouchOptions = {
    duration: 2000, // The click duration is 2000 ms.
    pressure: 0.8 // Touch pressure value.
  };
  // Long-click the target coordinate point, and specify the touch duration and pressure.
  await driver.longClickAt({ x: 100, y: 100, displayId: 0 }, options);
}

swipe⁹⁺

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

Swipes from the start coordinate point to the target coordinate point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
startx	number	Yes	Number, which indicates the horizontal coordinate of the start point. The value is an integer greater than or equal to 0.
starty	number	Yes	Number, which indicates the vertical coordinate of the start point. The value is an integer greater than or equal to 0.
endx	number	Yes	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
endy	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.swipe(100, 100, 200, 200, 600);
}

swipeBetween²⁰⁺

swipeBetween(from: Point, to: Point, speed?: number): Promise<void>

Swipes from the start coordinate point to the target coordinate point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Point object, which transfers the coordinates of the start point and the ID of the display to which the start point belongs.
to	Point	Yes	Point object, which transfers the coordinates of the target point and the ID of the display to which it belongs. Note: The target point and the start point must be on the same screen. Otherwise, the 17000007 exception is thrown.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, the 17000007 error code is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.swipeBetween({ x: 100, y: 100, displayId: 0 }, { x: 1000, y: 1000, displayId: 0 }, 800);
}

swipeBetween

swipeBetween(from: Point, to: Point, options?: TouchOptions): Promise<void>

Swipes from the start coordinate point to the target coordinate point. Touch options can be specified. This API uses a promise to return the result.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Point object, which transfers the coordinates of the start point and the ID of the display to which the start point belongs.
to	Point	Yes	Point object, which transfers the coordinates of the target point and the ID of the display to which it belongs. Note: The target point and the start point must be on the same screen. Otherwise, the 17000007 exception is thrown.
options	TouchOptions	No	Touch options. Only the speed and pressure properties in TouchOptions can be set. If other properties are set, the 17000007 parameter verification failure error is thrown. The default values are inherited from the default values of the properties in TouchOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, TouchOptions } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let options: TouchOptions = {
    speed: 800,   // Swipe speed: 800 px/s
    pressure: 0.5  // Touch pressure value.
  };
  // Swipes from the start coordinate point to the target coordinate point, and specifies the swipe speed and touch pressure.
  await driver.swipeBetween({ x: 100, y: 100, displayId: 0 }, { x: 1000, y: 1000, displayId: 0 }, options);
}

drag⁹⁺

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

Drags from the start coordinate point to the target coordinate point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
startx	number	Yes	Number, which indicates the horizontal coordinate of the start point. The value is an integer greater than or equal to 0.
starty	number	Yes	Number, which indicates the vertical coordinate of the start point. The value is an integer greater than or equal to 0.
endx	number	Yes	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
endy	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.drag(100, 100, 200, 200, 600);
}

dragBetween²⁰⁺

dragBetween(from: Point, to: Point, speed?: number, duration?: number): Promise<void>

Drags from the start point to the target point. You can specify the drag speed and the click duration before dragging. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Point object, which transfers the coordinates of the start point and the ID of the display to which the start point belongs.
to	Point	Yes	Point object, which transfers the coordinates of the target point and the ID of the display to which it belongs. Note: The target point and the start point must be on the same screen. Otherwise, the 17000007 exception is thrown.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, the 17000007 error code is returned.
duration	number	No	Click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.dragBetween({ x: 100, y: 100, displayId: 0 }, { x: 1000, y: 1000, displayId: 0 }, 800, 1500);
}

dragBetween

dragBetween(from: Point, to: Point, options?: TouchOptions): Promise<void>

Drags from the start coordinate point to the target coordinate point. Touch options can be specified. This API uses a promise to return the result.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Point object, which transfers the coordinates of the start point and the ID of the display to which the start point belongs.
to	Point	Yes	Point object, which transfers the coordinates of the target point and the ID of the display to which it belongs. Note: The target point and the start point must be on the same screen. Otherwise, the 17000007 exception is thrown.
options	TouchOptions	No	Touch options. Only the pressure, speed, and duration properties in TouchOptions can be set. If other properties are set, the 17000007 parameter verification failure error is thrown. The default values are inherited from the default values of the properties in TouchOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, TouchOptions } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let options: TouchOptions = {
    speed: 800,     // Drag speed: 800 px/s
    duration: 2000, // Click duration before dragging: 2000 ms.
    pressure: 0.5   // Touch pressure value.
  };
  // Drag from the start coordinate point to the target coordinate point, and specify the drag speed, click duration, and touch pressure.
  await driver.dragBetween({ x: 100, y: 100, displayId: 0 }, { x: 1000, y: 1000, displayId: 0 }, options);
}

screenCap⁹⁺

screenCap(savePath: string): Promise<boolean>

Captures the current screen and saves it as a PNG image to the given save path. This API uses a promise to return the result. This API can be used in scenarios where screenshots are supported.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
savePath	string	Yes	File save path. The path must be the sandbox path of the current application.

Return value

Type	Description
Promise<boolean>	Promise used to return whether the screenshot operation is successful. The value true indicates that the operation is successful, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

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

screenCap²⁰⁺

screenCap(savePath: string, displayId: number): Promise<boolean>

Captures the specified screen and saves it as a PNG image to the given save path. This API uses a promise to return the result. This API can be used in scenarios where screenshots are supported.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
savePath	string	Yes	File save path. The path must be the sandbox path of the current application.
displayId	number	Yes	Display ID. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported.

Return value

Type	Description
Promise<boolean>	Promise used to return whether the screenshot operation is successful. The value true indicates that the screen capture operation is successful, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.screenCap('/data/storage/el2/base/cache/1.png', 0);
}

dumpLayout

dumpLayout(savePath: string, displayId?: number): Promise<boolean>

Dumps the current layout information and saves it as a JSON file. This API uses a promise to return the result.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
savePath	string	Yes	Path for saving the JSON file. The path must be the sandbox directory of the current application.
displayId	number	No	Display ID. The default value is the display ID of the main screen.

Return value

Type	Description
Promise<boolean>	Promise used to return whether the layout information is successfully dumped and stored in the file storage. The value true indicates that the screen capture operation is successful, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  // Obtain the current layout information and save it as a JSON file.
  await driver.dumpLayout('/data/storage/el2/base/cache/layout.json', 0);
}

setDisplayRotation⁹⁺

setDisplayRotation(rotation: DisplayRotation): Promise<void>

Sets the display rotation of the current scene. This API uses a promise to return the result. It applies to rotatable scenarios.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

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

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, DisplayRotation } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.setDisplayRotation(DisplayRotation.ROTATION_180);
}

getDisplayRotation⁹⁺

getDisplayRotation(): Promise<DisplayRotation>

Obtains the display rotation of the current device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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	The API does not support concurrent calls.

Example

// xxx.test.ets
import { DisplayRotation, Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let rotation: DisplayRotation = await driver.getDisplayRotation();
}

getDisplayRotation²⁰⁺

getDisplayRotation(displayId: number): Promise<DisplayRotation>

Obtains the display rotation of the specified device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported.

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { DisplayRotation, Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let rotation: DisplayRotation = await driver.getDisplayRotation(0);
}

setDisplayRotationEnabled⁹⁺

setDisplayRotationEnabled(enabled: boolean): Promise<void>

Enables or disables display rotation. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
enabled	boolean	Yes	Whether the screen can be rotated. The value true indicates that the screen can be rotated, and false indicates the opposite.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.setDisplayRotationEnabled(false);
}

getDisplaySize⁹⁺

getDisplaySize(): Promise<Point>

Obtains the display size of the current device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Point>	Promise used to return the Point object. The size of the current device screen is Point.x * Point.y.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let size = await driver.getDisplaySize();
}

getDisplaySize²⁰⁺

getDisplaySize(displayId: number): Promise<Point>

Obtains the size of the specified display on the current device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported.

Return value

Type	Description
Promise<Point>	Promise used to return the Point object. The size of the specified display is Point.x * Point.y.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let size = await driver.getDisplaySize(0);
}

getDisplayDensity⁹⁺

getDisplayDensity(): Promise<Point>

Obtains the display density of the current device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<Point>	Promise used to return the Point object. The density of the current device display is Point.x*Point.y.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let density = await driver.getDisplayDensity();
}

getDisplayDensity²⁰⁺

getDisplayDensity(displayId: number): Promise<Point>

Obtains the density of the specified display of the current device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported.

Return value

Type	Description
Promise<Point>	Promise used to return the Point object. The density of the specified display is Point.x*Point.y.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let density = await driver.getDisplayDensity(0);
}

wakeUpDisplay⁹⁺

wakeUpDisplay(): Promise<void>

Wakes up the current display. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.wakeUpDisplay();
}

pressHome⁹⁺

pressHome(): Promise<void>

Injects an operation of returning to the home screen on the device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.pressHome();
}

pressHome²⁰⁺

pressHome(displayId: number): Promise<void>

Injects an operation of returning to the home screen on the specified display. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.pressHome(0);
}

waitForIdle⁹⁺

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

Checks whether all components on the current UI are idle. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
idleTime	number	Yes	Idle time threshold, in ms. If the duration for which a component remains inactive reaches this threshold, it is considered as idle. The value must be an integer greater than or equal to 0.
timeout	number	Yes	Maximum waiting time, in milliseconds. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<boolean>	Promise used to return whether all components on the current UI are idle. The value true indicates that all components on the current UI are idle, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let idled: boolean = await driver.waitForIdle(4000, 5000);
}

fling⁹⁺

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

Simulates a fling operation. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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	Step length, in pixels. The value is an integer greater than or equal to 0.
speed	number	Yes	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the range, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: 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-finger operation into a device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<boolean>	Promise used to return whether the operation is successful. The value true indicates that the operation is successful, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, PointerMatrix } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let pointers: PointerMatrix = PointerMatrix.create(2, 5);
  pointers.setPoint(0, 0, { x: 250, y: 480 });
  pointers.setPoint(0, 1, { x: 250, y: 440 });
  pointers.setPoint(0, 2, { x: 250, y: 400 });
  pointers.setPoint(0, 3, { x: 250, y: 360 });
  pointers.setPoint(0, 4, { x: 250, y: 320 });
  pointers.setPoint(1, 0, { x: 250, y: 480 });
  pointers.setPoint(1, 1, { x: 250, y: 440 });
  pointers.setPoint(1, 2, { x: 250, y: 400 });
  pointers.setPoint(1, 3, { x: 250, y: 360 });
  pointers.setPoint(1, 4, { x: 250, y: 320 });
  await driver.injectMultiPointerAction(pointers);
}

fling¹⁰⁺

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

Simulates a fling operation with the specified direction and speed. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
direction	UiDirection	Yes	Direction of the fling operation.
speed	number	Yes	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the range, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UiDirection } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.fling(UiDirection.DOWN, 10000);
}

fling²⁰⁺

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

Simulates a fling operation on a specified display with the specified direction and speed. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
direction	UiDirection	Yes	Direction of the fling operation.
speed	number	Yes	Fling speed, in px/s. The value ranges from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the range, the default value 600 is used. If the value is a negative number, error code 401 is returned.
displayId	number	Yes	Display ID. The value is an integer greater than or equal to 0. Note: If the input displayId does not exist, the exception 17000007 is reported.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UiDirection } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.fling(UiDirection.DOWN, 10000, 0);
}

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. This API uses a promise to return the result. This API can be used in scenarios where screenshots are supported.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
savePath	string	Yes	File save path. The path must be the sandbox path of the current application.
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 whether the screenshot operation is successful. The value true indicates the screenshot operation is successful, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: 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 action at the specified coordinates, with the optional key or key combination. This API uses a promise to return the result. For example, if the value of key1 is 2072, the Ctrl button is pressed with the mouse click.

Atomic service API: This API can be used in atomic services since API version 11.

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	First key value. For details about the value range, see KeyCode. The default value is 0.
key2	number	No	Second key value. For details about the value range, see KeyCode. The default value is 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, MouseButton } from '@kit.TestKit';

async function demo() {
  let driver: 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. This API uses a promise to return the result. For example, if the value of key1 is 2072, the Ctrl button is pressed with mouse scrolling.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
p	Point	Yes	Coordinates of the mouse click.
down	boolean	Yes	Whether the mouse wheel scrolls downward. The value true indicates the mouse wheel scrolls downward, and false indicates the mouse wheel scrolls upward.
d	number	Yes	Number of ticks scrolled by the mouse wheel. A tick indicates a 120 px shift to the target point. The value is an integer greater than or equal to 0.
key1	number	No	First key value. For details about the value range, see KeyCode. The default value is 0.
key2	number	No	Second key value. For details about the value range, see KeyCode. The default value is 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

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

mouseMoveTo¹⁰⁺

mouseMoveTo(p: Point): Promise<void>

Moves the mouse cursor to the target point. This API uses a promise to return the result.

System capability: SystemCapability.Test.UiTest

Atomic service API: This API can be used in atomic services since API version 11.

Parameters

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

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseMoveTo({ x: 100, y: 100 });
}

createUIEventObserver¹⁰⁺

createUIEventObserver(): UIEventObserver;

Creates a UI event listener.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
UIEventObserver	UI event listener.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.

Example

// xxx.test.ets
import { Driver, UIEventObserver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let observer: UIEventObserver = driver.createUIEventObserver();
}

mouseScroll¹¹⁺

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

Injects a mouse scroll action at the specified coordinates, with the optional key or key combination and the specified scroll speed. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
p	Point	Yes	Coordinates of the mouse click.
down	boolean	Yes	Whether the mouse wheel scrolls downward. The value true indicates the mouse wheel scrolls downward, and false indicates the mouse wheel scrolls upward.
d	number	Yes	Number of ticks scrolled by the mouse wheel. A tick indicates a 120 px shift to the target point. The value is an integer greater than or equal to 0.
key1	number	No	First key value. For details about the value range, see KeyCode. The default value is 0.
key2	number	No	Second key value. For details about the value range, see KeyCode. The default value is 0.
speed	number	No	Scrolling speed of the mouse wheel, in ticks/s. The value is an integer ranging from 1 to 500. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 20 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseScroll({ x: 360, y: 640 }, true, 30, 2072, 20);
}

mouseDoubleClick¹¹⁺

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

Injects a double-click action at the specified coordinates, with the optional key or key combination. This API uses a promise to return the result. For example, if the value of key is 2072, the Ctrl button is pressed with the double-click.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
p	Point	Yes	Coordinates of the double-click.
btnId	MouseButton	Yes	Mouse button pressed.
key1	number	No	First key value. For details about the value range, see KeyCode. The default value is 0.
key2	number	No	Second key value. For details about the value range, see KeyCode. The default value is 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, MouseButton } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseDoubleClick({ x: 248, y: 194 }, MouseButton.MOUSE_BUTTON_LEFT, 2072);
}

mouseLongClick¹¹⁺

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

Injects a mouse long-click action at the specified coordinates, with the optional key or key combination. This API uses a promise to return the result. For example, if the value of Key is 2072, the Ctrl button is long-clicked with the mouse device.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
p	Point	Yes	Coordinates of the long-click of the mouse device.
btnId	MouseButton	Yes	Mouse button pressed.
key1	number	No	First key value. For details about the value range, see KeyCode. The default value is 0.
key2	number	No	Second key value. For details about the value range, see KeyCode. The default value is 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, MouseButton } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseLongClick({ x: 248, y: 194 }, MouseButton.MOUSE_BUTTON_LEFT, 2072);
}

mouseLongClick²⁰⁺

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

Injects a mouse long-click action at the specified coordinates, with the optional key or key combination and the specified duration. This API uses a promise to return the result. For example, if the value of Key is 2072, the Ctrl button is long-clicked with the mouse device.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
p	Point	Yes	Coordinates of the long-click of the mouse device.
btnId	MouseButton	Yes	Mouse button pressed.
key1	number	No	First key value. For details about the value range, see KeyCode. The default value is 0.
key2	number	No	Second key value. For details about the value range, see KeyCode. The default value is 0.
duration	number	No	Long-click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, MouseButton } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseLongClick({ x: 248, y: 194 }, MouseButton.MOUSE_BUTTON_LEFT, 2072, 0, 2000);
}

mouseMoveWithTrack¹¹⁺

mouseMoveWithTrack(from: Point, to: Point, speed?: number): Promise<void>

Moves the mouse pointer from the start point to the end point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Coordinates of the start point.
to	Point	Yes	Coordinates of the end point.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseMoveWithTrack({ x: 100, y: 100 }, { x: 200, y: 200 }, 600);
}

mouseDrag¹¹⁺

mouseDrag(from: Point, to: Point, speed?: number): Promise<void>

Drags the mouse pointer from the start point to the end point. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Coordinates of the start point.
to	Point	Yes	Coordinates of the end point.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseDrag({ x: 100, y: 100 }, { x: 200, y: 200 }, 600);
}

mouseDrag²⁰⁺

mouseDrag(from: Point, to: Point, speed?: number, duration?: number): Promise<void>

Drags the mouse from the start point to the end point. You can specify the dragging speed and the duration before dragging. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Coordinates of the start point.
to	Point	Yes	Coordinates of the end point.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.
duration	number	No	Click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseDrag({ x: 100, y: 100 }, { x: 200, y: 200 }, 600, 2000);
}

mouseDrag

mouseDrag(from: Point, to: Point, touchOptions?: TouchOptions, keyOptions?: KeyOptions): Promise<void>

Drags from the start coordinate point to the end coordinate point by holding down the left mouse button. Touch options and key options can be specified. This API uses a promise to return the result.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Test.UiTest

Device behavior difference: This API takes effect only on phones, tablets, PCs/2-in-1 devices, and TVs.

Parameters

Name	Type	Mandatory	Description
from	Point	Yes	Coordinates of the start point.
to	Point	Yes	Coordinates of the end point.
touchOptions	TouchOptions	No	Touch options. Only the speed and duration properties in TouchOptions can be set. If other properties are set, the 17000007 parameter verification failure error is thrown. The default values are inherited from the default values of the properties in TouchOptions.
keyOptions	KeyOptions	No	Key options. This parameter is used to specify the keys to be clicked during the dragging. The default values are inherited from the default values of the properties in KeyOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, TouchOptions, KeyOptions } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let touchOptions: TouchOptions = {
    speed: 800,     // Drag speed: 800 px/s
    duration: 2000  // Click duration before dragging: 2000 ms.
  };
  let keyOptions: KeyOptions = {
    key1: 2072,  // Ctrl key
    key2: 2019   // C key
  };
  // Drag the mouse and press Ctrl+C.
  await driver.mouseDrag({ x: 100, y: 100 }, { x: 200, y: 200 }, touchOptions, keyOptions);
}

inputText¹¹⁺

inputText(p: Point, text: string): Promise<void>

Inputs text at a specified coordinate without clearing the original text in the component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
p	Point	Yes	Coordinates of the end point.
text	string	Yes	Input text. Currently, English, Chinese, and special characters are supported.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let text: Component = await driver.findComponent(ON.type('TextInput'));
  let point = await text.getBoundsCenter();
  await driver.inputText(point, '123');
}

inputText²⁰⁺

inputText(p: Point, text: string, mode: InputTextMode): Promise<void>

Inputs text at a specified coordinate point in a specified input mode. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
p	Point	Yes	Coordinates of the end point.
text	string	Yes	Input text. Currently, English, Chinese, and special characters are supported.
mode	InputTextMode	Yes	Text input mode. For details, see InputTextMode. NOTE If InputTextMode.addition is set to true, the cursor moves to the end of the text and the specified text is input. If the value is false, the specified text is input at the coordinate point.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not support, function can not work correctly due to limited device capabilities.

Example

// xxx.test.ets
import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let text: Component = await driver.findComponent(ON.type('TextInput'));
  let point = await text.getBoundsCenter();
  await driver.inputText(point, '123', { paste: true, addition: false });
}

async function demo_Chinese() {
  let driver: Driver = Driver.create();
  let text: Component = await driver.findComponent(ON.type('TextInput'));
  let point = await text.getBoundsCenter();
  await driver.inputText(point, 'Chinese&', { paste: false, addition: true });
  // Copy and paste Chinese and a special character to the end of the specified text.
}

touchPadMultiFingerSwipe¹⁸⁺

touchPadMultiFingerSwipe(fingers: number, direction: UiDirection, options?: TouchPadSwipeOptions): Promise<void>

Simulates a multi-finger swipe gesture on the touchpad. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Device behavior differences: This API can be properly called only on PCs/2-in-1 devices. If it is called on other device types, error code 17000005 is returned.

Parameters

Name	Type	Mandatory	Description
fingers	number	Yes	Number of fingers. The value can be 3 or 4.
direction	UiDirection	Yes	Swipe direction.
options	TouchPadSwipeOptions	No	Additional options for the multi-finger swipe gesture on the touchpad. The default values of the attributes in TouchPadSwipeOptions are used by default.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000005	This operation is not supported.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UiDirection } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.touchPadMultiFingerSwipe(3, UiDirection.UP);
}

touchPadTwoFingersScroll²²⁺

touchPadTwoFingersScroll(point: Point, direction: UiDirection, d: number, speed?: number): Promise<void>

Simulates a two-finger scroll gesture on the touchpad. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Device behavior differences: This API can be properly called only on PCs/2-in-1 devices. If it is called on other device types, error code 17000005 is returned.

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Point of the mouse cursor when the two-finger scrolling is performed on the touchpad.
direction	UiDirection	Yes	Direction of two-finger scrolling on the touchpad.
d	number	Yes	Number of grids scrolled by two fingers on the touchpad. A grid indicates a 120 px shift to the target point. The value is an integer greater than or equal to 0.
speed	number	No	Scrolling speed of two fingers on the touchpad, in ticks/s. The value is an integer ranging from 1 to 500. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 20 is used. If the value is a negative number, the 17000007 error code is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000005	This operation is not supported.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UiDirection } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.touchPadTwoFingersScroll({ x: 100, y: 100 }, UiDirection.UP, 20, 10);
}

penClick¹⁸⁺

penClick(point: Point): Promise<void>

Simulates a pen click operation. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Coordinates of the clicked point.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.penClick({ x: 100, y: 100 });
}

penLongClick¹⁸⁺

penLongClick(point: Point, pressure?: number): Promise<void>

Simulates a pen long-click operation. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Coordinates of the long-clicked point.
pressure	number	No	Swipe pressure of the pen. The value ranges from 0.0 to 1.0. The default value is 1.0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.penLongClick({ x: 100, y: 100 }, 0.5);
}

penDoubleClick¹⁸⁺

penDoubleClick(point: Point): Promise<void>

Simulates a pen double-click operation. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
point	Point	Yes	Coordinates of the double-clicked point.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.penDoubleClick({ x: 100, y: 100 });
}

penSwipe¹⁸⁺

penSwipe(startPoint: Point, endPoint: Point, speed?: number, pressure?: number): Promise<void>

Simulates a pen swipe operation. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
startPoint	Point	Yes	Coordinates of the start point.
endPoint	Point	Yes	Coordinates of the end point.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.
pressure	number	No	Swipe pressure of the pen. The value ranges from 0.0 to 1.0. The default value is 1.0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  await driver.penSwipe({ x: 100, y: 100 }, { x: 100, y: 500 }, 600, 0.5);
}

injectPenPointerAction¹⁸⁺

injectPenPointerAction(pointers: PointerMatrix, speed?: number, pressure?: number): Promise<void>

Simulates a continuous multi-point pen injection operation. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

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. Note: Currently, only the single-finger operation is supported. The value of fingers in PointerMatrix must be set to 1.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, error code 401 is returned.
pressure	number	No	Injection pressure. The value ranges from 0.0 to 1.0. The default value is 1.0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, PointerMatrix } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let pointer = PointerMatrix.create(1, 8);
  for (let step = 0; step < 8; step++) {
    pointer.setPoint(0, step, { x: 500, y: 1100 - 100 * step });
  }
  await driver.injectPenPointerAction(pointer, 600, 0.5);
}

crownRotate²⁰⁺

crownRotate(d: number, speed?: number): Promise<void>

Injects a crown rotation event. You can specify the rotation speed. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Device behavior differences: This API can be properly called on wearables. If it is called on other device types, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
d	number	Yes	Number of rotation ticks. A positive value indicates rotation, and a negative value indicates counterclockwise rotation. The value must be an integer.
speed	number	No	Rotation speed, in ticks/s. The value is an integer ranging from 1 to 500. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 20 is used. If the value is a negative number, the 17000007 error code is returned. Note: If the set value is not in the range, the default value 20 is used.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.
801	Capability not support, function can not work correctly due to limited device capabilities.

Example

// xxx.test.ets
import { Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  // Rotate 50 ticks clockwise at a speed of 30 ticks per second.
  await driver.crownRotate(50, 30);
  // Rotate 20 ticks counterclockwise at a speed of 30 ticks per second.
  await driver.crownRotate(-20, 30);
}

knuckleKnock²²⁺

knuckleKnock(pointers: Array<Point>, times: number): Promise<void>

Simulates a knuckle knock on the display. This API uses a promise to return the result.

NOTE

If the knuckle gesture is disabled on the device, 17000005 is returned.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Device behavior differences: This API can be properly called on phones and tablets that support knuckle operations. On other devices, the error code 17000005 is returned.

Parameters

Name	Type	Mandatory	Description
pointers	Array<Point>	Yes	Array of knuckle knock coordinates on the display. The array length can be 1 or 2.
times	number	Yes	Number of consecutive knocks on the display. The value can be 1 or 2.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000005	This operation is not supported.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, Point } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  // Simulate a single-knuckle double-knock gesture.
  let points: Array<Point> = [{ x: 100, y: 100 }];
  await driver.knuckleKnock(points, 2);
}

injectKnucklePointerAction²²⁺

injectKnucklePointerAction(pointers: PointerMatrix, speed?: number): Promise<void>

Simulates a multi-point knuckle scrolling operation. This API uses a promise to return the result.

NOTE

If the knuckle gesture is disabled on the device, 17000005 is returned.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Device behavior differences: This API can be properly called on phones and tablets that support knuckle operations. On other devices, the error code 17000005 is returned.

Parameters

Name	Type	Mandatory	Description
pointers	PointerMatrix	Yes	Scroll trajectory, including the number of fingers and an array of coordinates along the trajectory. Note: Currently, only the single-finger operation is supported. The value of fingers in PointerMatrix must be set to 1.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, the 17000007 error code is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000005	This operation is not supported.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, PointerMatrix } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  // Simulate a knuckle gesture to draw an S on the display.
  let pointers: PointerMatrix = PointerMatrix.create(1, 6);
  pointers.setPoint(0, 0, { x: 750, y: 300 });
  pointers.setPoint(0, 1, { x: 500, y: 100 });
  pointers.setPoint(0, 2, { x: 250, y: 300 });
  pointers.setPoint(0, 3, { x: 750, y: 800 });
  pointers.setPoint(0, 4, { x: 500, y: 1000 });
  pointers.setPoint(0, 5, { x: 250, y: 800 });
  await driver.injectKnucklePointerAction(pointers);
}

isComponentPresentWhenLongClick²²⁺

isComponentPresentWhenLongClick(on: On, point: Point, duration?: number): Promise<boolean>

Long-clicks at the specified coordinates and checks whether the target component exists. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
on	On	Yes	Attributes of the target component.
point	Point	Yes	Coordinates of the long-clicked point.
duration	number	No	Long-click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.

Return value

Type	Description
Promise<boolean>	Promise used to return whether the target component exists during a long-click operation. The value true indicates that the target component exists, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let isExist = await driver.isComponentPresentWhenLongClick(ON.id('123'), { x: 100, y: 100 }, 2000);
}

isComponentPresentWhenDrag²²⁺

isComponentPresentWhenDrag(on: On, from: Point, to: Point, speed?: number, duration?: number): Promise<boolean>

Drags from the start point to the end point and checks whether the target component exists. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
on	On	Yes	Attributes of the target component.
from	Point	Yes	Point object, which transfers the coordinates of the start point and the ID of the display to which the start point belongs.
to	Point	Yes	Point object, which transfers the coordinates of the target point and the ID of the display to which it belongs. Note: The target point and the start point must be on the same screen. Otherwise, the 17000007 exception is thrown.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, the 17000007 error code is returned.
duration	number	No	Click duration, in ms. The value is an integer greater than or equal to 1500. The default value is 1500.

Return value

Type	Description
Promise<boolean>	Promise used to return whether the target component exists during the dragging operation. The value true indicates that the target component exists, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let isExist = await driver.isComponentPresentWhenDrag(ON.id('123'), { x: 100, y: 100 }, { x: 200, y: 200 }, 1000, 2000);
}

isComponentPresentWhenSwipe²²⁺

isComponentPresentWhenSwipe(on: On, from: Point, to: Point, speed?: number): Promise<boolean>

Swipes from the start point to the end point and checks whether the target component exists. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
on	On	Yes	Attributes of the target component.
from	Point	Yes	Point object, which transfers the coordinates of the start point and the ID of the display to which the start point belongs.
to	Point	Yes	Point object, which transfers the coordinates of the target point and the ID of the display to which it belongs. Note: The target point and the start point must be on the same screen. Otherwise, the 17000007 exception is thrown.
speed	number	No	Swipe speed, in px/s. The value is an integer ranging from 200 to 40000. The default value is 600. If the value is a non-negative number that is not within the specified range or is null or undefined, the default value 600 is used. If the value is a negative number, the 17000007 error code is returned.

Return value

Type	Description
Promise<boolean>	Promise used to return whether the target component exists during the swiping operation. The value true indicates that the target component exists, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let isExist = await driver.isComponentPresentWhenSwipe(ON.id('123'), { x: 100, y: 100 }, { x: 200, y: 200 }, 1000);
}

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.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
fingers	number	Yes	Number of fingers injected during the multi-finger operation. The value is an integer ranging from 1 to 10.
steps	number	Yes	Number of steps performed by a finger. The value is an integer ranging from 1 to 1000.

Return value

Type	Description
PointerMatrix	PointerMatrix object created.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { PointerMatrix } from '@kit.TestKit';

async function demo() {
  let pointerMatrix: 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.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
finger	number	Yes	Number of fingers. The value is an integer greater than or equal to 0 and cannot exceed the number of fingers set when the PointerMatrix object is constructed.
step	number	Yes	Number of steps. The value is an integer greater than or equal to 0 and cannot exceed the number of steps set when the PointerMatrix object is constructed.
point	Point	Yes	Coordinates of the action. It is recommended that the distance between adjacent coordinates be within the range of 10 px to 80 px.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { PointerMatrix } from '@kit.TestKit';

async function demo() {
  let pointers: PointerMatrix = PointerMatrix.create(2, 5);
  pointers.setPoint(0, 0, { x: 250, y: 480 });
  pointers.setPoint(0, 1, { x: 250, y: 440 });
  pointers.setPoint(0, 2, { x: 250, y: 400 });
  pointers.setPoint(0, 3, { x: 250, y: 360 });
  pointers.setPoint(0, 4, { x: 250, y: 320 });
  pointers.setPoint(1, 0, { x: 250, y: 480 });
  pointers.setPoint(1, 1, { x: 250, y: 440 });
  pointers.setPoint(1, 2, { x: 250, y: 400 });
  pointers.setPoint(1, 3, { x: 250, y: 360 });
  pointers.setPoint(1, 4, { x: 250, y: 320 });
}

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 a window belongs. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<string>	Promise used to return the bundle name of the application to which the window belongs.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  let name: string = await window.getBundleName();
}

getBounds⁹⁺

getBounds(): Promise<Rect>

Obtains the bounds information of a window. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  let rect = await window.getBounds();
}

getTitle⁹⁺

getTitle(): Promise<string>

Obtains the window title. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  let title = await window.getTitle();
}

getWindowMode⁹⁺

getWindowMode(): Promise<WindowMode>

Obtains the window mode. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  let mode = await window.getWindowMode();
}

isFocused⁹⁺

isFocused(): Promise<boolean>

Checks whether a window is focused. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return whether the window is focused. The value true indicates that the component is focused, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  let focused = await window.isFocused();
}

isActived^(deprecated)

isActived(): Promise<boolean>

Checks whether a window is active. This API uses a promise to return the result.

NOTE

This API is supported since API version 9 and deprecated since API version 11. You are advised to use isActive¹¹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return whether the window is active. The value true indicates that the window is active, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  let focused = await window.isActived();
}

focus⁹⁺

focus(): Promise<void>

Focuses a window. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  await window.focus();
}

moveTo⁹⁺

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

Moves a window to the target point. This API uses a promise to return the result. This API is applicable to moveable windows.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device differences: In API version 22 and earlier versions, this API can be called on PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices. Since API version 23, this API can be called on phones, PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices.

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
y	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
17000005	This operation is not supported.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  await window.moveTo(100, 100);
}

resize⁹⁺

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

Resizes a window based on the specified width, height, and direction. This API uses a promise to return the result. This API is applicable to resizable windows.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device differences: In API version 22 and earlier versions, this API can be called on PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices. Since API version 23, this API can be called on phones, PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices.

Parameters

Name	Type	Mandatory	Description
wide	number	Yes	Width of the adjusted window, in number format. The value is an integer greater than or equal to 0.
height	number	Yes	Height of the adjusted window, in number format. The value is an integer greater than or equal to 0.
direction	ResizeDirection	Yes	Resize direction.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
17000005	This operation is not supported.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

// xxx.test.ets
import { Driver, ResizeDirection, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  await window.resize(100, 100, ResizeDirection.LEFT);
}

split⁹⁺

split(): Promise<void>

Switches to the split-screen mode. This API uses a promise to return the result. This API is applicable to windows that support screen splitting.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device differences: In API version 22 and earlier versions, this API can be called on PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices. Since API version 23, this API can be called on phones, PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
17000005	This operation is not supported.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  await window.split();
}

maximize⁹⁺

maximize(): Promise<void>

Maximizes a window. This API uses a promise to return the result. This API is applicable to windows that can be maximized.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device differences: In API version 22 and earlier versions, this API can be called on PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices. Since API version 23, this API can be called on phones, PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
17000005	This operation is not supported.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  await window.maximize();
}

minimize⁹⁺

minimize(): Promise<void>

Minimizes a window. This API uses a promise to return the result. This API is applicable to windows that can be minimized.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device differences: In API version 22 and earlier versions, this API can be called on PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices. Since API version 23, this API can be called on phones, PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
17000005	This operation is not supported.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  await window.minimize();
}

resume⁹⁺

resume(): Promise<void>

Resumes a window to its previous mode. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device differences: In API version 22 and earlier versions, this API can be called on PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices. Since API version 23, this API can be called on phones, PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
17000005	This operation is not supported.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  await window.resume();
}

close⁹⁺

close(): Promise<void>

Closes a window. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Device differences: In API version 22 and earlier versions, this API can be called on PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices. Since API version 23, this API can be called on phones, PCs, 2-in-1 devices, and tablets, and returns the error code 17000005 on other devices.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.
17000005	This operation is not supported.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ actived: true });
  await window.close();
}

isActive¹¹⁺

isActive(): Promise<boolean>

Checks whether a window is active. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<boolean>	Promise used to return whether the window is active. The value true indicates that the window is active, and false indicates the opposite.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { Driver, UiWindow } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ active: true });
  let focused = await window.isActive();
}

getDisplayId²⁰⁺

getDisplayId(): Promise<number>

Obtains the ID of the display to which a window belongs. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<number>	Promise used to return the ID of the display to which the window belongs.

Error codes

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

ID	Error Message
17000002	The API does not support concurrent calls.
17000004	The window or component is invisible or destroyed.

Example

// xxx.test.ets
import { UiWindow, Driver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({ active: true });
  let id = await window.getDisplayId();
}

UIEventObserver¹⁰⁺

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.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let observer: UIEventObserver = 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.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let observer: UIEventObserver = driver.createUIEventObserver();
  let callback = (UIElementInfo: UIElementInfo) => {
    console.info(UIElementInfo.bundleName);
    console.info(UIElementInfo.text);
    console.info(UIElementInfo.type);
  }
  observer.once('dialogShow', callback);
}

once('windowChange')²²⁺

once(type: 'windowChange', windowChangeType: WindowChangeType, options: WindowChangeOptions, callback: Callback<UIElementInfo>): void

Starts listening for window change events of the specified type with extended configuration supported. This API triggers a callback when a specified window change event is detected. This API can be used only in free windows mode.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to subscribe to, which can be windowChange. This event is triggered when the window changes.
windowChangeType	WindowChangeType	Yes	Type of the window change event.
options	WindowChangeOptions	Yes	Extended configuration, including the listening timeout interval and the bundle name of the window to be listened for.
callback	Callback<UIElementInfo>	Yes	Callback triggered to return event information when an event occurs.

Error codes

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

ID	Error Message
17000005	This operation is not supported.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UIElementInfo, UIEventObserver, WindowChangeOptions, WindowChangeType } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let observer: UIEventObserver = driver.createUIEventObserver();
  let options: WindowChangeOptions = {
    timeout: 20000,
    bundleName: 'com.example.myapplication'  // Use the actual bundle name.
  }
  let callback = (UIElementInfo: UIElementInfo) => {
    console.info(UIElementInfo.bundleName);
    console.info(UIElementInfo.text);
    console.info(UIElementInfo.type);
    console.info(UIElementInfo.windowChangeType?.toString());
    console.info(UIElementInfo.windowId?.toString());
  }
  observer.once('windowChange', WindowChangeType.WINDOW_ADDED, options, callback);
}

once('componentEventOccur')²²⁺

once(type: 'componentEventOccur', componentEventType: ComponentEventType, options: ComponentEventOptions, callback: Callback<UIElementInfo>): void

Starts listening for component operation events of the specified type with extended configuration supported. This API triggers a callback when a specified component operation event is detected.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Test.UiTest

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to subscribe to, which can be componentEventOccur. This event is triggered when the component operation is detected.
componentEventType	ComponentEventType	Yes	Type of the component operation event.
options	ComponentEventOptions	Yes	Extended configuration, including the listening timeout interval and the matching condition of the component to be listened for.
callback	Callback<UIElementInfo>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
17000005	This operation is not supported.
17000007	Parameter verification failed.

Example

// xxx.test.ets
import { Driver, UIElementInfo, UIEventObserver, ComponentEventOptions, ComponentEventType, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let observer: UIEventObserver = driver.createUIEventObserver();
  let option: ComponentEventOptions = {
    timeout: 20000,
    on: ON.id('123')  // Use the actual component ID.
  };
  let callback = (UIElementInfo: UIElementInfo) => {
    console.info(UIElementInfo.bundleName);
    console.info(UIElementInfo.text);
    console.info(UIElementInfo.type);
    console.info(UIElementInfo.componentEventType?.toString());
    console.info(UIElementInfo.windowId?.toString());
    console.info(UIElementInfo.componentId);
    console.info(UIElementInfo.componentRect?.left.toString());
    console.info(UIElementInfo.componentRect?.top.toString());
    console.info(UIElementInfo.componentRect?.right.toString());
    console.info(UIElementInfo.componentRect?.bottom.toString());
  };
  observer.once('componentEventOccur', ComponentEventType.COMPONENT_CLICKED, option, 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 APIs provided by the By class exhibit the following features:
1. Allow one or more attributes as the match conditions. For example, you can specify both the text and id attributes to find the target component.
2. Provide multiple match patterns for component attributes.
3. 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.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use On⁹⁺ instead.

// xxx.test.ets
import { BY } from '@kit.TestKit';

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.

NOTE

This API is supported since API version 8 and 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

// xxx.test.ets
import { BY, By } from '@kit.TestKit';

let by: 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.

NOTE

This API is supported since API version 8 and 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

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

let by: 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.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use id⁹⁺ instead.

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

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

let by: 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.

NOTE

This API is supported since API version 8 and 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

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

let by: 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 attribute of the target component.

NOTE

This API is supported since API version 8 and 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 component. The value true indicates that the component is clickable, and false indicates the opposite. Default value: true

Return value

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

Example

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

let by: By = BY.clickable(true); // Use the static constructor BY to create a By object and specify the clickable attribute of the target component.

scrollable^(deprecated)

scrollable(b?: boolean): By

Specifies the scrollable attribute of the target component.

NOTE

This API is supported since API version 8 and 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 component. The value true indicates that the component is scrollable, and false indicates the opposite. Default value: true

Return value

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

Example

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

let by: By = BY.scrollable(true); // Use the static constructor BY to create a By object and specify the scrollable attribute of the target component.

enabled^(deprecated)

enabled(b?: boolean): By

Specifies the enabled attribute of the target component.

NOTE

This API is supported since API version 8 and 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 component. The value true indicates that the component is enabled, and false indicates the opposite. Default value: true

Return value

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

Example

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

let by: By = BY.enabled(true); // Use the static constructor BY to create a By object and specify the enabled attribute of the target component.

focused^(deprecated)

focused(b?: boolean): By

Specifies the focused attribute of the target component.

NOTE

This API is supported since API version 8 and 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 component. The value true indicates that the component is focused, and false indicates the opposite. Default value: true

Return value

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

Example

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

let by: By = BY.focused(true); // Use the static constructor BY to create a By object and specify the focused attribute of the target component.

selected^(deprecated)

selected(b?: boolean): By

Specifies the selected status of the target component.

NOTE

This API is supported since API version 8 and 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 component. The value true indicates that the component is selected, and false indicates the opposite. Default value: true

Return value

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

Example

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

let by: By = BY.selected(true); // Use the static constructor BY to create a By object and specify the selected attribute of the target component.

isBefore^(deprecated)

isBefore(by: By): By

Specifies that the target component is located before the given attribute component.

NOTE

This API is supported since API version 8 and 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

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

// Use the static constructor BY to create a by object and specify that the target component is located before the given attribute component.
let by: By = BY.type('Button').isBefore(BY.text('123')); // Search for the first Button component located before the component whose text is 123.

isAfter^(deprecated)

isAfter(by: By): By

Specifies that the target component is located after the given attribute component.

NOTE

This API is supported since API version 8 and 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

// xxx.test.ets
import { By, BY } from '@kit.TestKit';

// Use the static constructor BY to create a by object and specify that the target component is located after the given attribute component.
let by: By = BY.type('Text').isAfter(BY.text('123')); // Search for the first Text component located after the component whose text is 123.

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.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use Component⁹⁺ instead.

click^(deprecated)

click(): Promise<void>

Clicks this component. This API uses a promise to return the result.

NOTE

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

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver, BY, Driver, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = await driver.findComponent(BY.type('Button'));
  await button.click();
}

doubleClick^(deprecated)

doubleClick(): Promise<void>

Double-clicks this component. This API uses a promise to return the result.

NOTE

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

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = await driver.findComponent(BY.type('Button'));
  await button.doubleClick();
}

longClick^(deprecated)

longClick(): Promise<void>

Long-clicks this component. This API uses a promise to return the result.

NOTE

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

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = await driver.findComponent(BY.type('Button'));
  await button.longClick();
}

getId^(deprecated)

getId(): Promise<number>

Obtains the ID of this component. This API uses a promise to return the result.

NOTE

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

System capability: SystemCapability.Test.UiTest

Return value

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

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = await driver.findComponent(BY.type('Button'));
  let id = await button.getId();
}

getKey^(deprecated)

getKey(): Promise<string>

Obtains the key of this component. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 value.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = await driver.findComponent(BY.type('Button'));
  let text = await button.getText();
}

getType^(deprecated)

getType(): Promise<string>

Obtains the type of this component. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 component type.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 whether the component is clickable. The value true indicates that the component is clickable, and false indicates the opposite.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 whether the component is scrollable. The value true indicates that the component is scrollable, and false indicates the opposite.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let scrollBar: UiComponent = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 whether the component is enabled. The value true indicates that the component is enabled, and false indicates the opposite.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 whether the component is focused. The value true indicates that the component is focused, and false indicates the opposite.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 whether the component is selected. The value true indicates that the component is selected, and false indicates the opposite.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = 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>

Inputs text to a component. This API takes effect only for editable text components. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let text: UiComponent = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let scrollBar: UiComponent = 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 UiDriver.create(), use a promise to return the result and must be invoked using await.

NOTE

This API is supported since API version 8 and 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.

NOTE

This method is supported since API version 8 and deprecated since API version 9. You are advised to use create⁹⁺ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
UiDriver	UiDriver object created.

Example

// xxx.test.ets
import { UiDriver } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
}

delayMs^(deprecated)

delayMs(duration: number): Promise<void>

Delays this UiDriver object within the specified duration. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 component.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let button: UiComponent = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 the list of components.

Example

// xxx.test.ets
import { UiDriver, BY, UiComponent } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  let buttonList: Array<UiComponent> = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
401	if the input parameters are invalid.
17000002	The API does not support concurrent calls.
17000003	if the assertion failed.

Example

// xxx.test.ets
import { UiDriver, BY } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  await driver.assertComponentExist(BY.text('next page'));
}

pressBack^(deprecated)

pressBack(): Promise<void>

Presses the Back button on this UiDriver object. This API uses a promise to return the result.

NOTE

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

System capability: SystemCapability.Test.UiTest

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 value. For details about the value range, see KeyCode.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { Driver, UiDriver } from '@kit.TestKit';
import { KeyCode } from '@kit.InputKit';

async function demo() {
  let driver: UiDriver = UiDriver.create();
  await driver.triggerKey(KeyCode.KEYCODE_BACK); // Back button
}

click^(deprecated)

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

Clicks a specific point of this UiDriver object based on the given coordinates. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
y	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
y	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
y	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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	Number, which indicates the horizontal coordinate of the start point. The value is an integer greater than or equal to 0.
starty	number	Yes	Number, which indicates the vertical coordinate of the start point. The value is an integer greater than or equal to 0.
endx	number	Yes	Number, which indicates the horizontal coordinate of the target point. The value is an integer greater than or equal to 0.
endy	number	Yes	Number, which indicates the vertical coordinate of the target point. The value is an integer greater than or equal to 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

// xxx.test.ets
import { UiDriver } from '@kit.TestKit';

async function demo() {
  let driver: UiDriver = 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 uses a promise to return the result.

NOTE

This API is supported since API version 8 and 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 whether the screenshot operation is successful. The value true indicates the screenshot operation is successful, and false indicates the opposite.

Example

// xxx.test.ets
import { UiDriver } from '@kit.TestKit';

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