To accelerate test automation of OpenHarmony, arkXtest — an automated test framework that supports both the JavaScript (JS) and TypeScript (TS) programming languages — is provided.
To accelerate test automation of OpenHarmony, arkXtest — an automated unit and UI test framework that supports both the JavaScript (JS) and TypeScript (TS) programming languages — is provided.
In this document you will learn about the key functions of arkXtest and how to use it to perform unit testing on application or system APIs and to write UI automated test scripts.
...
...
@@ -13,7 +13,7 @@ In this document you will learn about the key functions of arkXtest and how to u
arkXtest is part of the OpenHarmony toolkit and provides basic capabilities of writing and running OpenHarmony automated test scripts. In terms of test script writing, arkXtest offers a wide range of APIs, including basic process APIs, assertion APIs, and APIs related to UI operations. In terms of test script running, arkXtest offers such features as identifying, scheduling, and executing test scripts, as well as summarizing test script execution results.
### Principles
### Implementation
arkXtest is divided into two parts: unit test framework and UI test framework.
...
...
@@ -27,16 +27,16 @@ arkXtest is divided into two parts: unit test framework and UI test framework.
- UI Testing Framework
- UI Test Framework
The UI test framework provides [UiTest APIs](../reference/apis/js-apis-uitest.md) for you to call in different test scenarios. The test scripts are executed on top of the unit test framework mentioned above.
The UI test framework provides [UiTest APIs](../reference/apis/js-apis-uitest.md) for you to call in different test scenarios. The UI test scripts are executed on top of the aformentioned unit test framework.
The figure below shows the main functions of the UI test framework.
### Limitations and Constraints
### Constraints
- The features of the UI test framework are available only in OpenHarmony 3.1 and later versions.
- The feature availability of the unit test framework varies by version. For details about the mappings between the features and versions, see [arkXtest](https://gitee.com/openharmony/testfwk_arkxtest/blob/master/README_en.md).
...
...
@@ -46,9 +46,9 @@ arkXtest is divided into two parts: unit test framework and UI test framework.
### Environment Requirements
Software for writing test scripts: DevEco Studio 3.0 or later
Software: DevEco Studio 3.0 or later
Hardware for running test scripts: PC connected to an OpenHarmony device, such as the RK3568 development board
Hardware: PC connected to an OpenHarmony device, such as the RK3568 development board
### Setting Up the Environment
...
...
@@ -57,7 +57,7 @@ Hardware for running test scripts: PC connected to an OpenHarmony device, such a
## Creating a Test Script
1. Open DevEco Studio and create a project, where the **ohos** directory is where the test script is located.
1. Open DevEco Studio and create a project, in which the **ohos** directory is where the test script is located.
2. Open the .ets file of the module to be tested in the project directory. Move the cursor to any position in the code, and then right-click and choose **Show Context Actions** > **Create Ohos Test** or press **Alt+Enter** and choose **Create Ohos Test** to create a test class.
## Writing a Unit Test Script
...
...
@@ -95,7 +95,7 @@ export default function abilityTest() {
The unit test script must contain the following basic elements:
1. Import of the dependency package so that the dependent test APIs can be used.
1. Import of the dependencies so that the dependent test APIs can be used.
2. Test code, mainly about the related logic, such as API invoking.
...
...
@@ -105,7 +105,7 @@ The unit test script must contain the following basic elements:
You write a UI test script based on the unit test framework, adding the invoking of APIs provided by the UI test framework to implement the corresponding test logic.
In this example, the UI test script is written based on the preceding unit test script. First, add the dependency package, as shown below:
In this example, the UI test script is written based on the preceding unit test script. First, import the dependency, as shown below:
@@ -187,18 +185,18 @@ Parameters in aa test commands
The framework supports multiple test case execution modes, which are triggered by the key-value pair following the **-s** keyword. The table below lists the available keys and values.
| unittest | OpenHarmonyTestRunner object used for test case execution. | **OpenHarmonyTestRunner** or custom runner name. | - s unittest OpenHarmonyTestRunner |
| unittest | **OpenHarmonyTestRunner** object used for test case execution. | **OpenHarmonyTestRunner** or custom runner name. | - s unittest OpenHarmonyTestRunner |
| class | Test suite or test case to be executed. | {describeName}#{itName}, {describeName} | -s class attributeTest#testAttributeIt |
| notClass | Test suite or test case that does not need to be executed. | {describeName}#{itName}, {describeName} | -s notClass attributeTest#testAttributeIt |
| itName | Test case to be executed. | {itName} | -s itName testAttributeIt |
| timeout | Timeout interval for executing a test case. | Positive integer (unit: ms). If no value is set, the default value 5000 is used. | -s timeout 15000 |
| breakOnError | Whether to enable break-on-error mode. When this mode is enabled, the test execution process exits if a test assertion error or any other error occurs.| **true**/**false** (default value) | -s breakOnError true |
| breakOnError | Whether to enable break-on-error mode. When this mode is enabled, the test execution process exits if a test assertion failure or error occurs.| **true**/**false** (default value) | -s breakOnError true |
| random | Whether to execute test cases in random sequence.| **true**/**false** (default value) | -s random true |
| testType | Type of the test case to be executed. | function, performance, power, reliability, security, global, compatibility, user, standard, safety, resilience| -s testType function |
| level | Level of the test case to be executed. | 0, 1, 2, 3, 4 | -s level 0 |
| size | Size of the test case to be executed. | small, medium, large | -s size small |
| size | Size of the test case to be executed. | small, medium, large | -s size small
| stress | Number of times that the test case is executed. | Positive integer | -s stress 1000 |
| Error | Number of test cases whose execution encounters errors. |
| Pass | Number of passed test cases.|
| Ignore | Number of test cases not executed.|
| Ignore | Number of test cases not yet executed.|
| taskconsuming| Total time spent in executing the current test case.|
> When an error occurs in break-on-error mode, check the **Ignore** and interrupt information.
...
...
@@ -341,11 +339,11 @@ The logs added to the test case are displayed after the test case execution, rat
**Possible Causes**
More than one asynchronous interface is called in the test case.<br>In principle, logs in the test case are printed before the test case execution is complete.
More than one asynchronous API is called in the test case.<br>In principle, logs in the test case are printed before the test case execution is complete.
**Solution**
If more than one asynchronous interface is called, you are advised to encapsulate the interface invoking into the promise mode
If more than one asynchronous API is called, you are advised to encapsulate the API invoking into the promise mode.
#### Error "fail to start ability" is reported during test case execution
...
...
@@ -373,7 +371,7 @@ After the test case execution is complete, the console displays the error messag
2. The time taken for API invocation is longer than the timeout interval set for test case execution.
3. Test assertion fails, and a failure exception is thrown. As a result, the test case execution does not end until the timeout expires.
3. Test assertion fails, and a failure exception is thrown. As a result, the test case execution does not end until it times out.
**Solution**
...
...
@@ -388,11 +386,11 @@ After the test case execution is complete, the console displays the error messag
**Problem**
The UI test case fails to be executed. The HiLog file contains the error message "Get windows failed/GetRootByWindow failed".
The UI test case fails to be executed. The HiLog file contains the error message "Get windows failed/GetRootByWindow failed."
**Possible Causes**
The ArkUI feature is disabled. As a result, the control tree information on the test page is not generated.
The ArkUI feature is disabled. As a result, the component tree information is not generated on the test page.
**Solution**
...
...
@@ -410,13 +408,13 @@ The UI test case fails to be executed. The HiLog file contains the error message
**Possible Causes**
1. In the test case, the **await** operator is not added to the asynchronous interface provided by the UI test framework.
1. In the test case, the **await** operator is not added to the asynchronous API provided by the UI test framework.
2. The UI test case is executed in multiple processes. As a result, multiple UI test processes are started. The framework does not support multi-process invoking.
**Solution**
1. Check the case implementation and add the **await** operator to the asynchronous interface invoking.
1. Check the case implementation and add the **await** operator to the asynchronous API.
2. Do not execute UI test cases in multiple processes.
...
...
@@ -424,11 +422,11 @@ The UI test case fails to be executed. The HiLog file contains the error message
**Problem**
The UI test case fails to be executed. The HiLog file contains the error message "does not exist on current UI! Check if the UI has changed after you got the widget object".
The UI test case fails to be executed. The HiLog file contains the error message "does not exist on current UI! Check if the UI has changed after you got the widget object."
**Possible Causes**
After the target component is found in the code of the test case, the device UI changes. As a result, the found component is lost and the emulation operation cannot be performed.
After the target component is found in the code of the test case, the device UI changes, resulting in loss of the found component and inability to perform emulation.
To develop an application based on the [stage model](application-configuration-file-overview-stage.md), it will be helpful if you have a basic understanding of the structure of the application package created after the application is built and packaged, as well as the related basic concepts.
- In development, an application contains one or more modules. You can [create modules](https://developer.harmonyos.com/en/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3) in the application project in [DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio/). As a basic functional unit of an OpenHarmony application/service, a module contains source code, resource files, third-party libraries, and application/service configuration files, and can be built and run independently. Modules can be classified as Ability or Library. A module of the Ability type is built into a Harmony Ability Package (HAP) file, and a module of the Library type is built into a [Harmony Archive (HAR)](har-package.md) file or a [Harmony Shared Package (HSP)](shared-guide.md).
- In development, an application contains one or more modules. You can [create modules](https://developer.harmonyos.com/en/docs/documentation/doc-guides-V3/add_new_module-0000001053223741-V3) in the application project in [DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio/). As a basic functional unit of an OpenHarmony application/service, a module contains source code, resource files, third-party libraries, and application/service configuration files, and can be built and run independently. Modules can be classified as Ability or Library. A module of the Ability type is built into a Harmony Ability Package (HAP) file, and a module of the Library type is built into a [Harmony Archive (HAR)](har-package.md) file or a [Harmony Shared Package (HSP)](shared-guide.md).
A module can contain one or more [UIAbility](../application-models/uiability-overview.md) components, as shown in the figure below.
**Figure 1** Relationship between modules and UIAbility components
# $ Syntax: Two-Way Synchronization of Built-in Components
# $$ Syntax: Two-Way Synchronization of Built-in Components
The $$ operator provides a TS variable by-reference to a built-in component so that the variable value and the internal state of that component are kept in sync.
@@ -18,9 +18,9 @@ Sets a timer for the system to call a function after the timer goes off.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| handler | Function \| string | Yes| Function to be called after the timer goes off.|
| handler | Function \| string | Yes| Function to be called after the timer goes off. If the type is string, error information is printed and no other processing is performed.|
| delay | number | No| Number of milliseconds delayed before the execution. If this parameter is left empty, the default value **0** is used, which means that the execution starts immediately or as soon as possible.|
| ...arguments | Array<any> | No| Additional parameters to pass to the handler after the timer goes off.|
| ...arguments | any[] | No| Additional parameters to pass to the handler after the timer goes off.|
**Return value**
...
...
@@ -31,19 +31,15 @@ Sets a timer for the system to call a function after the timer goes off.
**Example**
```js
exportdefault{
setTimeOut(){
vartimeoutID=setTimeout(function(){
console.log('delay 1s');
},1000);
}
}
setTimeout(function(){
console.log('delay 1s');
},1000);
```
## clearTimeout
clearTimeout(timeoutID: number): void
clearTimeout(timeoutID?: number): void
Cancels the timer created via **setTimeout()**.
...
...
@@ -53,19 +49,15 @@ Cancels the timer created via **setTimeout()**.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timeoutID | number | Yes| ID of the timer to cancel, which is returned by **setTimeout()**|
| timeoutID | number | No| ID of the timer to cancel, which is returned by **setTimeout()** If this parameter is omitted, no timer is canceled.|
**Example**
```js
exportdefault{
clearTimeOut(){
vartimeoutID=setTimeout(function(){
console.log('do after 1s delay.');
},1000);
clearTimeout(timeoutID);
}
}
```js
lettimeoutID=setTimeout(function(){
console.log('do after 1s delay.');
},1000);
clearTimeout(timeoutID);
```
...
...
@@ -81,32 +73,28 @@ Sets a repeating timer for the system to repeatedly call a function at a fixed i
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| handler | Function \| string | Yes| Function to be called repeatedly.|
| handler | Function \| string | Yes| Function to be called repeatedly. If the type is string, error information is printed and no other processing is performed.|
| delay | number | Yes| Number of milliseconds delayed before the execution.|
| ...arguments | Array<any> | No| Additional parameters to pass to the handler after the timer goes off.|
| ...arguments | any[] | No| Additional parameters to pass to the handler after the timer goes off.|
**Return value**
| Type| Description|
| -------- | -------- |
| number | ID of the repeating timer.|
| number | Timer ID.|
**Example**
```js
exportdefault{
setInterval(){
varintervalID=setInterval(function(){
console.log('do very 1s.');
},1000);
}
}
setInterval(function(){
console.log('do every 1s.');
},1000);
```
## clearInterval
clearInterval(intervalID: number): void
clearInterval(intervalID?: number): void
Cancels the repeating timer set via **setInterval()**.
...
...
@@ -116,17 +104,13 @@ Cancels the repeating timer set via **setInterval()**.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| intervalID | number | Yes| ID of the repeating timer to cancel, which is returned by **setInterval()**.|
| intervalID | number | No| ID of the repeating timer to cancel, which is returned by **setInterval()**. If this parameter is omitted, no timer is canceled.|
