Tree

This chapter introduces control methods for tree controls (Tree) and their nodes (TreeItem). The table lists links to each API and brief descriptions for quick reference. For tree controls and nodes in trees, CukeTest provides Tree and TreeItem controls. The Tree control represents the entire tree, while TreeItem represents individual nodes in the tree.

Tree View Control: Tree

The Tree control represents the entire tree and mainly operates on related nodes by passing in itemPath. Since node names are not unique, using node names as identifying properties is unreliable. The Model Manager provides an identifying property that describes the node's position—itemPath. You can click itemPath property to view the specific introduction.

In addition to Common Control Methods, the Tree control also provides the following methods:

Method Name Description
collapseAll Collapses all tree nodes on the specified path.
getItem Gets the automation object of the tree node at the specified path position.
findItem Searches for the target tree node by name, returns the matching node or null.
select Selects the tree node at the specified position.
childCount Gets the number of direct child nodes of the current tree.
children Gets the array of direct child nodes of the current tree.
scrollTo Scrolls to the target tree node and expands to the target node position.

Type Definitions

JavaScript
Python
export interface IJTree extends IJControl {
    collapseAll(itemPath: ItemPath): Promise<void>;
    getItem(itemPath: ItemPath): IJTreeItem;
    findItem(text: string, options?: {exact?: boolean}): Promise<IJTreeItem | null>;
    select(itemPath: ItemPath): Promise<IJTreeItem>;
    childCount(): Promise<number>;
    children(): Promise<IJTreeItem[]>;
    scrollTo(itemPath: ItemPath): Promise<IJTreeItem>;
}
export type ItemPath = (number | string)[];
class JTree(JControl):
	def collapseAll(itemPath: TypedDict) -> None
	def getItem(itemPath: TypedDict) -> JTreeItem
	def findItem(text: str, options: Optional[TypedDict]=None) -> JTreeItem
	def select(itemPath: TypedDict) -> JTreeItem
	def childCount() -> int
	def children() -> List[JTreeItem]
	def scrollTo(itemPath: TypedDict) -> JTreeItem

collapseAll(itemPath)

Collapses all tree nodes on the specified path.

Parameters:

  • itemPath: ItemPath type, represents the position of the target node.

Return Value:

  • Asynchronous method that returns no value.

Sample Code:

JavaScript
Python
// Collapse all child nodes under the root node
await model.getTree("tree").collapseAll([0, 'rootNode']);
# Collapse all child nodes under the root node
model.getTree("tree").collapseAll([0, 'rootNode'])

getItem(itemPath)

Gets the automation object corresponding to the tree node at the specified itemPath position.

Parameters:

  • itemPath: ItemPath type, represents the position of the node.

Return Value:

  • IJTreeItem type, the automation object of the TreeItem control. Note this is a synchronous method and does not require the await keyword.

Sample Code:

JavaScript
Python
// Get the automation object of the root node
const node = model.getTree("tree").getItem([0, 'rootNode']);
# Get the automation object of the root node
node = model.getTree("tree").getItem([0, 'rootNode'])

findItem(text, options?)

Searches for the target tree node by name in the tree and returns the automation object of the target tree node. Returns null if not found.

Parameters:

  • text: string type, the content or text of the target tree node.
  • options: Optional parameter {exact?: boolean}, indicates whether to perform exact matching.

Return Value:

  • Promise<IJTreeItem | null> type, asynchronously returns the tree node object or null.

Sample Code:

JavaScript
Python
// Exact search for a node named 'NodeName'
const node = await model.getTree("tree").findItem('NodeName', {exact: true});
# Exact search for a node named 'NodeName'
node = model.getTree("tree").findItem('NodeName', {"exact": True})

select(itemPath)

Selects the tree node at the specified position.

Parameters:

  • itemPath: ItemPath type, the position of the target node.

Return Value:

  • Asynchronous method that returns no value.

Sample Code:

JavaScript
Python
// Select the root node
await model.getTree("tree").select([0, 'rootNode']);
# Select the root node
model.getTree("tree").select([0, 'rootNode'])

childCount()

Gets the number of all direct child nodes of the current tree.

Return Value:

  • Promise<number> type, represents the number of direct child nodes.

Sample Code:

JavaScript
Python
const count = await model.getTree("tree").childCount();
count = model.getTree("tree").childCount()

children()

Gets all direct child nodes of the current tree, returned as an array.

Return Value:

  • Promise<IJTreeItem[]> type, returns an array of automation objects of TreeItem type.

Sample Code:

JavaScript
Python
const children = await model.getTree("tree").children();
children = model.getTree("tree").children()

