Common Control Methods

The following introduces the basic operation and property methods shared by all controls (except virtual controls). These methods apply regardless of the specific type of control. Some methods simulate user operations, while others complete operations based on the underlying Accessibility API.

Type Definitions

These methods are all written on the base class of controls. You can click on the leanpro.atk library to view them. The definitions are as follows:

export interface IAtControl extends IAtContainer {
    click(x?: number, y?: number, mousekey?: number): Promise<void>;
    dblClick(x?: number, y?: number, mousekey?: number): Promise<void>;
    exists(seconds?: number): Promise<boolean>;
    moveMouse(x?: number, y?: number): Promise<void>;
    wheel(value: number): Promise<void>;
    pressKeys(keys: string, opt?: PressKeysOptions): Promise<void>;
    rect(): Promise<Rect>;
    highlight(milliseconds?: number);
    takeScreenshot(filePath?: string): Promise<void | string>;
    modelProperties(all?: boolean): {[x: string]: any};
    modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string | Buffer>;  //base64 is the default
    allProperties(): Promise<object>;
    property(propertyName: string): Promise<string | number | boolean | Rect>;
    checkProperty(propertyName: string, expectedValue: string | number | boolean | RegExp, message: string): Promise<void>;
    checkProperty(propertyName: string, expectedValue: string | number | boolean | RegExp, options: {message: string, operation: any}): Promise<void>;
    waitProperty(propertyName: string, value: string | number | boolean, timeOutSeconds?: number): Promise<boolean>
    firstChild(controlType?: AtControlType): Promise<IAtControl>;
    lastChild(controlType?: AtControlType): Promise<IAtControl>;
    next(controlType?: AtControlType): Promise<IAtControl>;
    previous(controlType?: AtControlType): Promise<IAtControl>;
    parent(): Promise<IAtControl>;
    name(): Promise<string>;
    enabled(): Promise<boolean>;
    visible(): Promise<boolean>;
    processId(): Promise<number>;
}

class AtControl(AtContainer):
	def click(x: Optional[int]=None, y: Optional[int]=None, mouseKey: Optional[int]=None) -> None
	def dblClick(x: Optional[int]=None, y: Optional[int]=None, mouseKey: Optional[int]=None) -> None
	def exists(seconds: Optional[int]=None) -> bool
	def moveMouse(x: Optional[int]=None, y: Optional[int]=None) -> None
	def wheel(value: int) -> None
	def pressKeys(keys: str, cpm: Optional[int]=None) -> None
	def rect() -> Rect
	def highlight(milliseconds: Optional[int]=None) -> None
	def takeScreenshot(filePath: Optional[str]=None) -> Union[str, None]
	def focus() -> None
	def modelProperties(all: Optional[bool]=None) -> { [x: string]: any; }
	def modelImage(encoding: Optional[str]=None) -> Union[str, bytearray]
	def allProperties() -> TypedDict
	def property(propertyName: str) -> Union[str, int, bool, Rect]
	def checkProperty(propertyName: str, expectedValue: Union[str, int, bool], optionsOrMessage: Optional[Union[str, TypedDict]]=None) -> None
	def waitProperty(propertyName: str, value: Union[str, int, bool], timeOutSeconds: Optional[int]=None) -> bool
	def firstChild(controlType: Optional[str]=None) -> AtControl
	def lastChild(controlType: Optional[str]=None) -> AtControl
	def next(controlType: Optional[str]=None) -> AtControl
	def previous(controlType: Optional[str]=None) -> AtControl
	def parent() -> AtControl
	def name() -> str
	def enabled() -> bool
	def visible() -> bool
	def processId() -> int

Operation Methods

click(x, y, mouseKey)

Simulates a mouse click on the control. You can modify the click position and mouse button used by passing parameters.

Parameters:

• x: number type, horizontal pixel position relative to the control's top-left corner. 0 represents the horizontal center of the control. Default value is 0.
• y: number type, vertical pixel position relative to the control's top-left corner. 0 represents the vertical center of the control. Default value is 0.
• mouseKey: MouseKey type, the mouse button to use. Default is 1, which is the left mouse button.

