模拟UI操作的能力

2024-01-23 18:23 更新

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开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

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

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

名称

类型

可读

可写

说明

left

number

控件边框的左上角的X坐标。

top

number

控件边框的左上角的Y坐标。

right

number

控件边框的右下角的X坐标。

bottom

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对象。

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

text9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

txt

string

指定控件文本,用于匹配目标控件文本。

pattern

MatchPattern

指定的文本匹配模式,默认为EQUALS

返回值:

类型

说明

On

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

示例:

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

id9+

id(id: string): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

id

string

指定控件的id值。

返回值:

类型

说明

On

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

示例:

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

type9+

type(tp: string): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

tp

string

指定控件类型。

返回值:

类型

说明

On

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

示例:

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

clickable9+

clickable(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件可点击状态,true:可点击,false:不可点击。默认为true。

返回值:

类型

说明

On

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

示例:

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

longClickable9+

longClickable(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件可长按点击状态,true:可长按点击,false:不可长按点击。默认为true。

返回值:

类型

说明

On

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

示例:

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

scrollable9+

scrollable(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

控件可滑动状态,true:可滑动,false:不可滑动。默认为true。

返回值:

类型

说明

On

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

示例:

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

enabled9+

enabled(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件使能状态,true:使能,false:未使能。默认为true。

返回值:

类型

说明

On

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

示例:

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

focused9+

focused(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

控件获焦状态,true:获焦,false:未获焦。默认为true。

返回值:

类型

说明

On

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

示例:

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

selected9+

selected(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件被选中状态,true:被选中,false:未被选中。默认为true。

返回值:

类型

说明

On

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

示例:

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

checked9+

checked(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件被勾选状态,true:被勾选,false:未被勾选。默认为false。

返回值:

类型

说明

On

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

示例:

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

checkable9+

checkable(b?: boolean): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件能否被勾选状态,true:能被勾选,false:不能被勾选。默认为false。

返回值:

类型

说明

On

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

示例:

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

isBefore9+

isBefore(on: On): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

on

On

特征控件的属性要求。

返回值:

类型

说明

On

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

示例:

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

isAfter9+

isAfter(on: On): On

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

on

On

特征控件的属性要求。

返回值:

类型

说明

On

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

示例:

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

Component9+

UiTest框架在API9中,Component类代表了UI界面上的一个控件,提供控件属性获取,控件点击,滑动查找,文本注入等API。

该类提供的所有方法都使用Promise方式作为异步方法,需使用await调用。

click9+

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.

示例:

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

doubleClick9+

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.

示例:

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

longClick9+

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.

示例:

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

getId9+

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.

示例:

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

getText9+

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.

示例:

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

getType9+

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.

示例:

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

getBounds9+

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.

示例:

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

getBoundsCenter9+

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.

示例:

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

isClickable9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let button = await driver.findComponent(ON.type('button'));
  4. if(await button.isClickable()) {
  5. console.info('This button can be Clicked');
  6. } else {
  7. console.info('This button can not be Clicked');
  8. }
  9. }

isLongClickable9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let button = await driver.findComponent(ON.type('button'));
  4. if(await button.isLongClickable()) {
  5. console.info('This button can longClick');
  6. } else {
  7. console.info('This button can not longClick');
  8. }
  9. }

isChecked9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let checkBox = await driver.findComponent(ON.type('Checkbox'));
  4. if(await checkBox.isChecked) {
  5. console.info('This checkBox is checked');
  6. } else {
  7. console.info('This checkBox is not checked');
  8. }
  9. }

isCheckable9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let checkBox = await driver.findComponent(ON.type('Checkbox'));
  4. if(await checkBox.isCheckable) {
  5. console.info('This checkBox is checkable');
  6. } else {
  7. console.info('This checkBox is not checkable');
  8. }
  9. }

isScrollable9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let scrollBar = await driver.findComponent(ON.scrollable(true));
  4. if(await scrollBar.isScrollable()) {
  5. console.info('This scrollBar can be operated');
  6. } else {
  7. console.info('This scrollBar can not be operated');
  8. }
  9. }

isEnabled9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let button = await driver.findComponent(ON.type('button'));
  4. if(await button.isEnabled()) {
  5. console.info('This button can be operated');
  6. } else {
  7. console.info('This button can not be operated');
  8. }
  9. }

isFocused9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let button = await driver.findComponent(ON.type('button'));
  4. if(await button.isFocused()) {
  5. console.info('This button is focused');
  6. } else {
  7. console.info('This button is not focused');
  8. }
  9. }

isSelected9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let button = await driver.findComponent(ON.type('button'));
  4. if(await button.isSelected()) {
  5. console.info('This button is selected');
  6. } else {
  7. console.info('This button is not selected');
  8. }
  9. }

