UiTest

UiTest提供模擬UI操作的能力，供開(kāi)發(fā)者在測(cè)試場(chǎng)景使用，主要支持如點(diǎn)擊、雙擊、長(zhǎng)按、滑動(dòng)等UI操作能力。

該模塊提供以下功能：

• [By]：提供控件特征描述能力，用于控件篩選匹配查找。
• [UiComponent]：代表UI界面上的指定控件，提供控件屬性獲取，控件點(diǎn)擊，滑動(dòng)查找，文本注入等能力。
• [UiDriver]：入口類(lèi)，提供控件匹配/查找，按鍵注入，坐標(biāo)點(diǎn)擊/滑動(dòng)，截圖等能能力。

說(shuō)明：
開(kāi)發(fā)前請(qǐng)熟悉鴻蒙開(kāi)發(fā)指導(dǎo)文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]
本模塊首批接口從API version 8開(kāi)始支持。后續(xù)版本的新增接口，采用上角標(biāo)單獨(dú)標(biāo)記接口的起始版本。

導(dǎo)入模塊

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

By

UiTest框架通過(guò)By類(lèi)提供了豐富的控件特征描述API，用以進(jìn)行控件篩選來(lái)匹配/查找出目標(biāo)控件。
By提供的API能力具有以下幾個(gè)特點(diǎn):
1、支持單屬性匹配和多屬性組合匹配，例如同時(shí)指定目標(biāo)控件text和id。
2、控件屬性支持多種匹配模式。
3、支持控件絕對(duì)定位，相對(duì)定位，可通過(guò)[By.isBefore]和[By.isAfter]等API限定鄰近控件特征進(jìn)行輔助定位。
By類(lèi)提供的所有API均為同步接口，建議使用者通過(guò)靜態(tài)構(gòu)造器BY來(lái)鏈?zhǔn)絼?chuàng)建By對(duì)象。

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

text

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

指定目標(biāo)控件文本屬性，支持多種匹配模式，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.text('123') //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的text屬性。

key

key(key: string): By

指定目標(biāo)控件key值屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.key('123') //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的key值屬性。

id

id(id: number): By

指定目標(biāo)控件id屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.id(123) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的id屬性。

type

type(tp: string): By

指定目標(biāo)控件的控件類(lèi)型屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.type('button') //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的控件類(lèi)型屬性。

clickable

clickable(b?: bool): By

指定目標(biāo)控件的可點(diǎn)擊狀態(tài)屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.clickable(true) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的可點(diǎn)擊狀態(tài)屬性。

longClickable9+

longClickable(b?: bool): By

指定目標(biāo)控件的可長(zhǎng)按點(diǎn)擊狀態(tài)屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.longClickable(true) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的可長(zhǎng)按點(diǎn)擊狀態(tài)屬性。

scrollable

scrollable(b?: bool): By

指定目標(biāo)控件的可滑動(dòng)狀態(tài)屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.scrollable(true) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的可滑動(dòng)狀態(tài)屬性。

enabled

enabled(b?: bool): By

指定目標(biāo)控件的使能狀態(tài)屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.enabled(true) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的使能狀態(tài)屬性。

focused

focused(b?: bool): By

指定目標(biāo)控件的獲焦?fàn)顟B(tài)屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.focused(true) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的獲焦?fàn)顟B(tài)屬性。

selected

selected(b?: bool): By

指定目標(biāo)控件的被選中狀態(tài)屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.selected(true) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的被選中狀態(tài)屬性。

checked9+

checked(b?: bool): By

指定目標(biāo)控件的被勾選狀態(tài)屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.checked(true) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的被勾選狀態(tài)屬性

checkable9+

checkable(b?: bool): By

指定目標(biāo)控件能否被勾選狀態(tài)屬性，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.checkable(true) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件的能否被勾選狀態(tài)屬性。

isBefore

isBefore(by: By): By

