@ohos.UiTest

The UiTest module provides APIs that you can use to simulate UI actions during testing, such as clicks, double-clicks, long-clicks, and swipes.

This module provides the following functions:

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

NOTE

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

Modules to Import

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

MatchPattern

Enumerates the match patterns supported for component attributes.

System capability: SystemCapability.Test.UiTest

Name Value Description
EQUALS 0 Equals the given value.
CONTAINS 1 Contains the given value.
STARTS_WITH 2 Starts with the given value.
ENDS_WITH 3 Ends with the given value.

ResizeDirection9+

Enumerates the directions in which a window can be resized.

System capability: SystemCapability.Test.UiTest

Name Value Description
LEFT 0 Left.
RIGHT 1 Right.
UP 2 Up.
DOWN 3 Down.
LEFT_UP 4 Upper left.
LEFT_DOWN 5 Lower left.
RIGHT_UP 6 Upper right.
RIGHT_DOWN 7 Lower right.

Point9+

Provides the coordinates of a point.

System capability: SystemCapability.Test.UiTest

Name Type Readable Writable Description
x number Yes No X coordinate of a point.
y number Yes No Y coordinate of a point.

Rect9+

Provides bounds information of a component.

System capability: SystemCapability.Test.UiTest

Name Type Readable Writable Description
left number Yes No X coordinate of the upper left corner of the component bounds.
top number Yes No Y coordinate of the upper left corner of the component bounds.
right number Yes No X coordinate of the lower right corner of the component bounds.
bottom number Yes No Y coordinate of the lower right corner of the component bounds.

WindowMode9+

Enumerates the window modes.

System capability: SystemCapability.Test.UiTest

Name Value Description
FULLSCREEN 0 Full-screen mode.
PRIMARY 1 Primary window mode.
SECONDARY 2 Secondary window mode.
FLOATING 3 Floating window mode.

DisplayRotation9+

Describes the display rotation of the device.

System capability: SystemCapability.Test.UiTest

Name Value Description
ROTATION_0 0 The device display is not rotated and is in its original vertical orientation.
ROTATION_90 1 The device display rotates 90° clockwise and is in landscape orientation.
ROTATION_180 2 The device display rotates 180° clockwise and is in reverse vertical orientation.
ROTATION_270 3 The device display rotates 270° clockwise and is in reverse landscape orientation.

WindowFilter9+

Provides the flag attributes of this window.

System capability: SystemCapability.Test.UiTest

Name Type Readable Writable Description
bundleName string Yes No Bundle name of the application to which the window belongs.
title string Yes No Title of the window.
focused boolean Yes No Whether the window is in focused state.
actived boolean Yes No Whether the window is interacting with the user.

UiDirection10+

Describes the direction of a UI operation such as fling.

System capability: SystemCapability.Test.UiTest

Name Value Description
LEFT 0 Leftward.
RIGHT 1 Rightward.
UP 2 Upward.
DOWN 3 Downward.

MouseButton10+

Describes the injected simulated mouse button.

System capability: SystemCapability.Test.UiTest

Name Value Description
MOUSE_BUTTON_LEFT 0 Left button on the mouse.
MOUSE_BUTTON_RIGHT 1 Right button on the mouse.
MOUSE_BUTTON_MIDDLE 2 Middle button on the mouse.

UIElementInfo10+

Provides information about the UI event.

System capability: SystemCapability.Test.UiTest

Name Type Readable Writable Description
bundleName string Yes No Bundle name of the home application.
type string Yes No Component or window type.
text string Yes No Text information of the component or window.

On9+

Since API version 9, the UiTest framework provides a wide range of UI component feature description APIs in the On class to filter and match components.

The APIs provided by the On class exhibit the following features:

  • Allow one or more attributes as the match conditions. For example, you can specify both the text and id attributes to find the target component.
  • Provide multiple match patterns for component attributes.
  • Support absolute positioning and relative positioning for components. APIs such as ON.isBefore and ON.isAfter can be used to specify the features of adjacent components to assist positioning.

All APIs provided in the On class are synchronous. You are advised to use the static constructor ON to create an On object in chain mode.

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

text9+

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

Specifies the text attribute of the target component. Multiple match patterns are supported.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Example

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

id9+

id(id: string): On

Specifies the ID attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
id string Yes Component ID.

Return value

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

Example

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

type9+

type(tp: string): On

Specifies the type attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
tp string Yes Component type.

Return value

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

Example

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

clickable9+

clickable(b?: boolean): On

