harmony 鸿蒙@ohos.UiTest

2022-08-09
浏览 (920)

@ohos.UiTest

UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要支持如点击、双击、长按、滑动等UI操作能力。

该模块提供以下功能：

On⁹⁺：提供控件特征描述能力，用于控件筛选匹配查找。
Component⁹⁺：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。
Driver⁹⁺：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。
UiWindow⁹⁺：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能力。
By^(deprecated)：提供控件特征描述能力，用于控件筛选匹配查找。从API version 9开始不再维护，建议使用On⁹⁺。
UiComponent^(deprecated)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。从API version 9开始不再维护，建议使用Component⁹⁺。
UiDriver^(deprecated)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。从API version 9开始不再维护，建议使用Driver⁹⁺。

说明：

本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

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

MatchPattern

控件属性支持的匹配模式。

系统能力：SystemCapability.Test.UiTest

名称	值	说明
EQUALS	0	等于给定值。
CONTAINS	1	包含给定值。
STARTS_WITH	2	以给定值开始。
ENDS_WITH	3	以给定值结束。

ResizeDirection⁹⁺

窗口调整大小的方向。

系统能力：SystemCapability.Test.UiTest

名称	值	说明
LEFT	0	左方。
RIGHT	1	右方。
UP	2	上方。
DOWN	3	下方。
LEFT_UP	4	左上方。
LEFT_DOWN	5	左下方。
RIGHT_UP	6	右上方。
RIGHT_DOWN	7	右下方。

Point⁹⁺

坐标点信息。

系统能力：SystemCapability.Test.UiTest

名称	类型	可读	可写	说明
x	number	是	否	坐标点的横坐标。
y	number	是	否	坐标点的纵坐标。

Rect⁹⁺

控件的边框信息。

系统能力：SystemCapability.Test.UiTest

名称	类型	可读	可写	说明
left	number	是	否	控件边框的左上角的X坐标。
top	number	是	否	控件边框的左上角的Y坐标。
right	number	是	否	控件边框的右下角的X坐标。
bottom	number	是	否	控件边框的右下角的Y坐标。

WindowMode⁹⁺

窗口的窗口模式。

系统能力：SystemCapability.Test.UiTest

名称	值	说明
FULLSCREEN	0	全屏模式。
PRIMARY	1	主窗口。
SECONDARY	2	第二窗口。
FLOATING	3	浮动窗口。

DisplayRotation⁹⁺

设备显示器的显示方向。

系统能力：SystemCapability.Test.UiTest

名称	值	说明
ROTATION_0	0	设备显示器不旋转，初始形态垂直显示。
ROTATION_90	1	设备显示器顺时针旋转90°，水平显示。
ROTATION_180	2	设备显示器顺时针旋转180°，逆向垂直显示。
ROTATION_270	3	设备显示器顺时针旋转270°，逆向水平显示。

WindowFilter⁹⁺

窗口的标志属性信息。

系统能力：SystemCapability.Test.UiTest

名称	类型	可读	可写	说明
bundleName	string	是	否	窗口归属应用的包名。
title	string	是	否	窗口的标题信息。
focused	boolean	是	否	窗口是否处于获焦状态。
actived	boolean	是	否	窗口是否正与用户进行交互。

UiDirection¹⁰⁺

进行抛滑等UI操作时的方向。

系统能力：SystemCapability.Test.UiTest

名称	值	说明
LEFT	0	向左。
RIGHT	1	向右。
UP	2	向上。
DOWN	3	向下。

MouseButton¹⁰⁺

模拟注入的鼠标按钮。

系统能力：SystemCapability.Test.UiTest

名称	值	说明
MOUSE_BUTTON_LEFT	0	鼠标左键。
MOUSE_BUTTON_RIGHT	1	鼠标右键。
MOUSE_BUTTON_MIDDLE	2	鼠标中间键。

UIElementInfo¹⁰⁺

UI事件的相关信息。

系统能力：SystemCapability.Test.UiTest

名称	类型	可读	可写	说明
bundleName	string	是	否	归属应用的包名。
type	string	是	否	控件/窗口类型。
text	string	是	否	控件/窗口的文本信息。

On⁹⁺

UiTest框架在API 9中，通过On类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
On提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过ON.isBefore和ON.isAfter等API限定邻近控件特征进行辅助定位。
On类提供的所有API均为同步接口，建议使用者通过静态构造器ON来链式创建On对象。

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

text⁹⁺

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

指定目标控件文本属性，支持多种匹配模式，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
txt	string	是	指定控件文本，用于匹配目标控件文本。
pattern	MatchPattern	否	指定的文本匹配模式，默认为EQUALS。

返回值：

类型	说明
On	返回指定目标控件文本属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.text('123'); // 使用静态构造器ON创建On对象，指定目标控件的text属性。

id⁹⁺

id(id: string): On

指定目标控件id属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
id	string	是	指定控件的id值。

返回值：

类型	说明
On	返回指定目标控件id属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.id('123'); // 使用静态构造器ON创建On对象，指定目标控件的id属性。

type⁹⁺

type(tp: string): On

指定目标控件的控件类型属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
tp	string	是	指定控件类型。

返回值：

类型	说明
On	返回指定目标控件的控件类型属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.type('button'); // 使用静态构造器ON创建On对象，指定目标控件的控件类型属性。

clickable⁹⁺

clickable(b?: boolean): On

指定目标控件的可点击状态属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件可点击状态，true：可点击，false：不可点击。默认为true。

返回值：

类型	说明
On	返回指定目标控件的可点击状态属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.clickable(true); // 使用静态构造器ON创建On对象，指定目标控件的可点击状态属性。

