gdharness 1.2.28 → 1.2.29

package/build/godot/addons/gdharness_runtime/runtime_accessibility.gd

@@ -10,6 +10,7 @@ extends RefCounted
 ## told, names left empty included.
 
 const Read = preload("reading.gd")
+const Says = preload("runtime_says.gd")
 
 ## How long the client keeps walking the tree for it to settle: the engine answers the first question
 ## with its windows alone and fills them in over the next frames.
@@ -23,6 +24,9 @@ const START_MS: int = 15000
 ## Deep enough for any interface a game builds, and inside the hundred levels ConvertTo-Json stops
 ## at, which are two to a level of the tree.
 const MOST_LEVELS: int = 40
+## Where an element holds its node's instance id between matching and placing, removed before the
+## answer goes.
+const NODE_ID: String = "_node_instance"
 
 ## The client, as PowerShell, with $Handles, $Out, $SettleMs, $EmptyMs and $MostLevels set before it. Each
 ## element answers what UI Automation names its role, its name, its value where it has one, its
@@ -170,12 +174,27 @@ func _init(host: Node) -> void:
 
 
 ## The game's windows as a screen reader is told them, each a tree of elements.
-func get_accessibility(_params: Dictionary) -> Dictionary:
+func get_accessibility(params: Dictionary) -> Dictionary:
 	if DisplayServer.get_name() == "headless":
+		# Both needs at once: told only the window, a caller started a windowed run and was then
+		# refused for the tree the engine had not been asked to build.
+		var also: String = ""
+		if _setting() != "always":
+			also = (
+				(
+					' and engineArgs ["--accessibility", "always"], since this project\'s'
+					+ " accessibility/general/accessibility_support is %s and the engine builds the tree"
+					+ " only when asked"
+				)
+				% _setting()
+			)
 		return _refused(
 			(
-				"A headless run has no window, so a screen reader is told nothing: start the run with"
-				+ " headless: false."
+				(
+					"A headless run has no window, so a screen reader is told nothing: start the run with"
+					+ " headless: false%s."
+				)
+				% also
 			)
 		)
 	if OS.get_name() != "Windows":
@@ -255,12 +274,16 @@ func get_accessibility(_params: Dictionary) -> Dictionary:
 		var window: Dictionary = windows[at]
 		var window_id: int = ids[at] if at < ids.size() else -1
 		window["window_id"] = window_id
+		_match(window, made_by, placing)
+	for at: int in windows.size():
+		var window: Dictionary = windows[at]
+		var window_id: int = window["window_id"]
 		var holder: Window = _window_with(_host.get_tree().root, window_id)
-		var holder_path: String = ""
 		if holder != null:
-			holder_path = str(holder.get_path())
-			window["node"] = holder_path
-		_place(window, holder_path, made_by, placing, true)
+			window["node"] = str(holder.get_path())
+			_attribute(window, holder, placing, true)
+		else:
+			_unmark(window)
 		elements += _count(window)
 		unnamed += _unnamed_text(window)
 	var result: Dictionary = {"windows": windows, "elements": elements}
@@ -315,9 +338,114 @@ func get_accessibility(_params: Dictionary) -> Dictionary:
 			)
 			% unnamed
 		)
+	_narrow(result, params)
 	return result
 
 