Return Value:

• Asynchronous method that returns no value.

Usage Example

The simplest way to call this is without any parameters, clicking the center of the control:

await model.getButton("Button").click();

model.getButton("Button").click()

If you need to click a specific coordinate position on the control, you can pass the horizontal pixel value (x) and vertical pixel value (y) relative to the control's top-left corner:

await model.getButton("Button").click(590, 10);

model.getButton("Button").click(590, 10)

Note: click(0, 0) will not click the top-left corner of the control, but rather the center; if you want to click the top-left corner, use click(1, 1).

If you need to right-click the control, you need to pass a third parameter and set it to 2:

await model.getButton("Button").click(590, 10, 2)

model.getButton("Button").click(590, 10, 2)

dblClick(x, y, mouseKey)

Simulates a mouse double-click on the control. Called in the same way as the click() method.

Parameters:

• x: number type, horizontal pixel position for the double-click relative to the control's top-left corner. Default value is 0.
• y: number type, vertical pixel position for the double-click relative to the control's top-left corner. Default value is 0.
• mouseKey: MouseKey type, the mouse button to use. Default is 1.

Return Value:

• Asynchronous method that returns no value.

Usage Example

Double-click the center of the control:

await model.getButton("Button").dblClick();

model.getButton("Button").dblClick()

moveMouse(x, y, seconds)

Moves the mouse cursor to a specified position on the control.

Parameters:

• x: number type, horizontal pixel position to move to, relative to the control's top-left corner. Default value is 0.
• y: number type, vertical pixel position to move to, relative to the control's top-left corner. Default value is 0.
• seconds: number type, duration of the mouse movement in seconds.

Return Value:

• Asynchronous method that returns no value.

Usage Example

Move the mouse to the center of the control:

await model.getPane("Pane").moveMouse();

model.getPane("Pane").moveMouse()

If you need to move the mouse to a specific position on the control and control the speed:

await model.getPane("Pane").moveMouse(500, 70, 5);

model.getPane("Pane").moveMouse(500, 70, 5)

wheel(value)

Scrolls the mouse wheel. The input parameter is the number of wheel notches to scroll.

Parameters:

• value: number type, wheel notches.

Return Value:

• Asynchronous method that returns no value.

Usage Example

Scroll the mouse wheel up by one notch:

await model.getPane("Pane").wheel(1);

model.getPane("Pane").wheel(1)

exists(time)

This method is used to determine whether a control exists. You can specify a maximum wait time. If the control is found within the specified time, it returns true, otherwise it returns false.

Parameters:

• time: number type, maximum number of seconds to wait for the control to appear. If omitted, the default is 0 seconds, meaning it only checks once.

Return Value:

• Asynchronously returns whether the control exists, true if it exists, false if it doesn't.

Usage Example

1. Without specifying wait time

let exists = model.getButton("Button").exists();

exists = model.getButton("Button").exists()

This code will check immediately once. If the control is found, the value of exists is true, otherwise it's false.

1. With specified wait time

let bool = await model.getButton("Button").exists(10);
assert.strictEqual(bool, true);

bool = model.getButton("Button").exists(10)
assert bool == True

This code will wait for a maximum of 10 seconds. If the control is found within these 10 seconds, the value of bool is true, otherwise it's false.

pressKeys(keys, options?)

Implements string input or key combination operations by simulating keyboard signals. Therefore, it can be used not only for simple text input, but also for complex keyboard operations such as simulating login, navigation, cut, paste, etc.

Note that certain special characters in strings (such as ^+~%{}()) will be parsed as control keys (such as Shift, Ctrl) rather than as character input. For specific key commands, please refer to Appendix: Key Codes. If you want to input pure text and ignore these control key symbols, use the {textOnly: true} option like this: pressKeys(str, {textOnly: true}).

Parameters:

• key: string type, the key, key combination, or string to input. Maximum support for 1024 characters.