longClickable⁹⁺

longClickable(b?: boolean): On

指定目标控件的可长按点击状态属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件可长按点击状态，true：可长按点击，false：不可长按点击。默认为true。

返回值：

类型	说明
On	返回指定目标控件的可长按点击状态属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.longClickable(true); // 使用静态构造器ON创建On对象，指定目标控件的可长按点击状态属性。

scrollable⁹⁺

scrollable(b?: boolean): On

指定目标控件的可滑动状态属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	控件可滑动状态，true：可滑动，false：不可滑动。默认为true。

返回值：

类型	说明
On	返回指定目标控件的可滑动状态属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.scrollable(true); // 使用静态构造器ON创建On对象，指定目标控件的可滑动状态属性。

enabled⁹⁺

enabled(b?: boolean): On

指定目标控件的使能状态属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件使能状态，true：使能，false：未使能。默认为true。

返回值：

类型	说明
On	返回指定目标控件的使能状态属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.enabled(true); // 使用静态构造器ON创建On对象，指定目标控件的使能状态属性。

focused⁹⁺

focused(b?: boolean): On

指定目标控件的获焦状态属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	控件获焦状态，true：获焦，false：未获焦。默认为true。

返回值：

类型	说明
On	返回指定目标控件的获焦状态属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.focused(true); // 使用静态构造器ON创建On对象，指定目标控件的获焦状态属性。

selected⁹⁺

selected(b?: boolean): On

指定目标控件的被选中状态属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件被选中状态，true：被选中，false：未被选中。默认为true。

返回值：

类型	说明
On	返回指定目标控件的被选中状态属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.selected(true); // 使用静态构造器ON创建On对象，指定目标控件的被选中状态属性。

checked⁹⁺

checked(b?: boolean): On

指定目标控件的被勾选状态属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件被勾选状态，true：被勾选，false：未被勾选。默认为false。

返回值：

类型	说明
On	返回指定目标控件的被勾选状态属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.checked(true); // 使用静态构造器ON创建On对象，指定目标控件的被勾选状态属性

checkable⁹⁺

checkable(b?: boolean): On

指定目标控件能否被勾选状态属性，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件能否被勾选状态，true：能被勾选，false：不能被勾选。默认为false。

返回值：

类型	说明
On	返回指定目标控件能否被勾选状态属性的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.checkable(true); // 使用静态构造器ON创建On对象，指定目标控件的能否被勾选状态属性。

isBefore⁹⁺

isBefore(on: On): On

指定目标控件位于给出的特征属性控件之前，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
on	On	是	特征控件的属性要求。

返回值：

类型	说明
On	返回指定目标控件位于给出的特征属性控件之前的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.isBefore(ON.text('123')); // 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之前。

isAfter⁹⁺

isAfter(on: On): On

指定目标控件位于给出的特征属性控件之后，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
on	On	是	特征控件的属性要求。

返回值：

类型	说明
On	返回指定目标控件位于给出的特征属性控件之后的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.isAfter(ON.text('123')); // 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之后。

within¹⁰⁺

within(on: On): On

指定目标控件位于给出的特征属性控件之内，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
on	On	是	特征控件的属性要求。

返回值：

类型	说明
On	返回指定目标控件位于给出的特征属性控件内的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.within(ON.type('List')); // 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之内。

inWindow¹⁰⁺

inWindow(bundleName: string): On;

指定目标控件位于给出的应用窗口内，返回On对象自身。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
bundleName	string	是	应用窗口的包名。

返回值：

类型	说明
On	返回指定目标控件位于给出的应用窗口内的On对象。

示例：

import { ON } from '@ohos.UiTest';
let on = ON.inWindow('com.uitestScene.acts'); // 使用静态构造器ON创建On对象，指定目标控件位于给出的应用窗口内。

Component⁹⁺

UiTest框架在API9中，Component类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。

click⁹⁺

click(): Promise<void>

控件对象进行点击操作。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

doubleClick⁹⁺

doubleClick(): Promise<void>

控件对象进行双击操作。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

longClick⁹⁺

longClick(): Promise<void>

控件对象进行长按操作。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

getId⁹⁺

getId(): Promise<string>

获取控件对象的id值。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<string>	以Promise形式返回的控件的id值。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

getText⁹⁺

getText(): Promise<string>

获取控件对象的文本信息。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<string>	以Promise形式返回控件的文本信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

getType⁹⁺

getType(): Promise<string>

获取控件对象的控件类型。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<string>	以Promise形式返回控件的类型。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

getBounds⁹⁺

getBounds(): Promise<Rect>

获取控件对象的边框信息。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<Rect>	以Promise形式返回控件对象的边框信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

getBoundsCenter⁹⁺

getBoundsCenter(): Promise<Point>

获取控件对象所占区域的中心点信息。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<Point>	以Promise形式返回控件对象所占区域的中心点信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

isClickable⁹⁺

isClickable(): Promise<boolean>

获取控件对象可点击属性。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象是否可点击，true：可点击，false：不可点击。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    if(await button.isClickable()) {
        console.info('This button can be Clicked');
    } else {
        console.info('This button can not be Clicked');
    }
}

isLongClickable⁹⁺

isLongClickable(): Promise<boolean>

获取控件对象可长按点击属性。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象是否可安装点击，true：可长按点击，false：不可长按点击。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    if(await button.isLongClickable()) {
        console.info('This button can longClick');
    } else {
        console.info('This button can not longClick');
    }
}

isChecked⁹⁺

isChecked(): Promise<boolean>

