@ohos.uitest (UiTest)


@ohos.uitest (UiTest)

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

该模块提供以下功能:

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

说明:

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

导入模块

import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix} from '@ohos.uitest';
1

MatchPattern

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

系统能力:SystemCapability.Test.UiTest

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

ResizeDirection9+

窗口调整大小的方向。

系统能力:SystemCapability.Test.UiTest

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

Point9+

坐标点信息。

系统能力:SystemCapability.Test.UiTest

名称 类型 可读 可写 说明
X number 坐标点的横坐标。
Y number 坐标点的纵坐标。

Rect9+

控件的边框信息。

系统能力:SystemCapability.Test.UiTest

名称 类型 可读 可写 说明
leftX number 控件边框的左上角的X坐标。
topY number 控件边框的左上角的Y坐标。
rightX number 控件边框的右下角的X坐标。
bottomY number 控件边框的右下角的Y坐标。

WindowMode9+

系统能力:SystemCapability.Test.UiTest

窗口的窗口模式。

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

DisplayRotation9+

系统能力:SystemCapability.Test.UiTest

设备显示器的显示方向。

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

WindowFilter9+

窗口的标志属性信息。

系统能力:SystemCapability.Test.UiTest

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

On9+

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

ON.text('123').type('button');
1

text9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.text('123'); // 使用静态构造器ON创建On对象,指定目标控件的text属性。
1

id9+

id(id: string): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.id('123'); // 使用静态构造器ON创建On对象,指定目标控件的id属性。
1

type9+

type(tp: string): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.type('button'); // 使用静态构造器ON创建On对象,指定目标控件的控件类型属性。
1

clickable9+

clickable(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.clickable(true); // 使用静态构造器ON创建On对象,指定目标控件的可点击状态属性。
1

longClickable9+

longClickable(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.longClickable(true); // 使用静态构造器ON创建On对象,指定目标控件的可长按点击状态属性。
1

scrollable9+

scrollable(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.scrollable(true); // 使用静态构造器ON创建On对象,指定目标控件的可滑动状态属性。
1

enabled9+

enabled(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.enabled(true); // 使用静态构造器ON创建On对象,指定目标控件的使能状态属性。
1

focused9+

focused(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.focused(true); // 使用静态构造器ON创建On对象,指定目标控件的获焦状态属性。
1

selected9+

selected(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.selected(true); // 使用静态构造器ON创建On对象,指定目标控件的被选中状态属性。
1

checked9+

checked(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.checked(true); // 使用静态构造器ON创建On对象,指定目标控件的被勾选状态属性
1

checkable9+

checkable(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let on = ON.checkable(true); // 使用静态构造器ON创建On对象,指定目标控件的能否被勾选状态属性。
1

isBefore9+

isBefore(on: On): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

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

isAfter9+

isAfter(on: On): On

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

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

Component9+

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

click9+

click(): Promise<void>

控件对象进行点击操作。

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.click();
}
1
2
3
4
5

doubleClick9+

doubleClick(): Promise<void>

控件对象进行双击操作。

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.doubleClick();
}
1
2
3
4
5

longClick9+

longClick(): Promise<void>

控件对象进行长按操作。

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.longClick();
}
1
2
3
4
5

getId9+

getId(): Promise<string>

获取控件对象的id值。

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let num = await button.getId();
}
1
2
3
4
5

getText9+

getText(): Promise<string>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let text = await button.getText();
}
1
2
3
4
5

getType9+

getType(): Promise<string>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let type = await button.getType();
}
1
2
3
4
5

getBounds9+

getBounds(): Promise<Rect>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let rect = await button.getBounds();
}
1
2
3
4
5

getBoundsCenter9+

getBoundsCenter(): Promise<Point>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let point = await button.getBoundsCenter();
}
1
2
3
4
5

isClickable9+

isClickable(): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

isLongClickable9+

isLongClickable(): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

isChecked9+

isChecked(): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

isCheckable9+

isCheckable(): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

isScrollable9+

isScrollable(): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

isEnabled9+

isEnabled(): Promise<boolean>

获取控件使能状态。

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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');
    }
}

1
2
3
4
5
6
7
8
9
10

isFocused9+

isFocused(): Promise<boolean>

判断控件对象获焦状态。

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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');
	}
}
1
2
3
4
5
6
7
8
9

isSelected9+

isSelected(): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

inputText9+

inputText(text: string): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let text = await driver.findComponent(ON.text('hello world'));
    await text.inputText('123');
}
1
2
3
4
5

clearText9+