Specifies the clickable attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Clickable status of the target component.
true: clickable.
false: not clickable.
Default value: true

Return value

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

Example

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

longClickable9+

longClickable(b?: boolean): On

Specifies the long-clickable attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Long-clickable status of the target component.
true: long-clickable.
false: not long-clickable.
Default value: true

Return value

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

Example

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

scrollable9+

scrollable(b?: boolean): On

Specifies the scrollable attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Scrollable status of the target component.
true: scrollable.
false: not scrollable.
Default value: true

Return value

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

Example

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

enabled9+

enabled(b?: boolean): On

Specifies the enabled attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Enabled status of the target component.
true: enabled.
false: not enabled.
Default value: true

Return value

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

Example

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

focused9+

focused(b?: boolean): On

Specifies the focused attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Focused status of the target component.
true: focused.
false: not focused.
Default value: true

Return value

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

Example

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

selected9+

selected(b?: boolean): On

Specifies the selected attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Selected status of the target component.
true: selected.
false: not selected.
Default value: true

Return value

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

Example

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

checked9+

checked(b?: boolean): On

Specifies the checked attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Checked status of the target component.
true: checked.
false: not checked.
Default value: false

Return value

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

Example

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

checkable9+

checkable(b?: boolean): On

Specifies the checkable attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Checkable status of the target component.
true: checkable.
false: not checkable.
Default value: false

Return value

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

Example

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

isBefore9+

isBefore(on: On): On

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

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
on On Yes Information about the attribute component.

Return value

Type Description
On On object.

Example

import { On, ON } from '@ohos.UiTest';

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

isAfter9+

isAfter(on: On): On

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

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
on On Yes Information about the attribute component.

Return value

Type Description
On On object.

Example

import { On, ON } from '@ohos.UiTest';

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

within10+

within(on: On): On

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

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
on On Yes Information about the attribute component.

Return value

Type Description
On On object.

Example

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

inWindow10+

inWindow(bundleName: string): On;

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

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
bundleName string Yes Bundle name of the application window.

Return value

Type Description
On On object.

Example

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

Component9+

Represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection.

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

click9+

click(): Promise<void>

Clicks this component.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

doubleClick9+

doubleClick(): Promise<void>

Double-clicks this component.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

longClick9+

longClick(): Promise<void>

Long-clicks this component.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

getId9+

getId(): Promise<string>

Obtains the ID of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

getText9+

getText(): Promise<string>

Obtains the text information of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

getType9+

getType(): Promise<string>

Obtains the type of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

getBounds9+

getBounds(): Promise<Rect>

Obtains the bounds of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

getBoundsCenter9+

getBoundsCenter(): Promise<Point>

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

System capability: SystemCapability.Test.UiTest

Return value

Type Description
Promise<Point> Promise used to return the information about the center of the bounding box around the component.

Error codes

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

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

Example

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

isClickable9+

isClickable(): Promise<boolean>

Obtains the clickable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

isLongClickable9+

isLongClickable(): Promise<boolean>

Obtains the long-clickable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

import { Component, Driver, ON } from '@ohos.UiTest';
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 can longClick');
  } else {
    console.info('This button can not longClick');
  }
}

isChecked9+

isChecked(): Promise<boolean>

Obtains the checked status of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

isCheckable9+

isCheckable(): Promise<boolean>

Obtains the checkable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

isScrollable9+

isScrollable(): Promise<boolean>

Obtains the scrollable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

isEnabled9+

isEnabled(): Promise<boolean>

Obtains the enabled status of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

isFocused9+

isFocused(): Promise<boolean>

Obtains the focused status of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

isSelected9+

isSelected(): Promise<boolean>

Obtains the selected status of this component.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

inputText9+

inputText(text: string): Promise<void>

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

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
text string Yes Text to enter, which can contain English and special characters.

Error codes

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

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

Example

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

clearText9+

clearText(): Promise<void>

Clears text in this component. This API is applicable to text boxes.

System capability: SystemCapability.Test.UiTest

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

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

Example

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

scrollSearch9+

scrollSearch(on: On): Promise<Component>

Scrolls on this component to search for the target component. This API is applicable to components that support scrolling.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Error codes

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

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

Example

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

scrollToTop9+

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

Scrolls to the top of this component. This API is applicable to components that support scrolling.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
speed number No Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.

Error codes

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

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

Example

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

scrollToBottom9+

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

Scrolls to the bottom of this component. This API is applicable to components that support scrolling.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
speed number No Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.

