ohos.ui_test (UI Testing)

Note:

Currently in the beta phase.

ui_test provides the capability to simulate UI operations for developers to use in testing scenarios, primarily supporting UI operations such as clicking, double-clicking, long-pressing, swiping, etc.

This module offers the following functionalities:

• On: Provides control feature description capabilities for control filtering and matching.
• Component: Represents a specified control on the UI interface, offering capabilities such as control property retrieval, control clicking, swiping to find, text injection, etc.
• Driver: Entry class providing capabilities such as control matching, finding, key injection, coordinate clicking or swiping, screenshots, etc.
• UiWindow: Entry class providing capabilities such as window property retrieval, window dragging, window resizing, etc.

Importing the Module

import kit.TestKit.*

Usage Instructions

API example code usage instructions:

• If the first line of the example code has a "// index.cj" comment, it indicates that the example can be compiled and run in the "index.cj" file of the Cangjie template project.
• If the example requires obtaining the Context application context, it needs to be configured in the "main_ability.cj" file of the Cangjie template project.

For details on the example project and configuration template mentioned above, refer to Cangjie Example Code Instructions.

Running Tests

Preparations

• Connect a device that supports the uitest framework to a PC, ensuring the PC has the corresponding drivers and hdc service installed.
• For devices using the uitest framework for the first time after flashing, execute hdc shell param set persist.ace.testmode.enabled 1 and restart the device to enable ACE, ensuring the device can retrieve ArkUI control node information via accessibility services.
• Execute hdc shell param set persist.sys.suspend_manager_enabled 0 and restart the device to disable the background application freeze mechanism.

Test Command

hdc shell aa test -b com.example.myapplication -m entry -s unittest CJTestRunner

• Here, -b com.example.myapplication -m entry should be filled in according to the actual bundle name and module name in the app.
• The final CJTestRunner is the first parameter registered with TestRunner.registerCreator.

class Component

public class Component {}

Functionality: The Component class represents a control on the UI interface, providing APIs for control property retrieval, control clicking, swiping to find, text injection, etc.

System Capability: SystemCapability.Test.UiTest

Since: 22

func clearText()

public func clearText(): Unit

Functionality: Clears the text information of the control, applicable to text box controls.

System Capability: SystemCapability.Test.UiTest

Since: 22

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

func click()

public func click(): Unit

Functionality: Performs a click operation on the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

func doubleClick()

public func doubleClick(): Unit

Functionality: Performs a double-click operation on the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

func dragTo(Component)

public func dragTo(target: Component): Unit

Functionality: Drags the control to the target control.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
target	Component	Yes	-	Target control.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
  17000004	The window or component is invisible or destroyed.

func getBounds()

public func getBounds(): Rect

Functionality: Retrieves the border information of the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Rect	Border information of the control object.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

func getBoundsCenter()

public func getBoundsCenter(): Point

Functionality: Retrieves the center point information of the area occupied by the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Point	Center point information of the area occupied by the control object.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

func getDescription()

public func getDescription(): String

Functionality: Retrieves the description information of the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
String	Description information of the control.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

func getId()

public func getId(): String

Functionality: Retrieves the ID value of the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
String	ID value of the control.

func getText()

public func getText(): String

Functionality: Retrieves the text information of the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
String	Text information of the control.

func getType()

public func getType(): String

Functionality: Retrieves the control type of the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
String	Type of the control.

func inputText(String)

public func inputText(text: String): Unit

Functionality: Inputs text into the control, applicable to text box controls.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
text	String	Yes	-	Text information to input, currently supporting English and special characters.

func isCheckable()

public func isCheckable(): Bool

Functionality: Determines whether the control object can be checked.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Whether the control object can be checked, true: checkable, false: not checkable.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

func isChecked()

public func isChecked(): Bool

Functionality: Retrieves the checked state of the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Checked state of the control object, true: checked, false: not checked.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

func isClickable()

public func isClickable(): Bool

Functionality: Determines whether the control object is clickable.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Whether the control object is clickable, true: clickable, false: not clickable.

func isEnabled()

public func isEnabled(): Bool

Functionality: Retrieves the enabled state of the control.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Enabled state of the control, true: enabled, false: disabled.

func isFocused()

public func isFocused(): Bool

Functionality: Determines the focus state of the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Focus state of the control object, true: focused, false: not focused.

func isLongClickable()

public func isLongClickable(): Bool

Functionality: Determines whether the control object can be long-clicked.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Whether the control object can be long-clicked, true: long-clickable, false: not long-clickable.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

func isScrollable()

public func isScrollable(): Bool

Functionality: Determines whether the control object is scrollable.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Whether the control object is scrollable, true: scrollable, false: not scrollable.

func isSelected()

public func isSelected(): Bool

Functionality: Retrieves the selected state of the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Selected state of the control object, true: selected, false: not selected.

func longClick()

public func longClick(): Unit

Functionality: Performs a long-click operation on the control object.

System Capability: SystemCapability.Test.UiTest

Since: 22

func pinchIn(Float32)

public func pinchIn(scale: Float32): Unit

Functionality: Pinches the control to reduce its size by the specified scale.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
scale	Float32	Yes	-	Specified reduction scale.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
  17000004	The window or component is invisible or destroyed.

func pinchOut(Float32)

public func pinchOut(scale: Float32): Unit

Functionality: Pinches the control to enlarge its size by the specified scale.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
scale	Float32	Yes	-	Specified enlargement scale.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
  17000004	The window or component is invisible or destroyed.

func scrollSearch(On)

public func scrollSearch(on: On): ?Component

Functionality: Swipes on the control to find the target control, applicable to scrollable controls.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
on	On	Yes	-	Property requirements of the target control.

Return Value:

Type	Description
?Component	Found target control object.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
  17000004	The window or component is invisible or destroyed.

func scrollToBottom(Int64)

public func scrollToBottom(speed!: Int64 = 600): Unit

Functionality: Swipes to the bottom on the control, applicable to scrollable controls.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
speed	Int64	No	600	Named parameter. Swipe speed, range: 200-15000, default value is 600 if out of range, unit: pixels/second.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.
  17000004	The window or component is invisible or destroyed.

func scrollToTop(Int64)

public func scrollToTop(speed!: Int64 = 600): Unit