• options: PressKeysOptions | number (optional)
  Optional parameter to control input mode, containing the following:

  • textOnly: boolean type, when set to true, all characters are input as plain text, ignoring control key commands.
  • cpm: number type, characters per minute, used to control input speed. It's recommended to set cpm value above 200. Due to different systems and applications handling input speed differently, the actual input speed may differ from the set value.

  If a number is passed directly as options, that value will be treated as the cpm parameter.

Return Value:

• Asynchronous method that returns no value.

Usage Example

await model.getEdit("Edit").pressKeys("Hello, World!", { textOnly: true });

model.getEdit("Edit").pressKeys("Hello, World!", { "textOnly": True })

modelImage(options?: {encoding: 'buffer' | 'base64'})

Gets the cached screenshot snapshot of the control in the model. The returned image can be in Buffer format or base64 string.

Parameters:

• options: object type, specifies the format of the returned image:
  • encoding: string type, image format, value is 'buffer' or 'base64'.

Return Value:

• string type or Buffer type, asynchronously returns image data according to the specified options.encoding option. Default is string type.

Usage Example

Get the cached image of the control and store it as a base64 string:

let img = await model.getPane("Pane").modelImage({ encoding: 'base64' });

img = model.getPane("Pane").modelImage({ 'encoding': 'base64' })

modelProperties(all?: boolean): object

Gets all cached properties of the control in the model. The returned property key-value pairs will include property names and corresponding values.

Parameters:

• all: (optional) boolean type, whether to get all properties. Default is false, only gets identifying properties.

Return Value:

• Property object.

Usage Example

let properties = await model.getButton("Button").modelProperties();

properties = model.getButton("Button").modelProperties()

property(propertyIds)

Gets the specified property value of the control. You can get various properties of the control as needed, such as text, visibility, position, etc.

Parameters:

• propertyIds: PropertyIds type, the property name to get.

Return Value:

• Asynchronously returns property values of various types corresponding to the property name, including string, number, boolean, Rect types, etc., depending on propertyIds.

Usage Example

Get the text content of the control:

let text = await model.getButton("Button").property("text");

text = model.getButton("Button").property("text")

waitProperty(propertyIds, value, timeoutSeconds)

Waits for a specified property of the control to become a specific value. You can use it to determine whether the control's state meets expectations, such as waiting for a button to become enabled.

Parameters:

• propertyIds: PropertyIds type, the property name to wait for.
• value: string type, the property value to wait for.
• timeoutSeconds: number type, wait time in seconds. Default is 5 seconds, -1 will wait indefinitely.

Return Value:

• boolean type, wait result. true means successfully waited for the value, otherwise it exceeded the wait time. If an error is reported, it means the control was not matched, possibly because the control did not appear or there is a problem with the object name.

Usage Example

Wait for the control's text content to become "OK", waiting a maximum of 30 seconds:

let isReady = await model.getButton("Button").waitProperty("text", "OK", 30);

isReady = model.getButton("Button").waitProperty("text", "OK", 30)

checkProperty(propertyName, expectedValue, optionsOrMessage)

Validates whether the control's property value meets expectations. If the specified property value does not match the expected value, an error will be thrown.

You can quickly generate property check scripts based on this method during recording. For details, please refer to Adding Property Checkpoints During Recording.

Parameters:

• propertyName: string type, the name of the property to check. Supported property names include enabled, text, value, etc., as well as all fields returned by the allProperties() method.
• expectedValue: string | number | boolean | RegExp type, the expected property value. When the control's property value matches the expected value, the test will pass; otherwise, an error will be thrown.
• optionsOrMessage: string | object type, optional parameter. If it's a string, it will be used as a custom error message; if it's an object, it can contain the following fields:
  • message: string type, custom error message.
  • operation: any type, specifies the operator used to compare the control property with the expected value. Default value is equal, which verifies whether the property value equals the expected value.

Return Value:

• Asynchronous method that returns no value.

Usage Example

For examples of using regular expressions in checkProperty(), please refer to Checking with Regular Expressions.

Verify that the text property of a text box control is "Hello World":

await model.getEdit("textEdit").checkProperty('text', 'Hello World', 'Text does not match expected value');

model.getEdit("textEdit").checkProperty('text', 'Hello World', 'Text does not match expected value')