Error codes

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

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

Example

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

dragTo9+

dragTo(target: Component): Promise<void>

Drags this component to the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
target Component Yes Target component.

Error codes

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

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

Example

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

pinchOut9+

pinchOut(scale: number): Promise<void>

Pinches a component to scale it up to the specified ratio.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
scale number Yes Scale factor.

Error codes

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

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

Example

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

pinchIn9+

pinchIn(scale: number): Promise<void>

Pinches a component to scale it down to the specified ratio.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
scale number Yes Scale factor.

Error codes

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

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

Example

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

Driver9+

The Driver class is the main entry to the UiTest framework. It provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot.

All APIs provided by this class, except Driver.create(), use a promise to return the result and must be invoked using await.

create9+

static create(): Driver

Creates a Driver object and returns the object created. This API is a static API.

System capability: SystemCapability.Test.UiTest

Return value

Type Description
Driver Driver object created.

Error codes

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

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

Example

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

delayMs9+

delayMs(duration: number): Promise<void>

Delays this Driver object within the specified duration.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
duration number Yes Duration of time, in ms.

Error codes

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

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

Example

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

findComponent9+

findComponent(on: On): Promise<Component>

Searches this Driver object for the target component that matches the given attributes.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Error codes

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

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

Example

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

findComponents9+

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

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

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Error codes

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

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

Example

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

findWindow9+

findWindow(filter: WindowFilter): Promise<UiWindow>

Searches for the window that matches the specified attributes.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Error codes

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

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

Example

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

waitForComponent9+

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

Searches this Driver object for the target component that matches the given attributes within the specified duration.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
On On Yes Attributes of the target component.
time number Yes Duration for searching for the target component, in ms.

Return value

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

Error codes

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

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

Example

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

assertComponentExist9+

assertComponentExist(on: On): Promise<void>

Asserts that a component that matches the given attributes exists on the current page.

System capability: SystemCapability.Test.UiTest

Parameters

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

Error codes

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

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

Example

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

pressBack9+

pressBack(): Promise<void>

Presses the Back button on this Driver object.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

triggerKey9+

triggerKey(keyCode: number): Promise<void>

Triggers the key of this Driver object that matches the given key code.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
keyCode number Yes Key code.

Error codes

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

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

Example

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

triggerCombineKeys9+

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

Triggers a key combination based on the specified key values. For example, if the value of Key is (2072, 2019), the Driver object finds and clicks the key combination that matches the value, for example, Ctrl+C.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
key0 number Yes The first key value.
key1 number Yes The second key value.
key2 number No The third key value.

Error codes

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

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

Example

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

click9+

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

Clicks a specific point of this Driver object based on the given coordinates.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
x number Yes X coordinate of the target point.
y number Yes Y coordinate of the target point.

Error codes

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

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

Example

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

doubleClick9+

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

Double-clicks a specific point of this Driver object based on the given coordinates.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
x number Yes X coordinate of the target point.
y number Yes Y coordinate of the target point.

Error codes

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

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

Example

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

longClick9+

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

Long-clicks a specific point of this Driver object based on the given coordinates.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
x number Yes X coordinate of the target point.
y number Yes Y coordinate of the target point.

Error codes

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

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

Example

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

swipe9+

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

Swipes on this Driver object from the given start point to the given end point.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
startx number Yes X coordinate of the start point.
starty number Yes Y coordinate of the start point.
endx number Yes X coordinate of the end point.
endy number Yes Y coordinate of the end point.
speed number No Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.

Error codes

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

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

Example

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

drag9+

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

Drags this Driver object from the given start point to the given end point.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
startx number Yes X coordinate of the start point.
starty number Yes Y coordinate of the start point.
endx number Yes X coordinate of the end point.
endy number Yes Y coordinate of the end point.
speed number No Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.

Error codes

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

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

Example

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

screenCap9+

screenCap(savePath: string): Promise<boolean>

Captures the current screen of this Driver object and saves it as a PNG image to the given save path.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
savePath string Yes File save path.

Return value

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

Error codes

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

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

Example

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

setDisplayRotation9+

setDisplayRotation(rotation: DisplayRotation): Promise<void>

Sets the display rotation of the device.

System capability: SystemCapability.Test.UiTest

Parameters

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

Error codes

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

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

Example

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

getDisplayRotation9+

getDisplayRotation(): Promise<DisplayRotation>

Obtains the display rotation of the current device.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

setDisplayRotationEnabled9+

setDisplayRotationEnabled(enabled: boolean): Promise<void>