Functionality: Swipes to the top on the control, applicable to scrollable controls.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
speed	Int64	No	600	Named parameter. Swipe speed, range: 200-15000, default value is 600 if out of range, unit: pixels/second.

Exceptions:

• BusinessException: Corresponding error codes are listed in the table below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.
  ## class Driver

public class Driver {}

Description: The Driver class serves as the main entry point for the uitest framework, providing capabilities such as component matching, searching, key injection, coordinate-based clicking or swiping, and screenshot capturing.

System Capability: SystemCapability.Test.UiTest

Since: 22

static func create()

public static func create(): Driver

Description: A static method that constructs and returns a Driver object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Driver	Returns the constructed Driver object.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, refer to uitest Error Codes.

  Error Code ID	Error Message
  17000001	Initialization failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()

func assertComponentExist(On)

public func assertComponentExist(on: On): Unit

Description: An assertion API used to verify whether a component matching the specified target attributes exists on the current screen.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default Value	Description
on	On	Yes	-	Attribute requirements for the target component.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
  17000003	Assertion failed.

Example:

// index.cj

import kit.PerformanceAnalysisKit.*
import kit.TestKit.*
import ohos.business_exception.BusinessException

let driver: Driver = Driver.create()
try {
    driver.assertComponentExist(On().text("next page"))
} catch (e: BusinessException) {
    Hilog.error(0, "UITest", "The component `text(\"next page\")` does not exist")
}

func click(Int32, Int32)

public func click(x: Int32, y: Int32): Unit

Description: Executes a click operation at the specified coordinates.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default Value	Description
x	Int32	Yes	-	The x-coordinate of the target point, passed as an Int32.
y	Int32	Yes	-	The y-coordinate of the target point, passed as an Int32.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.click(100, 100)

func createUIEventObserver()

public func createUIEventObserver(): UIEventObserver

Description: Creates a UI event observer.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
UIEventObserver	Returns the created UI event observer object.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let observer: UIEventObserver = driver.createUIEventObserver()

func delayMs(Int32)

public func delayMs(duration: Int32): Unit

Description: Delays execution for the specified duration.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default Value	Description
duration	Int32	Yes	-	The duration to delay, in milliseconds.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, refer to Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.delayMs(1000)

func doubleClick(Int32, Int32)

public func doubleClick(x: Int32, y: Int32): Unit

Description: Executes a double-click operation at the specified coordinates.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default Value	Description
x	Int32	Yes	-	The x-coordinate of the target point, passed as an Int32.
y	Int32	Yes	-	The y-coordinate of the target point, passed as an Int32.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.doubleClick(100, 100)

func drag(Int32, Int32, Int32, Int32, Int32)

public func drag(
    startx: Int32,
    starty: Int32,
    endx: Int32,
    endy: Int32,
    speed!: Int32 = 600
): Unit

Description: Executes a drag operation from the start coordinates to the end coordinates.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default Value	Description
startx	Int32	Yes	-	The x-coordinate of the start point, passed as an Int32.
starty	Int32	Yes	-	The y-coordinate of the start point, passed as an Int32.
endx	Int32	Yes	-	The x-coordinate of the end point, passed as an Int32.
endy	Int32	Yes	-	The y-coordinate of the end point, passed as an Int32.
speed	Int32	No	600	Named parameter. The swipe speed, ranging from 200 to 15000. If out of range, the default value of 600 is used. Unit: pixels per second.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, refer to uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.drag(100, 100, 200, 200, speed: 600)

func findComponent(On)

public func findComponent(on: On): ?Component

Description: Searches for a target component based on the specified attribute requirements. If multiple components match the criteria, the first one found via depth-first search is returned.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default Value	Description
on	On	Yes	-	Attribute requirements for the target component.

Return Value:

Type	Description
?Component	The found component object.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let button: Option<Component> = driver.findComponent(On().text("next page"))

func findComponents(On)

public func findComponents(on: On): ?Array<Component>

Description: Searches for all components matching the specified attribute requirements and returns them as a list.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default Value	Description
on	On	Yes	-	Attribute requirements for the target components.

Return Value:

Type	Description
?Array<Component>	Attribute requirements for the target components.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, refer to Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let buttonList: Option<Array<Component>> = driver.findComponents(On().text("next page"))

func findWindow(WindowFilter)

public func findWindow(filter: WindowFilter): ?UiWindow

Description: Searches for a target window based on the specified window attributes. If multiple windows match the criteria, the topmost visible window is returned.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default Value	Description
filter	WindowFilter	Yes	-	Attributes of the target window.

Return Value:

Type	Description
?UiWindow	The found target window object.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, refer to Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
```### func fling(Point, Point, Int32, Int32)

```cangjie
public func fling(from: Point, to: Point, stepLen: Int32, speed: Int32): Unit

Function: Simulates a fling gesture (rapid swipe followed by release) with specified direction and speed.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
from	Point	Yes	-	Starting coordinates where finger touches the screen.
to	Point	Yes	-	Ending coordinates where finger leaves the screen.
stepLen	Int32	Yes	-	Step interval distance in pixels.
speed	Int32	Yes	-	Swipe speed (range: 200-40000). Values outside this range default to 600. Unit: pixels/second.

Exceptions:

• BusinessException: Error codes as shown below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.fling(UiDirection.Down, 10000)

func fling(UiDirection, Int32)

public func fling(direction: UiDirection, speed: Int32): Unit

Function: Simulates a fling gesture (rapid swipe followed by release) with specified direction and speed.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
direction	UiDirection	Yes	-	Direction of the fling gesture.
speed	Int32	Yes	-	Swipe speed (range: 200-40000). Values outside this range default to 600. Unit: pixels/second.

Exceptions:

• BusinessException: Error codes as shown below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.fling(UiDirection.Down, 10000)

func getDisplayDensity()

public func getDisplayDensity(): Point

Function: Retrieves the screen resolution of the current device.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Point	Returns the screen resolution of the current device.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let density = driver.getDisplayDensity()

func getDisplayRotation()

public func getDisplayRotation(): DisplayRotation

Function: Retrieves the current screen orientation of the device.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
DisplayRotation	Returns the current screen orientation of the device.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let rotation: DisplayRotation = driver.getDisplayRotation()

func getDisplaySize()

public func getDisplaySize(): Point

Function: Retrieves the screen size of the current device.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Point	Returns the screen size of the current device.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let size = driver.getDisplaySize()