If the text does not meet expectations, an error will be thrown with the error message "Text does not match expected value".

highlight(duration)

Highlights the control for debugging and verification. You can pass in the duration of the highlight box (in milliseconds).

Parameters:

• duration: number type, duration of the highlight in seconds.

Return Value:

• Asynchronous method that returns no value.

Usage Example

Highlight the control for 2 seconds:

await model.getButton("Button").highlight(2);

model.getButton("Button").highlight(2)

takeScreenshot(filePath)

Takes a screenshot of the control. You can pass in a path to save the screenshot to that location.

Parameters:

• filePath: string type, the save path for the screenshot file, such as "./images/screenshot1.png".

Return Value:

• Asynchronously returns the screenshot as a base64 string.

Usage Example

The base64 encoded image returned by the takeScreenshot() method can be directly inserted as an image into the run report. For details, please refer to Report Attachments.

focus()

Sets focus to the control.

Usage Example

await model.getButton("Button").focus();

model.getButton("Button").focus()

Property Methods

Control property methods are all asynchronous. These methods communicate with the target control to get the control's real-time properties, not the identifying properties in the model object. The property methods listed below apply to all controls, but not every control supports all properties. It's recommended to try similar property methods based on specific needs to get the required information.

text()

The text content of the control, usually editable content. Controls such as text input boxes Edit, multi-line input boxes Document, etc. have this property. If the return value does not meet expectations, you can try the name() or value() property methods.

Return Value:

• Promise<string> type, asynchronously returns the text content of the control.

Usage Example

Get the text from a text editor and perform assertion validation

let actual = await model.getDocument("Text Editor").text();
let expected = 'Hello World!'
assert.equal(actual, expected);

actual_text = model.getDocument("Text Editor").text()
expected_text = 'Hello World!'
assert actual_text == expected_text

rect()

The bounding rectangle of the control, returns Rect type, containing the control's x, y, height, and width information, as defined in Rect type.

Return Value:

• Promise<Rect> type, asynchronously returns the rectangular boundary information of the control.

Usage Example

Get the rectangular information (position and size) of a Button control

let rect = await model.getButton("Button").rect();
console.log(`Button position: (${rect.x}, ${rect.y}) Size: ${rect.width}x${rect.height}`);

rect = model.getButton("Button").rect()
print(f"Button position: ({rect['x']}, {rect['y']}) Size: {rect['width']}x{rect['height']}")

name()

The name of the control. This name is usually consistent with the identifying property Name of the object in the Model Manager, so almost all controls have a value for this property. If the return value does not meet expectations, you can try the text() or value() property methods.

Return Value:

• Promise<string> type, asynchronously returns the name of the control.

Usage Example

Verify that the name of the first item in the list is correct:

let item = await model.getList("List").scrollTo(0);
assert.strictEqual(await item.name(), 'First Normal Item');

item = model.getList("List").scrollTo(0)
assert await item.name() == 'First Normal Item'

enabled()

Whether the control is enabled.

Return Value:

• Promise<boolean> type, asynchronously returns a boolean value indicating whether the control is enabled.

Usage Example

Check if a Button control is enabled, returns a boolean value

let isEnabled = await model.getButton("Button").enabled();
console.log(`Is Button control enabled: ${isEnabled}`);

is_enabled = model.getButton("Button").enabled()
print(f"Is Button control enabled: {is_enabled}")

focused()

Whether the control is focused/selected. Returns true when the control is selected, usually used to verify whether the control has been operated on.

Return Value:

• Promise<boolean> type, asynchronously returns a boolean value indicating whether the control is the current focus.

Usage Example

Determine if a text box has focus

let isFocused = await model.getEdit("TextBox").focused();
console.log(`Does the text box have focus: ${isFocused}`);

is_focused = model.getEdit("TextBox").focused()
print(f"Does the text box have focus: {is_focused}")

allProperties()

Gets all runtime properties of the target control, returned as an object. If you want to directly return the value of a specified property, refer to the property(propertyIds) method.

Return Value:

• Asynchronously returns an object composed of the properties of the target model object.