获取控件对象被勾选状态。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象被勾选状态，true：被勾选，false：未被勾选。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let checkBox = await driver.findComponent(ON.type('Checkbox'));
    if(await checkBox.isChecked()) {
        console.info('This checkBox is checked');
    } else {
        console.info('This checkBox is not checked');
    }
}

isCheckable⁹⁺

isCheckable(): Promise<boolean>

获取控件对象能否被勾选属性。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象能否可被勾选属性，true：可被勾选，false：不可被勾选。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let checkBox = await driver.findComponent(ON.type('Checkbox'));
    if(await checkBox.isCheckable()) {
        console.info('This checkBox is checkable');
    } else {
        console.info('This checkBox is not checkable');
    }
}

isScrollable⁹⁺

isScrollable(): Promise<boolean>

获取控件对象可滑动属性。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象是否可滑动，true：可滑动，false：不可滑动。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let scrollBar = await driver.findComponent(ON.scrollable(true));
    if(await scrollBar.isScrollable()) {
        console.info('This scrollBar can be operated');
    } else {
        console.info('This scrollBar can not be operated');
    }
}

isEnabled⁹⁺

isEnabled(): Promise<boolean>

获取控件使能状态。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件使能状态，true：使能，false：未使能。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    if(await button.isEnabled()) {
        console.info('This button can be operated');
    } else {
        console.info('This button can not be operated');
    }
}

isFocused⁹⁺

isFocused(): Promise<boolean>

判断控件对象获焦状态。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象获焦状态，true：获焦，false：未获焦。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    if(await button.isFocused()) {
        console.info('This button is focused');
    } else {
        console.info('This button is not focused');
	}
}

isSelected⁹⁺

isSelected(): Promise<boolean>

获取控件对象被选中状态。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	控件对象被选中状态，true：被选中，false：未被选中。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

import { Driver, ON } from '@ohos.UiTest';
async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    if(await button.isSelected()) {
        console.info('This button is selected');
	} else {
        console.info('This button is not selected');
    }
}

inputText⁹⁺

inputText(text: string): Promise<void>

向控件中输入文本(适用于文本框控件)。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
text	string	是	输入的文本信息，当前支持英文和特殊字符。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

clearText⁹⁺

clearText(): Promise<void>

清除控件的文本信息(适用于文本框控件)。

系统能力：SystemCapability.Test.UiTest

错误码：

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

scrollSearch⁹⁺

scrollSearch(on: On): Promise<Component>

在控件上滑动查找目标控件(适用支持滑动的控件)。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
on	On	是	目标控件的属性要求。

返回值：

类型	说明
Promise<Component>	以Promise形式返回找到的目标控件对象。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

scrollToTop⁹⁺

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

在控件上滑动到顶部(适用支持滑动的控件)。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
speed	number	否	滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

scrollToBottom⁹⁺

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

在控件上滑动到底部(适用支持滑动的控件)。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
speed	number	否	滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

dragTo⁹⁺

dragTo(target: Component): Promise<void>

将控件拖拽至目标控件处。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
target	Component	是	目标控件。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

pinchOut⁹⁺

pinchOut(scale: number): Promise<void>

将控件按指定的比例进行捏合放大。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
scale	number	是	指定放大的比例。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

pinchIn⁹⁺

pinchIn(scale: number): Promise<void>

将控件按指定的比例进行捏合缩小。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
scale	number	是	指定缩小的比例。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the component is invisible or destroyed.

示例：

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

Driver⁹⁺

Driver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。该类提供的方法除Driver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await方式调用。

create⁹⁺

static create(): Driver

静态方法，构造一个Driver对象，并返回该对象。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Driver	返回构造的Driver对象。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000001	if the test framework failed to initialize.

示例：

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

delayMs⁹⁺

delayMs(duration: number): Promise<void>

Driver对象在给定的时间内延时。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
duration	number	是	给定的时间，单位：ms。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

findComponent⁹⁺

findComponent(on: On): Promise<Component>

在Driver对象中，根据给出的目标控件属性要求查找目标控件。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
on	On	是	目标控件的属性要求。

返回值：

类型	说明
Promise<Component>	以Promise形式返回找到的控件对象。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

findComponents⁹⁺

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

在Driver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
on	On	是	目标控件的属性要求。

返回值：

类型	说明
Promise<Array<Component>>	以Promise形式返回找到的控件对象的列表。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

findWindow⁹⁺

findWindow(filter: WindowFilter): Promise<UiWindow>

通过指定窗口的属性来查找目标窗口。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
filter	WindowFilter	是	目标窗口的属性。

返回值：

类型	说明
Promise<UiWindow>	以Promise形式返回找到的目标窗口对象。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

waitForComponent⁹⁺

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

在Driver对象中，在用户给定的时间内，持续查找满足控件属性要求的目标控件。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
On	On	是	目标控件的属性要求。
time	number	是	查找目标控件的持续时间。单位ms。

返回值：

类型	说明
Promise<Component>	以Promise形式返回找到的控件对象。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

assertComponentExist⁹⁺

assertComponentExist(on: On): Promise<void>

断言API，用于断言当前界面是否存在满足给出的目标属性的控件。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
on	On	是	目标控件的属性要求。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000003	if the assertion failed.

示例：

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

pressBack⁹⁺

pressBack(): Promise<void>

Driver对象进行点击BACK键的操作。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

triggerKey⁹⁺

triggerKey(keyCode: number): Promise<void>

Driver对象采取如下操作：传入key值实现模拟点击对应按键的效果。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
keyCode	number	是	指定的key值。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

triggerCombineKeys⁹⁺

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

Driver对象通过给定的key值，找到对应组合键并点击。例如，Key值为(2072, 2019)时，Driver对象找到key值对应的组合键并点击，如ctrl+c。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
key0	number	是	指定的第一个key值。
key1	number	是	指定的第二个key值。
key2	number	否	指定的第三个key值。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