+## Cuts [param result] to what [param params] asks for: the elements made by a node and its
+## descendants, the elements saying some words, the fields named, and no more than a number of them.
+## Each window keeps as its children only the outermost elements that match, with what they hold, so
+## a question about one panel reads one panel.
+static func _narrow(result: Dictionary, params: Dictionary) -> void:
+	var under: String = str(params.get("node_path", "")).trim_suffix("/")
+	var said: String = str(params.get("says", ""))
+	var windows: Array = result.get("windows", [])
+	if not under.is_empty() or not said.is_empty():
+		var matched: int = 0
+		for window: Variant in windows:
+			if not window is Dictionary:
+				continue
+			var holder: Dictionary = window
+			if _matches(holder, under, said):
+				matched += 1
+				continue
+			var kept: Array = []
+			_outermost(holder, under, said, kept)
+			holder["children"] = kept
+			matched += kept.size()
+		result["matched"] = matched
+	var fields: Array = params.get("properties", [])
+	if not fields.is_empty():
+		for window: Variant in windows:
+			if window is Dictionary:
+				var holder: Dictionary = window
+				_keep_only(holder, fields)
+	var limit: int = Read.as_int(params.get("limit", 0), 0)
+	if limit > 0:
+		var left: Array[int] = [limit]
+		var omitted: Array[int] = [0]
+		for window: Variant in windows:
+			if window is Dictionary:
+				var holder: Dictionary = window
+				_cut(holder, left, omitted)
+		if omitted[0] > 0:
+			result["omitted"] = omitted[0]
+	var counted: int = 0
+	for window: Variant in windows:
+		if window is Dictionary:
+			var holder: Dictionary = window
+			counted += _count(holder)
+	result["elements"] = counted
+
+
+## Whether [param element] is made by the node at [param under] or one below it, and says
+## [param said], each where asked: words as find matches them, in the element's name or value.
+static func _matches(element: Dictionary, under: String, said: String) -> bool:
+	if not under.is_empty():
+		var path: String = str(element.get("node", element.get("part_of", "")))
+		if path != under and not path.begins_with(under + "/"):
+			return false
+	if not said.is_empty():
+		var name: String = str(element.get("name", ""))
+		var value: String = str(element.get("value", ""))
+		if not Says.matches(name, said) and not Says.matches(value, said):
+			return false
+	return true
+
+
+static func _outermost(element: Dictionary, under: String, said: String, kept: Array) -> void:
+	var children: Array = element.get("children", [])
+	for child: Variant in children:
+		if not child is Dictionary:
+			continue
+		var inner: Dictionary = child
+		if _matches(inner, under, said):
+			kept.append(inner)
+		else:
+			_outermost(inner, under, said, kept)
+
+
+## Leaves [param element] and everything under it only the [param fields] asked for, and the
+## children that hold the rest of the tree.
+static func _keep_only(element: Dictionary, fields: Array) -> void:
+	for key: Variant in element.keys():
+		if key != "children" and not fields.has(key):
+			var _dropped: bool = element.erase(key)
+	var children: Array = element.get("children", [])
+	for child: Variant in children:
+		if child is Dictionary:
+			var inner: Dictionary = child
+			_keep_only(inner, fields)
+
+
+## Keeps the first [param left] elements below [param element], depth first, and counts the ones
+## cut into [param omitted]. One-element arrays, so the count carries across windows.
+static func _cut(element: Dictionary, left: Array[int], omitted: Array[int]) -> void:
+	var children: Array = element.get("children", [])
+	var kept: Array = []
+	for child: Variant in children:
+		if not child is Dictionary:
+			continue
+		var inner: Dictionary = child
+		if left[0] <= 0:
+			omitted[0] += _count(inner)
+			continue
+		left[0] -= 1
+		kept.append(inner)
+		_cut(inner, left, omitted)
+	element["children"] = kept
+
+
 ## The project's accessibility mode, as the command line's --accessibility names them.
 static func _setting() -> String:
 	match Read.as_int(ProjectSettings.get_setting("accessibility/general/accessibility_support", 0), 0):
@@ -360,15 +488,13 @@ static func _window_with(node: Node, window_id: int) -> Window:
 	return null
 
 
-## Gives each child of [param element] the node that made it, or, for an element a node made as a
-## part of itself (a line of a text box, a window's announcements), the node it is a part of.
+## Gives every element below [param element] whose id is a node's element that node, and notes
+## which nodes UI Automation shows.
 ##
 ## UI Automation's runtime id for an element ends in the four halves of AccessKit's id for it, and
 ## Godot gives AccessKit the element's RID: measured on 4.7.2, /root/Main's element answered
 ## 114,1,0,0 with RID 114 << 32 | 1. Which pair holds it is not assumed, so both are tried.
-static func _place(
-	element: Dictionary, holder: String, made_by: Dictionary, placing: Placing, is_window: bool
-) -> void:
+static func _match(element: Dictionary, made_by: Dictionary, placing: Placing) -> void:
 	var children: Array = element.get("children", [])
 	for child: Variant in children:
 		if not child is Dictionary:
@@ -376,27 +502,127 @@ static func _place(
 		var inner: Dictionary = child
 		var parts: Array = inner.get("element_id", [])
 		var _dropped: bool = inner.erase("element_id")
-		var node: Node = null
 		if parts.size() == 4:
 			placing.asked += 1
-			node = _made(parts, made_by)
-		var path: String = holder
-		if node != null:
-			placing.placed += 1
-			path = str(node.get_path())
-			inner["node"] = path
-			if node is Control:
-				var control: Control = node
-				if not control.tooltip_text.is_empty():
-					inner["tooltip"] = control.tooltip_text
-					placing.tooltips += 1
+			var node: Node = _made(parts, made_by)
+			if node != null:
+				placing.placed += 1
+				placing.shown[node.get_instance_id()] = true
+				inner["node"] = str(node.get_path())
+				inner[NODE_ID] = node.get_instance_id()
+				if node is Control:
+					var control: Control = node
+					if not control.tooltip_text.is_empty():
+						inner["tooltip"] = control.tooltip_text
+						placing.tooltips += 1
+		_match(inner, made_by, placing)
+
+
+## Gives every element below [param element] that is no node's own the node it is a part of.
+##
+## UI Automation's parent is not that node: AccessKit leaves every container out of the tree it
+## gives UI Automation and hangs what the container held on the nearest element it keeps, and a
+## Control, a RichTextLabel and each of its lines are containers. A RichTextLabel's text in a
+## column of plain containers came out straight under the window. So the node is found where it
+## must be: below the shown element's node, itself left out of the tree (a node that is shown would
+## have the part under it), drawn around the part, and, for text, holding its words.
+static func _attribute(element: Dictionary, holder: Node, placing: Placing, is_window: bool) -> void:
+	var children: Array = element.get("children", [])
+	for child: Variant in children:
+		if not child is Dictionary:
+			continue
+		var inner: Dictionary = child
+		if inner.has(NODE_ID):
+			var node: Node = instance_from_id(Read.as_int(inner[NODE_ID], 0))
+			var _dropped: bool = inner.erase(NODE_ID)
+			_attribute(inner, node if node != null else holder, placing, false)
+			continue
+		var owners: Array[Node] = _owners_of(inner, holder, placing)
+		if owners.size() == 1:
+			inner["part_of"] = str(owners[0].get_path())
 		else:
-			inner["part_of"] = holder
-			# The one static text a window makes of itself: where it speaks what is announced, named
-			# only while something is.
-			if is_window and inner.get("role") == "text":
-				inner["part"] = "announcement"
-		_place(inner, path, made_by, placing, false)
+			inner["part_of"] = str(holder.get_path())
+			var paths: Array[String] = []
+			for owner: Node in owners:
+				paths.append(str(owner.get_path()))
+			inner["part_of_candidates"] = paths
+		# The one text a window makes of itself, where it speaks what is announced: it is given no
+		# bounds, where every text a node draws has them.
+		var only_holder: bool = owners.size() == 1 and owners[0] == holder
+		if is_window and inner.get("role") == "text" and not inner.has("bounds") and only_holder:
+			inner["part"] = "announcement"
+		_attribute(inner, owners[0] if owners.size() == 1 else holder, placing, false)
+
+
+## The nodes that may have made [param element], below [param holder]: the deepest ones drawn
+## around it whose own elements are not shown, narrowed to those holding its words when that leaves
+## any. [param holder] alone when none is drawn around it, or when it has no bounds to look by.
+static func _owners_of(element: Dictionary, holder: Node, placing: Placing) -> Array[Node]:
+	var bounds: Variant = element.get("bounds")
+	if not bounds is Dictionary:
+		return [holder]
+	var box: Dictionary = bounds
+	var drawn: Rect2 = Rect2(
+		Read.as_float(box.get("x", 0)),
+		Read.as_float(box.get("y", 0)),
+		Read.as_float(box.get("width", 0)),
+		Read.as_float(box.get("height", 0))
+	)
+	var found: Array[Node] = []
+	_drawn_around(holder, drawn, placing, found)
+	if found.is_empty():
+		return [holder]
+	# A RichTextLabel's line ends in a zero-width space its text does not have.
+	var words: String = str(element.get("name", "")).replace(String.chr(0x200b), "").strip_edges()
+	if found.size() > 1 and not words.is_empty():
+		var saying: Array[Node] = []
+		for node: Node in found:
+			if _text_of(node).contains(words):
+				saying.append(node)
+		if not saying.is_empty():
+			return saying
+	return found
+
+
+## Where a Control is drawn is read off its screen transform, which for a window that is not
+## embedded is in that window's own pixels, as the bounds are.
+static func _drawn_around(node: Node, drawn: Rect2, placing: Placing, found: Array[Node]) -> void:
+	for child: Node in node.get_children(true):
+		# A node that is shown has its parts under it, and so do the nodes below it.
+		if placing.shown.has(child.get_instance_id()):
+			continue
+		if child is CanvasItem:
+			var item: CanvasItem = child
+			if not item.is_visible_in_tree():
+				continue
+		var before: int = found.size()
+		_drawn_around(child, drawn, placing, found)
+		if found.size() > before or not child is Control:
+			continue
+		var control: Control = child
+		var around: Rect2 = control.get_screen_transform() * Rect2(Vector2.ZERO, control.size)
+		# Two pixels either way, for the rounding of bounds to whole pixels on both sides.
+		if around.grow(2.0).encloses(drawn):
+			found.append(control)
+
+
+## Takes the instance ids [method _match] left out of a window no node holds.
+static func _unmark(element: Dictionary) -> void:
+	var _dropped: bool = element.erase(NODE_ID)
+	var children: Array = element.get("children", [])
+	for child: Variant in children:
+		if child is Dictionary:
+			var inner: Dictionary = child
+			_unmark(inner)
+
+
+static func _text_of(node: Node) -> String:
+	if node is RichTextLabel:
+		var rich: RichTextLabel = node
+		return rich.get_parsed_text()
+	if "text" in node:
+		return str(node.get("text"))
+	return ""
 
 
 static func _made(parts: Array, made_by: Dictionary) -> Node:
@@ -410,12 +636,14 @@ static func _made(parts: Array, made_by: Dictionary) -> Node:
 	return null
 
 
-## Counts kept while the elements are placed.
+## Counts kept while the elements are placed, and the nodes whose own elements UI Automation shows,
+## by instance id.
 class Placing:
 	extends RefCounted
 	var asked: int = 0
 	var placed: int = 0
 	var tooltips: int = 0
+	var shown: Dictionary = {}
 
 
 ## Text elements with bounds and no name. The window's announcement element has no bounds and is

package/build/godot/addons/gdharness_runtime/runtime_changes.gd

@@ -32,15 +32,16 @@ func set_property(params: Dictionary) -> Dictionary:
 	if node_path.is_empty() or property.is_empty():
 		return {"type": "error", "message": "Node path and property required"}
 
-	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	var standing: Dictionary = Values.target_at(_host.get_tree().root, node_path)
 	if standing.has("message"):
 		return standing
 	var node: Node = standing["node"]
+	var target: Object = standing["object"]
 
 	# Through a path as well, for the reason [method Paths.walk_to] gives, and read back off the same
 	# holder afterwards: a set that does not take says so by answering with the old value, which is
 	# how a typed container refusing a write is told from one accepting it.
-	var reached: Dictionary = Paths.walk_to(node, node_path, property)
+	var reached: Dictionary = Paths.walk_to(target, node_path, property)
 	if reached.has("message"):
 		return reached
 
@@ -119,11 +120,28 @@ func set_property(params: Dictionary) -> Dictionary:
 				"%s.%s is a typed %s: %s." % [reached["called"], named, _sort_of(old_value), typed["message"]]
 			}
 		given = typed["value"]