inputText9+

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.

示例:

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

clearText9+

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.

示例:

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

scrollSearch9+

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.

示例:

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

scrollToTop9+

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.

示例:

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

scrollToBottom9+

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.

示例:

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

dragTo9+

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.

示例:

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

pinchOut9+

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.

示例:

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

pinchIn9+

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.

示例:

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

Driver9+

Driver类为uitest测试框架的总入口,提供控件匹配/查找,按键注入,坐标点击/滑动,截图等能力。

该类提供的方法除Driver.create()以外的所有方法都使用Promise方式作为异步方法,需使用await方式调用。

create9+

static create(): Driver

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Driver

返回构造的Driver对象。

错误码:

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

错误码ID

错误信息

17000001

if the test framework failed to initialize.

示例:

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

delayMs9+

delayMs(duration: number): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

duration

number

给定的时间,单位:ms。

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

findComponent9+

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.

示例:

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

findComponents9+

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.

示例:

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

findWindow9+

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.

示例:

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

waitForComponent9+

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.

示例:

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

assertComponentExist9+

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.

示例:

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

pressBack9+

pressBack(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

triggerKey9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. await driver.triggerKey(123);
  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

if the async function was not called with await.

示例:

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

click9+

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.

示例:

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

doubleClick9+

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.

示例:

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

longClick9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. await driver.longClick(100,100);
  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

if the async function was not called with await.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. await driver.swipe(100,100,200,200,600);
  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

if the async function was not called with await.

示例:

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

screenCap9+

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.

示例:

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

setDisplayRotation9+

setDisplayRotation(rotation: DisplayRotation): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

rotation

DisplayRotation

设备的显示方向。

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

getDisplayRotation9+

getDisplayRotation(): Promise<DisplayRotation>

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<DisplayRotation>

以Promise的形式返回当前设备的显示方向。

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

setDisplayRotationEnabled9+

setDisplayRotationEnabled(enabled: boolean): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

enabled

boolean

能否旋转屏幕的标识,true:可以旋转,false:不可以旋转。

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

getDisplaySize9+

getDisplaySize(): Promise<Point>

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<Point>

以Promise的形式返回当前设备的屏幕大小。

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

getDisplayDensity9+

getDisplayDensity(): Promise<Point>

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<Point>

以Promise的形式返回当前设备屏幕的分辨率。

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

wakeUpDisplay9+

wakeUpDisplay(): Promise<void>

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

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

pressHome9+

pressHome(): Promise<void>

设备返回到桌面。

系统能力:SystemCapability.Test.UiTest

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

示例:

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

waitForIdle9+

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.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let idled = await driver.waitForIdle(4000,5000);
  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

if the async function was not called with await.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. await driver.fling({x: 500, y: 480},{x: 450, y: 480},5,600);
  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

if the async function was not called with await.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let pointers = PointerMatrix.create(2,3);
  4. pointers.setPoint(0,0,{x:230,y:480});
  5. pointers.setPoint(0,1,{x:250,y:380});
  6. pointers.setPoint(0,2,{x:270,y:280});
  7. pointers.setPoint(1,0,{x:230,y:680});
  8. pointers.setPoint(1,1,{x:240,y:580});
  9. pointers.setPoint(1,2,{x:250,y:480});
  10. await driver.injectMultiPointerAction(pointers);
  11. }

PointerMatrix9+

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

create9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

fingers

number

多指操作中注入的手指数,取值范围:[1,10]。

steps

number

每根手指操作的步骤数,取值范围:[1,1000]。

返回值:

类型

说明

PointerMatrix

返回构造的PointerMatrix对象。

示例:

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

setPoint9+

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

finger

number

手指的序号。

step

number

步骤的序号。

point

Point

该行为的坐标点。

示例:

  1. async function demo() {
  2. let pointers = PointerMatrix.create(2,3);
  3. pointers.setPoint(0,0,{x:230,y:480});
  4. pointers.setPoint(0,1,{x:250,y:380});
  5. pointers.setPoint(0,2,{x:270,y:280});
  6. pointers.setPoint(1,0,{x:230,y:680});
  7. pointers.setPoint(1,1,{x:240,y:580});
  8. pointers.setPoint(1,2,{x:250,y:480});
  9. }

UiWindow9+

UiWindow代表了UI界面上的一个窗口,提供窗口属性获取,窗口拖动、调整窗口大小等能力。

该类提供的所有方法都使用Promise方式作为异步方法,需使用await方式调用。

getBundleName9+

getBundleName(): 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.

示例:

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

getBounds9+

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.

示例:

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

getTitle9+

getTitle(): 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.

示例:

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

getWindowMode9+

getWindowMode(): Promise<WindowMode>

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<WindowMode>