clearText(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let text = await driver.findComponent(ON.text('hello world'));
    await text.clearText();
}
1
2
3
4
5

scrollSearch9+

scrollSearch(on: On): Promise<Component>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('Scroll'));
    let button = await scrollBar.scrollSearch(ON.text('next page'));
}
1
2
3
4
5

scrollToTop9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let scrollBar = await driver.findComponent(ON.type('Scroll'));
    await scrollBar.scrollToTop();
}
1
2
3
4
5

scrollToBottom9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let scrollBar = await driver.findComponent(ON.type('Scroll'));
    await scrollBar.scrollToBottom();
}
1
2
3
4
5

dragTo9+

dragTo(target: Component): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

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);
    }
1
2
3
4
5
6

pinchOut9+

pinchOut(scale: number): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let image = await driver.findComponent(ON.type('image'));
    await image.pinchOut(1.5);
    }
1
2
3
4
5

pinchIn9+

pinchIn(scale: number): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let image = await driver.findComponent(ON.type('image'));
    await image.pinchIn(0.5);
    }
1
2
3
4
5

Driver9+

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

create9+

static create(): Driver

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000001 Initialize failed.

示例:

async function demo() {
    let driver = Driver.create();
}
1
2
3

delayMs9+

delayMs(duration: number): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.delayMs(1000);
}
1
2
3
4

findComponent9+

findComponent(on: On): Promise<Component>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.text('next page'));
}
1
2
3
4

findComponents9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    let buttonList = await driver.findComponents(ON.text('next page'));
}
1
2
3
4

findWindow9+

findWindow(filter: WindowFilter): Promise<UiWindow>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

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

waitForComponent9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

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

assertComponentExist9+

assertComponentExist(on: On): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000003 Component existence assertion failed.

示例:

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

pressBack9+

pressBack(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.pressBack();
}
1
2
3
4

triggerKey9+

triggerKey(keyCode: number): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.triggerKey(123);
}
1
2
3
4

triggerCombineKeys9+

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 API does not allow calling concurrently.

示例:

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

click9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.click(100,100);
}
1
2
3
4

doubleClick9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.doubleClick(100,100);
}
1
2
3
4

longClick9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.longClick(100,100);
}
1
2
3
4

swipe9+

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 API does not allow calling concurrently.

示例:

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

drag9+

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 API does not allow calling concurrently.

示例:

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

screenCap9+

screenCap(savePath: string): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.screenCap('/local/tmp/1.png');
}
1
2
3
4

setDisplayRotation9+

setDisplayRotation(rotation: DisplayRotation): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.setDisplayRotation(DisplayRotation.ROTATION_180);
}
1
2
3
4

getDisplayRotation9+

getDisplayRotation(): Promise<DisplayRotation>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    let rotation = await driver.getDisplayRotation();
}
1
2
3
4

setDisplayRotationEnabled9+

setDisplayRotationEnabled(enabled: boolean): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.setDisplayRotationEnabled(false);
}
1
2
3
4

getDisplaySize9+

getDisplaySize(): Promise<Point>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    let size = await driver.getDisplaySize();
}
1
2
3
4

getDisplayDensity9+

getDisplayDensity(): Promise<Point>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    let density = await driver.getDisplayDensity();
}
1
2
3
4

wakeUpDisplay9+

wakeUpDisplay(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.wakeUpDisplay();
}
1
2
3
4

pressHome9+

pressHome(): Promise<void>

设备返回到桌面。

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.pressHome();
}
1
2
3
4

waitForIdle9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    let idled = await driver.waitForIdle(4000,5000);
}
1
2
3
4

fling9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

async function demo() {
    let driver = Driver.create();
    await driver.fling({X: 500, Y: 480},{X: 450, Y: 480},5,600);
}
1
2
3
4

injectMultiPointerAction9+

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

向设备注入多指操作。

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.

示例:

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);
}
1
2
3
4
5
6
7
8
9
10
11

PointerMatrix9+

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

create9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

async function demo() {
    let pointerMatrix = PointerMatrix.create(2,3);
}
1
2
3

setPoint9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

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});
}
1
2
3
4
5
6
7
8
9

UiWindow9+

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

getBundleName9+

getBundleName(): Promise<string>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let name = await window.getBundleName();
}
1
2
3
4
5

getBounds9+

getBounds(): Promise<Rect>

获取窗口的边框信息。

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let rect = await window.getBounds();
}
1
2
3
4
5

getTitle9+

getTitle(): Promise<string>

获取窗口的标题信息。

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let rect = await window.getTitle();
}
1
2
3
4
5