click⁹⁺

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

Driver对象采取如下操作：在目标坐标点单击。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
x	number	是	以number的形式传入目标点的横坐标信息。
y	number	是	以number的形式传入目标点的纵坐标信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

doubleClick⁹⁺

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

Driver对象采取如下操作：在目标坐标点双击。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
x	number	是	以number的形式传入目标点的横坐标信息。
y	number	是	以number的形式传入目标点的纵坐标信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

longClick⁹⁺

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

Driver对象采取如下操作：在目标坐标点长按。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
x	number	是	以number的形式传入目标点的横坐标信息。
y	number	是	以number的形式传入目标点的纵坐标信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

swipe⁹⁺

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

Driver对象采取如下操作：从起始坐标点滑向目的坐标点。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
startx	number	是	以number的形式传入起始点的横坐标信息。
starty	number	是	以number的形式传入起始点的纵坐标信息。
endx	number	是	以number的形式传入目的点的横坐标信息。
endy	number	是	以number的形式传入目的点的纵坐标信息。
speed	number	否	滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

drag⁹⁺

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

Driver对象采取如下操作：从起始坐标点拖拽至目的坐标点。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
startx	number	是	以number的形式传入起始点的横坐标信息。
starty	number	是	以number的形式传入起始点的纵坐标信息。
endx	number	是	以number的形式传入目的点的横坐标信息。
endy	number	是	以number的形式传入目的点的纵坐标信息。
speed	number	否	滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

screenCap⁹⁺

screenCap(savePath: string): Promise<boolean>

Driver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
savePath	string	是	文件保存路径。

返回值：

类型	说明
Promise<boolean>	截图操作是否成功完成。成功完成为true。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

setDisplayRotation⁹⁺

setDisplayRotation(rotation: DisplayRotation): Promise<void>

将设备的屏幕显示方向设置为指定的显示方向。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
rotation	DisplayRotation	是	设备的显示方向。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

getDisplayRotation⁹⁺

getDisplayRotation(): Promise<DisplayRotation>

获取当前设备的屏幕显示方向。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<DisplayRotation>	以Promise的形式返回当前设备的显示方向。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

setDisplayRotationEnabled⁹⁺

setDisplayRotationEnabled(enabled: boolean): Promise<void>

启用/禁用设备旋转屏幕的功能。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
enabled	boolean	是	能否旋转屏幕的标识，true：可以旋转，false：不可以旋转。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

getDisplaySize⁹⁺

getDisplaySize(): Promise<Point>

获取当前设备的屏幕大小。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<Point>	以Promise的形式返回当前设备的屏幕大小。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

getDisplayDensity⁹⁺

getDisplayDensity(): Promise<Point>

获取当前设备屏幕的分辨率。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<Point>	以Promise的形式返回当前设备屏幕的分辨率。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

wakeUpDisplay⁹⁺

wakeUpDisplay(): Promise<void>

唤醒当前设备即设备亮屏。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

pressHome⁹⁺

pressHome(): Promise<void>

设备返回到桌面。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

waitForIdle⁹⁺

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

判断当前界面的所有控件是否已经空闲。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
idleTime	number	是	空闲时间的阈值。在这个时间段控件不发生变化，视为该控件空闲，单位：毫秒。
timeout	number	是	等待空闲的最大时间，单位：毫秒。

返回值：

类型	说明
Promise<boolean>	以Promise的形式返回当前界面的所有控件是否已经空闲。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

fling⁹⁺

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

模拟手指滑动后脱离屏幕的快速滑动操作。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
from	Point	是	手指接触屏幕的起始点坐标。
to	Point	是	手指离开屏幕时的坐标点。
stepLen	number	是	间隔距离，单位：像素点。
speed	number	是	滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

injectMultiPointerAction⁹⁺

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

向设备注入多指操作。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
pointers	PointerMatrix	是	滑动轨迹，包括操作手指个数和滑动坐标序列。
speed	number	否	滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。

返回值：

类型	说明
Promise<boolean>	以Promise的形式返回操作是否成功完成。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

fling¹⁰⁺

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

指定方向和速度，模拟手指滑动后脱离屏幕的快速滑动操作。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
direction	UiDirection	是	进行抛滑的方向。
speed	number	是	滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

screenCapture¹⁰⁺

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

捕获当前屏幕的指定区域，并保存为PNG格式的图片至给出的保存路径中。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
savePath	string	是	文件保存路径。
rect	Rect	否	截图区域，默认为全屏。

返回值：

类型	说明
Promise<boolean>	截图操作是否成功完成。成功完成为true。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

mouseClick¹⁰⁺

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

在指定坐标点注入鼠标点击动作，支持同时按下对应键盘组合键。例如，Key值为2072时，按下ctrl并进行鼠标点击动作。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
p	Point	是	鼠标点击的坐标。
btnId	MouseButton	是	按下的鼠标按钮。
key1	number	否	指定的第一个key值。
key2	number	否	指定的第二个key值。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

mouseScroll¹⁰⁺

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

在指定坐标点注入鼠标滚轮滑动动作，支持同时按下对应键盘组合键。例如，Key值为2072时，按下ctrl并进行鼠标滚轮滑动动作。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
p	Point	是	鼠标点击的坐标。
down	boolean	是	滚轮滑动方向是否向下，true表示向下滑动，false表示向上滚动。
d	number	是	鼠标滚轮滚动的格数，每格对应目标点位移120个像素点。
key1	number	否	指定的第一个key值。
key2	number	否	指定的第二个key值。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

mouseMoveTo¹⁰⁺

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