scrollTo(itemPath)

Scrolls to the position of the target tree node and returns this object. If the target position is not expanded, it will continue to expand until the target node is visible.

Parameters:

  • itemPath: ItemPath type, the position of the target node.

Return Value:

  • Promise<IJTreeItem> type, returns the tree node object scrolled to.

Sample Code:

JavaScript
Python
// Scroll to child node 'childNode'
const node = await model.getTree("tree").scrollTo([0, 'rootNode', 'childNode']);
# Scroll to child node 'childNode'
const node = model.getTree("tree").scrollTo([0, 'rootNode', 'childNode'])

Tree Node Control: TreeItem

The TreeItem control represents individual nodes in the tree and can be expanded, collapsed, selected, or have child nodes retrieved.

In addition to Common Control Methods, the TreeItem control also provides the following methods:

Method Name Description
expand Expands the tree node.
expandState Gets the expansion state of the node
collapse Collapses the tree node.
children Gets the array of direct child nodes of the current tree.
childCount Gets the number of direct child nodes of the current tree.
select Selects the tree node.
selected Gets the selection state of the tree node.

Type Definitions

JavaScript
Python
export interface IJTreeItem extends IJControl {
    expand(): Promise<void>;
    collapse(): Promise<void>;
    expandState(): Promise<ExpandCollapseState>;
    childCount(): Promise<number>;
    children(): Promise<IJTreeItem[]>;
    select(): Promise<void>;
    selected(): Promise<boolean>;
}

export enum ExpandCollapseState {
    collapsed = 0,
    expanded = 1,
    partiallyExpanded = 2,
    leafNode = 3,
    unknown = -1
}
class JTreeItem(JControl):
	def expand() -> None
	def collapse() -> None
	def expandState() -> ExpandCollapseState
	def childCount() -> int
	def children() -> List[JTreeItem]
	def select() -> None
	def selected() -> bool

expand()

Expands the tree node. If it cannot be expanded, there will be no effect.

Return Value:

  • Asynchronous method that returns no value.

Sample Code:

JavaScript
Python
// Expand the node named 'temp'
await model.getTreeItem('temp').expand();
# Expand the node named 'temp'
model.getTreeItem('temp').expand()

expandState()

Gets the expansion state of the node.

Return Value:

  • Promise<ExpandCollapseState> type, returns the expansion state of the tree node, with the following states:

JavaScript
export enum ExpandCollapseState {
    collapsed = 0,
    expanded = 1,
    partiallyExpanded = 2,
    leafNode = 3,
    unknown = -1
}

Sample Code:

// Expand the node named 'temp'
await model.getTreeItem('temp').expand();

# Expand the node named 'temp'
model.getTreeItem('temp').expand()

collapse()

Collapses the tree node. If it cannot be collapsed, there will be no effect.

Return Value:

  • Asynchronous method that returns no value.

Sample Code:

JavaScript
Python
// Collapse the node named 'temp'
await model.getTreeItem('temp').collapse();
# Collapse the node named 'temp'
model.getTreeItem('temp').collapse()

select()

Selects the tree node. If the node is not in the visible range, it will automatically execute scrollIntoView() to expand and scroll to the position where the item is located.

Return Value:

  • Asynchronous method that returns no value.

Sample Code:

JavaScript
Python
// Select the node named 'temp'
await model.getTreeItem('temp').select();
# Select the node named 'temp'
model.getTreeItem('temp').select()

selected()

Gets the selection state of the tree node, true if selected, false if not selected.

Return Value:

  • Promise<boolean> type, indicates whether the tree node is selected.

Sample Code:

JavaScript
Python
// Verify if the node is selected
const isSelected = await model.getTreeItem('temp').selected();
assert.equal(isSelected, true);
# Verify if the node is selected
isSelected = model.getTreeItem('temp').selected()
assert isSelected == True

childCount()

Gets the number of direct child nodes of the current tree node.

Return Value:

  • Promise<number> type, represents the number of direct child nodes.

Sample Code:

JavaScript
Python
// Get the number of child nodes of the node named 'temp'
const count = await model.getTreeItem('temp').childCount();
# Get the number of child nodes of the node named 'temp'
count = model.getTreeItem('temp').childCount()

children()

Gets the direct child nodes of the current tree node, returned as an array.

Return Value:

  • Promise<IJTreeItem[]> type, returns an array of automation objects of TreeItem type.

Sample Code:

JavaScript
Python
// Get all child nodes of the node named 'temp'
const children = await model.getTreeItem('temp').children();
# Get all child nodes of the node named 'temp'
children = model.getTreeItem('temp').children()