Enables or disables display rotation.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
enabled boolean Yes Whether to enable display rotation. The value true means to enable display rotation, and false means the opposite.

Error codes

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

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

Example

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

getDisplaySize9+

getDisplaySize(): Promise<Point>

Obtains the display size of the current device.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

import { Driver, } from '@ohos.UiTest';

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

getDisplayDensity9+

getDisplayDensity(): Promise<Point>

Obtains the display density of the current device.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

wakeUpDisplay9+

wakeUpDisplay(): Promise<void>

Wakes up the device display.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

pressHome9+

pressHome(): Promise<void>

Returns to the home screen.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

waitForIdle9+

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

Checks whether all components on the current page are idle.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
idleTime number Yes Idle time threshold, in milliseconds. If the duration for which a component remains inactive reaches this threshold, it is considered as idle.
timeout number Yes Maximum idle waiting time, in milliseconds.

Return value

Type Description
Promise<boolean> Promise used to return the result.

Error codes

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

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

Example

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

fling9+

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

Simulates a fling operation on the screen.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
from Point Yes Coordinates of the point where the finger touches the screen.
to Point Yes Coordinates of the point where the finger leaves the screen.
stepLen number Yes Fling step length, in pixels.
speed number Yes Fling speed, in pixel/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value 600 is used.

Error codes

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

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

Example

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

injectMultiPointerAction9+

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

Injects a multi-touch operation to the device.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
pointers PointerMatrix Yes Scroll trajectory, including the number of fingers and an array of coordinates along the trajectory.
speed number No Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.

Return value

Type Description
Promise<boolean> Promise used to return the result.

Error codes

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

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

Example

import { Driver, PointerMatrix } from '@ohos.UiTest';
async function demo() {
  let driver: Driver = Driver.create();
  let pointers: PointerMatrix = PointerMatrix.create(2,3);
  pointers.setPoint(0,0,{x:230,y:480});
  pointers.setPoint(0,1,{x:250,y:380});
  pointers.setPoint(0,2,{x:270,y:280});
  pointers.setPoint(1,0,{x:230,y:680});
  pointers.setPoint(1,1,{x:240,y:580});
  pointers.setPoint(1,2,{x:250,y:480});
  await driver.injectMultiPointerAction(pointers);
}

fling10+

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

Simulates a fling operation on the screen, in the specified direction and speed.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
direction UiDirection Yes Direction of the fling operation.
speed number Yes Fling speed, in pixel/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value 600 is used.

Error codes

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

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

Example

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

screenCapture10+

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

Captures the specified area of the current screen and saves the captured screenshot as a PNG image to the specified path.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
savePath string Yes File save path.
rect Rect No Area of the screen to capture. The default value is the entire screen.

Return value

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

Error codes

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

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

Example

import { Driver } from '@ohos.UiTest';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.screenCapture('/data/storage/el2/base/cache/1.png', {left: 0, top: 0, right: 100, bottom: 100});
}

mouseClick10+

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

Injects a mouse click at the specified coordinates, with the optional key or key combination. For example, if the value of key1 is 2072, the Ctrl button is pressed with the mouse click.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
p Point Yes Coordinates of the mouse click.
btnId MouseButton Yes Mouse button pressed.
key1 number No The first key value.
key2 number No The second key value.

Error codes

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

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

Example

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

mouseScroll10+

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

Injects a mouse scroll action at the specified coordinates, with the optional key or key combination. For example, if the value of key1 is 2072, the Ctrl button is pressed with mouse scrolling.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
p Point Yes Coordinates of the mouse click.
down boolean Yes Whether the mouse wheel scrolls downward.
true: The mouse wheel scrolls downward.
false: The mouse wheel scrolls upward.
d number Yes Number of cells by which the mouse wheel scrolls. Scrolling by one cell means a 120-pixel offset of the target point.
key1 number No The first key value.
key2 number No The second key value.

Error codes

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

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

Example

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

mouseMoveTo10+

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

Moves the cursor to the target point.

System capability: SystemCapability.Test.UiTest

Parameters

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

Error codes

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

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

Example

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

createUIEventObserver10+

createUIEventObserver(): UIEventObserver;

Creates a UI event listener.

System capability: SystemCapability.Test.UiTest

Return value

Type Description
UIEventObserver UI event listener.

Error codes

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

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

Example

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

PointerMatrix9+

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

create9+

static create(fingers: number, steps: number): PointerMatrix

