gdharness 1.2.27 → 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
@@ -41,12 +45,45 @@ try {
     if ($element.TryGetCurrentPattern($pattern, [ref]$found)) { return $found }
     return $null
   }
+  # FullDescription is where the description is put, and the managed client refuses every property
+  # newer than itself, so it is asked through the core call the client makes for the rest.
+  $script:unread = $null
+  try {
+    $client = [System.Windows.Automation.AutomationElement]
+    $core = $client.Assembly.GetType('MS.Internal.Automation.UiaCoreApi')
+    $ask = $core.GetMethod('UiaGetPropertyValue', [System.Reflection.BindingFlags]'NonPublic,Public,Static')
+    $nodeField = $client.GetField('_hnode', [System.Reflection.BindingFlags]'NonPublic,Instance')
+    if ($null -eq $ask -or $null -eq $nodeField) {
+      $script:unread = 'this Windows has no UiaGetPropertyValue to ask it through'
+    }
+  } catch {
+    $script:unread = "$_"
+  }
+  function FullDescription($element) {
+    if ($null -ne $script:unread) { return '' }
+    try {
+      $asked = @($nodeField.GetValue($element), [int]30159, $null)
+      $null = $ask.Invoke($null, $asked)
+      if ($asked[2] -is [string]) { return $asked[2] }
+    } catch {
+      $script:unread = "$_"
+    }
+    return ''
+  }
   function Describe($element, $ox, $oy, $depth) {
     $c = $element.Current
     $role = $c.ControlType.ProgrammaticName -replace '^ControlType[.]', ''
     $role = ($role -creplace '(?<=[a-z])(?=[A-Z])', '_').ToLowerInvariant()
     $node = [ordered]@{ role = $role; name = $c.Name }
-    if ($c.HelpText) { $node.description = $c.HelpText }
+    $description = FullDescription $element
+    if ($description) { $node.description = $description }
+    if ($c.HelpText) { $node.placeholder = $c.HelpText }
+    # The element's own id, the last four parts of its runtime id, which the game reads back as the
+    # node that made it.
+    $runtime = $element.GetRuntimeId()
+    if ($null -ne $runtime -and $runtime.Length -ge 4) {
+      $node.element_id = @($runtime[-4], $runtime[-3], $runtime[-2], $runtime[-1])
+    }
     $r = $c.BoundingRectangle
     if (-not $r.IsEmpty) {
       $node.bounds = [ordered]@{ x = [int]($r.X - $ox); y = [int]($r.Y - $oy) }
@@ -121,7 +158,9 @@ try {
     }
     $windows += , $tree
   }
-  Answer @{ windows = $windows }
+  $answer = @{ windows = $windows }
+  if ($null -ne $script:unread) { $answer.description_unread = $script:unread }
+  Answer $answer
 } catch {
   Answer @{ error = "$_" }
 }
@@ -135,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":
@@ -211,14 +265,45 @@ func get_accessibility(_params: Dictionary) -> Dictionary:
 		return _refused("UI Automation could not read the game's windows: %s" % str(answer["error"]))
 
 	var windows: Array = answer.get("windows", [])
+	var made_by: Dictionary = {}
+	_note_elements(_host.get_tree().root, made_by)
+	var placing: Placing = Placing.new()
 	var elements: int = 0
 	var unnamed: int = 0
 	for at: int in windows.size():
 		var window: Dictionary = windows[at]
-		window["window_id"] = ids[at] if at < ids.size() else -1
+		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)
+		if holder != null:
+			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}
+	if placing.tooltips > 0:
+		result["tooltip_note"] = (
+			"tooltip is the node's tooltip_text, which the engine puts in the tree, and UI Automation, as"
+			+ " AccessKit fills it in, has no property that carries it (measured on 4.7.2), so a screen"
+			+ " reader on Windows is not told it. Say what a reader needs in accessibility_description."
+		)
+	if placing.asked > 0 and placing.placed == 0:
+		# Nothing at all matched: the element ids are not the engine's element RIDs any more, which
+		# an AccessKit that numbers its elements another way would do, and every node would read null.
+		result["node_note"] = (
+			"No element could be matched to the node that made it: UI Automation's runtime ids did not"
+			+ " carry the engine's element ids, so node and part_of are the windows' alone."
+		)
+	if answer.has("description_unread"):
+		result["description_note"] = (
+			"Descriptions could not be read, so none is shown: %s" % str(answer["description_unread"])
+		)
 	if elements <= windows.size():
 		var setting: String = _setting()
 		# The command line's --accessibility is consumed by the engine and not handed on, so only
@@ -253,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):
@@ -276,8 +466,188 @@ static func _count(element: Dictionary) -> int:
 	return total
 
 
-## Text elements with bounds and no name. A window also holds a nameless text element with no bounds
-## that no node of the game made, in every scene tried, which is left out.
+## Every node's element by its id, for the walk's elements to be read back as the node that made
+## them. Internal children too: a dialog's buttons are elements like any other.
+static func _note_elements(node: Node, made_by: Dictionary) -> void:
+	var element: RID = node.get_accessibility_element()
+	if element.is_valid():
+		made_by[element.get_id()] = node
+	for child: Node in node.get_children(true):
+		_note_elements(child, made_by)
+
+
+static func _window_with(node: Node, window_id: int) -> Window:
+	if node is Window:
+		var window: Window = node
+		if window.get_window_id() == window_id:
+			return window
+	for child: Node in node.get_children(true):
+		var found: Window = _window_with(child, window_id)
+		if found != null:
+			return found
+	return null
+
+
+## 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 _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:
+			continue
+		var inner: Dictionary = child
+		var parts: Array = inner.get("element_id", [])
+		var _dropped: bool = inner.erase("element_id")
+		if parts.size() == 4:
+			placing.asked += 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"] = 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:
+	var halves: Array[int] = []
+	for part: Variant in parts:
+		halves.append(Read.as_int(part, 0) & 0xFFFFFFFF)
+	for at: int in [0, 2]:
+		var id: int = (halves[at] << 32) | halves[at + 1]
+		if made_by.has(id):
+			return made_by[id]
+	return null
+
+
+## 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
+## left out with them: it is empty until something is announced.
 static func _unnamed_text(element: Dictionary) -> int:
 	var total: int = 0
 	if element.get("role") == "text" and str(element.get("name", "")).is_empty() and element.has("bounds"):

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,