func injectMultiPointerAction(PointerMatrix, Int32)

public func injectMultiPointerAction(pointers: PointerMatrix, speed!: Int32 = 600): Bool

Function: Injects a multi-touch gesture into the device.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
pointers	PointerMatrix	Yes	-	Gesture trajectory, including the number of fingers and coordinate sequences.
speed	Int32	No	600	Named parameter. Swipe speed (range: 200-15000). Values outside this range default to 600. Unit: pixels/second.

Return Value:

Type	Description
Bool	Returns whether the operation completed successfully. true indicates success; false otherwise.

Exceptions:

• BusinessException: Error codes as shown below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import ohos.ui_test.Point as PT
import ohos.ui_test.Driver
import ohos.ui_test.PointerMatrix

let driver: Driver = Driver.create()
let pointers: PointerMatrix = PointerMatrix.create(2, 3)
pointers.setPoint(0, 0, PT(230, 480))
pointers.setPoint(0, 1, PT(250, 380))
pointers.setPoint(0, 2, PT(270, 280))
pointers.setPoint(1, 0, PT(230, 680))
pointers.setPoint(1, 1, PT(240, 580))
pointers.setPoint(1, 2, PT(250, 480))
driver.injectMultiPointerAction(pointers)

func inputText(Point, String)

public func inputText(p: Point, text: String): Unit

Function: Inputs text at the specified coordinates.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
p	Point	Yes	-	Coordinates where text will be input.
text	String	Yes	-	Text to be input.

Exceptions:

• BusinessException: Error codes as shown below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException

let driver: Driver = Driver.create()
try {
    let text: Component = driver.findComponent(On().onType("TextInput")).getOrThrow()
    let point = text.getBoundsCenter()
    driver.inputText(point, "123")
} catch (e: BusinessException) {
    Hilog.error(0, "UITest", "The component `TextInput` does not exist")
}

func longClick(Int32, Int32)

public func longClick(x: Int32, y: Int32): Unit

Function: Performs a long-press operation at the specified coordinates for the Driver object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
x	Int32	Yes	-	X-coordinate of the target point (Int32).
y	Int32	Yes	-	Y-coordinate of the target point (Int32).

Exceptions:

• BusinessException: Error codes as shown below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.longClick(100, 100)

func mouseClick(Point, MouseButton, Int32, Int32)

public func mouseClick(p: Point, btnId: MouseButton, key1!: Int32 = 0, key2!: Int32 = 0): Unit

Function: Injects a mouse click action at the specified coordinates, optionally with keyboard key combinations. For example, when Key value is 2072, it simulates pressing CTRL while performing the mouse click.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
p	Point	Yes	-	Coordinates for the mouse click.
btnId	MouseButton	Yes	-	Mouse button to press.
key1	Int32	No	0	Named parameter. First key value to press.
key2	Int32	No	0	Named parameter. Second key value to press.

Exceptions:

• BusinessException: Error codes as shown below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import ohos.ui_test.Point as PT

let driver: Driver = Driver.create()
driver.mouseClick(PT(248, 194), MouseButton.MouseButtonLeft, key1: 2072)

func mouseDoubleClick(Point, MouseButton, Int32, Int32)

public func mouseDoubleClick(p: Point, btnId: MouseButton, key1!: Int32 = 0, key2!: Int32 = 0): Unit

Function: Injects a mouse double-click action at the specified coordinates, optionally with keyboard key combinations. For example, when Key value is 2072, it simulates pressing CTRL while performing the mouse double-click.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
p	Point	Yes	-	Coordinates for the mouse double-click.
btnId	MouseButton	Yes	-	Mouse button to press.
key1	Int32	No	0	Named parameter. First key value to press.
key2	Int32	No	0	Named parameter. Second key value to press.

Exceptions:

• BusinessException: Error codes as shown below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import ohos.ui_test.Point as PT

let driver: Driver = Driver.create()
driver.mouseDoubleClick(PT(248, 194), MouseButton.MouseButtonLeft, key1: 2072)

func mouseDrag(Point, Point, Int32)

public func mouseDrag(from: Point, to: Point, speed!: Int32 = 600): Unit

Function: Drags the mouse while holding the left button from the starting point to the destination point.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
from	Point	Yes	-	Coordinates of the starting point.
to	Point	Yes	-	Coordinates of the destination point.
speed	Int32	No	600	Named parameter. Drag speed, range: 200-15000. If out of range, the default value 600 is used. Unit: pixels/second.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import ohos.ui_test.Point as PT

let driver: Driver = Driver.create()
driver.mouseDrag(PT(100, 100), PT(200, 200))

func mouseLongClick(Point, MouseButton, Int32, Int32)

public func mouseLongClick(p: Point, btnId: MouseButton, key1!: Int32 = 0, key2!: Int32 = 0): Unit

Function: Injects a mouse long-press action at the specified coordinates, supporting simultaneous pressing of corresponding keyboard key combinations. For example, when the Key value is 2072, press CTRL and perform a mouse long-press action.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
p	Point	Yes	-	Coordinates for the mouse long-press.
btnId	MouseButton	Yes	-	The mouse button to press.
key1	Int32	No	0	Named parameter. The first specified key value.
key2	Int32	No	0	Named parameter. The second specified key value.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import ohos.ui_test.Point as PT

let driver: Driver = Driver.create()
driver.mouseLongClick(PT(248, 194), MouseButton.MouseButtonLeft, key1: 2072)

func mouseMoveTo(Point)

public func mouseMoveTo(p: Point): Unit

Function: Moves the mouse cursor to the target point.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
p	Point	Yes	-	Coordinates of the target point.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import ohos.ui_test.Point as PT

let driver: Driver = Driver.create()
driver.mouseMoveTo(PT(248, 194))

func mouseMoveWithTrack(Point, Point, Int32)

public func mouseMoveWithTrack(from: Point, to: Point, speed!: Int32 = 600): Unit

Function: Moves the mouse from the starting point coordinates to the destination point coordinates.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
from	Point	Yes	-	Coordinates of the starting point.
to	Point	Yes	-	Coordinates of the destination point.
speed	Int32	No	600	Named parameter. Movement speed, range: 200-15000. If out of range, the default value 600 is used. Unit: pixels/second.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import ohos.ui_test.Point as PT

let driver: Driver = Driver.create()
driver.mouseMoveWithTrack(PT(100, 100), PT(200, 200))