getWindowMode9+

getWindowMode(): Promise<WindowMode>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let mode = await window.getWindowMode();
}
1
2
3
4
5

isFocused9+

isFocused(): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let focused = await window.isFocused();
}
1
2
3
4
5

isActived9+

isActived(): Promise<boolean>

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let focused = await window.isActived();
}
1
2
3
4
5

focus9+

focus(): Promise<void>

让窗口获焦。

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.focus();
}
1
2
3
4
5

moveTo9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.
17000005 This operation is not supported.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.moveTo(100, 100);
}
1
2
3
4
5

resize9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

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

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.
17000005 This operation is not supported.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.resize(100, 100, ResizeDirection.LEFT);
}
1
2
3
4
5

split9+

split(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.
17000005 This operation is not supported.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.split();
}
1
2
3
4
5

maximize9+

maximize(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.
17000005 This operation is not supported.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.maximize();
}
1
2
3
4
5

minimize9+

minimize(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.
17000005 This operation is not supported.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.minimize();
}
1
2
3
4
5

resume9+

resume(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.
17000005 This operation is not supported.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.resume();
}
1
2
3
4
5

close9+

close(): Promise<void>

将窗口关闭。

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID 错误信息
17000002 API does not allow calling concurrently.
17000004 Component lost/UiWindow lost.
17000005 This operation is not supported.

示例:

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.close();
}
1
2
3
4
5

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开始不再维护,建议使用On9+

BY.text('123').type('button');
1

text(deprecated)

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

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

从API version 9开始不再维护,建议使用text9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.text('123'); // 使用静态构造器BY创建by对象,指定目标控件的text属性。
1

key(deprecated)

key(key: string): By

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

从API version 9开始不再维护,建议使用id9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.key('123'); // 使用静态构造器BY创建by对象,指定目标控件的key值属性。
1

id(deprecated)

id(id: number): By

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

从API version 9开始废弃。

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.id(123); // 使用静态构造器BY创建by对象,指定目标控件的id属性。
1

type(deprecated)

type(tp: string): By

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

从API version 9开始不再维护,建议使用type9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.type('button'); // 使用静态构造器BY创建by对象,指定目标控件的控件类型属性。
1

clickable(deprecated)

clickable(b?: boolean): By

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

从API version 9开始不再维护,建议使用clickable9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.clickable(true); // 使用静态构造器BY创建by对象,指定目标控件的可点击状态属性。
1

scrollable(deprecated)

scrollable(b?: boolean): By

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

从API version 9开始不再维护,建议使用scrollable9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.scrollable(true); // 使用静态构造器BY创建by对象,指定目标控件的可滑动状态属性。
1

enabled(deprecated)

enabled(b?: boolean): By

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

从API version 9开始不再维护,建议使用enabled9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.enabled(true); // 使用静态构造器BY创建by对象,指定目标控件的使能状态属性。
1

focused(deprecated)

focused(b?: boolean): By

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

从API version 9开始不再维护,建议使用focused9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.focused(true); // 使用静态构造器BY创建by对象,指定目标控件的获焦状态属性。
1

selected(deprecated)

selected(b?: boolean): By

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

从API version 9开始不再维护,建议使用selected9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

let by = BY.selected(true); // 使用静态构造器BY创建by对象,指定目标控件的被选中状态属性。
1

isBefore(deprecated)

isBefore(by: By): By

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

从API version 9开始不再维护,建议使用isBefore9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

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

isAfter(deprecated)

isAfter(by: By): By

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

从API version 9开始不再维护,建议使用isAfter9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

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

UiComponent(deprecated)

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

从API version 9开始不再维护,建议使用Component9+

click(deprecated)

click(): Promise<void>

控件对象进行点击操作。

从API version 9开始不再维护,建议使用click9+

系统能力:SystemCapability.Test.UiTest

示例:

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.click();
}
1
2
3
4
5

doubleClick(deprecated)

doubleClick(): Promise<void>

控件对象进行双击操作。

从API version 9开始不再维护,建议使用doubleClick9+

系统能力:SystemCapability.Test.UiTest

示例:

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.doubleClick();
}
1
2
3
4
5

longClick(deprecated)

longClick(): Promise<void>

控件对象进行长按操作。

从API version 9开始不再维护,建议使用longClick9+

系统能力:SystemCapability.Test.UiTest

示例:

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.longClick();
}
1
2
3
4
5

getId(deprecated)

getId(): Promise<number>