指定目標(biāo)控件位于給出的特征屬性控件之前，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.isBefore(BY.text('123')) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件位于給出的特征屬性控件之前。

isAfter

isAfter(by: By): By

指定目標(biāo)控件位于給出的特征屬性控件之后，返回By對(duì)象自身。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

let by = BY.isAfter(BY.text('123')) //使用靜態(tài)構(gòu)造器BY創(chuàng)建by對(duì)象，指定目標(biāo)控件位于給出的特征屬性控件之后。

UiComponent

UiTest中，UiComponent類(lèi)代表了UI界面上的一個(gè)控件，提供控件屬性獲取，控件點(diǎn)擊，滑動(dòng)查找，文本注入等API。 該類(lèi)提供的所有方法都使用Promise方式作為異步方法，需使用await調(diào)用。

Rect9+

控件的邊框信息。

click

click(): Promise

控件對(duì)象進(jìn)行點(diǎn)擊操作。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

示例：

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

doubleClick

doubleClick(): Promise

控件對(duì)象進(jìn)行雙擊操作。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

示例：

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

longClick

longClick(): Promise

控件對(duì)象進(jìn)行長(zhǎng)按操作。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

示例：

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

getId

getId(): Promise

獲取控件對(duì)象的id值。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

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

getKey

getKey(): Promise

獲取控件對(duì)象的key值。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

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

getText

getText(): Promise

獲取控件對(duì)象的文本信息。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

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

getType

getType(): Promise

獲取控件對(duì)象的控件類(lèi)型。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

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

getBounds9+

getBounds(): Promise

獲取控件對(duì)象的邊框信息。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

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

isClickable

isClickable(): Promise

獲取控件對(duì)象可點(diǎn)擊狀態(tài)。

系統(tǒng)能力 ：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')
    }
}

isLongClickable9+

isLongClickable(): Promise

獲取控件對(duì)象可長(zhǎng)按點(diǎn)擊狀態(tài)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

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

isChecked9+

isChecked(): Promise

獲取控件對(duì)象被勾選狀態(tài)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

async function demo() {
    let driver = UiDriver.create()
    let checkBox = await driver.findComponent(BY.type('Checkbox'))
    if(await checkBox.isChecked) {
        console.info('This checkBox is checked')
    }
    else{
        console.info('This checkBox is not checked')
    }
}

isCheckable9+

isCheckable(): Promise

獲取控件對(duì)象能否被勾選的屬性。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

async function demo() {
    let driver = UiDriver.create()
    let checkBox = await driver.findComponent(BY.type('Checkbox'))
    if(await checkBox.isCheckable) {
        console.info('This checkBox is checkable')
    }
    else{
        console.info('This checkBox is not checkable')
    }
}

isScrollable

isScrollable(): Promise

獲取控件對(duì)象可滑動(dòng)狀態(tài)。

系統(tǒng)能力 ：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')
    }
}

isEnabled

isEnabled(): Promise

獲取控件使能狀態(tài)。

系統(tǒng)能力 ：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')
    }
}

isFocused

isFocused(): Promise

判斷控件對(duì)象是否獲焦。

系統(tǒng)能力 ：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')
	}
}

isSelected

isSelected(): Promise

獲取控件對(duì)象被選中狀態(tài)。

系統(tǒng)能力 ：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')
    }
}

inputText

inputText(text: string): Promise

向控件中輸入文本(適用于文本框控件)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

clearText9+

clearText(): Promise

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

系統(tǒng)能力 ：SystemCapability.Test.UiTest

示例：

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

scrollSearch

scrollSearch(by: By): Promise

在控件上滑動(dòng)查找目標(biāo)控件(適用于List等支持滑動(dòng)的控件)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

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

scrollToTop9+

scrollToTop(): Promise

在控件上滑動(dòng)到頂部(適用于List等支持滑動(dòng)的控件)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

示例：

async function demo() {
    let driver = UiDriver.create()
    let scrollBar = await driver.findComponent(BY.type('Scroll'))
    await scrollBar.scrollToTop()
}