func mouseScroll(Point, Bool, Int32, Int32, Int32, Int32)

public func mouseScroll(p: Point, down: Bool, d: Int32, key1!: Int32 = 0, key2!: Int32 = 0, speed!: Int32 = 20): Unit

Function: Injects a mouse wheel scrolling action at the specified coordinates, supporting simultaneous pressing of corresponding keyboard key combinations and specifying the scrolling speed.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
p	Point	Yes	-	Coordinates for the mouse click.
down	Bool	Yes	-	Whether the wheel scroll direction is downward. true: scroll down; false: scroll up.
d	Int32	Yes	-	Number of notches the mouse wheel scrolls. Each notch corresponds to a displacement of 120 pixels at the target point.
key1	Int32	No	0	Named parameter. The first specified key value.
key2	Int32	No	0	Named parameter. The second specified key value.
speed	Int32	No	20	Named parameter. Mouse wheel scrolling speed, range: 1-500. If out of range, the default value 20 is used. Unit: notches/second.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import ohos.ui_test.Point as PT

let driver: Driver = Driver.create()
driver.mouseScroll(PT(360, 640), true, 30, key1: 2072)

func pressBack()

public func pressBack(): Unit

Function: The Driver object performs a BACK key press operation.

System Capability: SystemCapability.Test.UiTest

Since: 22

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.pressBack()

func pressHome()

public func pressHome(): Unit

Function: Returns the device to the home screen.

System Capability: SystemCapability.Test.UiTest

Since: 22

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.pressHome()

func screenCap(String)

public func screenCap(savePath: String): Bool

Function: The Driver object captures the current screen and saves it as a PNG image to the path specified by the parameter.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
savePath	String	Yes	-	File save path.

Return Value:

Type	Description
Bool	Whether the screenshot operation was successfully completed. true: successful; false: failed.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.screenCap("/data/storage/el2/base/cache/1.png")

func screenCapture(String, Rect)

public func screenCapture(savePath: String, rect!: Rect = Rect(0,0,0,0)): Bool

Function: Captures the current screen and saves it as a PNG image to the path specified by the parameter.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
savePath	String	Yes	-	File save path.
rect	Rect	No	Rect(0, 0, 0, 0)	Named parameter. Screenshot area, defaults to full screen.

Return Value:

Type	Description
Bool	Whether the screenshot operation was successfully completed. true: successful; false: failed.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.screenCapture("/data/storage/el2/base/cache/1.png", rect: Rect(0, 0, 100, 100))

func setDisplayRotation(DisplayRotation)

public func setDisplayRotation(rotation: DisplayRotation): Unit

Function: Sets the device's screen display orientation to the specified display orientation.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
rotation	DisplayRotation	Yes	-	The device's display orientation.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.setDisplayRotation(DisplayRotation.Rotation180)

func setDisplayRotationEnabled(Bool)

public func setDisplayRotationEnabled(enabled: Bool): Unit

Function: Enables or disables the device's screen rotation functionality.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
enabled	Bool	Yes	-	Flag indicating whether screen rotation is enabled. true: enabled; false: disabled.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.setDisplayRotationEnabled(false)

func swipe(Int32, Int32, Int32, Int32, Int32)

public func swipe(
    startx: Int32,
    starty: Int32,
    endx: Int32,
    endy: Int32,
    speed!: Int32 = 600
): Unit

Function: The Driver object performs a swipe operation from the starting coordinates to the destination coordinates.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
startx	Int32	Yes	-	The x-coordinate of the starting point, passed as Int32.
starty	Int32	Yes	-	The y-coordinate of the starting point, passed as Int32.
endx	Int32	Yes	-	The x-coordinate of the destination point, passed as Int32.
endy	Int32	Yes	-	The y-coordinate of the destination point, passed as Int32.
speed	Int32	No	600	Named parameter. Swipe speed, range: 200-15000. If out of range, the default value 600 is used. Unit: pixels/second.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.swipe(100, 100, 200, 200, speed: 600)

func triggerCombineKeys(Int32, Int32, Int32)

public func triggerCombineKeys(key0: Int32, key1: Int32, key2!: Int32 = 0): Unit

Function: The Driver object finds and clicks the corresponding key combination based on the given key values. For example, when the Key values are (2072, 2019), the Driver object finds and clicks the corresponding key combination, such as CTRL+C.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
key0	Int32	Yes	-	The first specified key value.
key1	Int32	Yes	-	The second specified key value.
key2	Int32	No	0	Named parameter. The third specified key value.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
driver.triggerCombineKeys(2072, 2047, key2: 2035)

func triggerKey(Int32)

public func triggerKey(keyCode: Int32): Unit

Function: The Driver object simulates pressing the corresponding key by passing in a key value.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
keyCode	Int32	Yes	-	The specified key value.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  | Error Code ID | Error Message | | :## class On

public class On {
    public init()
}

Function: In the UiTest framework, the On class provides rich control feature description APIs for filtering controls to match or locate target controls.

The APIs provided by On have the following characteristics:

1. Supports single-attribute matching and multi-attribute combination matching, such as simultaneously specifying the target control's text and id.

2. Control attributes support multiple matching patterns.

3. Supports absolute positioning and relative positioning of controls. APIs like isBefore and isAfter can be used to define adjacent control features for auxiliary positioning.

System Capability: SystemCapability.Test.UiTest

Since: 22

init()

public init()

Function: Creates an On instance.

System Capability: SystemCapability.Test.UiTest

Since: 22

func checkable(Bool)

public func checkable(b!: Bool = true): On

Function: Specifies the checkable state attribute of the target control and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
b	Bool	No	true	Named parameter. Specifies whether the control can be checked. true: checkable, false: not checkable. Default is false.

Return Value:

Type	Description
On	Returns the On object with the specified checkable state attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest error codes and universal error codes.

  Error Code ID	Error Message
  401	Parameter error. 1. Incorrect parameter types; 2. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().checkable(b: true) // Specifies the checkable state attribute of the target control.
    }
}

func checked(Bool)

public func checked(b!: Bool = true): On

Function: Specifies the checked state attribute of the target control and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
b	Bool	No	true	Named parameter. Specifies the checked state of the control. true: checked, false: unchecked. Default is false.

Return Value:

Type	Description
On	Returns the On object with the specified checked state attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest error codes and universal error codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().checked(b: true) // Specifies the checked state attribute of the target control.
    }
}

func clickable(Bool)

public func clickable(b!: Bool = true): On

Function: Specifies the clickable state attribute of the target control and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
b	Bool	No	true	Named parameter. Specifies the clickable state of the control. true: clickable, false: not clickable. Default is true.

Return Value:

Type	Description
On	Returns the On object with the specified clickable state attribute of the target control.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().clickable(b: true) // Specifies the clickable state attribute of the target control.
    }
}

func description(String, MatchPattern)

public func description(val: String, pattern!: MatchPattern = MatchPattern.Equals): On

Function: Specifies the description attribute of the target control, supporting multiple matching patterns, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
val	String	Yes	-	The description attribute of the control.
pattern	MatchPattern	No	MatchPattern.Equals	Named parameter. Specifies the text matching pattern. Default is EQUALS.

Return Value:

Type	Description
On	Returns the On object with the specified control type attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest error codes and universal error codes.

  Error Code ID	Error Message
  401	if the input parameters are invalid.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().description("123") // Specifies the control type attribute of the target control.
    }
}

func enabled(Bool)

public func enabled(b!: Bool = true): On

Function: Specifies the enabled state attribute of the target control and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
b	Bool	No	true	Named parameter. Specifies the enabled state of the control. true: enabled, false: disabled. Default is true.

Return Value:

Type	Description
On	Returns the On object with the specified enabled state attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest error codes and universal error codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().enabled(b: true) // Specifies the enabled state attribute of the target control.
    }
}

func focused(Bool)

public func focused(b!: Bool = true): On

Function: Specifies the focused state attribute of the target control and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
b	Bool	No	true	Named parameter. Specifies the focused state of the control. true: focused, false: not focused. Default is true.

Return Value:

Type	Description
On	Returns the On object with the specified focused state attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest error codes and universal error codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().focused(b: true) // Specifies the focused state attribute of the target control.
    }
}

func id(String)

public func id(id: String): On

Function: Specifies the id attribute of the target control and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
id	String	Yes	-	The id value of the specified control.

Return Value:

Type	Description
On	Returns the On object with the specified id attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest error codes and universal error codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().id("123") // Specifies the id attribute of the target control.
    }
}
```### func inWindow(String)

```cangjie
public func inWindow(bundleName: String): On

Function: Specifies that the target control is within the given application window, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
bundleName	String	Yes	-	The package name of the application window.

Return Value:

Type	Description
On	Returns the On object specifying that the target control is within the given application window.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().inWindow("com.uitestScene.acts") // Specifies that the target control is within the given application window.
    }
}

func isAfter(On)

public func isAfter(on: On): On

Function: Specifies that the target control is located after the given characteristic attribute control, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
on	On	Yes	-	The attribute requirements of the characteristic control.

Return Value:

Type	Description
On	Returns the On object specifying that the target control is located after the given characteristic attribute control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on1: On = On().text("123") // Specifies the characteristic attribute control
        let on2: On = On().onType("Text").isAfter(on1)  // Finds the first Text component after the control with text "123"
    }
}

func isBefore(On)

public func isBefore(on: On): On

Function: Specifies that the target control is located before the given characteristic attribute control, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
on	On	Yes	-	The attribute requirements of the characteristic control.

Return Value:

Type	Description
On	Returns the On object specifying that the target control is located before the given characteristic attribute control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on1: On = On().text("123") // Specifies the characteristic attribute control
        let on2: On = On().onType("Button").isBefore(on1)  // Finds the first Button component before the control with text "123"
    }
}

func longClickable(Bool)

public func longClickable(b!: Bool = true): On

Function: Specifies the long-clickable state attribute of the target control, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
b	Bool	No	true	Named parameter. Specifies the long-clickable state of the control: true for long-clickable, false for non-long-clickable. Default is true.

Return Value:

Type	Description
On	Returns the On object specifying the long-clickable state attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().longClickable(b: true) // Specifies the long-clickable state attribute of the target control.
    }
}

func onType(String)

public func onType(tp: String): On

Function: Specifies the control type attribute of the target control, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
tp	String	Yes	-	Specifies the control type.

Return Value:

Type	Description
On	Returns the On object specifying the control type attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().onType("Button") // Specifies the control type attribute of the target control.
    }
}

func scrollable(Bool)

public func scrollable(b!: Bool = true): On

Function: Specifies the scrollable state attribute of the target control, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
b	Bool	No	true	Named parameter. Specifies the scrollable state of the control: true for scrollable, false for non-scrollable. Default is true.

Return Value:

Type	Description
On	Returns the On object specifying the scrollable state attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().scrollable(b: true) // Specifies the scrollable state attribute of the target control.
    }
}

func selected(Bool)

public func selected(b!: Bool = true): On

Function: Specifies the selected state attribute of the target control, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
b	Bool	No	true	Named parameter. Specifies the selected state of the control: true for selected, false for unselected. Default is true.

Return Value:

Type	Description
On	Returns the On object specifying the selected state attribute of the target control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().selected(b: true) // Specifies the selected state attribute of the target control.
    }
}

func text(String, MatchPattern)

public func text(txt: String, pattern!: MatchPattern = MatchPattern.Equals): On

Function: Specifies the text attribute of the target control, supporting multiple matching patterns, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
txt	String	Yes	-	Specifies the control text for matching the target control text.
pattern	MatchPattern	No	MatchPattern.Equals	Named parameter. Specifies the text matching pattern. Default is EQUALS.

Return Value:

Type	Description
On	Returns the On object specifying the text attribute of the target control.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on: On = On().text("123") // Specifies the text attribute of the target control.
    }
}

func within(On)

public func within(on: On): On

Function: Specifies that the target control is within the given characteristic attribute control, and returns the On object itself.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
on	On	Yes	-	The attribute requirements of the characteristic control.

Return Value:

Type	Description
On	Returns the On object specifying that the target control is within the given characteristic attribute control.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

//example_test.cj

import kit.TestKit.*

@Test
class TestExample00 {
    @TestCase
    func test00(): Unit {
        unittest()
    }
    @TestCase
    func test01(): Unit {
        let on1: On = On().onType("Scroll") // Specifies the characteristic attribute control
        let on2: On = On().text("123").within(on1) // Finds the child component with text "123" within the Scroller
    }
}
```## class Point

```cangjie
public class Point {
    public var x: Int32
    public var y: Int32
    public var displayId:?Int32
    public init(x: Int32, y: Int32, displayId!: ?Int32 = None)
}