获取控件对象的id值。

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

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let num = await button.getId();
}
1
2
3
4
5

getKey(deprecated)

getKey(): Promise<string>

获取控件对象的key值。

从API version 9开始不再维护,建议使用getId9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let str_key = await button.getKey();
}
1
2
3
4
5

getText(deprecated)

getText(): Promise<string>

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

从API version 9开始不再维护,建议使用getText9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let text = await button.getText();
}
1
2
3
4
5

getType(deprecated)

getType(): Promise<string>

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

从API version 9开始不再维护,建议使用getType9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let type = await button.getType();
}
1
2
3
4
5

isClickable(deprecated)

isClickable(): Promise<boolean>

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

从API version 9开始不再维护,建议使用isClickable9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

isScrollable(deprecated)

isScrollable(): Promise<boolean>

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

从API version 9开始不再维护,建议使用isScrollable9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

isEnabled(deprecated)

isEnabled(): Promise<boolean>

获取控件使能状态。

从API version 9开始不再维护,建议使用isEnabled9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

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');
    }
}

1
2
3
4
5
6
7
8
9
10

isFocused(deprecated)

isFocused(): Promise<boolean>

判断控件对象是否获焦。

从API version 9开始不再维护,建议使用isFocused9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

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');
	}
}
1
2
3
4
5
6
7
8
9

isSelected(deprecated)

isSelected(): Promise<boolean>

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

从API version 9开始不再维护,建议使用isSelected9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

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');
    }
}
1
2
3
4
5
6
7
8
9

inputText(deprecated)

inputText(text: string): Promise<void>

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

从API version 9开始不再维护,建议使用inputText9+

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    let text = await driver.findComponent(BY.text('hello world'));
    await text.inputText('123');
}
1
2
3
4
5

scrollSearch(deprecated)

scrollSearch(by: By): Promise<UiComponent>

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

从API version 9开始不再维护,建议使用scrollSearch9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    let scrollBar = await driver.findComponent(BY.type('Scroll'));
    let button = await scrollBar.scrollSearch(BY.text('next page'));
}
1
2
3
4
5

UiDriver(deprecated)

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

从API version 9开始不再维护,建议使用Driver9+

create(deprecated)

static create(): UiDriver

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

从API version 9开始不再维护,建议使用create9+

系统能力:SystemCapability.Test.UiTest

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
}
1
2
3

delayMs(deprecated)

delayMs(duration: number): Promise<void>

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

从API version 9开始不再维护,建议使用delayMs9+

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.delayMs(1000);
}
1
2
3
4

findComponent(deprecated)

findComponent(by: By): Promise<UiComponent>

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

从API version 9开始不再维护,建议使用findComponent9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.text('next page'));
}
1
2
3
4

findComponents(deprecated)

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

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

从API version 9开始不再维护,建议使用findComponents9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    let buttonList = await driver.findComponents(BY.text('next page'));
}
1
2
3
4

assertComponentExist(deprecated)

assertComponentExist(by: By): Promise<void>

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

从API version 9开始不再维护,建议使用assertComponentExist9+

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.assertComponentExist(BY.text('next page'));
}
1
2
3
4

pressBack(deprecated)

pressBack(): Promise<void>

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

从API version 9开始不再维护,建议使用pressBack9+

系统能力:SystemCapability.Test.UiTest

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.pressBack();
}
1
2
3
4

triggerKey(deprecated)

triggerKey(keyCode: number): Promise<void>

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

从API version 9开始不再维护,建议使用triggerKey9+

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.triggerKey(123);
}
1
2
3
4

click(deprecated)

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

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

从API version 9开始不再维护,建议使用click9+

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.click(100,100);
}
1
2
3
4

doubleClick(deprecated)

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

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

从API version 9开始不再维护,建议使用doubleClick9+

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.doubleClick(100,100);
}
1
2
3
4

longClick(deprecated)

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

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

从API version 9开始不再维护,建议使用longClick9+

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.longClick(100,100);
}
1
2
3
4

swipe(deprecated)

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

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

从API version 9开始不再维护,建议使用swipe9+

系统能力:SystemCapability.Test.UiTest

参数:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.swipe(100,100,200,200);
}
1
2
3
4

screenCap(deprecated)

screenCap(savePath: string): Promise<boolean>

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

从API version 9开始不再维护,建议使用screenCap9+

系统能力:SystemCapability.Test.UiTest

参数:

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

返回值:

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

示例:

async function demo() {
    let driver = UiDriver.create();
    await driver.screenCap('/local/tmp/1.png');
}
1
2
3
4