将鼠标光标移到目标点。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
p	Point	是	目标点的坐标。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

createUIEventObserver¹⁰⁺

createUIEventObserver(): UIEventObserver;

创建一个UI事件监听器。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<UIEventObserver>	以Promise形式返回找到的目标窗口对象。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

mouseScroll¹¹⁺

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

在指定坐标点注入鼠标滚轮滑动动作，支持同时按下对应键盘组合键并且指定滑动速度。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
p	Point	是	鼠标点击的坐标。
down	boolean	是	滚轮滑动方向是否向下，true表示向下滑动，false表示向上滚动。
d	number	是	鼠标滚轮滚动的格数，每格对应目标点位移120个像素点。
key1	number	否	指定的第一个key值。
key2	number	否	指定的第二个key值。
speed	number	否	鼠标滚轮滚动的速度，范围：1-500，不在范围内设为默认值为20，单位：格/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

mouseDoubleClick¹¹⁺

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

在指定坐标点注入鼠标双击动作，支持同时按下对应键盘组合键。例如，Key值为2072时，按下ctrl并进行鼠标双击动作。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
p	Point	是	鼠标双击的坐标。
btnId	MouseButton	是	按下的鼠标按钮。
key1	number	否	指定的第一个key值。
key2	number	否	指定的第二个key值。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

mouseLongClick¹¹⁺

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

在指定坐标点注入鼠标长按动作，支持同时按下对应键盘组合键。例如，Key值为2072时，按下ctrl并进行鼠标长按动作。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
p	Point	是	鼠标长按的坐标。
btnId	MouseButton	是	按下的鼠标按钮。
key1	number	否	指定的第一个key值。
key2	number	否	指定的第二个key值。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

mouseMoveWithTrack¹¹⁺

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

鼠标从起始坐标点滑向终点坐标点。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
from	Point	是	起始点坐标。
to	Point	是	终点坐标。
speed	number	否	滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

mouseDrag¹¹⁺

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

鼠标按住鼠标左键从起始坐标点拖拽至终点坐标点。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
from	Point	是	起始点坐标。
to	Point	是	终点坐标。
speed	number	否	滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

inputText¹¹⁺

inputText(p: Point, text: string): Promise<void>

在指定坐标点输入文本。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
p	Point	是	输入文本的坐标点。
text	string	是	输入的文本信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.

示例：

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

PointerMatrix⁹⁺

存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。

create⁹⁺

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

静态方法，构造一个PointerMatrix对象，并返回该对象。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
fingers	number	是	多指操作中注入的手指数，取值范围：[1,10]。
steps	number	是	每根手指操作的步骤数，取值范围：[1,1000]。

返回值：

类型	说明
PointerMatrix	返回构造的PointerMatrix对象。

示例：

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

setPoint⁹⁺

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

设置PointerMatrix对象中指定手指和步骤对应动作的坐标点。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
finger	number	是	手指的序号。
step	number	是	步骤的序号。
point	Point	是	该行为的坐标点。

示例：

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

UiWindow⁹⁺

UiWindow代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等能力。该类提供的所有方法都使用Promise方式作为异步方法，需使用await方式调用。

getBundleName⁹⁺

getBundleName(): Promise<string>

获取窗口归属应用的包名信息。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<string>	以Promise形式返回窗口归属应用的包名信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

示例：

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

getBounds⁹⁺

getBounds(): Promise<Rect>

获取窗口的边框信息。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<Rect>	以Promise形式返回窗口的边框信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

示例：

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

getTitle⁹⁺

getTitle(): Promise<string>

获取窗口的标题信息。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<string>	以Promise形式返回窗口的标题信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

示例：

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

getWindowMode⁹⁺

getWindowMode(): Promise<WindowMode>

获取窗口的窗口模式信息。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<WindowMode>	以Promise形式返回窗口的窗口模式信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

示例：

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

isFocused⁹⁺

isFocused(): Promise<boolean>

判断窗口是否处于获焦状态。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回窗口对象是否获取获焦状态，true：获焦，false：未获焦。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

示例：

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

isActived⁹⁺

isActived(): Promise<boolean>

判断窗口是否为用户正在交互窗口。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回窗口对象是否为用户正在交互窗口，true：交互窗口，false：非交互窗口。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

示例：

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

focus⁹⁺

focus(): Promise<void>

让窗口获焦。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000004	if the window is invisible or destroyed.

示例：

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

moveTo⁹⁺

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

将窗口移动到目标点。适用于支持移动的窗口。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
x	number	是	以number的形式传入目标点的横坐标信息。
y	number	是	以number的形式传入目标点的纵坐标信息。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
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.

示例：

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

resize⁹⁺

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

根据传入的宽、高和调整方向来调整窗口的大小。适用于支持调整大小的窗口。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
wide	number	是	以number的形式传入调整后窗口的宽度。
height	number	是	以number的形式传入调整后窗口的高度。
direction	ResizeDirection	是	以ResizeDirection的形式传入窗口调整的方向。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
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.

示例：

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

split⁹⁺

split(): Promise<void>

将窗口模式切换成分屏模式。适用于支持切换分屏模式的窗口。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
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.

示例：

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

maximize⁹⁺

maximize(): Promise<void>

将窗口最大化。适用于支持窗口最大化操作的窗口。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
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.

示例：

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

minimize⁹⁺

minimize(): Promise<void>

将窗口最小化。适用于支持窗口最小化操作的窗口。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
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.

示例：

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

resume⁹⁺

resume(): Promise<void>

将窗口恢复到之前的窗口模式。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
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.

示例：

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

close⁹⁺

close(): Promise<void>

将窗口关闭。

