Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 c769e097 编写于 作者: E ester.zhou
浏览文件
操作

update js-apis-uitest.md 

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 c5345c22
显示空白变更内容
内联 并排
Showing with 575 addition and 315 deletion
en/application-dev/reference/apis/js-apis-uitest.md
浏览文件 @ c769e097
# UiTest # UiTest
>**NOTE** >**NOTE**<br>The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> >
>The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Modules to Import
...@@ -13,46 +12,27 @@ import {UiDriver,BY,MatchPattern} from '@ohos.uitest' ...@@ -13,46 +12,27 @@ import {UiDriver,BY,MatchPattern} from '@ohos.uitest'
## By ## By
The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components. The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components.<br>
The API capabilities provided by the **By** class exhibit the following features: The API capabilities provided by the **By** class exhibit the following features: <br>1. Allow one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component. <br>2. Provide multiple match patterns for component attributes. <br>3. Support absolute positioning and relative positioning for components. APIs such as [By.isBefore](#byisbefore) and [By.isAfter](#byisafter) can be used to specify the features of adjacent components to assist positioning. <br>All APIs provided in the **By** class are synchronous. You are advised to use the static constructor **BY** to create a **By** object in chain mode.
- Allows one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component. ```js
BY.text('123').type('button')
- Provides multiple match patterns for component attributes. ```
- Supports absolute positioning and relative positioning for components. APIs such as **isBefore** and **isAfter** can be used to specify the features of adjacent components to assist positioning.
All APIs provided in the **By** class are synchronous. You are advised to use the static constructor **BY** to create a **By** object in chain mode, for example, **BY.text('123').type('button')**.
### enum MatchPattern
Enumerates the match patterns supported for component attributes.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ----------- | ---- | ------------ |
| EQUALS | 0 | Equal to the given value. |
| CONTAINS | 1 | Contain the given value. |
| STARTS_WITH | 2 | Start with the given value.|
| ENDS_WITH | 3 | End with the given value.|
### By.text ### By.text
text(txt:string,pattern?:MatchPattern):By text(txt: string, pattern?: MatchPattern): By
Specifies the text attribute of the target component. Multiple match patterns are supported. Specifies the text attribute of the target component. Multiple match patterns are supported.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| ------- | ------------ | ---- | ---------------------------------- | | ------- | ------------ | ---- | ------------------------------------------------- |
| txt | string | Yes | Component text, used to match the target component.| | txt | string | Yes | Component text, used to match the target component. |
| pattern | MatchPattern | No | Match pattern. The default value is **EQUALS**. | | pattern | MatchPattern | No | Match pattern. The default value is [EQUALS](#matchpattern).|
**Return value** **Return value**
...@@ -62,324 +42,382 @@ Specifies the text attribute of the target component. Multiple match patterns ar ...@@ -62,324 +42,382 @@ Specifies the text attribute of the target component. Multiple match patterns ar
**Example** **Example**
``` ```js
let by = BY.text('123') // Use the static constructor BY to create a By object and specify the text attribute let by = BY.text('123') // Use the static constructor BY to create a By object and specify the text attribute of the target component.
of the target component.
``` ```
### By.key ### By.key
key(key:string):By; key(key: string): By
Specifies the key attribute of the target component. Specifies the key attribute of the target component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | --------------- | | ------ | ------ | ---- | ----------------- |
| key | string | Yes | Component key.| | key | string | Yes | Component key.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
``` ```js
let by = BY.key('123') // Use the static constructor BY to create a By object and specify the key attribute let by = BY.key('123') // Use the static constructor BY to create a By object and specify the key attribute of the target component.
of the target component.
``` ```
### By.id ### By.id
id(id:number):By; id(id: number): By
Specifies the ID property of the target component. Specifies the ID attribute of the target component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------ | | ------ | ------ | ---- | ---------------- |
| id | number | Yes | Component ID.| | id | number | Yes | Component ID.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
``` ```js
let by = BY.id(123) // Use the static constructor BY to create a By object and specify the ID attribute let by = BY.id(123) // Use the static constructor BY to create a By object and specify the id attribute of the target component.
of the target component.
``` ```
### By.type ### By.type
type(tp:string):By; type(tp: string): By
Specifies the type property of the target component. Specifies the type attribute of the target component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------ | | ------ | ------ | ---- | -------------- |
| tp | string | Yes | Component type.| | tp | string | Yes | Component type.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
``` ```js
let by = BY.type('button') // Use the static constructor BY to create a By object and specify the type attribute let by = BY.type('button') // Use the static constructor BY to create a By object and specify the type attribute of the target component.
of the target component.
``` ```
### By.clickable ### By.clickable
clickable(b?:bool):By; clickable(b?: bool): By
Specifies the clickable attribute of the target component. Specifies the clickable attribute of the target component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------------ | | ------ | ---- | ---- | -------------------------------- |
| b | bool | No | Clickable status of the target component. The default value is **true**.| | b | bool | No | Clickable status of the target component. The default value is **true**.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
```js
let by = BY.clickable(true) // Use the static constructor BY to create a By object and specify the clickable status attribute of the target component.
``` ```
let by = BY.clickable(true) // Use the static constructor BY to create a By object and specify the clickable attribute
of the target component. ### By.longClickable<sup>9+</sup>
longClickable(b?: bool): By
Specifies the long-clickable status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------------------ |
| b | bool | No | Long-clickable status of the target component. The default value is **true**.|
**Return value**
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```js
let by = BY.longClickable(true) // Use the static constructor BY to create a By object and specify the long-clickable status attribute of the target component.
``` ```
### By.scrollable ### By.scrollable
scrollable(b?:bool):By; scrollable(b?: bool): By
Specifies the scrollable attribute of the target component.
**Required permissions**: none Specifies the scrollable status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------------------- | | ------ | ---- | ---- | ---------------------------- |
| b | bool | No | Scrollable status of the target component. The default value is **true**.| | b | bool | No | Scrollable status of the target component. The default value is **true**.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
``` ```js
let by = BY.scrollable(true) // Use the static constructor BY to create a By object and specify the scrollable attribute let by = BY.scrollable(true) // Use the static constructor BY to create a By object and specify the scrollable status attribute of the target component.
of the target component.
``` ```
### By.enabled ### By.enabled
enabled(b?:bool):By; enabled(b?: bool): By
Specifies the enable attribute of the target component.
**Required permissions**: none Specifies the enabled status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ---------------------------- | | ------ | ---- | ---- | ------------------------------ |
| b | bool | No | Enable status of the target component. The default value is **true**.| | b | bool | No | Enabled status of the target component. The default value is **true**.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
``` ```js
let by = BY.enabled(true) // Use the static constructor BY to create a By object and specify the enable attribute let by = BY.enabled(true) // Use the static constructor BY to create a By object and specify the enabled status attribute of the target component.
of the target component.
``` ```
### By.focused ### By.focused
focused(b?:bool):By; focused(b?: bool): By
Specifies the focused attribute of the target component. Specifies the focused status attribute of the target component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------ | | ------ | ---- | ---- | -------------------------- |
| b | bool | No | Focused status of the target component. The default value is **true**.| | b | bool | No | Focused status of the target component. The default value is **true**.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
``` ```js
let by = BY.enabled(true) // Use the static constructor BY to create a By object and specify the focused attribute let by = BY.enabled(true) // Use the static constructor BY to create a By object and specify the focused status attribute of the target component.
of the target component.
``` ```
### By.selected ### By.selected
selected(b?:bool):By; selected(b?: bool): By
Specifies the selected attribute of the target component.
**Required permissions**: none Specifies the selected status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------------ | | ------ | ---- | ---- | -------------------------------- |
| b | bool | No | Selected status of the target component. The default value is **true**.| | b | bool | No | Selected status of the target component. The default value is **true**.|
**Return value** **Return value**
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```js
let by = BY.selected(true) // Use the static constructor BY to create a By object and specify the selected status attribute of the target component.
```
### By.checked<sup>9+</sup>
checked(b?: bool): By
Specifies the checked status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | --------------------------------- |
| b | bool | No | Checked status of the target component. The default value is **false**.|
**Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | -------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
```js
let by = BY.checked(true) // Use the static constructor BY to create a By object and specify the checked status attribute of the target component.
``` ```
let by = BY.selected(true) // Use the static constructor BY to create a By object and specify the selected attribute
of the target component. ### By.checkable<sup>9+</sup>
checkable(b?: bool): By
Specifies the checkable status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------------------- |
| b | bool | No | Checkable status of the target component. The default value is **false**.|
**Return value**
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```js
let by = BY.checkable(true) // Use the static constructor BY to create a By object and specify the checkable status attribute of the target component.
``` ```
### By.isBefore ### By.isBefore
isBefore(by:By):By; isBefore(by: By): By
Specifies the attributes of the component before which the target component is located. Specifies the attributes of the component before which the target component is located.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------- | | ------ | ---- | ---- | ---------------- |
| by | By | Yes | Attributes of the component before which the target component is located.| | by | By | Yes | Attributes of the component before which the target component is located.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
``` ```js
let by = BY.isBefore(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes let by = BY.isBefore(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes of the component before which the target component is located.
of the component before which the target component is located.
``` ```
### By.isAfter ### By.isAfter
isAfter(by:By):By; isAfter(by: By): By
Specifies the attributes of the component after which the target component is located. Specifies the attributes of the component after which the target component is located.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------- | | ------ | ---- | ---- | ---------------- |
| by | By | Yes | Attributes of the component before which the target component is located.| | by | By | Yes | Attributes of the component before which the target component is located.|
**Return value** **Return value**
| Type| Description | | Type| Description |
| ---- | -------------- | | ---- | ---------------- |
| By | Returns the **By** object itself.| | By | Returns the **By** object itself.|
**Example** **Example**
``` ```js
let by = BY.isAfter(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes let by = BY.isAfter(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes of the component after which the target component is located.
of the component after which the target component is located.
``` ```
## UiComponent ## UiComponent
In **UiTest**, the **UiComponent** class represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. In **UiTest**, the **UiComponent** class represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection.
All APIs provided by this class use a promise to return the result and must be invoked using **await**. All APIs provided in this class use a promise to return the result and must be invoked using **await**.
### Rect<sup>9+</sup>
Provides border information of a component.
**System capability**: SystemCapability.Test.UiTest
| Name | Type| Readable| Writable| Description |
| ------- | -------- | ---- | ---- | ------------------------- |
| leftX | number | Yes | No | X coordinate of the upper left corner of the component borders.|
| topY | number | Yes | No | Y coordinate of the upper left corner of the component borders.|
| rightX | number | Yes | No | X coordinate of the lower right corner of the component borders.|
| bottomY | number | Yes | No | Y coordinate of the lower right corner of the component borders.|
### UiComponent.click ### UiComponent.click
click():Promise<void>; click(): Promise\<void>
Clicks this component. Clicks this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -389,37 +427,33 @@ async function demo() { ...@@ -389,37 +427,33 @@ async function demo() {
### UiComponent.doubleClick ### UiComponent.doubleClick
doubleClick():Promise<void>; doubleClick(): Promise\<void>
Double-clicks this component. Double-clicks this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
await buttont.doubleClick() await button.doubleClick()
} }
``` ```
### UiComponent.longClick ### UiComponent.longClick
longClick():Promise<void>; longClick(): Promise\<void>
Long-clicks this component. Long-clicks this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -429,23 +463,21 @@ async function demo() { ...@@ -429,23 +463,21 @@ async function demo() {
### UiComponent.getId ### UiComponent.getId
getId():Promise<number>; getId(): Promise\<number>
Obtains the ID of this component. Obtains the ID of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------- | ------------------------- | | ---------------- | ------------------------------- |
| Promise<number>; | Promise used to return the component ID.| | Promise\<number> | Promise used to return the ID of the component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -455,23 +487,21 @@ async function demo() { ...@@ -455,23 +487,21 @@ async function demo() {
### UiComponent.getKey ### UiComponent.getKey
getKey():Promise<string>; getKey(): Promise\<string>
Obtains the key of this component. Obtains the key of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------- | -------------------------- | | ---------------- | ------------------------------ |
| Promise<string>; | Promise used to return the component key.| | Promise\<string> | Promise used to return the key of the component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -481,23 +511,21 @@ async function demo() { ...@@ -481,23 +511,21 @@ async function demo() {
### UiComponent.getText ### UiComponent.getText
getText():Promise<string>; getText(): Promise\<string>
Obtains the text information of this component. Obtains the text information of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------- | ------------------------------- | | ---------------- | --------------------------------- |
| Promise<string>; | Promise used to return the text information of the component.| | Promise\<string> | Promise used to return the text information of the component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -507,23 +535,21 @@ async function demo() { ...@@ -507,23 +535,21 @@ async function demo() {
### UiComponent.getType ### UiComponent.getType
getType():Promise<string>; getType(): Promise\<string>
Obtains the type of this component. Obtains the type of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------- | ------------------------------- | | ---------------- | ----------------------------- |
| Promise<string>; | Promise used to return the component type.| | Promise\<string> | Promise used to return the type of the component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -531,25 +557,47 @@ async function demo() { ...@@ -531,25 +557,47 @@ async function demo() {
} }
``` ```
### UiComponent.getBounds<sup>9+</sup>
getBounds(): Promise\<Rect>
Obtains the bounds of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------- | ------------------------------------- |
| Promise\<Rect> | Promise used to return the bounds of the component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let rect = await button.getBounds()
}
```
### UiComponent.isClickable ### UiComponent.isClickable
isClickable():Promise<bool>; isClickable(): Promise\<bool>
Obtains the clickable status of this component. Obtains the clickable status of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| -------------- | ----------------------------------- | | -------------- | ------------------------------------- |
| Promise<bool>; | Promise used to return the clickable status of the component.| | Promise\<bool> | Promise used to return the clickable status of the component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -562,25 +610,110 @@ async function demo() { ...@@ -562,25 +610,110 @@ async function demo() {
} }
``` ```
### UiComponent.isScrollable ### UiComponent.isLongClickable<sup>9+</sup>
isScrollable():Promise<bool>; isLongClickable(): Promise\<bool>
Obtains the scrollable status of this component. Obtains the long clickable status of this component.
**System capability**: SystemCapability.Test.UiTest
**Required permissions**: none **Return value**
| Type | Description |
| -------------- | ------------------------------------------- |
| Promise\<bool> | Promise used to return the long clickable status of the component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
if(await button.isLongClickable()) {
console.info('This button can longClick')
}
else{
console.info('This button can not longClick')
}
}
```
### UiComponent.isChecked<sup>9+</sup>
isChecked(): Promise\<bool>
Obtains the checked status of this component.
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| -------------- | ----------------------------------- | | -------------- | ------------------------------------- |
| Promise<bool>; | Promise used to return the scrollable status of the component.| | Promise\<bool> | Promise used to return the checked status of the component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create()
let checkBox = await driver.findComponent(BY.type('Checkbox'))
if(await checkBox.isChecked) {
console.info('This checkBox is checked')
}
else{
console.info('This checkBox is not checked')
}
}
```
### UiComponent.isCheckable<sup>9+</sup>
isCheckable(): Promise\<bool>
Obtains the checked status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------- | ------------------------------------------- |
| Promise\<bool> | Promise used to return the checked status of the component.|
**Example** **Example**
```js
async function demo() {
let driver = UiDriver.create()
let checkBox = await driver.findComponent(BY.type('Checkbox'))
if(await checkBox.isCheckable) {
console.info('This checkBox is checkable')
}
else{
console.info('This checkBox is not checkable')
}
}
``` ```
### UiComponent.isScrollable
isScrollable(): Promise\<bool>
Obtains the scrollable status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------- | ------------------------------------- |
| Promise\<bool> | Promise used to return the scrollable status of the component.|
**Example**
```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let scrollBar = await driver.findComponent(BY.scrollable(true)) let scrollBar = await driver.findComponent(BY.scrollable(true))
...@@ -596,23 +729,21 @@ async function demo() { ...@@ -596,23 +729,21 @@ async function demo() {
### UiComponent.isEnabled ### UiComponent.isEnabled
isEnabled():Promise<bool>; isEnabled(): Promise\<bool>
Obtains the enable status of this component.
**Required permissions**: none Obtains the enabled status of this component.
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| -------------- | ----------------------------- | | -------------- | ------------------------------- |
| Promise<bool>; | Promise used to return the enable status of the component.| | Promise\<bool> | Promise used to return the enabled status of the component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -628,23 +759,21 @@ async function demo() { ...@@ -628,23 +759,21 @@ async function demo() {
### UiComponent.isFocused ### UiComponent.isFocused
isFocused():Promise<bool>; isFocused(): Promise\<bool>
Obtains the focused status of this component. Obtains the focused status of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| -------------- | --------------------------------- | | -------------- | ----------------------------------- |
| Promise<bool>; | Promise used to return the focused status of the component.| | Promise\<bool> | Promise used to return the focused status of the component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -659,23 +788,21 @@ async function demo() { ...@@ -659,23 +788,21 @@ async function demo() {
### UiComponent.isSelected ### UiComponent.isSelected
isSelected():Promise<bool>; isSelected(): Promise\<bool>
Obtains the selected status of this component. Obtains the selected status of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| -------------- | ----------------------------------- | | -------------- | -------------------- |
| Promise<bool>; | Promise used to return the selected status of the component.| | Promise\<bool> | Promise used to return the selected status of the component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let button = await driver.findComponent(BY.type('button'))
...@@ -690,37 +817,51 @@ async function demo() { ...@@ -690,37 +817,51 @@ async function demo() {
### UiComponent.inputText ### UiComponent.inputText
inputText(text: string):Promise<void>; inputText(text: string): Promise\<void>
Enters text into this component (available for text boxes). Enters text into this component (available for text boxes).
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------- | | ------ | ------ | ---- | ---------------- |
| text | string | Yes | Text to be entered to the component.| | text | string | Yes | Text to enter.|
**Example** **Example**
```js
async function demo() {
let driver = UiDriver.create()
let text = await driver.findComponent(BY.text('hello world'))
await text.inputText('123')
}
``` ```
### UiComponent.clearText<sup>9+</sup>
clearText(): Promise\<void>
Clears text in this component (available for text boxes).
**System capability**: SystemCapability.Test.UiTest
**Example**
```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button')) let text = await driver.findComponent(BY.text('hello world'))
await button.inputText('next page') await text.clearText()
} }
``` ```
### UiComponent.scrollSearch ### UiComponent.scrollSearch
scrollSearch(by:By):Promise<UiComponent>; scrollSearch(by: By): Promise\<UiComponent>
Scrolls on this component to search for the target component (available for lists). Scrolls on this component to search for the target component (applicable to component that support scrolling, such as **\<List>**).
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
...@@ -733,19 +874,80 @@ Scrolls on this component to search for the target component (available for list ...@@ -733,19 +874,80 @@ Scrolls on this component to search for the target component (available for list
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------- | ----------------------------------- | | --------------------- | ------------------------------------- |
| Promise<UiComponent>; | Promise used to return the target component.| | Promise\<UiComponent> | Promise used to return the target component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let scrollBar = await driver.findComponent(BY.scrollable(true)) let scrollBar = await driver.findComponent(BY.type('Scroll'))
let button = await scrollBar.scrollSearch(BY.text('next page')) let button = await scrollBar.scrollSearch(BY.text('next page'))
} }
``` ```
### UiComponent.scrollToTop<sup>9+</sup>
scrollToTop(): Promise\<void>
Scrolls to the top of this a component (applicable to component that support scrolling, such as **\<List>**).
**System capability**: SystemCapability.Test.UiTest
**Example**
```js
async function demo() {
let driver = UiDriver.create()
let scrollBar = await driver.findComponent(BY.type('Scroll'))
await scrollBar.scrollToTop()
}
```
### UiComponent.scrollToBottom<sup>9+</sup>
scrollToBottom(): Promise\<void>
Scrolls to the bottom of this a component (applicable to component that support scrolling, such as **\<List>**).
**System capability**: SystemCapability.Test.UiTest
**Example**
```js
async function demo() {
let driver = UiDriver.create()
let scrollBar = await driver.findComponent(BY.type('Scroll'))
await scrollBar.scrollToBottom()
}
```
### UiComponent.dragTo<sup>9+</sup>
dragTo(target: UiComponent): Promise\<void>
Drags this component to the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------- | ---- | ---------- |
| target | UiComponent | Yes | Target component.|
**Example**
```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'))
await button.dragTo(text)
}
```
## UiDriver ## UiDriver
The **UiDriver** class is the main entry to the **uitest** test framework. It provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. The **UiDriver** class is the main entry to the **uitest** test framework. It provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot.
...@@ -753,23 +955,21 @@ All APIs provided by this class, except for **UiDriver.create()**, use a promise ...@@ -753,23 +955,21 @@ All APIs provided by this class, except for **UiDriver.create()**, use a promise
### UiDriver.create ### UiDriver.create
static create():UiDriver; static create(): UiDriver
Creates a **UiDriver** object and returns the object created. This API is a static API. Creates a **UiDriver** object and returns the object created. This API is a static API.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------- | ---------------------- | | ------- | ------------------------ |
| UiDrive | Returns the **UiDriver** object created.| | UiDrive | Returns the **UiDriver** object created.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
} }
...@@ -777,23 +977,21 @@ async function demo() { ...@@ -777,23 +977,21 @@ async function demo() {
### UiDriver.delayMs ### UiDriver.delayMs
delayMs(duration:number):Promise<void>; delayMs(duration: number): Promise\<void>
Delays this **UiDriver** object within the specified duration. Delays this **UiDriver** object within the specified duration.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ---------- | | -------- | ------ | ---- | ------------ |
| duration | number | Yes | Duration of time.| | duration | number | Yes | Duration of time.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.delayMs(1000) await driver.delayMs(1000)
...@@ -802,29 +1000,27 @@ async function demo() { ...@@ -802,29 +1000,27 @@ async function demo() {
### UiDriver.findComponent ### UiDriver.findComponent
findComponent(by:By):Promise<UiComponent>; findComponent(by: By): Promise\<UiComponent>
Searches this **UiDriver** object for the target component that has the given attributes.
**Required permissions**: none Searches this **UiDriver** object for the target component that matches the given attributes.
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------ | | ------ | ---- | ---- | -------------------- |
| by | By | Yes | Attributes of the target component.| | by | By | Yes | Attributes of the target component.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------- | ------------------------------- | | --------------------- | --------------------------------- |
| Promise<UiComponent>; | Promise used to return the found component.| | Promise\<UiComponent> | Promise used to return the found component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let button = await driver.findComponent(BY.text('next page')) let button = await driver.findComponent(BY.text('next page'))
...@@ -833,54 +1029,80 @@ async function demo() { ...@@ -833,54 +1029,80 @@ async function demo() {
### UiDriver.findComponents ### UiDriver.findComponents
findComponents(by:By):Promise<Array<UiComponent>>; findComponents(by: By): Promise\<Array\<UiComponent>>
Searches this **UiDriver** object for all components that match the given attributes. Searches this **UiDriver** object for all components that match the given attributes.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------ | | ------ | ---- | ---- | -------------------- |
| by | By | Yes | Attributes of the target component.| | by | By | Yes | Attributes of the target component.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------------------- | ------------------------------------- | | ----------------------------- | --------------------------------------- |
| Promise<Array<UiComponent>>; | Promise used to return a list of found components.| | Promise\<Array\<UiComponent>> | Promise used to return a list of found components.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
let buttonList = await driver.findComponents(BY.text('next page')) let buttonList = await driver.findComponents(BY.text('next page'))
} }
``` ```
### UiDriver.waitForComponent<sup>9+</sup>
waitForComponent(by: By, time: number): Promise\<UiComponent>
Searches this **UiDriver** object for the target component that matches the given attributes within the specified duration.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------- |
| by | By | Yes | Attributes of the target component. |
| time | number | Yes | Duration for searching for the target component, in ms.|
**Return value**
| Type | Description |
| --------------------- | --------------------------------- |
| Promise\<UiComponent> | Promise used to return the found component.|
**Example**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.waitForComponent(BY.text('next page'),500)
}
```
### UiDriver.assertComponentExist ### UiDriver.assertComponentExist
assertComponentExist(by:By):Promise<void>; assertComponentExist(by: By): Promise\<void>
Asserts that a component that matches the given attributes exists on the current page. If the component does not exist, the API throws a JS exception, causing the current test case to fail. Asserts that a component that matches the given attributes exists on the current page. If the component does not exist, the API throws a JS exception, causing the current test case to fail.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type| Mandatory| Description | | Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------ | | ------ | ---- | ---- | -------------------- |
| by | By | Yes | Attributes of the target component.| | by | By | Yes | Attributes of the target component.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.assertComponentExist(BY.text('next page')) await driver.assertComponentExist(BY.text('next page'))
...@@ -889,17 +1111,15 @@ async function demo() { ...@@ -889,17 +1111,15 @@ async function demo() {
### UiDriver.pressBack ### UiDriver.pressBack
pressBack():Promise<void>; pressBack(): Promise\<void>
Presses the Back button on this **UiDriver** object. Presses the Back button on this **UiDriver** object.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.pressBack() await driver.pressBack()
...@@ -908,23 +1128,21 @@ async function demo() { ...@@ -908,23 +1128,21 @@ async function demo() {
### UiDriver.triggerKey ### UiDriver.triggerKey
triggerKey(keyCode:number):Promise<void>; triggerKey(keyCode: number): Promise\<void>
Triggers the key of this **UiDriver** object that matches the given key code. Triggers the key of this **UiDriver** object that matches the given key code.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| ------- | ------ | ---- | --------- | | ------- | ------ | ---- | ------------- |
| keyCode | number | Yes | Key code.| | keyCode | number | Yes | Key code.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.triggerKey(123) await driver.triggerKey(123)
...@@ -933,23 +1151,22 @@ async function demo() { ...@@ -933,23 +1151,22 @@ async function demo() {
### UiDriver.click ### UiDriver.click
click(x:number,y:number):Promise<void>; click(x: number, y: number): Promise\<void>
Clicks a specific point of this **UiDriver** object based on the given coordinates. Clicks a specific point of this **UiDriver** object based on the given coordinates.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------------- | ---- | ------------------------------------------- | | ------ | ------ | ---- | -------------------------------------- |
| x,y | number,number | Yes | Coordinate information of a specific point in the (number,number) format.| | x | number | Yes | X coordinate of the target point.|
| y | number | Yes | Y coordinate of the target point.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.click(100,100) await driver.click(100,100)
...@@ -958,23 +1175,22 @@ async function demo() { ...@@ -958,23 +1175,22 @@ async function demo() {
### UiDriver.doubleClick ### UiDriver.doubleClick
doubleClick(x:number,y:number):Promise<void>; doubleClick(x: number, y: number): Promise\<void>
Double-clicks a specific point of this **UiDriver** object based on the given coordinates. Double-clicks a specific point of this **UiDriver** object based on the given coordinates.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------------- | ---- | ------------------------------------------- | | ------ | ------ | ---- | -------------------------------------- |
| x,y | number,number | Yes | Coordinate information of a specific point in the (number,number) format.| | x | number | Yes | X coordinate of the target point.|
| y | number | Yes | Y coordinate of the target point.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.doubleClick(100,100) await driver.doubleClick(100,100)
...@@ -983,23 +1199,22 @@ async function demo() { ...@@ -983,23 +1199,22 @@ async function demo() {
### UiDriver.longClick ### UiDriver.longClick
longClick(x:number,y:number):Promise<void>; longClick(x: number, y: number): Promise\<void>
Long-clicks a specific point of this **UiDriver** object based on the given coordinates. Long-clicks a specific point of this **UiDriver** object based on the given coordinates.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------------- | ---- | ------------------------------------------- | | ------ | ------ | ---- | -------------------------------------- |
| x,y | number,number | Yes | Coordinate information of a specific point in the (number,number) format.| | x | number | Yes | X coordinate of the target point.|
| y | number | Yes | Y coordinate of the target point.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.longClick(100,100) await driver.longClick(100,100)
...@@ -1008,51 +1223,96 @@ async function demo() { ...@@ -1008,51 +1223,96 @@ async function demo() {
### UiDriver.swipe ### UiDriver.swipe
swipe(startx:number,starty:number,endx:number,endy:number):Promise<void>; swipe(startx: number, starty: number, endx: number, endy: number): Promise\<void>
Swipes from the start point to the end point of this **UiDriver** object based on the given coordinates.
**Required permissions**: none Swipes on this **UiDriver** object from the start point to the end point based on the given coordinates.
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------------- | ------------- | ---- | ------------------------------------------- | | ------ | ------ | ---- | -------------------------------------- |
| startx,starty | number,number | Yes | Coordinate information of the start point in the (number,number) format.| | startx | number | Yes | X coordinate of the start point.|
| endx,endy | number,number | Yes | Coordinate information of the end point in the (number,number) format.| | starty | number | Yes | Y coordinate of the start point.|
| endx | number | Yes | X coordinate of the end point.|
| endy | number | Yes | Y coordinate of the end point.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.swipe(100,100,200,200) await driver.swipe(100,100,200,200)
} }
``` ```
### UiDriver.drag<sup>9+</sup>
drag(startx: number, starty: number, endx: number, endy: number): Promise\<void>
Drags this **UiDriver** object from the given start point to the given end point.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| startx | number | Yes | X coordinate of the start point.|
| starty | number | Yes | Y coordinate of the start point.|
| endx | number | Yes | X coordinate of the end point.|
| endy | number | Yes | Y coordinate of the end point.|
**Example**
```js
async function demo() {
let driver = UiDriver.create()
await driver.drag(100,100,200,200)
}
```
### UiDriver.screenCap ### UiDriver.screenCap
screenCap(savePath:string):Promise<bool>; screenCap(savePath: string): Promise\<bool>
Captures the current screen of this **UiDriver** object and saves it as a PNG image to the given save path. Captures the current screen of this **UiDriver** object and saves it as a PNG image to the given save path.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------ | | -------- | ------ | ---- | -------------- |
| savePath | string | Yes | File save path.| | savePath | string | Yes | File save path.|
**Return value**
| Type | Description |
| -------------- | -------------------------------------- |
| Promise\<bool> | Promise used to return the operation result. The value **true** means that the operation is successful.|
**Example** **Example**
``` ```js
async function demo() { async function demo() {
let driver = UiDriver.create() let driver = UiDriver.create()
await driver.screenCap('/local/tmp/') await driver.screenCap('/local/tmp/')
} }
``` ```
## MatchPattern
Enumerates the match patterns supported for component attributes.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ----------- | ---- | -------------- |
| EQUALS | 0 | Equal to the given value. |
| CONTAINS | 1 | Containing the given value. |
| STARTS_WITH | 2 | Starting from the given value.|
| ENDS_WITH | 3 | Ending with the given value.|
###
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或