Function: Coordinate point information.

System Capability: SystemCapability.Test.UiTest

Since: 22

var displayId

public var displayId:?Int32

Function: The screen ID to which the coordinate point belongs.

Type: ?Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var x

public var x: Int32

Function: The x-coordinate of the point.

Type: Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var y

public var y: Int32

Function: The y-coordinate of the point.

Type: Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

init(Int32, Int32, ?Int32)

public init(x: Int32, y: Int32, displayId!: ?Int32 = None)

Function: Creates a Point instance.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
x	Int32	Yes	-	The x-coordinate of the point.
y	Int32	Yes	-	The y-coordinate of the point.
displayId	?Int32	No	None	Named parameter. The screen ID to which the coordinate point belongs. Valid values: integers greater than or equal to 0.

class PointerMatrix

public class PointerMatrix {}

Function: Used for multi-touch operations, storing a two-dimensional array of coordinate points for each finger and actions for each step.

System Capability: SystemCapability.Test.UiTest

Since: 22

static func create(Int32, Int32)

public static func create(fingers: Int32, steps: Int32): PointerMatrix

Function: A static method that constructs a PointerMatrix object and returns it.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
fingers	Int32	Yes	-	The number of fingers to inject in the multi-touch operation. Valid range: [1,10].
steps	Int32	Yes	-	The number of steps for each finger operation. Valid range: [1,1000].

Return Value:

Type	Description
PointerMatrix	Returns the constructed PointerMatrix object.

Exceptions:

• BusinessException: Corresponding error codes are listed below. See Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*

let pointerMatrix: PointerMatrix = PointerMatrix.create(2, 3)

func setPoint(Int32, Int32, Point)

public func setPoint(finger: Int32, step: Int32, point: Point): Unit

Function: Sets the coordinate point for the specified finger and step action in the PointerMatrix object.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
finger	Int32	Yes	-	The index of the finger.
step	Int32	Yes	-	The index of the step.
point	Point	Yes	-	The coordinate point for this action.

Exceptions:

• BusinessException: Corresponding error codes are listed below. See Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example:

// index.cj

import kit.TestKit.*
import ohos.ui_test.Point as PT

let pointerMatrix: PointerMatrix = PointerMatrix.create(2, 3)
pointerMatrix.setPoint(0, 0, PT(230, 480))
pointerMatrix.setPoint(0, 1, PT(250, 380))
pointerMatrix.setPoint(0, 2, PT(270, 280))
pointerMatrix.setPoint(1, 0, PT(230, 680))
pointerMatrix.setPoint(1, 1, PT(240, 580))
pointerMatrix.setPoint(1, 2, PT(250, 480))

class Rect

public class Rect {
    public var left: Int32
    public var top: Int32
    public var right: Int32
    public var bottom: Int32
    public var displayId:?Int32
    public init(left: Int32, top: Int32, right: Int32, bottom: Int32, displayId!: ?Int32 = None)
}

Function: Border information of a control.

System Capability: SystemCapability.Test.UiTest

Since: 22

var bottom

public var bottom: Int32

Function: The Y-coordinate of the bottom-right corner of the control's border.

Type: Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var displayId

public var displayId:?Int32

Function: The screen ID to which the control's border belongs.

Type: ?Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var left

public var left: Int32

Function: The X-coordinate of the top-left corner of the control's border.

Type: Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var right

public var right: Int32

Function: The X-coordinate of the bottom-right corner of the control's border.

Type: Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var top

public var top: Int32

Function: The Y-coordinate of the top-left corner of the control's border.

Type: Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

init(Int32, Int32, Int32, Int32, ?Int32)

public init(left: Int32, top: Int32, right: Int32, bottom: Int32, displayId!: ?Int32 = None)

Function: Creates a Rect instance.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
left	Int32	Yes	-	The X-coordinate of the top-left corner of the control's border.
top	Int32	Yes	-	The Y-coordinate of the top-left corner of the control's border.
right	Int32	Yes	-	The X-coordinate of the bottom-right corner of the control's border.
bottom	Int32	Yes	-	The Y-coordinate of the bottom-right corner of the control's border.
displayId	?Int32	No	None	Named parameter. The screen ID to which the control's border belongs. Valid values: integers greater than or equal to 0.

class UIElementInfo

public class UIElementInfo {
    public let bundleName: String
    public let componentType: String
    public let text: String
}

Function: Information related to UI events.

System Capability: SystemCapability.Test.UiTest

Since: 22

let bundleName

public let bundleName: String

Function: The package name of the application to which the element belongs.

Type: String

Access: Read-only

System Capability: SystemCapability.Test.UiTest

Since: 22

let componentType

public let componentType: String

Function: The type of the control or window.

Type: String

Access: Read-only

System Capability: SystemCapability.Test.UiTest

Since: 22

let text

public let text: String

Function: The text information of the control or window.

Type: String

Access: Read-only

System Capability: SystemCapability.Test.UiTest

Since: 22

class UIEventObserver

public class UIEventObserver {}

Function: UI event observer.

System Capability: SystemCapability.Test.UiTest

Since: 22

func once(OnceType, Callback<UIElementInfo>)

public func once(onceType: OnceType, callback: Callback<UIElementInfo>): Unit

Function: Listens for the event when a specified control appears.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
onceType	OnceType	Yes	-	The type of the control.
callback	Callback<UIElementInfo>	Yes	-	The callback function to be executed when the event occurs.

Exceptions:

• BusinessException: Corresponding error codes are listed below. See Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

public class UiWindow {}

Description: UiWindow represents a window in the UI interface, providing capabilities to obtain window properties, drag windows, resize windows, etc.

System Capability: SystemCapability.Test.UiTest

Since: 22

func close()

public func close(): Unit

Description: Closes the window.

System Capability: SystemCapability.Test.UiTest

Device behavior difference: For API version 22, this API can be called normally on PC and Tablet devices, and returns error code 17000005 on other devices. Starting from API version 23, this API can be called normally on Phone, PC, and Tablet devices, and returns error code 17000005 on other devices.

Since: 22

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.
  17000005	This operation is not supported.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
window?.close()

func focus()

public func focus(): Unit

