Object Operation APIs

Windows object operation APIs are divided into two categories: commands and properties. Commands perform actual actions on controls, while properties retrieve runtime attributes of controls. Since control access is asynchronous, retrieving properties is also in the form of methods, meaning parentheses "()" are required when calling, and they return a Promise. In async functions, the actual value can be obtained by adding await.

Common APIs

Different types of objects have different commands and properties. However, they all share some common commands and properties, as follows:

JavaScript
Python
export interface IWinControl extends IWinContainer {
  //methods
	click(x?: number, y?: number, mousekey?: MouseKey): Promise<void>;
	dblClick(x?: number, y?: number, mousekey?: MouseKey): Promise<void>;
	moveMouse(x?: number, y?: number, seconds?: number): Promise<void>
	wheel(value: number): Promise<void>;
	exists(time?: number): Promise<boolean>;
	hScroll(value: number | ScrollAmount): Promise<void>;
	vScroll(value: number | ScrollAmount): Promise<void>;
	property(propertyIds: PropertyIds | string): Promise<string | boolean | number | Rect>;
	checkImage(options?: CompareOptions): Promise<void>;
	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(propertyIds: PropertyIds, value: string, timeoutSeconds?: number/* default value 5 seconds */): Promise<boolean>;
	drop(x?: number, y?: number, seconds?: number): Promise<void>;
	drag(x?: number, y?: number): Promise<void>;
	pressKeys(keys: string, opt?: PressKeysOptions | number): Promise<void>;
	takeScreenshot(filePath?: string): Promise<void | string>;
	highlight(duration?: number);

  //properties
	type(): Promise<string>;
	text(): Promise<string>;
	name(): Promise<string>;
	hwnd(): Promise<number>;
	x(): Promise<number>;
	y(): Promise<number>;
	height(): Promise<number>;
	width(): Promise<number>;
	enabled(): Promise<boolean>;
	focused(): Promise<boolean>;
	helpText(): Promise<string>;
	labeledText(): Promise<string>;
	value(): Promise<string | number>;
	processId(): Promise<number>;
	rect(): Promise<Rect>;
	visible(): Promise<boolean>;
  
	//navigation methods
	firstChild(controlType?: ControlType): Promise<IWinControl>;
	lastChild(controlType?: ControlType): Promise<IWinControl>;
	next(controlType?: ControlType): Promise<IWinControl>;
	previous(controlType?: ControlType): Promise<IWinControl>;
	parent(): Promise<IWinControl>;
	all(): Promise<IWinControl[]>;
	findControls(...conditions: ConditionFilter[]): Promise<IWinControl[]>; //used to be getControls
	
	modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string | Buffer>;  //base64 is the default
	modelProperties(all?: boolean): {[x: string]: any};
	allProperties(): Promise<object>;
	doDefaultAction(): Promise<void>;
	rawText(): Promise<string>
}
class WinControl(WinContainer):
	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 moveMouse(x: Optional[int]=None, y: Optional[int]=None, seconds: Optional[int]=None) -> None
	def wheel(value: int) -> None
	def exists(time: Optional[int]=None) -> bool
	def hScroll(value: int) -> None
	def vScroll(value: int) -> None
	def property(propertyds: str) -> Union[str, int, bool, Rect]
	def waitProperty(propertyds: str, value: str, timeoutSeconds: Optional[int]=None) -> bool
	def checkProperty(propertyName: str, expectedValue: Union[str, int, bool], optionsOrMessage: Optional[Union[str, TypedDict]]=None) -> "bool"
	def checkImage(options: Optional[any]=None) -> None
	def drop(x: Optional[int]=None, y: Optional[int]=None) -> None
	def drag(x: Optional[int]=None, y: Optional[int]=None) -> None
	def pressKeys(keys: str, opt: Optional[Union[int, PressKeysOptions]]=None) -> None
	def takeScreenshot(filePath: Optional[str]=None) -> Union[str, None]
	def highlight(duration: Optional[int]=None) -> None
	def type() -> str
	def text() -> str
	def name() -> str
	def hwnd() -> int
	def x() -> int
	def y() -> int
	def height() -> int
	def width() -> int
	def enabled() -> bool
	def focused() -> bool
	def visible() -> bool
	def helpText() -> str
	def labeledText() -> str
	def value() -> Union[str, int]
	def processId() -> int
	def rect() -> "Rect"
	def firstChild(controlType: Optional[str]=None) -> "WinControl"
	def lastChild(controlType: Optional[str]=None) -> "WinControl"
	def next(controlType: Optional[str]=None) -> "WinControl"
	def previous(controlType: Optional[str]=None) -> "WinControl"
	def parent() -> "WinControl"
	def findControls(*conditions: List[Union[str, Dict]]) -> List[WinControl]
	def modelmage(encoding: Optional[str]=None) -> Union[str, bytearray]
	def modelProperties(all: Optional[bool]=None) -> TypedDict
	def all() -> List[WinControl]
	def allProperties() -> TypedDict
	def doDefaultAction() -> None
	def rawText() -> str