Creates a PointerMatrix object and returns the object created. This API is a static API.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
fingers number Yes Number of fingers in the multi-touch operation. Value range: [1,10].
steps number Yes Number of steps operated by each finger. Value range: [1,1000].

Return value

Type Description
PointerMatrix PointerMatrix object created.

Example

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

setPoint9+

setPoint(finger: number, step: number, point: Point): void

Sets the coordinates for the action corresponding to the specified finger and step in the PointerMatrix object.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
finger number Yes Sequence number of the finger.
step number Yes Sequence number of the step.
point Point Yes Coordinates of the action.

Example

import { PointerMatrix } from '@ohos.UiTest';
async function demo() {
  let pointers: PointerMatrix = PointerMatrix.create(2,3);
  pointers.setPoint(0,0,{x:230,y:480});
  pointers.setPoint(0,1,{x:250,y:380});
  pointers.setPoint(0,2,{x:270,y:280});
  pointers.setPoint(1,0,{x:230,y:680});
  pointers.setPoint(1,1,{x:240,y:580});
  pointers.setPoint(1,2,{x:250,y:480});
}

UiWindow9+

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

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

getBundleName9+

getBundleName(): Promise<string>

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

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

import { Driver, UiWindow } from '@ohos.UiTest';

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

getBounds9+

getBounds(): Promise<Rect>

Obtains the bounds information of this window.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

getTitle9+

getTitle(): Promise<string>

Obtains the title of this window.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

getWindowMode9+

getWindowMode(): Promise<WindowMode>

Obtains the window mode of this window.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

isFocused9+

isFocused(): Promise<boolean>

Checks whether this window is in focused state.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

isActived9+

isActived(): Promise<boolean>

Checks whether this window is active.

System capability: SystemCapability.Test.UiTest

Return value

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

Error codes

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

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

Example

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

focus9+

focus(): Promise<void>

Moves the focus to this window.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

moveTo9+

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

Moves this window to the target point. This API is applicable to moveable windows.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
x number Yes X coordinate of the target point.
y number Yes Y coordinate of the target point.

Error codes

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

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

Example

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

resize9+

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

Resizes this window based on the specified width, height, and resize direction. This API is applicable to resizable windows.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
wide number Yes Target width.
height number Yes Target height.
direction ResizeDirection Yes Resize direction.

Error codes

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

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

Example

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

split9+

split(): Promise<void>

Switches the window to split-screen mode. This API is applicable to windows that support screen splitting.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

maximize9+

maximize(): Promise<void>

Maximizes this window. This API is applicable to windows that can be maximized.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

minimize9+

minimize(): Promise<void>

Minimizes this window. This API is applicable to windows that can be minimized.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

resume9+

resume(): Promise<void>

Restores this window to the previous window mode.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

close9+

close(): Promise<void>

Closes this window.

System capability: SystemCapability.Test.UiTest

Error codes

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

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

Example

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

UIEventObserver10+

UI event listener.

once('toastShow')

once(type: 'toastShow', callback: Callback<UIElementInfo>): void;

Subscribes to events of the toast component. This API uses a callback to return the result.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
type string Yes Event type. The value is fixed at 'toastShow'.
callback Callback<UIElementInfo> Yes Callback used to return the result.

Example

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

once('dialogShow')

once(type: 'dialogShow', callback: Callback<UIElementInfo>): void;

Subscribes to events of the dialog component. This API uses a callback to return the result.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
type string Yes Event type. The value is fixed at 'dialogShow'.
callback Callback<UIElementInfo> Yes Callback used to return the result.

Example

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

By(deprecated)

The UiTest framework provides a wide range of UI component feature description APIs in the By class to filter and match components.

The APIs provided by the By class exhibit the following features:

  • Allow one or more attributes as the match conditions. For example, you can specify both the text and id attributes to find the target component.
  • Provide multiple match patterns for component attributes.
  • Support absolute positioning and relative positioning for components. APIs such as By.isBefore(deprecated) and By.isAfter(deprecated) can be used to specify the features of adjacent components to assist positioning.

All APIs provided in the By class are synchronous. You are advised to use the static constructor BY to create a By object in chain mode.

This class is deprecated since API version 9. You are advised to use On9+ instead.

import { BY } from '@ohos.UiTest';
BY.text('123').type('Button');

text(deprecated)

text(txt: string, pattern?: MatchPattern): By

Specifies the text attribute of the target component. Multiple match patterns are supported.

This API is deprecated since API version 9. You are advised to use text9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Example

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