Description: Sets focus to the window.

Note: This API can be called normally on PC/2-in-1 and Tablet devices. On other devices, it returns error code 17000005.

System Capability: SystemCapability.Test.UiTest

Since: 22

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
window?.focus()

func getBounds()

public func getBounds(): Rect

Description: Obtains the border information of the window.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Rect	Returns the border information of the window.

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
let rect = window?.getBounds()

func getBundleName()

public func getBundleName(): String

Description: Obtains the package name of the application to which the window belongs.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
String	Returns the package name of the application to which the window belongs.

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
let rect = window?.getBundleName()

func getTitle()

public func getTitle(): String

Description: Obtains the title of the window.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
String	Returns the title of the window.

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
let title: Option<String> = window?.getTitle()

func getWindowMode()

public func getWindowMode(): WindowMode

Description: Obtains the window mode of the window.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
WindowMode	Returns the window mode of the window.

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
let mode = window?.getWindowMode()

func isActive()

public func isActive(): Bool

Description: Checks whether the window is the one currently interacting with the user.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Returns the interaction status of the window object. true: interactive window; false: non-interactive window.

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
let active = window?.isActive()

func isFocused()

public func isFocused(): Bool

Description: Checks whether the window is in focus.

System Capability: SystemCapability.Test.UiTest

Since: 22

Return Value:

Type	Description
Bool	Returns whether the window object is in focus. true: focused; false: not focused.

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
let focused = window?.isFocused()

func maximize()

public func maximize(): Unit

Description: Maximizes the window. This applies to windows that support the maximize operation.

System Capability: SystemCapability.Test.UiTest

Device behavior difference: For API version 22, this API can be called normally on PC and Tablet devices, and returns error code 17000005 on other devices. Starting from API version 23, this API can be called normally on Phone, PC, and Tablet devices, and returns error code 17000005 on other devices.

Since: 22

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.
  17000005	This operation is not supported.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
window?.maximize()

func minimize()

public func minimize(): Unit

Description: Minimizes the window. This applies to windows that support the minimize operation.

System Capability: SystemCapability.Test.UiTest

Device behavior difference: For API version 22, this API can be called normally on PC and Tablet devices, and returns error code 17000005 on other devices. Starting from API version 23, this API can be called normally on Phone, PC, and Tablet devices, and returns error code 17000005 on other devices.

Since: 22

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.
  17000005	This operation is not supported.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
window?.minimize()

func moveTo(Int32, Int32)

public func moveTo(x: Int32, y: Int32): Unit

Description: Moves the window to the target point. This applies to windows that support movement.

System Capability: SystemCapability.Test.UiTest

Device behavior difference: For API version 22, this API can be called normally on PC and Tablet devices, and returns error code 17000005 on other devices. Starting from API version 23, this API can be called normally on Phone, PC, and Tablet devices, and returns error code 17000005 on other devices.

Since: 22

Parameters:

Parameter	Type	Mandatory	Default Value	Description
x	Int32	Yes	-	The x-coordinate of the target point in IntNative format.
y	Int32	Yes	-	The y-coordinate of the target point in IntNative format.

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
  17000004	The window or component is invisible or destroyed.
  17000005	This operation is not supported.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
window?.moveTo(100, 100)

func resize(Int32, Int32, ResizeDirection)

public func resize(wide: Int32, height: Int32, direction: ResizeDirection): Unit

Description: Resizes the window based on the specified width, height, and resize direction. This applies to windows that support resizing.

System Capability: SystemCapability.Test.UiTest

Device behavior difference: For API version 22, this API can be called normally on PC and Tablet devices, and returns error code 17000005 on other devices. Starting from API version 23, this API can be called normally on Phone, PC, and Tablet devices, and returns error code 17000005 on other devices.

Since: 22

Parameters:

Parameter	Type	Mandatory	Default Value	Description
wide	Int32	Yes	-	The width of the resized window in IntNative format.
height	Int32	Yes	-	The height of the resized window in IntNative format.
direction	ResizeDirection	Yes	-	The resize direction of the window in ResizeDirection format.

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
  17000004	The window or component is invisible or destroyed.
  17000005	This operation is not supported.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
window?.resize(100, 100, ResizeDirection.Left)

func resume()

public func resume(): Unit

Description: Restores the window to its previous window mode.

System Capability: SystemCapability.Test.UiTest

Device behavior difference: For API version 22, this API can be called normally on PC and Tablet devices, and returns error code 17000005 on other devices. Starting from API version 23, this API can be called normally on Phone, PC, and Tablet devices, and returns error code 17000005 on other devices.

Since: 22

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.
  17000005	This operation is not supported.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
window?.resume()

func split()

public func split(): Unit

Description: Switches the window to split-screen mode. This applies to windows that support switching to split-screen mode.

System Capability: SystemCapability.Test.UiTest

Device behavior difference: For API version 22, this API can be called normally on PC and Tablet devices, and returns error code 17000005 on other devices. Starting from API version 23, this API can be called normally on Phone, PC, and Tablet devices, and returns error code 17000005 on other devices.

Since: 22

Exceptions:

• BusinessException: Error codes are listed in the table below. For details, see uitest Error Codes and Universal Error Codes.

  Error Code ID	Error Message
  17000004	The window or component is invisible or destroyed.
  17000005	This operation is not supported.

Example:

// index.cj

import kit.TestKit.*

let driver: Driver = Driver.create()
let window: Option<UiWindow> = driver.findWindow(WindowFilter(active: true))
window?.split()
```## class WindowFilter

```cangjie
public class WindowFilter {
    public var bundleName:?String
    public var title:?String
    public var focused:?Bool
    public var active:?Bool
    public var displayId:?Int32
    public init(bundleName!: ?String = None, title!: ?String = None, focused!: ?Bool = None, active!: ?Bool = None, displayId!: ?Int32 = None)
}

Function: Window attribute information.

System Capability: SystemCapability.Test.UiTest

Since: 22

var active

public var active:?Bool

Function: Whether the window is interacting with the user.

Type: ?Bool

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var bundleName

public var bundleName:?String

Function: Package name of the application to which the window belongs.

Type: ?String

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var displayId

public var displayId:?Int32

Function: Screen ID to which the control border belongs.

Type: ?Int32

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var focused

public var focused:?Bool

Function: Whether the window is in focused state.

Type: ?Bool

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

var title