scrollToBottom9+

scrollToBottom(): Promise

在控件上滑動(dòng)到底部(適用于List等支持滑動(dòng)的控件)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

示例：

async function demo() {
    let driver = UiDriver.create()
    let scrollBar = await driver.findComponent(BY.type('Scroll'))
    await scrollBar.scrollToBottom()
}

dragTo9+

dragTo(target: UiComponent): Promise

將控件拖拽至目標(biāo)控件處。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

UiDriver

UiDriver類(lèi)為uitest測(cè)試框架的總?cè)肟?，提供控件匹?查找，按鍵注入，坐標(biāo)點(diǎn)擊/滑動(dòng)，截圖等API。 該類(lèi)提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作為異步方法，需使用await調(diào)用。

create

static create(): UiDriver

靜態(tài)方法，構(gòu)造一個(gè)UiDriver對(duì)象，并返回該對(duì)象。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

返回值：

示例：

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

delayMs

delayMs(duration: number): Promise

UiDriver對(duì)象在給定的時(shí)間內(nèi)延時(shí)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

findComponent

findComponent(by: By): Promise

在UiDriver對(duì)象中，根據(jù)給出的目標(biāo)控件屬性要求查找目標(biāo)控件。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

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

findComponents

findComponents(by: By): Promise>

在UiDriver對(duì)象中，根據(jù)給出的目標(biāo)控件屬性要求查找出所有匹配控件，以列表保存。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

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

waitForComponent9+

waitForComponent(by: By, time: number): Promise

在UiDriver對(duì)象中，在用戶(hù)給定的時(shí)間內(nèi)，持續(xù)查找滿足控件屬性要求的目標(biāo)控件。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

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

assertComponentExist

assertComponentExist(by: By): Promise

斷言API，用于斷言當(dāng)前界面存在滿足給出的目標(biāo)控件屬性的控件; 如果控件不存在，該API將拋出JS異常，使當(dāng)前測(cè)試用例失敗。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

pressBack

pressBack(): Promise

UiDriver對(duì)象進(jìn)行點(diǎn)擊BACK鍵的操作。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

示例：

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

triggerKey

triggerKey(keyCode: number): Promise

UiDriver對(duì)象采取如下操作：通過(guò)key值找到對(duì)應(yīng)鍵并點(diǎn)擊。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

click

click(x: number, y: number): Promise

UiDriver對(duì)象采取如下操作：在目標(biāo)坐標(biāo)點(diǎn)單擊。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

doubleClick

doubleClick(x: number, y: number): Promise

UiDriver對(duì)象采取如下操作：在目標(biāo)坐標(biāo)點(diǎn)雙擊。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

longClick

longClick(x: number, y: number): Promise

UiDriver對(duì)象采取如下操作：在目標(biāo)坐標(biāo)點(diǎn)長(zhǎng)按下鼠標(biāo)左鍵。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

swipe

swipe(startx: number, starty: number, endx: number, endy: number): Promise

UiDriver對(duì)象采取如下操作：從給出的起始坐標(biāo)點(diǎn)滑向給出的目的坐標(biāo)點(diǎn)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

drag9+

drag(startx: number, starty: number, endx: number, endy: number): Promise

UiDriver對(duì)象采取如下操作：從給出的起始坐標(biāo)點(diǎn)拖拽至給出的目的坐標(biāo)點(diǎn)。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

示例：

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

screenCap

screenCap(savePath: string): Promise

UiDriver對(duì)象采取如下操作：捕獲當(dāng)前屏幕，并保存為PNG格式的圖片至給出的保存路徑中。

系統(tǒng)能力 ：SystemCapability.Test.UiTest

參數(shù)：

返回值：

示例：

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

MatchPattern

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

系統(tǒng)能力 ：以下各項(xiàng)對(duì)應(yīng)的系統(tǒng)能力均為SystemCapability.Test.UiTest

審核編輯 黃宇