This API is deprecated since API version 9. You are advised to use id9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
key string Yes Component key.

Return value

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

Example

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

This API is deprecated since API version 9.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
id number Yes Component ID.

Return value

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

Example

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

This API is deprecated since API version 9. You are advised to use type9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
tp string Yes Component type.

Return value

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

Example

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

This API is deprecated since API version 9. You are advised to use clickable9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Clickable status of the target component.
true: clickable.
false: not clickable.
Default value: true

Return value

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

Example

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

This API is deprecated since API version 9. You are advised to use scrollable9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Scrollable status of the target component.
true: scrollable.
false: not scrollable.
Default value: true

Return value

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

Example

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

This API is deprecated since API version 9. You are advised to use enabled9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Enabled status of the target component.
true: enabled.
false: not enabled.
Default value: true

Return value

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

Example

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

This API is deprecated since API version 9. You are advised to use focused9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Focused status of the target component.
true: focused.
false: not focused.
Default value: true

Return value

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

Example

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

This API is deprecated since API version 9. You are advised to use selected9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
b boolean No Selected status of the target component.
true: selected.
false: not selected.
Default value: true

Return value

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

Example

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

This API is deprecated since API version 9. You are advised to use isBefore9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

Type Description
By By object.

Example

import { By, BY } from '@ohos.UiTest';

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

This API is deprecated since API version 9. You are advised to use isAfter9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

Type Description
By By object.

Example

import { By, BY } from '@ohos.UiTest';

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

This class is deprecated since API version 9. You are advised to use Component9+ instead.

click(deprecated)

click(): Promise<void>

Clicks this component.

This API is deprecated since API version 9. You are advised to use click9+ instead.

System capability: SystemCapability.Test.UiTest

Example

import { UiDriver, BY, Driver, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use doubleClick9+ instead.

System capability: SystemCapability.Test.UiTest

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use longClick9+ instead.

System capability: SystemCapability.Test.UiTest

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use getId9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use getText9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use getType9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use isClickable9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use isScrollable9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use isEnabled9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use isFocused9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use isSelected9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

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

Example

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

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

This API is deprecated since API version 9. You are advised to use inputText9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
text string Yes Text to enter.

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use scrollSearch9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Example

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

This class is deprecated since API version 9. You are advised to use Driver9+ instead.

create(deprecated)

static create(): UiDriver

Creates a UiDriver object and returns the object created. This API is a static API.

This API is deprecated since API version 9. You are advised to use create9+ instead.

System capability: SystemCapability.Test.UiTest

Return value

Type Description
UiDriver Returns the UiDriver object created.

Example

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

delayMs(deprecated)

delayMs(duration: number): Promise<void>

Delays this UiDriver object within the specified duration.

This API is deprecated since API version 9. You are advised to use delayMs9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
duration number Yes Duration of time.

Example

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

findComponent(deprecated)

findComponent(by: By): Promise<UiComponent>

Searches this UiDriver object for the target component that matches the given attributes.

This API is deprecated since API version 9. You are advised to use findComponent9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use findComponents9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

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

Return value

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

Example

import { UiDriver, BY, UiComponent } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use assertComponentExist9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

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

Error codes

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

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

Example

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

pressBack(deprecated)

pressBack(): Promise<void>

Presses the Back button on this UiDriver object.

This API is deprecated since API version 9. You are advised to use pressBack9+ instead.

System capability: SystemCapability.Test.UiTest

Example

import { UiDriver } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use triggerKey9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
keyCode number Yes Key code.

Example

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

click(deprecated)

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

Clicks a specific point of this UiDriver object based on the given coordinates.

This API is deprecated since API version 9. You are advised to use click9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
x number Yes X coordinate of the target point.
y number Yes Y coordinate of the target point.

Example

import { UiDriver } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use doubleClick9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
x number Yes X coordinate of the target point.
y number Yes Y coordinate of the target point.

Example

import { UiDriver } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use longClick9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
x number Yes X coordinate of the target point.
y number Yes Y coordinate of the target point.

Example

import { UiDriver } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use swipe9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
startx number Yes X coordinate of the start point.
starty number Yes Y coordinate of the start point.
endx number Yes X coordinate of the end point.
endy number Yes Y coordinate of the end point.

Example

import { UiDriver } from '@ohos.UiTest';
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 is deprecated since API version 9. You are advised to use screenCap9+ instead.

System capability: SystemCapability.Test.UiTest

Parameters

Name Type Mandatory Description
savePath string Yes File save path.

Return value

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

Example

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