public var title:?String

Function: Title information of the window.

Type: ?String

Access: Read-write

System Capability: SystemCapability.Test.UiTest

Since: 22

init(?String, ?String, ?Bool, ?Bool, ?Int32)

public init(bundleName!: ?String = None, title!: ?String = None, focused!: ?Bool = None, active!: ?Bool = None, displayId!: ?Int32 = None)

Function: Creates a WindowFilter instance.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parameters:

Name	Type	Mandatory	Default	Description
bundleName	?String	No	None	Named parameter. Package name of the application to which the window belongs.
title	?String	No	None	Named parameter. Title information of the window.
focused	?Bool	No	None	Named parameter. Whether the window is in focused state.
active	?Bool	No	None	Named parameter. Whether the window is interacting with the user.
displayId	?Int32	No	None	Named parameter. Screen ID to which the control border belongs, must be an integer greater than or equal to 0.

enum DisplayRotation

public enum DisplayRotation {
    | Rotation0
    | Rotation90
    | Rotation180
    | Rotation270
    | ...
}

Function: Display orientation of the device screen.

System Capability: SystemCapability.Test.UiTest

Since: 22

Rotation0

Rotation0

Function: The device screen is not rotated, initially displayed vertically.

System Capability: SystemCapability.Test.UiTest

Since: 22

Rotation180

Rotation180

Function: The device screen is rotated 180° clockwise, displayed vertically in reverse.

System Capability: SystemCapability.Test.UiTest

Since: 22

Rotation270

Rotation270

Function: The device screen is rotated 270° clockwise, displayed horizontally in reverse.

System Capability: SystemCapability.Test.UiTest

Since: 22

Rotation90

Rotation90

Function: The device screen is rotated 90° clockwise, displayed horizontally.

System Capability: SystemCapability.Test.UiTest

Since: 22

enum MatchPattern

public enum MatchPattern {
    | Equals
    | Contains
    | StartsWith
    | EndsWith
    | ...
}

Function: Supported matching patterns for control properties.

System Capability: SystemCapability.Test.UiTest

Since: 22

Contains

Contains

Function: Contains the given value.

System Capability: SystemCapability.Test.UiTest

Since: 22

EndsWith

EndsWith

Function: Ends with the given value.

System Capability: SystemCapability.Test.UiTest

Since: 22

Equals

Equals

Function: Equals the given value.

System Capability: SystemCapability.Test.UiTest

Since: 22

StartsWith

StartsWith

Function: Starts with the given value.

System Capability: SystemCapability.Test.UiTest

Since: 22

enum MouseButton

public enum MouseButton {
    | MouseButtonLeft
    | MouseButtonRight
    | MouseButtonMiddle
    | ...
}

Function: Simulated mouse button for injection.

System Capability: SystemCapability.Test.UiTest

Since: 22

MouseButtonLeft

MouseButtonLeft

Function: Left mouse button.

System Capability: SystemCapability.Test.UiTest

Since: 22

MouseButtonMiddle

MouseButtonMiddle

Function: Middle mouse button.

System Capability: SystemCapability.Test.UiTest

Since: 22

MouseButtonRight

MouseButtonRight

Function: Right mouse button.

System Capability: SystemCapability.Test.UiTest

Since: 22

enum OnceType

public enum OnceType <: Equatable<OnceType> & ToString {
    | ToastShow
    | DialogShow
    | ...
}

Function: Type of the control.

System Capability: SystemCapability.Test.UiTest

Since: 22

Parent Types:

• Equatable<OnceType>
• ToString

DialogShow

DialogShow

Function: Dialog control type.

System Capability: SystemCapability.Test.UiTest

Since: 22

ToastShow

ToastShow

Function: Toast control type.

System Capability: SystemCapability.Test.UiTest

Since: 22

func !=(OnceType)

public operator func !=(other: OnceType): Bool

Function: Determines whether two enum values are not equal.

Parameters:

Name	Type	Mandatory	Default	Description
other	OnceType	Yes	-	Another enum value.

Return Value:

Type	Description
Bool	Returns true if the two enum values are not equal, otherwise returns false.

func ==(OnceType)

public operator func ==(other: OnceType): Bool

Function: Determines whether two enum values are equal.

Parameters:

Name	Type	Mandatory	Default	Description
other	OnceType	Yes	-	Another enum value.

Return Value:

Type	Description
Bool	Returns true if the two enum values are equal, otherwise returns false.

func toString()

public func toString(): String

Function: Gets the value of the enum.

Return Value:

Type	Description
String	Description of the enum.

public enum ResizeDirection {
    | Left
    | Right
    | Up
    | Down
    | LeftUp
    | LeftDown
    | RightUp
    | RightDown
    | ...
}

Function: Direction for window resizing.

System Capability: SystemCapability.Test.UiTest

Since: 22

Down

Down

Function: Downward direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

Left

Left

Function: Leftward direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

LeftDown

LeftDown

Function: Lower-left direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

LeftUp

LeftUp

Function: Upper-left direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

Right

Right

Function: Rightward direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

RightDown

RightDown

Function: Lower-right direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

RightUp

RightUp

Function: Upper-right direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

Up

Up

Function: Upward direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

enum UiDirection

public enum UiDirection {
    | Left
    | Right
    | Up
    | Down
    | ...
}

Function: Direction for UI operations such as flicking and sliding.

System Capability: SystemCapability.Test.UiTest

Since: 22

Down

Down

Function: Downward direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

Left

Left

Function: Leftward direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

Right

Right

Function: Rightward direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

Up

Up

Function: Upward direction.

System Capability: SystemCapability.Test.UiTest

Since: 22

enum WindowMode

public enum WindowMode {
    | Fullscreen
    | Primary
    | Secondary
    | Floating
    | ...
}

Function: Window display mode.

System Capability: SystemCapability.Test.UiTest

Since: 22

Floating

Floating

Function: Floating window mode.

System Capability: SystemCapability.Test.UiTest

Since: 22

Fullscreen

Fullscreen

Function: Full-screen mode.

System Capability: SystemCapability.Test.UiTest

Since: 22

Primary

Primary

Function: Primary window mode.

System Capability: SystemCapability.Test.UiTest

Since: 22

Secondary

Secondary

Function: Secondary window mode.

System Capability: SystemCapability.Test.UiTest

Since: 22