+	# A component of a vector or a transform is written into a copy, which is put back where it was
+	# read from, setter and all; the read back is then taken off the game again, since the copy here
+	# says only what was written into it.
+	var chain: Array[Dictionary] = reached["chain"]
+	var copied: bool = Paths.composite(holder)
+	if copied:
+		var unwritable: String = Paths.unwritable_copy(chain)
+		if not unwritable.is_empty():
+			return {"type": "error", "message": unwritable}
 	# The write alone, setter included, which is where a property's cost is.
 	var began: int = Time.get_ticks_usec()
-	Paths.write(holder, named, given)
+	var written: Variant = Paths.write(holder, named, given)
+	if copied:
+		Paths.write_back(chain, written)
 	var elapsed: int = Time.get_ticks_usec() - began
 	var now: Variant = Paths.read_under(holder, named)
+	if copied:
+		var again: Dictionary = Paths.walk_to(target, node_path, property)
+		if again.has("message"):
+			return again
+		var reread: Variant = again["holder"]
+		now = Paths.read_under(reread, named) if Paths.can_read(reread, named) else null
 	# Read back rather than trusted. The engine drops a write it will not take without a word, and
 	# the answer then showed the old value as the new one, shaped as a success: a typed container
 	# refusing a plain list did exactly that. A value the property changed on the way in, a setter