Help for each specific command and property can be found in the Model Manager, or viewed in Common Control Methods.

Object specific APIs

Other objects inherit from IWinControl, so in addition to these commands and properties, they have some other commands and properties. For example:

CheckBox control has one command check used to set whether it is checked or cleared, and one property checked used to determine the check state of the CheckBox:

JavaScript
Python
export interface IWinCheckBox extends IWinControl {
  check(value: boolean): Promise<void>;
  checked(): Promise<boolean>;
}
class WinCheckBox(WinControl):
	def check(checked: bool) -> None
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None

Below are the unique methods and properties of ComboBox:

JavaScript
Python
export interface IWinComboBox extends IWinControl {
  options(index: number): Promise<string>;
  itemCount(): Promise<number>;
  selectedName(): Promise<string>;
  select(value: string | number): Promise<void>;
  open(): void;
}
class WinComboBox(WinControl):
	def options(index: Optional[int]=None) -> Union[str, List[str]]
	def itemCount() -> int
	def selectedName() -> str
	def select(value: Union[str, int]) -> None
	def open() -> None

Window Object: Window

The Window object is usually the top-level control (or container) of an application, so several window operation APIs are provided for it:

  • activate(): Activates the window, bringing it to the top. Invalid if the window is minimized.
  • close(): Closes the window.
  • maximize(): Maximizes the window. Invalid if the window is minimized.
  • minimize(): Minimizes the window, collapsing the target window to the taskbar.
  • restore(): Restores the window, exiting from minimized or maximized state to default size.
  • isModal(): Gets whether the specified window is a modal window.
  • interactionState(): Window interaction state, return values can be: Running, ReadyForUserInteraction, BlockedByModalWindow, Closing, NotResponding.
  • visualState(): Window visual state, return values are Minimized, Maximized, or Normal.

For detailed API explanation, see: Window Control: Window

Type definition is as follows:

JavaScript
Python
export interface IWinWindow extends IWinControl {
    activate(): Promise<void>;
    close(): Promise<void>;
    maximize(): Promise<void>;
    minimize(): Promise<void>;
    restore(): Promise<void>;
    isModal(): Promise<boolean>;
    interactionState(): Promise<string>;
    visualState(): Promise<string>;
}
class WinWindow(WinControl):
	def activate() -> None
	def close() -> None
	def maximize() -> None
	def minimize() -> None
	def restore() -> None
	def isModal() -> bool
	def interactionState() -> str
	def visualState() -> str

Flexible Window Operation Calls

Although in most cases the top-level control of an application will be a Window control, due to differences in desktop application framework implementations, the top-level control of some applications might be other containers, such as Pane control or Custom control. How do we perform window operations in this case? In fact, window operations in CukeTest do not strictly require the control type to be Window. Therefore, if we assume the top level of the target application is Pane("New Tab") (Chrome windows are recognized as Pane), there are two ways to write scripts for calling window operation methods:

Method 1:

JavaScript
Python
await model.getPane("New Tab").maximize();
model.getPane("New Tab").maximize()
Since window operations do not restrict control types, this writing style is valid, but there is a problem that this style does not support code completion, so you won't see window operation methods in the popped-up intellisense. However, you can see these methods in the Model Manager and copy them directly.

Therefore, the following method is recommended.

Method 2:

JavaScript
Python
await model.getWindow("New Tab").maximize();
model.getWindow("New Tab").maximize()
Even if the control type of the test object "New Tab" is Pane, you can still get this object through the getWindow() method, thereby performing window operations on it.

Note: The above operations are allowed, but if the target control is not a top-level control but a container within the application, then window operations will naturally not take effect.

More help on control commands and properties can be found in the Model Manager.

Virtual Control APIs

Virtual controls are special controls, so their operations differ from other controls. They do not have the common operations and properties of other Windows controls. For more information about virtual controls: Virtual Controls