系统能力：SystemCapability.Test.UiTest

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
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.

示例：

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

UIEventObserver¹⁰⁺

UI事件监听器。

once(‘toastShow’)

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

开始监听toast控件出现的事件，使用callback的形式返回结果。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，取值为’toastShow’
callback	Callback<UIElementInfo>	是	事件发生时执行的回调函数

示例：

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

once(‘dialogShow’)

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

开始监听dialog控件出现的事件，使用callback的形式返回结果。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，取值为’dialogShow’
callback	Callback<UIElementInfo>	是	事件发生时执行的回调函数

示例：

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

By^(deprecated)

UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
By提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过By.isBefore^(deprecated)和By.isAfter^(deprecated)等API限定邻近控件特征进行辅助定位。
By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。

从API version 9开始不再维护，建议使用On⁹⁺。

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

text^(deprecated)

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

指定目标控件文本属性，支持多种匹配模式，返回By对象自身。

从API version 9开始不再维护，建议使用text⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
txt	string	是	指定控件文本，用于匹配目标控件文本。
pattern	MatchPattern	否	指定的文本匹配模式，默认为EQUALS。

返回值：

类型	说明
By	返回指定目标控件文本属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.text('123'); // 使用静态构造器BY创建by对象，指定目标控件的text属性。

key^(deprecated)

key(key: string): By

指定目标控件key值属性，返回By对象自身。

从API version 9开始不再维护，建议使用id⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
key	string	是	指定控件的Key值。

返回值：

类型	说明
By	返回指定目标控件key值属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.key('123'); // 使用静态构造器BY创建by对象，指定目标控件的key值属性。

id^(deprecated)

id(id: number): By

指定目标控件id属性，返回By对象自身。

从API version 9开始废弃。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
id	number	是	指定控件的id值。

返回值：

类型	说明
By	返回指定目标控件id属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.id(123); // 使用静态构造器BY创建by对象，指定目标控件的id属性。

type^(deprecated)

type(tp: string): By

指定目标控件的控件类型属性，返回By对象自身。

从API version 9开始不再维护，建议使用type⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
tp	string	是	指定控件类型。

返回值：

类型	说明
By	返回指定目标控件的控件类型属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.type('button'); // 使用静态构造器BY创建by对象，指定目标控件的控件类型属性。

clickable^(deprecated)

clickable(b?: boolean): By

指定目标控件的可点击状态属性，返回By对象自身。

从API version 9开始不再维护，建议使用clickable⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件可点击状态，true：可点击，false：不可点击。默认为true。

返回值：

类型	说明
By	返回指定目标控件的可点击状态属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.clickable(true); // 使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。

scrollable^(deprecated)

scrollable(b?: boolean): By

指定目标控件的可滑动状态属性，返回By对象自身。

从API version 9开始不再维护，建议使用scrollable⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	控件可滑动状态，true：可滑动，false：不可滑动。默认为true。

返回值：

类型	说明
By	返回指定目标控件的可滑动状态属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.scrollable(true); // 使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。

enabled^(deprecated)

enabled(b?: boolean): By

指定目标控件的使能状态属性，返回By对象自身。

从API version 9开始不再维护，建议使用enabled⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件使能状态，true：使能，false：未使能。默认为true。

返回值：

类型	说明
By	返回指定目标控件的使能状态属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.enabled(true); // 使用静态构造器BY创建by对象，指定目标控件的使能状态属性。

focused^(deprecated)

focused(b?: boolean): By

指定目标控件的获焦状态属性，返回By对象自身。

从API version 9开始不再维护，建议使用focused⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	控件获焦状态，true：获焦，false：未获焦。默认为true。

返回值：

类型	说明
By	返回指定目标控件的获焦状态属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.focused(true); // 使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。

selected^(deprecated)

selected(b?: boolean): By

指定目标控件的被选中状态属性，返回By对象自身。

从API version 9开始不再维护，建议使用selected⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
b	boolean	否	指定控件被选中状态，true：被选中，false：未被选中。默认为true。

返回值：

类型	说明
By	返回指定目标控件的被选中状态属性的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.selected(true); // 使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。

isBefore^(deprecated)

isBefore(by: By): By

指定目标控件位于给出的特征属性控件之前，返回By对象自身。

从API version 9开始不再维护，建议使用isBefore⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
by	By	是	特征控件的属性。

返回值：

类型	说明
By	返回指定目标控件位于给出的特征属性控件之前的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.isBefore(BY.text('123')); // 使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。

isAfter^(deprecated)

isAfter(by: By): By

指定目标控件位于给出的特征属性控件之后，返回By对象自身。

从API version 9开始不再维护，建议使用isAfter⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
by	By	是	特征控件的属性。

返回值：

类型	说明
By	返回指定目标控件位于给出的特征属性控件之后的By对象。

示例：

import { BY } from '@ohos.UiTest';
let by = BY.isAfter(BY.text('123')); // 使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。

UiComponent^(deprecated)

UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。

从API version 9开始不再维护，建议使用Component⁹⁺。

click^(deprecated)

click(): Promise<void>

控件对象进行点击操作。

从API version 9开始不再维护，建议使用click⁹⁺。

系统能力：SystemCapability.Test.UiTest

示例：

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

doubleClick^(deprecated)

doubleClick(): Promise<void>

控件对象进行双击操作。

从API version 9开始不再维护，建议使用doubleClick⁹⁺。

系统能力：SystemCapability.Test.UiTest

示例：

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

longClick^(deprecated)

longClick(): Promise<void>

控件对象进行长按操作。

从API version 9开始不再维护，建议使用longClick⁹⁺。

系统能力：SystemCapability.Test.UiTest

