HarmonyOS Next UI测试框架API总结

HarmonyOS Next中UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要支持如点击、双击、长按、滑动等UI操作能力，该模块提供以下功能：

On：提供控件特征描述能力，用于控件筛选匹配查找。
Component：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。
Driver：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。
UiWindow：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能力。
By(deprecated)：提供控件特征描述能力，用于控件筛选匹配查找。从API version 9开始不再维护，建议使用On。
UiComponent(deprecated)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。从API version 9开始不再维护，建议使用Component。
UiDriver(deprecated)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。从API version 9开始不再维护，建议使用Driver。
这里面可以看到很多API都已经被废弃不在维护，UI自动测试框架主要提供了以下能力：
Driver：Ui测试的入口，提供查找控件，检查控件存在性以及注入按键能力。
On：用于描述目标控件特征(文本、id、类型等)，Driver根据On描述的控件特征信息来查找控件。
Component：Driver查找返回的控件对象，提供查询控件属性，滑动查找等触控和检视能力。
UiWindow：Driver查找返回的窗口对象，提供获取窗口属性、操作窗口的能力。

UI自动化的原理不外乎是查找控件，操作控件，HarmonyOS Next通过上述几个对象对外提供操作UI能力。

Driver

Driver类作为UiTest测试框架的总入口，提供查找控件，注入按键，单击坐标，滑动控件，手势操作，截图等能力。

API	功能描述
create():Promise	静态方法，构造Driver。
findComponent(on:On):Promise	查找匹配控件。
pressBack():Promise	单击BACK键。
click(x:number, y:number):Promise	基于坐标点的单击。
swipe(x1:number, y1:number, x2:number, y2:number):Promise	基于坐标点的滑动。
assertComponentExist(on:On):Promise	断言匹配的控件存在。
delayMs(t:number):Promise	延时。
screenCap(s:path):Promise	截屏。
findWindow(filter: WindowFilter): Promise	查找匹配窗口。

其中assertComponentExist接口是断言API，用于断言当前界面存在目标控件；如果控件不存在，该API将抛出JS异常，使当前测试用例失败。

import { describe, it} from '@ohos/hypium';
import { Driver, ON } from '@kit.TestKit';

export default function assertComponentExistTest() {
  describe('assertComponentExistTest', () => {
    it('Uitest_demo0', 0, async (done: Function) => {
      try{
        // create Driver
        let driver: Driver = Driver.create();
        // assert text 'hello' exists on current Ui
        await driver.assertComponentExist(ON.text('hello'));
      } finally {
        done();
      }
    })
  })
}

On

Ui测试框架通过On类提供了丰富的控件特征描述API，用来匹配查找要操作或检视的目标控件。On提供的API能力具有以下特点：

支持匹配单属性和匹配多属性组合，例如同时指定目标控件text和id。
控件属性支持多种匹配模式(等于，包含，STARTS_WITH，ENDS_WITH，REG_EXP，REG_EXP_ICASE)。
支持相对定位控件，可通过isBefore和isAfter等API限定邻近控件特征进行辅助定位。

API	功能描述
id(i:string):On	指定控件id。
text(t:string, p?:MatchPattern):On	指定控件文本，可指定匹配模式。
type(t:string):On	指定控件类型。
enabled(e:bool):On	指定控件使能状态。
clickable(c:bool):On	指定控件可单击状态。
longClickable(l:bool):On	指定控件可长按状态。
focused(f:bool):On	指定控件获焦状态。
scrollable(s:bool):On	指定控件可滑动状态。
selected(s:bool):On	指定控件选中状态。
checked(c:bool):On	指定控件选择状态。
checkable(c:bool):On	指定控件可选择状态。
isBefore(b:On):On	相对定位，限定目标控件位于指定特征控件之前。
isAfter(b:On):On	相对定位，限定目标控件位于指定特征控件之后。
id(i:string，p?:MatchPattern:On	指定控件id，可指定匹配模式。
hint(h:string, p?:MatchPattern):On	指定控件提示文本，可指定匹配模式。
type(t:string，p?:MatchPattern):On	指定控件类型，可指定匹配模式。
description(d:string，p?:MatchPattern):On	指定控件描述文本信息，可指定匹配模式。

Component

Component类代表了Ui界面上的一个控件，一般是通过Driver.findComponent(on)方法查找到的。通过该类的实例，用户可以获取控件属性，单击控件，滑动查找，注入文本等操作。

Component包含的常用API：

API	功能描述
click():Promise	单击该控件。
inputText(t:string):Promise	向控件中输入文本(适用于文本框控件)。
scrollSearch(s:On):Promise	在该控件上滑动查找目标控件(适用于List等控件)。
scrollToTop(s:number):Promise	滑动到该控件顶部(适用于List等控件)。
scrollTobottom(s:number):Promise	滑动到该控件底部(适用于List等控件)。
getText():Promise	获取控件text。
getId():Promise	获取控件id。
getType():Promise	获取控件类型。
isEnabled():Promise	获取控件使能状态。

UiWindow

UiWindow类代表了Ui界面上的一个窗口，一般是通过Driver.findWindow(WindowFilter)方法查找到的。通过该类的实例，用户可以获取窗口属性，并进行窗口拖动、调整窗口大小等操作。

UiWindow包含的常用API：

API	功能描述
getBundleName(): Promise	获取窗口所属应用包名。
getTitle(): Promise	获取窗口标题信息。
focus(): Promise	使得当前窗口获取焦点。
moveTo(x: number, y: number): Promise	将当前窗口移动到指定位置（适用于支持移动的窗口）。
resize(wide: number, height: number, direction: ResizeDirection): Promise	调整窗口大小（适用于支持调整大小的窗口）。
split(): Promise	将窗口模式切换为分屏模式(适用于支持分屏的窗口)。
close(): Promise	关闭当前窗口。

总结

本文介绍了HarmonyOS Next提供的UI自动化操作相关对象：Driver、On、Component、UiWindow对应的API能力，后续文章根据具体业务场景和页面介绍这些API的具体操作步骤。

HarmonyOS Next UI测试框架API总结