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.
**Required permissions**: none Specifies the ID 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 |
| ------ | ------ | ---- | ------------ | | ------ | ------ | ---- | ---------------- |
| 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. Specifies the scrollable 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 | 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.
**Required permissions**: none Specifies the focused 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 | 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
**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>
**Required permissions**: none 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** **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**
```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. Obtains the enabled 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 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).
**Required permissions**: none Scrolls on this component to search for the target component (applicable to component that support scrolling, such as **\<List>**).
**System capability**: SystemCapability.Test.UiTest **System capability**: SystemCapability.Test.UiTest
...@@ -732,20 +873,81 @@ Scrolls on this component to search for the target component (available for list ...@@ -732,20 +873,81 @@ 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.
先完成此消息的编辑！
想要评论请 注册 或