UiTest

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

该模块提供以下功能：

• By：提供控件特征描述能力，用于控件筛选匹配查找。
• UiComponent：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。
• UiDriver：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。

说明：

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

导入模块

import {UiDriver,BY,MatchPattern} from '@ohos.uitest'

By

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

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

By.text

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

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.key

key(key: string): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.id

id(id: number): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.type

type(tp: string): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.clickable

clickable(b?: bool): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.scrollable

scrollable(b?: bool): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.enabled

enabled(b?: bool): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.focused

focused(b?: bool): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.selected

selected(b?: bool): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.isBefore

isBefore(by: By): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

By.isAfter

isAfter(by: By): By

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

UiComponent

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

UiComponent.click

click(): Promise<void>

控件对象进行点击操作。

系统能力：SystemCapability.Test.UiTest

示例：

async function demo() {
    let driver = UiDriver.create()
    let button = await driver.findComponent(BY.type('button'))
    await button.click()
}

UiComponent.doubleClick

doubleClick(): Promise<void>

控件对象进行双击操作。

系统能力：SystemCapability.Test.UiTest

示例：

async function demo() {
    let driver = UiDriver.create()
    let button = await driver.findComponent(BY.type('button'))
    await button.doubleClick()
}

UiComponent.longClick

longClick(): Promise<void>

控件对象进行长按操作。

系统能力：SystemCapability.Test.UiTest

示例：

async function demo() {
    let driver = UiDriver.create()
    let button = await driver.findComponent(BY.type('button'))
    await button.longClick()
}

UiComponent.getId

getId(): Promise<number>

获取控件对象的id值。

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

async function demo() {
    let driver = UiDriver.create()
    let button = await driver.findComponent(BY.type('button'))
    let num = await button.getId()
}

UiComponent.getKey

getKey(): Promise<string>

获取控件对象的key值。

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

async function demo() {
    let driver = UiDriver.create()
    let button = await driver.findComponent(BY.type('button'))
    let str_key = await button.getKey()
}

UiComponent.getText

getText(): Promise<string>

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

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

async function demo() {
    let driver = UiDriver.create()
    let button = await driver.findComponent(BY.type('button'))
    let text = await button.getText()
}

UiComponent.getType

getType(): Promise<string>

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

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

async function demo() {
    let driver = UiDriver.create()
    let button = await driver.findComponent(BY.type('button'))
    let type = await button.getType()
}

UiComponent.isClickable

isClickable(): Promise<bool>

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

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

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

UiComponent.isScrollable

isScrollable(): Promise<bool>

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

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

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

UiComponent.isEnabled

isEnabled(): Promise<bool>

获取控件使能状态。

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

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

UiComponent.isFocused

isFocused(): Promise<bool>

判断控件对象是否获焦。

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

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

UiComponent.isSelected

isSelected(): Promise<bool>

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

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

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

UiComponent.inputText

inputText(text: string): Promise<void>

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

系统能力：SystemCapability.Test.UiTest

参数：

示例：

async function demo() {
    let driver = UiDriver.create()
    let text = await driver.findComponent(BY.text('hello world'))
    await text.inputText('123')
}

UiComponent.scrollSearch

scrollSearch(by:By): Promise<UiComponent>

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

UiDriver

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

UiDriver.create

static create(): UiDriver

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

系统能力：SystemCapability.Test.UiTest

返回值：

示例：

async function demo() {
    let driver = UiDriver.create()
}

UiDriver.delayMs

delayMs(duration: number): Promise<void>

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

系统能力：SystemCapability.Test.UiTest

参数：

示例：

async function demo() {
    let driver = UiDriver.create()
    await driver.delayMs(1000)
}

UiDriver.findComponent

findComponent(by: By): Promise<UiComponent>

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

UiDriver.findComponents

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

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

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

UiDriver.assertComponentExist

assertComponentExist(by: By): Promise<void>

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

系统能力：SystemCapability.Test.UiTest

参数：

示例：

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

UiDriver.pressBack

pressBack(): Promise<void>

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

系统能力：SystemCapability.Test.UiTest

示例：

async function demo() {
    let driver = UiDriver.create()
    await driver.pressBack()
}

UiDriver.triggerKey

triggerKey(keyCode: number): Promise<void>

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

系统能力：SystemCapability.Test.UiTest

参数：

示例：

async function demo() {
    let driver = UiDriver.create()
    await driver.triggerKey(123)
}

UiDriver.click

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

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

系统能力：SystemCapability.Test.UiTest

参数：

示例：

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

UiDriver.doubleClick

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

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

系统能力：SystemCapability.Test.UiTest

参数：

示例：

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

UiDriver.longClick

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

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

系统能力：SystemCapability.Test.UiTest

参数：

示例：

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

UiDriver.swipe

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

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

系统能力：SystemCapability.Test.UiTest

参数：

示例：

async function demo() {
    let driver = UiDriver.create()
    await driver.swipe(100,100,200,200)
}

UiDriver.screenCap

screenCap(savePath: string): Promise<bool>

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

系统能力：SystemCapability.Test.UiTest

参数：

返回值：

示例：

async function demo() {
    let driver = UiDriver.create()
    await driver.screenCap('/local/tmp/')
}

MatchPattern

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

系统能力：以下各项对应的系统能力均为SystemCapability.Test.UiTest