Usage Example

Get all properties of a Button control and output to console

let properties = await model.getButton("Button").allProperties();
console.log(properties);

properties = model.getButton("Button").allProperties()
print(properties)

This will get all properties of the button and print:

{
  "name": "New Project",
  "className": "push button",
  Rect: {"x":1695,"y":373,"width":127,"height":51},
  "states": "enabled,focusable,visible,showing",
  "interfaces": [
    "value",
    "action"
  ],
  "text": "",
  "Value": {"value":"0","maximum":"1","minimum":"0"},
  "Action": {
    "actions": [
      "Click"
    ]
  }
}

The interfaces field is used to return the pattern information of the control, helping users confirm the operations supported by the control.

Control Navigation Methods

CukeTest provides a series of control navigation methods to help users retrieve and operate interface elements in applications. Through these methods, you can locate a control's parent control, child controls, and sibling controls. They are suitable for scenarios that require traversing the control tree or precisely locating specific controls, such as input box positioning, batch operations, etc.

These navigation methods are asynchronous, meaning they will retrieve the target control in the application before returning results. Unlike navigating directly in the Model Manager tree, these methods perform actual retrieval at runtime.

firstChild()

Gets the first direct child control of the control. If the control has no child controls or the qualifying child control is not visible, this method will return null. If you want to get all controls under a control, you can use the findControls method.

Return Value:

• Asynchronously returns a control object, the specific type depends on the type of control navigated to. Returns null if no child control is found.

Usage Example

Get the first child control of a specified control:

let firstChild = await model.getPane("Pane").firstChild();

firstChild = model.getPane("Pane").firstChild()

lastChild()

Gets the last direct child control of the control.

Return Value:

• Asynchronously returns a control object, the specific type depends on the type of control navigated to. Returns null if no child control is found.

Usage Example

Get the last child control of a specified control:

let lastChild = await model.getPane("Pane").lastChild();

lastChild = model.getPane("Pane").lastChild()

next()

Gets the next sibling control of the control, usually the adjacent node to the right or below, depending on the container's layout direction. Returns null if there is no next sibling control.

Return Value:

• Asynchronously returns a control object, the specific type depends on the type of control navigated to. Returns null if no sibling control is found.

Usage Example

Get the next sibling control of a specified control:

let nextSibling = await model.getPane("Pane").next();

nextSibling = model.getPane("Pane").next()

previous()

Gets the previous sibling control of the control, usually the adjacent node to the left or above, depending on the container's layout direction. Returns null if there is no previous sibling control.

Return Value:

• Asynchronously returns a control object, the specific type depends on the type of control navigated to. Returns null if no sibling control is found.

Usage Example

Get the previous sibling control of a specified control:

let previousSibling = await model.getPane("Pane").previous();

previousSibling = model.getPane("Pane").previous()

parent()

Used to get the parent control of the control. Returns null if the control is a top-level control (has no parent control).

Return Value:

• Asynchronously returns a control object, the specific type depends on the type of control navigated to. Returns null if no parent control is found.

Usage Example

Get the parent control of a control:

let parentControl = await model.getPane("Pane").parent();

parentControl = model.getPane("Pane").parent()

findControls(...conditions: ConditionFilter[])

Finds controls based on conditions. Used to filter out a set of controls that meet a series of conditions. It accepts one or more ConditionFilter objects as parameters, which define the conditions for control filtering.

This method is suitable for scenarios where controls need to be retrieved from an application based on specific conditions. For example, on an interface with dynamic content, you may need to find all controls with specific properties or states. The findControls() method can dynamically identify and return these controls based on the conditions you provide. For detailed usage, see Container API.

Return Value:

• Asynchronously returns an array of control objects containing all controls that meet the conditions. Returns an empty array if no controls meeting the conditions are found.

Usage Example

Find controls based on conditions, for example, find all controls with type Button and className of Button:

let controls = await model.getPane("Pane").findControls({
   "type": "Button",
   "className": "Button"
});

controls = model.getPane("Pane").findControls({
   "type": "Button",
   "className": "Button"
})