示例：

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

getId^(deprecated)

getId(): Promise<number>

获取控件对象的id值。

从API version 9开始不再维护，被废弃。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<number>	以Promise形式返回的控件的id值。

示例：

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

getKey^(deprecated)

getKey(): Promise<string>

获取控件对象的key值。

从API version 9开始不再维护，建议使用getId⁹⁺

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<string>	以Promise形式返回控件的key值。

示例：

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

getText^(deprecated)

getText(): Promise<string>

获取控件对象的文本信息。

从API version 9开始不再维护，建议使用getText⁹⁺。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<string>	以Promise形式返回控件的文本信息。

示例：

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

getType^(deprecated)

getType(): Promise<string>

获取控件对象的控件类型。

从API version 9开始不再维护，建议使用getType⁹⁺。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<string>	以Promise形式返回控件的类型。

示例：

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

isClickable^(deprecated)

isClickable(): Promise<boolean>

获取控件对象可点击状态。

从API version 9开始不再维护，建议使用isClickable⁹⁺。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象可点击状态，true：可点击，false：不可点击。

示例：

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    if(await button.isClickable()) {
        console.info('This button can be Clicked');
    } else {
        console.info('This button can not be Clicked');
    }
}

isScrollable^(deprecated)

isScrollable(): Promise<boolean>

获取控件对象可滑动状态。

从API version 9开始不再维护，建议使用isScrollable⁹⁺。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象可滑动状态，true：可滑动，false：不可滑动。

示例：

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let scrollBar = await driver.findComponent(BY.scrollable(true));
    if(await scrollBar.isScrollable()) {
        console.info('This scrollBar can be operated');
    } else {
        console.info('This scrollBar can not be operated');
    }
}

isEnabled^(deprecated)

isEnabled(): Promise<boolean>

获取控件使能状态。

从API version 9开始不再维护，建议使用isEnabled⁹⁺。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件使能状态，true：使能，false：未使能。

示例：

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    if(await button.isEnabled()) {
        console.info('This button can be operated');
    } else {
        console.info('This button can not be operated');
    }
}

isFocused^(deprecated)

isFocused(): Promise<boolean>

判断控件对象是否获焦。

从API version 9开始不再维护，建议使用isFocused⁹⁺。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	以Promise形式返回控件对象是否获焦，true：获焦，false：未获焦。

示例：

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    if(await button.isFocused()) {
        console.info('This button is focused');
    } else {
        console.info('This button is not focused');
	}
}

isSelected^(deprecated)

isSelected(): Promise<boolean>

获取控件对象被选中状态。

从API version 9开始不再维护，建议使用isSelected⁹⁺。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
Promise<boolean>	控件对象被选中的状态，true：被选中，false：未被选中。

示例：

import { UiDriver, BY } from '@ohos.UiTest';
async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    if(await button.isSelected()) {
        console.info('This button is selected');
    } else {
        console.info('This button is not selected');
    }
}

inputText^(deprecated)

inputText(text: string): Promise<void>

向控件中输入文本(适用于文本框控件)。

从API version 9开始不再维护，建议使用inputText⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
text	string	是	输入的文本信息。

示例：

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

scrollSearch^(deprecated)

scrollSearch(by: By): Promise<UiComponent>

在控件上滑动查找目标控件(适用于List等支持滑动的控件)。

从API version 9开始不再维护，建议使用scrollSearch⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
by	By	是	目标控件的属性要求。

返回值：

类型	说明
Promise<UiComponent>	以Promise形式返回找到的目标控件对象。

示例：

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

UiDriver^(deprecated)

UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。

从API version 9开始不再维护，建议使用Driver⁹⁺。

create^(deprecated)

static create(): UiDriver

静态方法，构造一个UiDriver对象，并返回该对象。

从API version 9开始不再维护，建议使用create⁹⁺。

系统能力：SystemCapability.Test.UiTest

返回值：

类型	说明
UiDriver	返回构造的UiDriver对象。

示例：

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

delayMs^(deprecated)

delayMs(duration: number): Promise<void>

UiDriver对象在给定的时间内延时。

从API version 9开始不再维护，建议使用delayMs⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
duration	number	是	给定的时间。

示例：

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

findComponent^(deprecated)

findComponent(by: By): Promise<UiComponent>

在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。

从API version 9开始不再维护，建议使用findComponent⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
by	By	是	目标控件的属性要求。

返回值：

类型	说明
Promise<UiComponent>	以Promise形式返回找到的控件对象。

示例：

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

findComponents^(deprecated)

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

在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。

从API version 9开始不再维护，建议使用findComponents⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
by	By	是	目标控件的属性要求。

返回值：

类型	说明
Promise<Array<UiComponent>>	以Promise形式返回找到的控件对象的列表。

示例：

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

assertComponentExist^(deprecated)

assertComponentExist(by: By): Promise<void>

断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。

从API version 9开始不再维护，建议使用assertComponentExist⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
by	By	是	目标控件的属性要求。

错误码：

以下错误码的详细介绍请参见uitest测试框架错误码。

错误码ID	错误信息
17000002	if the async function was not called with await.
17000003	if the assertion failed.

示例：

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

pressBack^(deprecated)

pressBack(): Promise<void>

UiDriver对象进行点击BACK键的操作。

从API version 9开始不再维护，建议使用pressBack⁹⁺。

系统能力：SystemCapability.Test.UiTest

示例：

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

triggerKey^(deprecated)

triggerKey(keyCode: number): Promise<void>

UiDriver对象采取如下操作：通过key值找到对应键并点击。

从API version 9开始不再维护，建议使用triggerKey⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
keyCode	number	是	指定的key值。

示例：

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

