diff --git a/zh-cn/application-dev/reference/apis/js-apis-uitest.md b/zh-cn/application-dev/reference/apis/js-apis-uitest.md index 0e824de04cfa4dd1de206838d519ace19d934ce2..a15cbc4c9236e22ce85790f7202dd96324812b7c 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-uitest.md +++ b/zh-cn/application-dev/reference/apis/js-apis-uitest.md @@ -4,10 +4,13 @@ UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要 该模块提供以下功能： -- [By](#by)：提供控件特征描述能力，用于控件筛选匹配查找。 -- [UiComponent](#uicomponent)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。 -- [UiDriver](#uidriver)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。 -- [UiWINDOW9+](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能能力。 +- [On9+](#on9)：提供控件特征描述能力，用于控件筛选匹配查找。 +- [Component9+](#component9)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。 +- [Driver9+](#driver9)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。 +- [UiWindow9+](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能能力。 +- [By](#by)：提供控件特征描述能力，用于控件筛选匹配查找。从API version9开始不再维护，建议使用[[On9+](#on9)](#Driver9)。 +- [UiComponent](#uicomponent)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。从API version9开始不再维护，建议使用[Component9+](#component9)。 +- [UiDriver](#uidriver)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。从API version9开始不再维护，建议使用[Driver9+](#Driver9)。 >**说明：** > @@ -16,79 +19,60 @@ UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要 ## 导入模块 -``` -import {UiDriver, BY, MatchPattern, ResizeDirection, WindowMode, DisplayRotation, PointerMatrix} from '@ohos.uitest' +```js +import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix} from '@ohos.uitest' ``` -## By +## On9+ -UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
-By提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[By.isBefore](#isbefore)和[By.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。
By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。 +UiTest框架在API9中，通过On类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
+On提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[ON.isBefore](#isbefore)和[ON.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。
On类提供的所有API均为同步接口，建议使用者通过静态构造器ON来链式创建On对象。 ```js -BY.text('123').type('button') +ON.text('123').type('button') ``` -### text +### text9+ -text(txt: string, pattern?: MatchPattern): By +text(txt: string, pattern?: MatchPattern): On -指定目标控件文本属性，支持多种匹配模式，返回By对象自身。 +指定目标控件文本属性，支持多种匹配模式，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------------ | ---- | --------------------------------------------------- | -| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 | -| pattern | MatchPattern | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------- | ---- | --------------------------------------------------- | +| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 | +| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | **返回值：** -| 类型 | 说明 | -| --------- | ---------------------------------- | -| [By](#by) | 返回指定目标控件文本属性的By对象。 | - -**示例：** - -```js -let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性。 -``` - - -### key - -key(key: string): By - -指定目标控件key值属性，返回By对象自身。 - -**系统能力**：SystemCapability.Test.UiTest - -**参数：** +| 类型 | 说明 | +| ---------- | ---------------------------------- | +| [On](#on9) | 返回指定目标控件文本属性的On对象。 | -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ----------------- | -| key | string | 是 | 指定控件的Key值。 | +**错误码：** -**返回值：** +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| --------- | ----------------------------------- | -| [By](#by) | 返回指定目标控件key值属性的By对象。 | +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.key('123') //使用静态构造器BY创建by对象，指定目标控件的key值属性。 +let on = ON.text('123') //使用静态构造器ON创建On对象，指定目标控件的text属性。 ``` -### id +### id9+ -id(id: number): By +id(id: string): On -指定目标控件id属性，返回By对象自身。 +指定目标控件id属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest @@ -96,26 +80,34 @@ id(id: number): By | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ---------------- | -| id | number | 是 | 指定控件的id值。 | +| id | string | 是 | 指定控件的id值。 | **返回值：** -| 类型 | 说明 | -| --------- | -------------------------------- | -| [By](#by) | 返回指定目标控件id属性的By对象。 | +| 类型 | 说明 | +| ---------- | -------------------------------- | +| [On](#on9) | 返回指定目标控件id属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.id(123) //使用静态构造器BY创建by对象，指定目标控件的id属性。 +let on = ON.id(123) //使用静态构造器ON创建On对象，指定目标控件的id属性。 ``` -### type +### type9+ -type(tp: string): By +type(tp: string): On -指定目标控件的控件类型属性，返回By对象自身。 +指定目标控件的控件类型属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest @@ -127,326 +119,399 @@ type(tp: string): By **返回值：** -| 类型 | 说明 | -| --------- | ---------------------------------------- | -| [By](#by) | 返回指定目标控件的控件类型属性的By对象。 | +| 类型 | 说明 | +| ---------- | ---------------------------------------- | +| [On](#on9) | 返回指定目标控件的控件类型属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.type('button') //使用静态构造器BY创建by对象，指定目标控件的控件类型属性。 +let on = ON.type('button') //使用静态构造器ON创建On对象，指定目标控件的控件类型属性。 ``` -### clickable +### clickable9+ -clickable(b?: boolean): By +clickable(b?: boolean): On -指定目标控件的可点击状态属性，返回By对象自身。 +指定目标控件的可点击状态属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | -------------------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | | b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 | **返回值：** -| 类型 | 说明 | -| --------- | ------------------------------------------ | -| [By](#by) | 返回指定目标控件的可点击状态属性的By对象。 | +| 类型 | 说明 | +| ---------- | ------------------------------------------ | +| [On](#on9) | 返回指定目标控件的可点击状态属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.clickable(true) //使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。 +let on = ON.clickable(true) //使用静态构造器ON创建On对象，指定目标控件的可点击状态属性。 ``` ### longClickable9+ -longClickable(b?: boolean): By +longClickable(b?: boolean): On -指定目标控件的可长按点击状态属性，返回By对象自身。 +指定目标控件的可长按点击状态属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------------------------ | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | | b | boolean | 否 | 指定控件可长按点击状态，true：可长按点击，false：不可长按点击。默认为true。 | **返回值：** -| 类型 | 说明 | -| --------- | ---------------------------------------------- | -| [By](#by) | 返回指定目标控件的可长按点击状态属性的By对象。 | +| 类型 | 说明 | +| ---------- | ---------------------------------------------- | +| [On](#on9) | 返回指定目标控件的可长按点击状态属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.longClickable(true) //使用静态构造器BY创建by对象，指定目标控件的可长按点击状态属性。 +let on = ON.longClickable(true) //使用静态构造器ON创建On对象，指定目标控件的可长按点击状态属性。 ``` -### scrollable +### scrollable9+ -scrollable(b?: boolean): By +scrollable(b?: boolean): On -指定目标控件的可滑动状态属性，返回By对象自身。 +指定目标控件的可滑动状态属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ---------------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ----------------------------------------------------------- | | b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 | **返回值：** -| 类型 | 说明 | -| --------- | ------------------------------------------ | -| [By](#by) | 返回指定目标控件的可滑动状态属性的By对象。 | +| 类型 | 说明 | +| ---------- | ------------------------------------------ | +| [On](#on9) | 返回指定目标控件的可滑动状态属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.scrollable(true) //使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。 +let on = ON.scrollable(true) //使用静态构造器ON创建On对象，指定目标控件的可滑动状态属性。 ``` -### enabled +### enabled9+ -enabled(b?: boolean): By +enabled(b?: boolean): On -指定目标控件的使能状态属性，返回By对象自身。 +指定目标控件的使能状态属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------------------ | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | --------------------------------------------------------- | | b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 | **返回值：** -| 类型 | 说明 | -| --------- | ---------------------------------------- | -| [By](#by) | 返回指定目标控件的使能状态属性的By对象。 | +| 类型 | 说明 | +| ---------- | ---------------------------------------- | +| [On](#on9) | 返回指定目标控件的使能状态属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.enabled(true) //使用静态构造器BY创建by对象，指定目标控件的使能状态属性。 +let on = ON.enabled(true) //使用静态构造器ON创建On对象，指定目标控件的使能状态属性。 ``` -### focused +### focused9+ -focused(b?: boolean): By +focused(b?: boolean): On -指定目标控件的获焦状态属性，返回By对象自身。 +指定目标控件的获焦状态属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | -------------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ----------------------------------------------------- | | b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 | **返回值：** -| 类型 | 说明 | -| --------- | ---------------------------------------- | -| [By](#by) | 返回指定目标控件的获焦状态属性的By对象。 | +| 类型 | 说明 | +| ---------- | ---------------------------------------- | +| [On](#on9) | 返回指定目标控件的获焦状态属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.focused(true) //使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。 +let on = ON.focused(true) //使用静态构造器ON创建On对象，指定目标控件的获焦状态属性。 ``` -### selected +### selected9+ -selected(b?: boolean): By +selected(b?: boolean): On -指定目标控件的被选中状态属性，返回By对象自身。 +指定目标控件的被选中状态属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | -------------------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | | b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 | **返回值：** -| 类型 | 说明 | -| --------- | ------------------------------------------ | -| [By](#by) | 返回指定目标控件的被选中状态属性的By对象。 | +| 类型 | 说明 | +| ---------- | ------------------------------------------ | +| [On](#on9) | 返回指定目标控件的被选中状态属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.selected(true) //使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。 +let on = ON.selected(true) //使用静态构造器ON创建On对象，指定目标控件的被选中状态属性。 ``` ### checked9+ -checked(b?: boolean): By +checked(b?: boolean): On -指定目标控件的被勾选状态属性，返回By对象自身。 +指定目标控件的被勾选状态属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | --------------------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | | b | boolean | 否 | 指定控件被勾选状态，true：被勾选，false：未被勾选。默认为false。 | **返回值：** -| 类型 | 说明 | -| --------- | ------------------------------------------ | -| [By](#by) | 返回指定目标控件的被勾选状态属性的By对象。 | +| 类型 | 说明 | +| ---------- | ------------------------------------------ | +| [On](#on9) | 返回指定目标控件的被勾选状态属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.checked(true) //使用静态构造器BY创建by对象，指定目标控件的被勾选状态属性 +let on = ON.checked(true) //使用静态构造器ON创建On对象，指定目标控件的被勾选状态属性 ``` ### checkable9+ -checkable(b?: boolean): By +checkable(b?: boolean): On -指定目标控件能否被勾选状态属性，返回By对象自身。 +指定目标控件能否被勾选状态属性，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | | b | boolean | 否 | 指定控件能否被勾选状态，true：能被勾选，false：不能被勾选。默认为false。 | **返回值：** -| 类型 | 说明 | -| --------- | -------------------------------------------- | -| [By](#by) | 返回指定目标控件能否被勾选状态属性的By对象。 | +| 类型 | 说明 | +| ---------- | -------------------------------------------- | +| [On](#on9) | 返回指定目标控件能否被勾选状态属性的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.checkable(true) //使用静态构造器BY创建by对象，指定目标控件的能否被勾选状态属性。 +let on = ON.checkable(true) //使用静态构造器ON创建On对象，指定目标控件的能否被勾选状态属性。 ``` -### isBefore +### isBefore9+ -isBefore(by: By): By +isBefore(on: On): On -指定目标控件位于给出的特征属性控件之前，返回By对象自身。 +指定目标控件位于给出的特征属性控件之前，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | ---------------- | -| by | [By](#by) | 是 | 特征控件的属性。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------- | ---- | -------------------- | +| on | [On](#on9) | 是 | 特征控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| --------- | ---------------------------------------------------- | -| [By](#by) | 返回指定目标控件位于给出的特征属性控件之前的By对象。 | +| 类型 | 说明 | +| ---------- | ---------------------------------------------------- | +| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之前的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.isBefore(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。 +let on = ON.isBefore(ON.text('123')) //使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之前。 ``` -### isAfter +### isAfter9+ -isAfter(by: By): By +isAfter(on: On): On -指定目标控件位于给出的特征属性控件之后，返回By对象自身。 +指定目标控件位于给出的特征属性控件之后，返回On对象自身。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | ---------------- | -| by | [By](#by) | 是 | 特征控件的属性。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------- | ---- | -------------------- | +| on | [On](#on9) | 是 | 特征控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| --------- | ---------------------------------------------------- | -| [By](#by) | 返回指定目标控件位于给出的特征属性控件之后的By对象。 | +| 类型 | 说明 | +| ---------- | ---------------------------------------------------- | +| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之后的On对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js -let by = BY.isAfter(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。 +let on = ON.isAfter(ON.text('123')) //使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之后。 ``` -## UiComponent +## Component9+ -UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 +UiTest框架在API9中，Component类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 -### Point9+ - -坐标点信息。 - -**系统能力**：SystemCapability.Test.UiTest - -| 名称 | 参数类型 | 可读 | 可写 | 描述 | -| ---- | -------- | ---- | ---- | ---------------- | -| X | number | 是 | 否 | 坐标点的横坐标。 | -| Y | number | 是 | 否 | 坐标点的纵坐标。 | +### click9+ -### Rect9+ +click(): Promise\ -控件的边框信息。 +控件对象进行点击操作。 **系统能力**：SystemCapability.Test.UiTest -| 名称 | 参数类型 | 可读 | 可写 | 描述 | -| ------- | -------- | ---- | ---- | ------------------------- | -| leftX | number | 是 | 否 | 控件边框的左上角的X坐标。 | -| topY | number | 是 | 否 | 控件边框的左上角的Y坐标。 | -| rightX | number | 是 | 否 | 控件边框的右下角的X坐标。 | -| bottomY | number | 是 | 否 | 控件边框的右下角的Y坐标。 | - -### UiComponent.click - -click(): Promise\ +**错误码：** -控件对象进行点击操作。 +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -**系统能力**：SystemCapability.Test.UiTest +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) await button.click() } ``` -### doubleClick +### doubleClick9+ doubleClick(): Promise\ @@ -454,17 +519,26 @@ doubleClick(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) await button.doubleClick() } ``` -### longClick +### longClick9+ longClick(): Promise\ @@ -472,19 +546,28 @@ longClick(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) await button.longClick() } ``` -### getId +### getId9+ -getId(): Promise\ +getId(): Promise\ 获取控件对象的id值。 @@ -494,43 +577,28 @@ getId(): Promise\ | 类型 | 说明 | | ---------------- | ------------------------------- | -| Promise\ | 以Promise形式返回的控件的id值。 | - -**示例：** - -```js -async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) - let num = await button.getId() -} -``` - -### getKey - -getKey(): Promise\ - -获取控件对象的key值。 +| Promise\ | 以Promise形式返回的控件的id值。 | -**系统能力**：SystemCapability.Test.UiTest +**错误码：** -**返回值：** +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| ---------------- | ------------------------------ | -| Promise\ | 以Promise形式返回控件的key值。 | +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) - let str_key = await button.getKey() + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) + let num = await button.getId() } ``` -### getText +### getText9+ getText(): Promise\ @@ -544,17 +612,26 @@ getText(): Promise\ | ---------------- | --------------------------------- | | Promise\ | 以Promise形式返回控件的文本信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) let text = await button.getText() } ``` -### getType +### getType9+ getType(): Promise\ @@ -568,12 +645,21 @@ getType(): Promise\ | ---------------- | ----------------------------- | | Promise\ | 以Promise形式返回控件的类型。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) let type = await button.getType() } ``` @@ -592,12 +678,21 @@ getBounds(): Promise\ | ------------------------ | ------------------------------------- | | Promise\<[Rect](#rect9)> | 以Promise形式返回控件对象的边框信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) let rect = await button.getBounds() } ``` @@ -616,17 +711,26 @@ getBoundsCenter(): Promise\ | -------------------------- | --------------------------------------- | | Promise\<[Point](#point9)> | 以Promise形式返回控件对象的中心点信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) let point = await button.getBoundsCenter() } ``` -### isClickable +### isClickable9+ isClickable(): Promise\ @@ -636,16 +740,25 @@ isClickable(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象可点击状态，true：可点击，false：不可点击。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) if(await button.isClickable()) { console.info('This button can be Clicked') } @@ -665,16 +778,25 @@ isLongClickable(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象能否长按点击状态，true：可长按点击，false：不可长按点击。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) if(await button.isLongClickable()) { console.info('This button can longClick') } @@ -694,16 +816,25 @@ isChecked(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象被勾选状态，true：被勾选，false：未被勾选。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let checkBox = await driver.findComponent(BY.type('Checkbox')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('Checkbox')) if(await checkBox.isChecked) { console.info('This checkBox is checked') } @@ -723,16 +854,25 @@ isCheckable(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------------- | +| 错误码ID | 错误码信息 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象能否被勾选的属性，true：可被勾选，false：不可被勾选。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 类型 | 说明 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let checkBox = await driver.findComponent(BY.type('Checkbox')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('Checkbox')) if(await checkBox.isCheckable) { console.info('This checkBox is checkable') } @@ -742,7 +882,7 @@ async function demo() { } ``` -### isScrollable +### isScrollable9+ isScrollable(): Promise\ @@ -752,16 +892,25 @@ isScrollable(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象可滑动状态，true：可滑动，false：不可滑动。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let scrollBar = await driver.findComponent(BY.scrollable(true)) + let driver = Driver.create() + let button = await driver.findComponent(ON.scrollable(true)) if(await scrollBar.isScrollable()) { console.info('This scrollBar can be operated') } @@ -772,7 +921,7 @@ async function demo() { ``` -### isEnabled +### isEnabled9+ isEnabled(): Promise\ @@ -782,16 +931,25 @@ isEnabled(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------- | +| 类型 | 说明 | +| ----------------- | ---------------------------------------------------------- | | Promise\ | 以Promise形式返回控件使能状态，true：使能，false：未使能。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) if(await button.isEnabled()) { console.info('This button can be operated') } @@ -802,7 +960,7 @@ async function demo() { ``` -### isFocused +### isFocused9+ isFocused(): Promise\ @@ -812,16 +970,25 @@ isFocused(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象是否获焦，true：获焦，false：未获焦。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) if(await button.isFocused()) { console.info('This button is focused') } @@ -831,7 +998,7 @@ async function demo() { } ``` -### isSelected +### isSelected9+ isSelected(): Promise\ @@ -841,16 +1008,25 @@ isSelected(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | -------------------- | +| 类型 | 说明 | +| ----------------- | ----------------------------------------------------- | | Promise\ | 控件对象被选中的状态，true：被选中，false：未被选中。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('button')) if(await button.isSelected()) { console.info('This button is selected') } @@ -860,7 +1036,7 @@ async function demo() { } ``` -### inputText +### inputText9+ inputText(text: string): Promise\ @@ -874,12 +1050,22 @@ inputText(text: string): Promise\ | ------ | ------ | ---- | ---------------- | | text | string | 是 | 输入的文本信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let text = await driver.findComponent(BY.text('hello world')) + let driver = Driver.create() + let button = await driver.findComponent(ON.text('hello world')) await text.inputText('123') } ``` @@ -892,19 +1078,26 @@ clearText(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**错误码：** + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let text = await driver.findComponent(BY.text('hello world')) + let driver = Driver.create() + let button = await driver.findComponent(ON.text('hello world')) await text.clearText() } ``` -### scrollSearch +### scrollSearch9+ -scrollSearch(by: By): Promise\ +scrollSearch(on: ON): Promise\ 在控件上滑动查找目标控件(适用于List等支持滑动的控件)。 @@ -912,23 +1105,33 @@ scrollSearch(by: By): Promise\ **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | -------------------- | -| by | [By](#by) | 是 | 目标控件的属性要求。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------- | ---- | -------------------- | +| on | [On](#on9) | 是 | 目标控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| ------------------------------------- | ------------------------------------- | -| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的目标控件对象。 | +| 类型 | 说明 | +| ---------------------------------- | ------------------------------------- | +| Promise\<[Component](#component9)> | 以Promise形式返回找到的目标控件对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let scrollBar = await driver.findComponent(BY.type('Scroll')) - let button = await scrollBar.scrollSearch(BY.text('next page')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('Scroll')) + let button = await scrollBar.scrollSearch(ON.text('next page')) } ``` @@ -944,14 +1147,24 @@ scrollToTop(speed?: number): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------------------------------------ | -| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 | +| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let scrollBar = await driver.findComponent(BY.type('Scroll')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('Scroll')) await scrollBar.scrollToTop() } ``` @@ -968,21 +1181,31 @@ scrollToBottom(speed?: number): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------------------------------------ | -| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 | +| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let scrollBar = await driver.findComponent(BY.type('Scroll')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('Scroll')) await scrollBar.scrollToBottom() } ``` ### dragTo9+ -dragTo(target: UiComponent): Promise\ +dragTo(target: Component): Promise\ 将控件拖拽至目标控件处。 @@ -990,17 +1213,27 @@ dragTo(target: UiComponent): Promise\ **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------------------------- | ---- | ---------- | -| target | [UiComponent](#uicomponent) | 是 | 目标控件。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------ | ---- | ---------- | +| target | [Component](#component9) | 是 | 目标控件。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) - let text = await driver.findComponent(BY.text('hello world')) + 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) } ``` @@ -1019,12 +1252,22 @@ pinchOut(scale: number): Promise\ | ------ | ------ | ---- | ---------------- | | scale | number | 是 | 指定放大的比例。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let image = await driver.findComponent(BY.type('image')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('image')) await image.pinchOut(1.5) } ``` @@ -1043,121 +1286,166 @@ pinchIn(scale: number): Promise\ | ------ | ------ | ---- | ---------------- | | scale | number | 是 | 指定缩小的比例。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() - let image = await driver.findComponent(BY.type('image')) + let driver = Driver.create() + let button = await driver.findComponent(ON.type('image')) await image.pinchIn(0.5) } ``` -## UiDriver +## Driver9+ -UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。 -该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。 +UiTest框架在API9中，Driver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。 +该类提供的方法除Driver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。 -### create +### create9+ -static create(): UiDriver +static create(): Driver -静态方法，构造一个UiDriver对象，并返回该对象。 +静态方法，构造一个Driver对象，并返回该对象。 **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| -------- | ------------------------ | -| UiDriver | 返回构造的UiDriver对象。 | +| 错误码ID | 错误码信息 | +| -------- | ---------------------- | +| Driver | 返回构造的Driver对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 类型 | 说明 | +| -------- | ------------------ | +| 17000001 | Initialize failed. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() } ``` -### delayMs +### delayMs9+ delayMs(duration: number): Promise\ -UiDriver对象在给定的时间内延时。 +Driver对象在给定的时间内延时。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ------------ | -| duration | number | 是 | 给定的时间。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ---------------------- | +| duration | number | 是 | 给定的时间，单位：ms。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.delayMs(1000) } ``` -### findComponent +### findComponent9+ -findComponent(by: By): Promise\ +findComponent(on: On): Promise\ -在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。 +在Driver对象中，根据给出的目标控件属性要求查找目标控件。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | -------------------- | -| by | [By](#by) | 是 | 目标控件的属性要求。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------- | ---- | -------------------- | +| on | [On](#on9) | 是 | 目标控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| ------------------------------------- | --------------------------------- | -| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的控件对象。 | +| 类型 | 说明 | +| ---------------------------------- | --------------------------------- | +| Promise\<[Component](#Component9)> | 以Promise形式返回找到的控件对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.text('next page')) + let driver = Driver.create() + let button = await driver.findComponent(ON.text('next page')) } ``` -### findComponents +### findComponents9+ -findComponents(by: By): Promise\> +findComponents(on: On): Promise\> -在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 +在Driver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | -------------------- | -| by | [By](#by) | 是 | 目标控件的属性要求。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------- | ---- | -------------------- | +| on | [On](#on9) | 是 | 目标控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| --------------------------------------------- | --------------------------------------- | -| Promise\> | 以Promise形式返回找到的控件对象的列表。 | +| 类型 | 说明 | +| ------------------------------------------ | --------------------------------------- | +| Promise\> | 以Promise形式返回找到的控件对象的列表。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let buttonList = await driver.findComponents(BY.text('next page')) + let driver = Driver.create() + let buttonList = await driver.findComponents(ON.text('next page')) } ``` @@ -1181,90 +1469,126 @@ findWindow(filter: WindowFilter): Promise\ | -------------------------------- | ------------------------------------- | | Promise\<[UiWindow](#uiwindow9)> | 以Promise形式返回找到的目标窗口对象。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) } ``` ### waitForComponent9+ -waitForComponent(by: By, time: number): Promise\ +waitForComponent(on: On, time: number): Promise\ -在UiDriver对象中，在用户给定的时间内，持续查找满足控件属性要求的目标控件。 +在Driver对象中，在用户给定的时间内，持续查找满足控件属性要求的目标控件。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | -------------------------------- | -| by | [By](#by) | 是 | 目标控件的属性要求。 | -| time | number | 是 | 查找目标控件的持续时间。单位ms。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------- | ---- | -------------------------------- | +| On | [On](#on9) | 是 | 目标控件的属性要求。 | +| time | number | 是 | 查找目标控件的持续时间。单位ms。 | **返回值：** -| 类型 | 说明 | -| ------------------------------------- | --------------------------------- | -| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的控件对象。 | +| 类型 | 说明 | +| --------------------------------- | --------------------------------- | +| Promise\<[Component](#Component)> | 以Promise形式返回找到的控件对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let button = await driver.waitForComponent(BY.text('next page'),500) + let driver = Driver.create() + let button = await driver.waitForComponent(ON.text('next page'),500) } ``` -### assertComponentExist +### assertComponentExist9+ -assertComponentExist(by: By): Promise\ +assertComponentExist(on: On): Promise\ -断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。 +断言API，用于断言当前界面存在满足给出的目标控件属性的控件。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | -------------------- | -| by | [By](#by) | 是 | 目标控件的属性要求。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------- | ---- | -------------------- | +| on | [On](#on9) | 是 | 目标控件的属性要求。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000003 | Component existence assertion failed. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - await driver.assertComponentExist(BY.text('next page')) + let driver = Driver.create() + await driver.assertComponentExist(ON.text('next page')) } ``` -### pressBack +### pressBack9+ pressBack(): Promise\ -UiDriver对象进行点击BACK键的操作。 +Driver对象进行点击BACK键的操作。 **系统能力**：SystemCapability.Test.UiTest +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.pressBack() } ``` -### triggerKey +### triggerKey9+ triggerKey(keyCode: number): Promise\ -UiDriver对象采取如下操作：通过key值找到对应键并点击。 +Driver对象采取如下操作：通过key值找到对应键并点击。 **系统能力**：SystemCapability.Test.UiTest @@ -1274,11 +1598,20 @@ UiDriver对象采取如下操作：通过key值找到对应键并点击。 | ------- | ------ | ---- | ------------- | | keyCode | number | 是 | 指定的key值。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.triggerKey(123) } ``` @@ -1287,33 +1620,42 @@ async function demo() { triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\ -UiDriver对象通过给定的key值，找到对应组合键并点击。例如，Key值为(2072, 2019)时，UiDriver对象找到组合键并点击ctrl+c。 +Driver对象通过给定的key值，找到对应组合键并点击。例如，Key值为(2072, 2019)时，Driver对象找到组合键并点击ctrl+c。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------- | -| key0 | number | 是 | 指定的第一个key值。 | -| key1 | number | 是 | 指定的第二个key值。 | -| key2 | number | 否 | 指定的第三个key值。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------- | +| key0 | number | 是 | 指定的第一个key值。 | +| key1 | number | 是 | 指定的第二个key值。 | +| key2 | number | 否 | 指定的第三个key值。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.triggerCombineKeys(2072, 2047, 2035) } ``` -### click +### click9+ click(x: number, y: number): Promise\ -UiDriver对象采取如下操作：在目标坐标点单击。 +Driver对象采取如下操作：在目标坐标点单击。 **系统能力**：SystemCapability.Test.UiTest @@ -1324,20 +1666,29 @@ UiDriver对象采取如下操作：在目标坐标点单击。 | x | number | 是 | 以number的形式传入目标点的横坐标信息。 | | y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.click(100,100) } ``` -### doubleClick +### doubleClick9+ doubleClick(x: number, y: number): Promise\ -UiDriver对象采取如下操作：在目标坐标点双击。 +Driver对象采取如下操作：在目标坐标点双击。 **系统能力**：SystemCapability.Test.UiTest @@ -1348,20 +1699,29 @@ UiDriver对象采取如下操作：在目标坐标点双击。 | x | number | 是 | 以number的形式传入目标点的横坐标信息。 | | y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.doubleClick(100,100) } ``` -### longClick +### longClick9+ longClick(x: number, y: number): Promise\ -UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。 +Driver对象采取如下操作：在目标坐标点长按下。 **系统能力**：SystemCapability.Test.UiTest @@ -1372,11 +1732,28 @@ UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。 | x | number | 是 | 以number的形式传入目标点的横坐标信息。 | | y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** + + + + + + + + ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.longClick(100,100) } ``` @@ -1385,7 +1762,7 @@ async function demo() { swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\ -UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。 +Driver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。 **系统能力**：SystemCapability.Test.UiTest @@ -1397,13 +1774,22 @@ UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目 | starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 | | endx | number | 是 | 以number的形式传入目的点的横坐标信息。 | | endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 | -| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 | +| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.swipe(100,100,200,200,600) } ``` @@ -1412,7 +1798,7 @@ async function demo() { drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\ -UiDriver对象采取如下操作：从给出的起始坐标点拖拽至给出的目的坐标点。 +Driver对象采取如下操作：从给出的起始坐标点拖拽至给出的目的坐标点。 **系统能力**：SystemCapability.Test.UiTest @@ -1424,22 +1810,31 @@ UiDriver对象采取如下操作：从给出的起始坐标点拖拽至给出的 | starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 | | endx | number | 是 | 以number的形式传入目的点的横坐标信息。 | | endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 | -| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 | +| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.drag(100,100,200,200,600) } ``` -### screenCap +### screenCap9+ screenCap(savePath: string): Promise\ -UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 +Driver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 **系统能力**：SystemCapability.Test.UiTest @@ -1451,15 +1846,24 @@ UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的 **返回值：** -| 类型 | 说明 | -| -------------- | -------------------------------------- | +| 类型 | 说明 | +| ----------------- | -------------------------------------- | | Promise\ | 截图操作是否成功完成。成功完成为true。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.screenCap('/local/tmp/') } ``` @@ -1478,11 +1882,20 @@ setDisplayRotation(rotation: DisplayRotation): Promise\ | -------- | ------------------------------------ | ---- | ---------------- | | rotation | [DisplayRotation](#displayrotation9) | 是 | 设备的显示方向。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.setDisplayRotation(DisplayRotation.ROTATION_180) } ``` @@ -1501,11 +1914,19 @@ getDisplayRotation(): Promise\ | ---------------------------------------------- | --------------------------------------- | | Promise\<[DisplayRotation](#displayrotation9)> | 以Promise的形式返回当前设备的显示方向。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let rotation = await driver.getDisplayRotation() } ``` @@ -1520,15 +1941,24 @@ setDisplayRotationEnabled(enabled: boolean): Promise\ **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ---- | ---- | -------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------- | ---- | ------------------------------------------------------- | | enabled | boolean | 是 | 能否旋转屏幕的标识，true：可以旋转，false：不可以旋转。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.setDisplayRotationEnabled(false) } ``` @@ -1547,11 +1977,19 @@ getDisplaySize(): Promise\ | -------------------------- | --------------------------------------- | | Promise\<[Point](#point9)> | 以Promise的形式返回当前设备的屏幕大小。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let size = await driver.getDisplaySize() } ``` @@ -1570,11 +2008,19 @@ getDisplayDensity(): Promise\ | -------------------------- | ------------------------------------------- | | Promise\<[Point](#point9)> | 以Promise的形式返回当前设备的屏幕的分辨率。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let density = await driver.getDisplayDensity() } ``` @@ -1587,11 +2033,19 @@ wakeUpDisplay(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.wakeUpDisplay() } ``` @@ -1604,11 +2058,19 @@ pressHome(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.pressHome() } ``` @@ -1630,15 +2092,24 @@ waitForIdle(idleTime: number, timeout: number): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------------------------------- | +| 类型 | 说明 | +| ----------------- | --------------------------------------------------- | | Promise\ | 以Promise的形式返回当前界面的所有控件是否已经空闲。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let idled = await driver.waitForIdle(4000,5000) } ``` @@ -1656,15 +2127,24 @@ fling(from: Point, to: Point, stepLen: number, speed: number): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------- | ---- | ------------------------------------------------------------ | | from | [Point](#point9) | 是 | 手指接触屏幕的起始点坐标。 | -| to | [Point](#point9) | 是 | 手指离开屏幕时的坐标点。 | +| to | [Point](#point9) | 是 | 手指离开屏幕时的坐标点。 | | stepLen | number | 是 | 间隔距离，单位：像素点。 | -| speed | number | 是 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 | +| speed | number | 是 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() await driver.fling({X: 500, Y: 480},{X: 450, Y: 480},5,600) } ``` @@ -1682,14 +2162,23 @@ injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\ | 以Promise的形式返回植入操作是否成功完成。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js @@ -1705,53 +2194,128 @@ async function demo() { } ``` -## UiWindow9+ +## PointerMatrix9+ -UiTest中，UiWindow类代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等API。 -该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 +表示存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。 + +### create9+ -### WindowFilter9+ +static create(fingers: number, steps: number): PointerMatrix -窗口的标志属性信息。 +静态方法，构造一个PointerMatrix对象，并返回该对象。 **系统能力**：SystemCapability.Test.UiTest -| 名称 | 参数类型 | 必填 | 可读 | 可写 | 描述 | -| ---------- | -------- | ---- | ---- | ---- | -------------------------- | -| bundleName | string | 否 | 是 | 否 | 窗口对应的包名。 | -| title | string | 否 | 是 | 否 | 窗口的标题。 | -| focused | boolean | 否 | 是 | 否 | 窗口是否获焦。 | -| actived | boolean | 否 | 是 | 否 | 窗口是否正与用户进行交互。 | +**参数：** -### getBundleName9+ +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------ | +| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1,10]。 | +| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1,1000]。 | -getBundleName(): Promise\ +**返回值：** -获取窗口的包名信息。 +| 类型 | 说明 | +| -------------------------------- | ----------------------------- | +| [PointerMatrix](#pointermatrix9) | 返回构造的PointerMatrix对象。 | -**系统能力**：SystemCapability.Test.UiTest +**错误码：** -**返回值：** +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| ---------------- | --------------------------------- | -| Promise\ | 以Promise形式返回窗口的包名信息。 | +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | **示例：** ```js async function demo() { - let driver = UiDriver.create() - let window = await driver.findWindow({actived: true}) - let name = await window.getBundleName() + let pointerMatrix = PointerMatrix.create(2,3) } ``` -### getBounds9+ +### setPoint9+ -getBounds(): Promise\ +setPoint(finger: number, step: number, point: Point): void -获取窗口的边框信息。 +设置PointerMatrix对象中指定手指和步骤对应动作的坐标点。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------- | ---- | ---------------- | +| finger | number | 是 | 手指的序号。 | +| step | number | 是 | 步骤的序号。 | +| point | [Point](#point9) | 是 | 该行为的坐标点。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ------------------------ | +| 401 | Invalid input parameter. | + +**示例：** + +```js +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}) +} +``` + +## UiWindow9+ + +UiTest中，UiWindow类代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等API。 +该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 + +### getBundleName9+ + +getBundleName(): Promise\ + +获取窗口的包名信息。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | --------------------------------- | +| Promise\ | 以Promise形式返回窗口的包名信息。 | + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + +**示例：** + +```js +async function demo() { + let driver = Driver.create() + let window = await driver.findWindow({actived: true}) + let name = await window.getBundleName() +} +``` + +### getBounds9+ + +getBounds(): Promise\ + +获取窗口的边框信息。 **系统能力**：SystemCapability.Test.UiTest @@ -1761,11 +2325,20 @@ getBounds(): Promise\ | ------------------------ | --------------------------------- | | Promise\<[Rect](#rect9)> | 以Promise形式返回窗口的边框信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) let rect = await window.getBounds() } @@ -1785,11 +2358,20 @@ getTitle(): Promise\ | ---------------- | --------------------------------- | | Promise\ | 以Promise形式返回窗口的标题信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) let rect = await window.getTitle() } @@ -1805,15 +2387,24 @@ getWindowMode(): Promise\ **返回值：** -| 类型 | 说明 | -| ------------------------------------------------ | ------------------------------------- | +| 类型 | 说明 | +| ------------------------------------ | ------------------------------------- | | Promise\<[WindowMode](#windowmode9)> | 以Promise形式返回窗口的窗口模式信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) let mode = await window.getWindowMode() } @@ -1829,15 +2420,24 @@ isFocused(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回窗口对象是否获焦，true：获焦，false：未获焦。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) let focused = await window.isFocused() } @@ -1853,15 +2453,24 @@ isActived(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回窗口对象是否为用户交互窗口，true：交互窗口，false：非交互窗口。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) let focused = await window.isActived() } @@ -1869,23 +2478,26 @@ async function demo() { ### focus9+ -focus(): Promise\ +focus(): Promise\ 让窗口获焦。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.focus() } @@ -1893,7 +2505,7 @@ async function demo() { ### moveTo9+ -moveTo(x: number, y: number): Promise\ +moveTo(x: number, y: number): Promise\ 将窗口移动到目标点。适用于支持移动的窗口。 @@ -1906,17 +2518,22 @@ moveTo(x: number, y: number): Promise\ | x | number | 是 | 以number的形式传入目标点的横坐标信息。 | | y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | -**返回值：** +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 17000005 | This operation is not supported. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.moveTo(100, 100) } @@ -1924,7 +2541,7 @@ async function demo() { ### resize9+ -resize(wide: number, height: number, direction: ResizeDirection): Promise\ +resize(wide: number, height: number, direction: ResizeDirection): Promise\ 根据传入的宽、高和调整方向来调整窗口的大小。适用于支持大小调整的窗口。 @@ -1932,23 +2549,28 @@ resize(wide: number, height: number, direction: ResizeDirection): Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 401 | Invalid input parameter. | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 17000005 | This operation is not supported. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.resize(100, 100, ResizeDirection.LEFT) } @@ -1956,23 +2578,27 @@ async function demo() { ### split9+ -split(): Promise\ +split(): Promise\ 将窗口模式切换成分屏模式。适用于支持切屏操作的窗口。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +| 类型 | 说明 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 17000005 | This operation is not supported. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.split() } @@ -1980,23 +2606,27 @@ async function demo() { ### maximize9+ -maximize(): Promise\ +maximize(): Promise\ 将窗口最大化。适用于支持窗口最大化操作的窗口。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 17000005 | This operation is not supported. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.maximize() } @@ -2004,23 +2634,27 @@ async function demo() { ### minimize9+ -minimize(): Promise\ +minimize(): Promise\ 将窗口最小化。适用于支持窗口最小化操作的窗口。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 17000005 | This operation is not supported. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.minimize() } @@ -2028,23 +2662,27 @@ async function demo() { ### resume9+ -resume(): Promise\ +resume(): Promise\ 将窗口恢复到之前的窗口模式。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 17000005 | This operation is not supported. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.resume() } @@ -2052,93 +2690,32 @@ async function demo() { ### close9+ -close(): Promise\ +close(): Promise\ 将窗口关闭。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 17000005 | This operation is not supported. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.close() } ``` -## PointerMatrix9+ - -表示存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。 - -### create9+ - -static create(fingers: number, steps: number): PointerMatrix - -静态方法，构造一个PointerMatrix对象，并返回该对象。 - -**系统能力**：SystemCapability.Test.UiTest - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------ | -| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1,10]。 | -| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1,1000]。 | - -**返回值：** - -| 类型 | 说明 | -| -------------------------------- | ----------------------------- | -| [PointerMatrix](#pointermatrix9) | 返回构造的PointerMatrix对象。 | - -**示例：** - -```js -async function demo() { - let pointerMatrix = PointerMatrix.create(2,3) -} -``` - -### setPoint9+ - -setPoint(finger: number, step: number, point: Point): void - -设置PointerMatrix对象中指定手指和步骤对应动作的坐标点。 - -**系统能力**：SystemCapability.Test.UiTest - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---------------- | ---- | ---------------- | -| finger | number | 是 | 手指的序号。 | -| step | number | 是 | 步骤的序号。 | -| point | [Point](#point9) | 是 | 该行为的坐标点。 | - -**示例：** - -```js -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}) -} -``` - -### - ## MatchPattern 控件属性支持的匹配模式。 @@ -2169,6 +2746,30 @@ async function demo() { | RIGHT_UP | 右上方。 | | RIGHT_DOWN | 右下方。 | +## 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 @@ -2194,3 +2795,1052 @@ async function demo() { | ROTATION_90 | 设备显示器顺时针旋转90°，水平显示。 | | ROTATION_180 | 设备显示器顺时针旋转180°，逆向垂直显示。 | | ROTATION_270 | 设备显示器顺时针旋转270°，逆向水平显示。 | + +## WindowFilter9+ + +窗口的标志属性信息。 + +**系统能力**：SystemCapability.Test.UiTest + +| 名称 | 参数类型 | 必填 | 可读 | 可写 | 描述 | +| ---------- | -------- | ---- | ---- | ---- | -------------------------- | +| bundleName | string | 否 | 是 | 否 | 窗口对应的包名。 | +| title | string | 否 | 是 | 否 | 窗口的标题。 | +| focused | boolean | 否 | 是 | 否 | 窗口是否获焦。 | +| actived | boolean | 否 | 是 | 否 | 窗口是否正与用户进行交互。 | + +## By(deprecated) + +UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
+By提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[By.isBefore](#isbefore)和[By.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。
By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。 + +从API version9开始不再维护，建议使用[On9+](#On9)。 + +```js +BY.text('123').type('button') +``` + +### text(deprecated) + +text(txt: string, pattern?: MatchPattern): By + +指定目标控件文本属性，支持多种匹配模式，返回By对象自身。 + +从API version9开始不再维护，建议使用[text9+](#text9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------- | ---- | --------------------------------------------------- | +| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 | +| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------- | +| [By](#by) | 返回指定目标控件文本属性的By对象。 | + +**示例：** + +```js +let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性。 +``` + + +### key(deprecated) + +key(key: string): By + +指定目标控件key值属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[id9+](#id9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ----------------- | +| key | string | 是 | 指定控件的Key值。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ----------------------------------- | +| [By](#by) | 返回指定目标控件key值属性的By对象。 | + +**示例：** + +```js +let by = BY.key('123') //使用静态构造器BY创建by对象，指定目标控件的key值属性。 +``` + + +### id(deprecated) + +id(id: number): By + +指定目标控件id属性，返回By对象自身。 + +从API version9开始不再维护，被废弃。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| id | number | 是 | 指定控件的id值。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | -------------------------------- | +| [By](#by) | 返回指定目标控件id属性的By对象。 | + +**示例：** + +```js +let by = BY.id(123) //使用静态构造器BY创建by对象，指定目标控件的id属性。 +``` + + +### type(deprecated) + +type(tp: string): By + +指定目标控件的控件类型属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[type9+](#type9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------- | +| tp | string | 是 | 指定控件类型。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------- | +| [By](#by) | 返回指定目标控件的控件类型属性的By对象。 | + +**示例：** + +```js +let by = BY.type('button') //使用静态构造器BY创建by对象，指定目标控件的控件类型属性。 +``` + + +### clickable(deprecated) + +clickable(b?: boolean): By + +指定目标控件的可点击状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[clickable9+](#clickable9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | +| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ------------------------------------------ | +| [By](#by) | 返回指定目标控件的可点击状态属性的By对象。 | + +**示例：** + +```js +let by = BY.clickable(true) //使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。 +``` + + +### scrollable(deprecated) + +scrollable(b?: boolean): By + +指定目标控件的可滑动状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[scrollable9+](#scrollable9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ----------------------------------------------------------- | +| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ------------------------------------------ | +| [By](#by) | 返回指定目标控件的可滑动状态属性的By对象。 | + +**示例：** + +```js +let by = BY.scrollable(true) //使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。 +``` + +### enabled(deprecated) + +enabled(b?: boolean): By + +指定目标控件的使能状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[enabled9+](#enabled9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | --------------------------------------------------------- | +| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------- | +| [By](#by) | 返回指定目标控件的使能状态属性的By对象。 | + +**示例：** + +```js +let by = BY.enabled(true) //使用静态构造器BY创建by对象，指定目标控件的使能状态属性。 +``` + +### focused(deprecated) + +focused(b?: boolean): By + +指定目标控件的获焦状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[focused9+](#focused9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ----------------------------------------------------- | +| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------- | +| [By](#by) | 返回指定目标控件的获焦状态属性的By对象。 | + +**示例：** + +```js +let by = BY.focused(true) //使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。 +``` + +### selected(deprecated) + +selected(b?: boolean): By + +指定目标控件的被选中状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[selected9+](#selected9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | +| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ------------------------------------------ | +| [By](#by) | 返回指定目标控件的被选中状态属性的By对象。 | + +**示例：** + +```js +let by = BY.selected(true) //使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。 +``` + +### isBefore(deprecated) + +isBefore(by: By): By + +指定目标控件位于给出的特征属性控件之前，返回By对象自身。 + +从API version9开始不再维护，建议使用[isBefore9+](#isBefore9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ---------------- | +| by | [By](#by) | 是 | 特征控件的属性。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------------------- | +| [By](#by) | 返回指定目标控件位于给出的特征属性控件之前的By对象。 | + +**示例：** + +```js +let by = BY.isBefore(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。 +``` + +### isAfter(deprecated) + +isAfter(by: By): By + +指定目标控件位于给出的特征属性控件之后，返回By对象自身。 + +从API version9开始不再维护，建议使用[isAfter9+](#isAfter9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ---------------- | +| by | [By](#by) | 是 | 特征控件的属性。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------------------- | +| [By](#by) | 返回指定目标控件位于给出的特征属性控件之后的By对象。 | + +**示例：** + +```js +let by = BY.isAfter(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。 +``` + +## UiComponent(deprecated) + +UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 +该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 + +从API version9开始不再维护，建议使用[Component9+](#component9)。 + +### click(deprecated) + +click(): Promise\ + +控件对象进行点击操作。 + +从API version9开始不再维护，建议使用[click9+](#click9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + await button.click() +} +``` + +### doubleClick(deprecated) + +doubleClick(): Promise\ + +控件对象进行双击操作。 + +从API version9开始不再维护，建议使用[doubleClick9+](#doubleClick9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + await button.doubleClick() +} +``` + +### longClick(deprecated) + +longClick(): Promise\ + +控件对象进行长按操作。 + +从API version9开始不再维护，建议使用[longClick9+](#longClick9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + await button.longClick() +} +``` + +### getId(deprecated) + +getId(): Promise\ + +获取控件对象的id值。 + +从API version9开始不再维护，建议使用[getId9+](#getId9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ------------------------------- | +| Promise\ | 以Promise形式返回的控件的id值。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + let num = await button.getId() +} +``` + +### getKey(deprecated) + +getKey(): Promise\ + +获取控件对象的key值。 + +从API version9开始不再维护，被废弃。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ------------------------------ | +| Promise\ | 以Promise形式返回控件的key值。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + let str_key = await button.getKey() +} +``` + +### getText(deprecated) + +getText(): Promise\ + +获取控件对象的文本信息。 + +从API version9开始不再维护，建议使用[getText9+](#getText9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | --------------------------------- | +| Promise\ | 以Promise形式返回控件的文本信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + let text = await button.getText() +} +``` + +### getType(deprecated) + +getType(): Promise\ + +获取控件对象的控件类型。 + +从API version9开始不再维护，建议使用[getType9+](#getType9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ----------------------------- | +| Promise\ | 以Promise形式返回控件的类型。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + let type = await button.getType() +} +``` + +### isClickable(deprecated) + +isClickable(): Promise\ + +获取控件对象可点击状态。 + +从API version9开始不再维护，建议使用[isClickable9+](#isClickable9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | +| Promise\ | 以Promise形式返回控件对象可点击状态，true：可点击，false：不可点击。 | + +**示例：** + +```js +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') + } +} +``` + +### isScrollable(deprecated) + +isScrollable(): Promise\ + +获取控件对象可滑动状态。 + +从API version9开始不再维护，建议使用[isScrollable9+](#isScrollable9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | +| Promise\ | 以Promise形式返回控件对象可滑动状态，true：可滑动，false：不可滑动。 | + +**示例：** + +```js +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(deprecated) + +isEnabled(): Promise\ + +获取控件使能状态。 + +从API version9开始不再维护，建议使用[isEnabled9+](#isEnabled9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ---------------------------------------------------------- | +| Promise\ | 以Promise形式返回控件使能状态，true：使能，false：未使能。 | + +**示例：** + +```js +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(deprecated) + +isFocused(): Promise\ + +判断控件对象是否获焦。 + +从API version9开始不再维护，建议使用[isFocused9+](#isFocused9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | +| Promise\ | 以Promise形式返回控件对象是否获焦，true：获焦，false：未获焦。 | + +**示例：** + +```js +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(deprecated) + +isSelected(): Promise\ + +获取控件对象被选中状态。 + +从API version9开始不再维护，建议使用[isSelected9+](#isSelected9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ----------------------------------------------------- | +| Promise\ | 控件对象被选中的状态，true：被选中，false：未被选中。 | + +**示例：** + +```js +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(deprecated) + +inputText(text: string): Promise\ + +向控件中输入文本(适用于文本框控件)。 + +从API version9开始不再维护，建议使用[inputText9+](#inputText9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| text | string | 是 | 输入的文本信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let text = await driver.findComponent(BY.text('hello world')) + await text.inputText('123') +} +``` + +### scrollSearch(deprecated) + +scrollSearch(by: By): Promise\ + +在控件上滑动查找目标控件(适用于List等支持滑动的控件)。 + +从API version9开始不再维护，建议使用[scrollSearch9+](#scrollSearch9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------- | +| by | [By](#by) | 是 | 目标控件的属性要求。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------- | ------------------------------------- | +| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的目标控件对象。 | + +**示例：** + +```js +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(deprecated) + +UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。 +该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。 + +从API version9开始不再维护，建议使用[Driver9+](#Driver9)。 + +### create(deprecated) + +static create(): UiDriver + +静态方法，构造一个UiDriver对象，并返回该对象。 + +从API version9开始不再维护，建议使用[create9+](#create9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| -------- | ------------------------ | +| UiDriver | 返回构造的UiDriver对象。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() +} +``` + +### delayMs(deprecated) + +delayMs(duration: number): Promise\ + +UiDriver对象在给定的时间内延时。 + +从API version9开始不再维护，建议使用[delayMs9+](#delayMs9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------ | +| duration | number | 是 | 给定的时间。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.delayMs(1000) +} +``` + +### findComponent(deprecated) + +findComponent(by: By): Promise\ + +在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。 + +从API version9开始不再维护，建议使用[findComponent9+](#findComponent9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------- | +| by | [By](#by) | 是 | 目标控件的属性要求。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------- | --------------------------------- | +| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的控件对象。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.text('next page')) +} +``` + +### findComponents(deprecated) + +findComponents(by: By): Promise\> + +在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 + +从API version9开始不再维护，建议使用[findComponents9+](#findComponents9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------- | +| by | [By](#by) | 是 | 目标控件的属性要求。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------------------- | --------------------------------------- | +| Promise\> | 以Promise形式返回找到的控件对象的列表。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let buttonList = await driver.findComponents(BY.text('next page')) +} +``` + +### assertComponentExist(deprecated) + +assertComponentExist(by: By): Promise\ + +断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。 + +从API version9开始不再维护，建议使用[assertComponentExist9+](#assertComponentExist9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------- | +| by | [By](#by) | 是 | 目标控件的属性要求。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.assertComponentExist(BY.text('next page')) +} +``` + +### pressBack(deprecated) + +pressBack(): Promise\ + +UiDriver对象进行点击BACK键的操作。 + +从API version9开始不再维护，建议使用[pressBack9+](#pressBack9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.pressBack() +} +``` + +### triggerKey(deprecated) + +triggerKey(keyCode: number): Promise\ + +UiDriver对象采取如下操作：通过key值找到对应键并点击。 + +从API version9开始不再维护，建议使用[triggerKey9+](#triggerKey9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------- | +| keyCode | number | 是 | 指定的key值。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.triggerKey(123) +} +``` + + +### click(deprecated) + +click(x: number, y: number): Promise\ + +UiDriver对象采取如下操作：在目标坐标点单击。 + +从API version9开始不再维护，建议使用[click9+](#click9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.click(100,100) +} +``` + +### doubleClick(deprecated) + +doubleClick(x: number, y: number): Promise\ + +UiDriver对象采取如下操作：在目标坐标点双击。 + +从API version9开始不再维护，建议使用[doubleClick9+](#doubleClick9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.doubleClick(100,100) +} +``` + +### longClick(deprecated) + +longClick(x: number, y: number): Promise\ + +UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。 + +从API version9开始不再维护，建议使用[longClick9+](#longClick9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.longClick(100,100) +} +``` + +### swipe(deprecated) + +swipe(startx: number, starty: number, endx: number, endy: number): Promise\ + +UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。 + +从API version9开始不再维护，建议使用[swipe9+](#swipe9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 | +| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 | +| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 | +| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.swipe(100,100,200,200) +} +``` + +### screenCap(deprecated) + +screenCap(savePath: string): Promise\ + +UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 + +从API version9开始不再维护，建议使用[screenCap9+](#screenCap9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | -------------- | +| savePath | string | 是 | 文件保存路径。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | -------------------------------------- | +| Promise\ | 截图操作是否成功完成。成功完成为true。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.screenCap('/local/tmp/') +} +``` diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-uitest.md b/zh-cn/application-dev/reference/errorcodes/errorcode-uitest.md new file mode 100644 index 0000000000000000000000000000000000000000..95c04ca1a42117566684e1f56d86584222feb8e7 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-uitest.md @@ -0,0 +1,73 @@ +# uitest错误码 + +## 401 参数错误 + +### 错误信息 + +Invalid input parameter. + +### 错误描述 + +输入参数不合理。 + +### 可能原因 + +1. 入参数量不足。 +2. 参数类型错误。 + +### 处理步骤 + +1. 检查入参，补充足够的入参数量。 +2. 检查入参，修正参数类型错误。 + +## 17000001 初始化失败 + +### 错误信息 +Initialize failed. +### 错误描述 +框架初始化失败。 +### 可能原因 +无法连接到无障碍服务。 +### 处理步骤 +执行param set persist.ace.testmode.enabled 1，并重启设备。 + +## 17000002 当前无法调用 +### 错误信息 +API does not allow calling concurrently. +### 错误描述 +当前无法调用API。 +### 可能原因 +API没有使用await进行异步调用，造成堵塞。 + +### 处理步骤 +检查测试用例，确保异步接口使用await调用。 + +## 17000003 断言失败 +### 错误信息 +Component existence assertion failed. +### 错误描述 +用户断言失败。 +### 可能原因 +用户断言存在的控件实际不存在。 +### 处理步骤 +检查用户断言存在的控件实际是否存在。 + +## 17000004 目标控件/窗口丢失 +### 错误信息 +Component lost/UiWindow lost. +### 错误描述 +目标控件/窗口丢失，无法进行操作。 +### 可能原因 +获取到目标控件/窗口后，页面发生变化导致目标丢失。 +### 处理步骤 +检查获取到目标控件/窗口后，页面是否发生变化导致目标丢失。 + +## 17000005 操作不支持 +### 错误信息 +This operation is not supported. +### 错误描述 +UI对象不支持该操作。 +### 可能原因 +当前界面控件/窗口属性不支持该操作。 +### 处理步骤 +检查当前界面控件/窗口属性是否该操作。