@@ -211,15 +229,16 @@ func call_method(params: Dictionary) -> Dictionary:
 	if node_path.is_empty() or method.is_empty():
 		return {"type": "error", "message": "Node path and method required"}
 
-	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	var standing: Dictionary = Values.target_at(_host.get_tree().root, node_path)
 	if standing.has("message"):
 		return standing
 	var node: Node = standing["node"]
+	var target: Object = standing["object"]
 
 	# Through a path as well, for the reason [method Paths.walk_to] gives. What a game does hangs off its
 	# nodes as much as its state does, so reading `_game:run:day` while being unable to call
 	# `_game:run:advance` answers half of what a node holds and refuses the other half.
-	var reached: Dictionary = Paths.walk_to(node, node_path, method)
+	var reached: Dictionary = Paths.walk_to(target, node_path, method)
 	if reached.has("message"):
 		return reached
 
@@ -461,8 +480,11 @@ static func _walk_from(object: Object, path: String) -> Dictionary:
 	var holder: Variant = object
 	var called: String = "the result"
 	for named: String in Paths.steps_of(path):
-		if not (holder is Object or holder is Array or holder is Dictionary or Paths.packed(holder)):
-			return {"message": "%s holds no object to read %s off" % [called, named]}
+		if not Paths.can_hold(holder):
+			return {
+				"message":
+				"%s holds %s, which has nothing to read %s off" % [called, type_string(typeof(holder)), named]
+			}
 		if not Paths.can_read(holder, named):
 			return {"message": Paths.nothing_there(holder, named, called)}
 		holder = Paths.read_under(holder, named)

package/build/godot/addons/gdharness_runtime/runtime_input.gd

@@ -122,12 +122,16 @@ func inject_action(params: Dictionary) -> Dictionary:
 
 	if not InputMap.has_action(action):
 		return {"type": "error", "message": "Action not found: " + action}
+	var holding: Variant = Values.held_for(params)
+	if holding is String:
+		return {"type": "error", "message": holding}
+	var frames: int = holding
 
 	_say_action(action, whole or held, strength)
 	if whole:
-		# A frame between the halves, as a click has: a listener that acts on the press and a
-		# listener that acts on the release both get their own frame to do it in.
-		await _host.get_tree().process_frame
+		# A frame between the halves at least, as a click has: a listener that acts on the press and
+		# a listener that acts on the release both get their own frame to do it in.
+		await _held(frames)
 		_say_action(action, false, strength)
 		await _host.get_tree().process_frame
 
@@ -137,9 +141,16 @@ func inject_action(params: Dictionary) -> Dictionary:
 		"action": action,
 		"pressed": held and not whole,
 		"whole": whole,
+		"held_frames": Values.held_answer(whole, frames),
 	}
 
 
+## Waits out [param frames] process frames, which is how long a whole press is held down.
+func _held(frames: int) -> void:
+	for _frame: int in frames:
+		await _host.get_tree().process_frame
+
+
 func _say_action(action: String, down: bool, strength: float) -> void:
 	var event: InputEventAction = InputEventAction.new()
 	event.action = action
@@ -160,6 +171,10 @@ func inject_key(params: Dictionary) -> Dictionary:
 		if not named.is_empty() and key_label.is_empty():
 			key_label = named
 	var keycode: int = 0 if keycode_raw is String else Read.as_int(keycode_raw)