以Promise形式返回窗口的窗口模式信息。

错误码:

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

错误码ID

错误信息

17000002

if the async function was not called with await.

17000004

if the component is invisible or destroyed.

示例:

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

isFocused9+

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.

示例:

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

isActived9+

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 component is invisible or destroyed.

示例:

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

focus9+

focus(): 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.

示例:

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

moveTo9+

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 component is invisible or destroyed.

17000005

if the action is not supported on this window.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let window = await driver.findWindow({actived: true});
  4. await window.moveTo(100, 100);
  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

if the async function was not called with await.

17000004

if the component is invisible or destroyed.

17000005

if the action is not supported on this window.

示例:

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

split9+

split(): 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.

17000005

if the action is not supported on this window.

示例:

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

maximize9+

maximize(): 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.

17000005

if the action is not supported on this window.

示例:

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

minimize9+

minimize(): 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.

17000005

if the action is not supported on this window.

示例:

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

resume9+

resume(): 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.

17000005

if the action is not supported on this window.

示例:

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

close9+

close(): 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.

17000005

if the action is not supported on this window.

示例:

  1. async function demo() {
  2. let driver = Driver.create();
  3. let window = await driver.findWindow({actived: true});
  4. await window.close();
  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+

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

text(deprecated)

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

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

txt

string

指定控件文本,用于匹配目标控件文本。

pattern

MatchPattern

指定的文本匹配模式,默认为EQUALS

返回值:

类型

说明

By

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

示例:

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

key(deprecated)

key(key: string): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

key

string

指定控件的Key值。

返回值:

类型

说明

By

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

示例:

  1. 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对象。

示例:

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

type(deprecated)

type(tp: string): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

tp

string

指定控件类型。

返回值:

类型

说明

By

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

示例:

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

clickable(deprecated)

clickable(b?: boolean): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件可点击状态,true:可点击,false:不可点击。默认为true。

返回值:

类型

说明

By

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

示例:

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

scrollable(deprecated)

scrollable(b?: boolean): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

控件可滑动状态,true:可滑动,false:不可滑动。默认为true。

返回值:

类型

说明

By

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

示例:

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

enabled(deprecated)

enabled(b?: boolean): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件使能状态,true:使能,false:未使能。默认为true。

返回值:

类型

说明

By

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

示例:

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

focused(deprecated)

focused(b?: boolean): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

控件获焦状态,true:获焦,false:未获焦。默认为true。

返回值:

类型

说明

By

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

示例:

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

selected(deprecated)

selected(b?: boolean): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

b

boolean

指定控件被选中状态,true:被选中,false:未被选中。默认为true。

返回值:

类型

说明

By

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

示例:

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

isBefore(deprecated)

isBefore(by: By): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

by

By

特征控件的属性。

返回值:

类型

说明

By

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

示例:

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

isAfter(deprecated)

isAfter(by: By): By

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

by

By

特征控件的属性。

返回值:

类型

说明

By

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

示例:

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

UiComponent(deprecated)

UiTest中,UiComponent类代表了UI界面上的一个控件,提供控件属性获取,控件点击,滑动查找,文本注入等API。

该类提供的所有方法都使用Promise方式作为异步方法,需使用await调用。

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

click(deprecated)

click(): Promise<void>

控件对象进行点击操作。

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

系统能力:SystemCapability.Test.UiTest

示例:

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

doubleClick(deprecated)

doubleClick(): Promise<void>

控件对象进行双击操作。

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

系统能力:SystemCapability.Test.UiTest

示例:

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

longClick(deprecated)

longClick(): Promise<void>

控件对象进行长按操作。

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

系统能力:SystemCapability.Test.UiTest

示例:

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

getId(deprecated)

getId(): Promise<number>

获取控件对象的id值。

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<number>

以Promise形式返回的控件的id值。

示例:

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

getKey(deprecated)

getKey(): Promise<string>

获取控件对象的key值。

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<string>

以Promise形式返回控件的key值。

示例:

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

getText(deprecated)

getText(): Promise<string>

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

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<string>

以Promise形式返回控件的文本信息。

示例:

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

getType(deprecated)

getType(): Promise<string>

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

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<string>

以Promise形式返回控件的类型。

示例:

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

isClickable(deprecated)

isClickable(): Promise<boolean>

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

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<boolean>

以Promise形式返回控件对象可点击状态,true:可点击,false:不可点击。

示例:

  1. async function demo() {
  2. let driver = UiDriver.create();
  3. let button = await driver.findComponent(BY.type('button'));
  4. if(await button.isClickable()) {
  5. console.info('This button can be Clicked');
  6. } else {
  7. console.info('This button can not be Clicked');
  8. }
  9. }

isScrollable(deprecated)

isScrollable(): Promise<boolean>

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

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<boolean>

以Promise形式返回控件对象可滑动状态,true:可滑动,false:不可滑动。

示例:

  1. async function demo() {
  2. let driver = UiDriver.create();
  3. let scrollBar = await driver.findComponent(BY.scrollable(true));
  4. if(await scrollBar.isScrollable()) {
  5. console.info('This scrollBar can be operated');
  6. } else {
  7. console.info('This scrollBar can not be operated');
  8. }
  9. }

isEnabled(deprecated)

isEnabled(): Promise<boolean>

获取控件使能状态。

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<boolean>

以Promise形式返回控件使能状态,true:使能,false:未使能。

示例:

  1. async function demo() {
  2. let driver = UiDriver.create();
  3. let button = await driver.findComponent(BY.type('button'));
  4. if(await button.isEnabled()) {
  5. console.info('This button can be operated');
  6. } else {
  7. console.info('This button can not be operated');
  8. }
  9. }

isFocused(deprecated)

isFocused(): Promise<boolean>

判断控件对象是否获焦。

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<boolean>

以Promise形式返回控件对象是否获焦,true:获焦,false:未获焦。

示例:

  1. async function demo() {
  2. let driver = UiDriver.create();
  3. let button = await driver.findComponent(BY.type('button'));
  4. if(await button.isFocused()) {
  5. console.info('This button is focused');
  6. } else {
  7. console.info('This button is not focused');
  8. }
  9. }

isSelected(deprecated)

isSelected(): Promise<boolean>

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

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

系统能力:SystemCapability.Test.UiTest

返回值:

类型

说明

Promise<boolean>

控件对象被选中的状态,true:被选中,false:未被选中。

示例:

  1. async function demo() {
  2. let driver = UiDriver.create();
  3. let button = await driver.findComponent(BY.type('button'));
  4. if(await button.isSelected()) {
  5. console.info('This button is selected');
  6. } else {
  7. console.info('This button is not selected');
  8. }
  9. }

inputText(deprecated)

inputText(text: string): Promise<void>

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

text

string

输入的文本信息。

示例:

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

scrollSearch(deprecated)

scrollSearch(by: By): Promise<UiComponent>

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

by

By

目标控件的属性要求。

返回值:

类型

说明

Promise<UiComponent>

以Promise形式返回找到的目标控件对象。

示例:

  1. async function demo() {
  2. let driver = UiDriver.create();
  3. let scrollBar = await driver.findComponent(BY.type('Scroll'));
  4. let button = await scrollBar.scrollSearch(BY.text('next page'));
  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对象。

示例:

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

delayMs(deprecated)

delayMs(duration: number): Promise<void>

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

duration

number

给定的时间。

示例:

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

findComponent(deprecated)

findComponent(by: By): Promise<UiComponent>

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

by

By

目标控件的属性要求。

返回值:

类型

说明

Promise<UiComponent>

以Promise形式返回找到的控件对象。

示例:

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

findComponents(deprecated)

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

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

by

By

目标控件的属性要求。

返回值:

类型

说明

Promise<Array<UiComponent>>

以Promise形式返回找到的控件对象的列表。

示例:

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

assertComponentExist(deprecated)

assertComponentExist(by: By): Promise<void>

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

by

By

目标控件的属性要求。

示例:

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

pressBack(deprecated)

pressBack(): Promise<void>

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

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

系统能力:SystemCapability.Test.UiTest

示例:

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

triggerKey(deprecated)

triggerKey(keyCode: number): Promise<void>

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

keyCode

number

指定的key值。

示例:

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

click(deprecated)

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

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

x

number

以number的形式传入目标点的横坐标信息。

y

number

以number的形式传入目标点的纵坐标信息。

示例:

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

doubleClick(deprecated)

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

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

x

number

以number的形式传入目标点的横坐标信息。

y

number

以number的形式传入目标点的纵坐标信息。

示例:

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

longClick(deprecated)

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

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

x

number

以number的形式传入目标点的横坐标信息。

y

number

以number的形式传入目标点的纵坐标信息。

示例:

  1. async function demo() {
  2. let driver = UiDriver.create();
  3. await driver.longClick(100,100);
  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的形式传入目的点的纵坐标信息。

示例:

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

screenCap(deprecated)

screenCap(savePath: string): Promise<boolean>

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

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

系统能力:SystemCapability.Test.UiTest

参数:

参数名

类型

必填

说明

savePath

string

文件保存路径。

返回值:

类型

说明

Promise<boolean>

截图操作是否成功完成。成功完成为true。

示例:

  1. async function demo() {
  2. let driver = UiDriver.create();
  3. await driver.screenCap('/local/tmp/1.png');
  4. }
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号