click^(deprecated)

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

UiDriver对象采取如下操作：在目标坐标点单击。

从API version 9开始不再维护，建议使用click⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
x	number	是	以number的形式传入目标点的横坐标信息。
y	number	是	以number的形式传入目标点的纵坐标信息。

示例：

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

doubleClick^(deprecated)

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

UiDriver对象采取如下操作：在目标坐标点双击。

从API version 9开始不再维护，建议使用doubleClick⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
x	number	是	以number的形式传入目标点的横坐标信息。
y	number	是	以number的形式传入目标点的纵坐标信息。

示例：

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

longClick^(deprecated)

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

UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。

从API version 9开始不再维护，建议使用longClick⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
x	number	是	以number的形式传入目标点的横坐标信息。
y	number	是	以number的形式传入目标点的纵坐标信息。

示例：

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

swipe^(deprecated)

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

UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。

从API version 9开始不再维护，建议使用swipe⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
startx	number	是	以number的形式传入起始点的横坐标信息。
starty	number	是	以number的形式传入起始点的纵坐标信息。
endx	number	是	以number的形式传入目的点的横坐标信息。
endy	number	是	以number的形式传入目的点的纵坐标信息。

示例：

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

screenCap^(deprecated)

screenCap(savePath: string): Promise<boolean>

UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。

从API version 9开始不再维护，建议使用screenCap⁹⁺。

系统能力：SystemCapability.Test.UiTest

参数：

参数名	类型	必填	说明
savePath	string	是	文件保存路径。

返回值：

类型	说明
Promise<boolean>	截图操作是否成功完成。成功完成为true。

示例：

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述（仅对系统应用开放）

harmony 鸿蒙BundleStatusCallback

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

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

0 赞

所属分类： 后端技术
本文标签： 软件鸿蒙
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/c97587a07eb5449da88dfe95f80ef7ad

harmony 鸿蒙@ohos.UiTest

@ohos.UiTest

导入模块

MatchPattern

ResizeDirection9+

Point9+

Rect9+

WindowMode9+

DisplayRotation9+

WindowFilter9+

UiDirection10+

MouseButton10+

UIElementInfo10+

On9+

text9+

id9+

type9+

clickable9+

longClickable9+

scrollable9+

enabled9+

focused9+

selected9+

checked9+

checkable9+

isBefore9+

isAfter9+

within10+

inWindow10+

Component9+

click9+

doubleClick9+

longClick9+

getId9+

getText9+

getType9+

getBounds9+

getBoundsCenter9+

isClickable9+

isLongClickable9+

isChecked9+

isCheckable9+

isScrollable9+

isEnabled9+

isFocused9+

isSelected9+

inputText9+

clearText9+

scrollSearch9+

scrollToTop9+

scrollToBottom9+

dragTo9+

pinchOut9+

pinchIn9+

Driver9+

create9+

delayMs9+

findComponent9+

findComponents9+

findWindow9+

waitForComponent9+

assertComponentExist9+

pressBack9+

triggerKey9+

triggerCombineKeys9+

click9+

doubleClick9+

longClick9+

swipe9+

drag9+

screenCap9+

setDisplayRotation9+

getDisplayRotation9+

setDisplayRotationEnabled9+

getDisplaySize9+

getDisplayDensity9+

wakeUpDisplay9+

pressHome9+

waitForIdle9+

fling9+

ResizeDirection⁹⁺

Point⁹⁺

Rect⁹⁺

WindowMode⁹⁺

DisplayRotation⁹⁺

WindowFilter⁹⁺

UiDirection¹⁰⁺

MouseButton¹⁰⁺

UIElementInfo¹⁰⁺

On⁹⁺

text⁹⁺

id⁹⁺

type⁹⁺

clickable⁹⁺

longClickable⁹⁺

scrollable⁹⁺

enabled⁹⁺

focused⁹⁺

selected⁹⁺

checked⁹⁺

checkable⁹⁺

isBefore⁹⁺

isAfter⁹⁺

within¹⁰⁺

inWindow¹⁰⁺

Component⁹⁺

click⁹⁺

doubleClick⁹⁺

longClick⁹⁺

getId⁹⁺

getText⁹⁺

getType⁹⁺

getBounds⁹⁺

getBoundsCenter⁹⁺

isClickable⁹⁺

isLongClickable⁹⁺

isChecked⁹⁺

isCheckable⁹⁺

isScrollable⁹⁺

isEnabled⁹⁺

isFocused⁹⁺

isSelected⁹⁺

inputText⁹⁺

clearText⁹⁺

scrollSearch⁹⁺

scrollToTop⁹⁺

scrollToBottom⁹⁺

dragTo⁹⁺

pinchOut⁹⁺

pinchIn⁹⁺

Driver⁹⁺

create⁹⁺

delayMs⁹⁺

findComponent⁹⁺

findComponents⁹⁺

findWindow⁹⁺

waitForComponent⁹⁺

assertComponentExist⁹⁺

pressBack⁹⁺

triggerKey⁹⁺

triggerCombineKeys⁹⁺

click⁹⁺

doubleClick⁹⁺

longClick⁹⁺

swipe⁹⁺

drag⁹⁺

screenCap⁹⁺

setDisplayRotation⁹⁺

getDisplayRotation⁹⁺

setDisplayRotationEnabled⁹⁺

getDisplaySize⁹⁺

getDisplayDensity⁹⁺

wakeUpDisplay⁹⁺

pressHome⁹⁺

waitForIdle⁹⁺

fling⁹⁺

injectMultiPointerAction⁹⁺

fling¹⁰⁺

screenCapture¹⁰⁺

mouseClick¹⁰⁺