+	var holding: Variant = Values.held_for(params)
+	if holding is String:
+		return {"type": "error", "message": holding}
+	var frames: int = holding
 
 	var event: InputEventKey = InputEventKey.new()
 	event.pressed = whole or held
@@ -193,7 +208,7 @@ func inject_key(params: Dictionary) -> Dictionary:
 
 	Input.parse_input_event(event)
 	if whole:
-		await _host.get_tree().process_frame
+		await _held(frames)
 		var up: InputEventKey = event.duplicate()
 		up.pressed = false
 		Input.parse_input_event(up)
@@ -202,6 +217,7 @@ func inject_key(params: Dictionary) -> Dictionary:
 	return {
 		"type": "input_injected",
 		"input_type": "key",
+		"held_frames": Values.held_answer(whole, frames),
 		"keycode": event.keycode,
 		"physical_keycode": event.physical_keycode,
 		"shift": event.shift_pressed,
@@ -266,6 +282,15 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 	# than under the pointer, landing true and doing nothing, until a release was sent by hand.
 	var notch: bool = held and _mask_of(button) == 0
 	var whole: bool = notch or not params.has("pressed")
+	var holding: Variant = Values.held_for(params)
+	if holding is String:
+		return {"type": "error", "message": holding}
+	var frames: int = holding
+	if notch and params.has("holdFrames"):
+		return {
+			"type": "error",
+			"message": "A wheel step is pressed and let go at once, so holdFrames cannot hold one."
+		}
 
 	# A button pressed somewhere puts the pointer there: the motion after a held press measures
 	# its drag from the press, which is where a real pointer would be.
@@ -274,9 +299,9 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 	if notch:
 		Input.parse_input_event(_button(position, button, false, false))
 	elif whole:
-		# A frame between the halves, as inject_action has, so a control that acts on the press and
-		# one that acts on the release each get a frame to do it in.
-		await _host.get_tree().process_frame
+		# A frame between the halves at least, as inject_action has, so a control that acts on the
+		# press and one that acts on the release each get a frame to do it in.
+		await _held(frames)
 		Input.parse_input_event(_button(position, button, false, false))
 		await _host.get_tree().process_frame
 
@@ -284,6 +309,7 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 		{
 			"type": "input_injected",
 			"input_type": "mouse_click",
+			"held_frames": Values.held_answer(whole and not notch, frames),
 			"position": [position.x, position.y],
 			"button": button,
 			"pressed": held and not whole,

package/build/godot/addons/gdharness_runtime/runtime_pad.gd

@@ -9,6 +9,7 @@ extends RefCounted
 ## calling the game's own methods. The engine still fires the actions bound to a button from these.
 
 const Read = preload("reading.gd")
+const Values = preload("runtime_values.gd")
 
 ## Controller buttons by the names Godot gives them, for a caller naming one rather than numbering it.
 const JOY_BUTTONS: Dictionary[String, int] = {
@@ -62,18 +63,24 @@ func inject_joypad_button(params: Dictionary) -> Dictionary:
 	var device: int = Read.as_int(params.get("device", 0), 0)
 	var held: bool = Read.as_bool(params.get("pressed", true), true)
 	var whole: bool = not params.has("pressed")
+	var holding: Variant = Values.held_for(params)
+	if holding is String:
+		return {"type": "error", "message": holding}
+	var frames: int = holding
 
 	Input.parse_input_event(_button(button, device, whole or held))
 	if whole:
-		# A frame between the halves, as a key has, so a game that acts on the press and one that
-		# acts on the release each get a frame to do it in.
-		await _host.get_tree().process_frame
+		# A frame between the halves at least, as a key has, so a game that acts on the press and one
+		# that acts on the release each get a frame to do it in.
+		for _frame: int in frames:
+			await _host.get_tree().process_frame
 		Input.parse_input_event(_button(button, device, false))
 		await _host.get_tree().process_frame
 
 	return {
 		"type": "input_injected",
 		"input_type": "joypad_button",
+		"held_frames": Values.held_answer(whole, frames),
 		"button": button,
 		"button_name": _name_of(button, JOY_BUTTONS),
 		"device": device,