gdharness 1.2.34 → 1.2.36

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

@@ -12,8 +12,10 @@ const REFUSED: String = "Error calling method from 'callv': "
 
 ## The engine's reason for refusing the call, without [constant REFUSED], or "" when it ran.
 var refused: String = ""
-## What was reported while it ran, a line each, warnings marked as such.
+## The errors reported while it ran, a line each.
 var raised: Array[String] = []
+## The warnings reported while it ran, a line each.
+var warned: Array[String] = []
 
 
 func _log_message(_message: String, _error: bool) -> void:
@@ -39,4 +41,7 @@ func _log_error(
 	if function == "callv" and text.begins_with(REFUSED) and refused.is_empty():
 		refused = text.trim_prefix(REFUSED)
 		return
-	raised.append(("WARNING: " if error_type == ERROR_TYPE_WARNING else "") + text)
+	if error_type == ERROR_TYPE_WARNING:
+		warned.append(text)
+	else:
+		raised.append(text)

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

@@ -108,6 +108,9 @@ try {
     }
     $p = Patterned $element 'RangeValue'
     if ($p) {
+      # A reader speaks the Value pattern's words, such as "75%" for a slider whose game sets them,
+      # and the number would otherwise replace them.
+      if ($node.Contains('value') -and "$($node.value)") { $node.value_text = $node.value }
       $node.value = $p.Current.Value
       $node.range = @($p.Current.Minimum, $p.Current.Maximum)
       if (-not $p.Current.IsReadOnly) { $actions += 'set_value' }
@@ -389,17 +392,18 @@ static func _narrow(result: Dictionary, params: Dictionary) -> void:
 
 
 ## 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.
+## [param said], each where asked: words as find matches them, in the element's name, value or
+## value_text.
 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
+		for field: String in ["name", "value", "value_text"]:
+			if element.has(field) and Says.matches(str(element[field]), said):
+				return true
+		return false
 	return true
 
 

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

@@ -18,6 +18,7 @@ const InputCommands = preload("runtime_input.gd")
 const Pad = preload("runtime_pad.gd")
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
+const Targets = preload("runtime_targets.gd")
 const Typing = preload("runtime_typing.gd")
 const Values = preload("runtime_values.gd")
 const Waits = preload("runtime_waits.gd")
@@ -153,6 +154,7 @@ func _init() -> void:
 		"choose": _typing.choose,
 		"wait_frames": _waits.wait_frames,
 		"wait_signal": _waits.wait_signal,
+		"watch_signal": _waits.watch_signal,
 		"wait_until": _waits.wait_until,
 		"send_profile": _send_profile_now,
 		"close_game": _close_game,
@@ -160,6 +162,36 @@ func _init() -> void:
 	_wait_for_the_profiler()
 
 
+## Gives a game with no window the size the project opens its window at. Measured: a
+## headless engine's root viewport is 64 by 64 whatever the project settings or --resolution say, so
+## a headless game laid its interface out in 64 pixels, and a button every windowed run shows was
+## refused as off screen. The root takes a size set once the autoloads are in the tree, before the
+## main scene enters it, and the scene lays out at it from its first frame. A size set at the
+## autoload's construction does not hold: the root is a 100 by 100 placeholder then, and the engine
+## gives it the 64 by 64 afterwards. A script run is not a game and keeps the viewport its own code
+## gives it, and a release build is left as the engine made it.
+func _size_a_windowless_game() -> void:
+	if DisplayServer.get_name() != "headless" or _script_run() or not OS.is_debug_build():
+		return
+	var root: Window = get_tree().root
+	if Vector2(root.size) != Targets.HEADLESS_VIEWPORT:
+		return
+	root.size = Vector2i(_window_dimension("width", 1152), _window_dimension("height", 648))
+
+
+## The window's [param axis] as the project opens it: the override when one is set, otherwise the
+## viewport's size, whose engine default is [param fallback].
+static func _window_dimension(axis: String, fallback: int) -> int:
+	var override: int = Read.as_int(
+		ProjectSettings.get_setting("display/window/size/window_%s_override" % axis, 0)
+	)
+	if override > 0:
+		return override
+	return Read.as_int(
+		ProjectSettings.get_setting("display/window/size/viewport_%s" % axis, fallback), fallback
+	)
+
+
 ## Holds the game's start until the profiler is on, when whatever started the game asked for a
 ## profile from its start. The debugger switches the profiler on with a message the game reads only
 ## on a poll, which comes every [constant POLLS_PER_READ] lines of script, so the main scene's _ready
@@ -197,6 +229,7 @@ func _ready() -> void:
 	# even be un-paused over the socket. A debug server has to stay responsive while the game
 	# is frozen, to inspect, capture, inject or resume it.
 	process_mode = Node.PROCESS_MODE_ALWAYS
+	_size_a_windowless_game()
 	var watched: int = get_tree().root.tree_exiting.connect(_send_the_profile)
 	if watched != OK:
 		push_error("gdharness could not watch for the game quitting: %d" % watched)

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

@@ -441,16 +441,24 @@ func call_method(params: Dictionary) -> Dictionary:
 		"result": _values.serialize(result),
 		"elapsed_usec": elapsed
 	}
-	if not caught.raised.is_empty():
-		answer["errors"] = caught.raised.slice(0, ERRORS_KEPT)
-		if caught.raised.size() > ERRORS_KEPT:
-			answer["errors_not_shown"] = caught.raised.size() - ERRORS_KEPT
+	_keep_reported(answer, "errors", caught.raised)
+	_keep_reported(answer, "warnings", caught.warned)
 	var asked: Variant = params.get("properties")
 	if _reads_the_result(asked):
 		answer.merge(_read_off_result(result, asked))
 	return answer
 
 
+## Puts the first [constant ERRORS_KEPT] of [param reported] in [param answer] under [param field],
+## with how many more there were, when anything was reported.
+static func _keep_reported(answer: Dictionary, field: String, reported: Array[String]) -> void:
+	if reported.is_empty():
+		return
+	answer[field] = reported.slice(0, ERRORS_KEPT)
+	if reported.size() > ERRORS_KEPT:
+		answer[field + "_not_shown"] = reported.size() - ERRORS_KEPT
+
+
 ## Why [param named], the last step of a call's method, names no method of [param holder] to call, or
 ## "" when it does. Brackets on it holding arguments are refused rather than read: the arguments are
 ## taken from args alone, so a call is never made with half of them in one place and half in the

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

@@ -412,17 +412,19 @@ static func _outside_note(outside: int, root: Node) -> String:
 ## headless game's button twenty pixels in from the corner was refused as off screen, and the
 ## refusal read as though the button were not there.
 ##
-## The size is only claimed where it is true: the rect is printed beside this, so naming 64 by 64
-## over a viewport somebody has resized says two different things in one sentence.
+## The size named is the one in force, which the rect printed beside it agrees with. A game the
+## runtime started headless has the size the project opens its window at, and a window of that size
+## would not reach the control either, so only the engine's own 64 by 64 is answered with a window.
 static func no_window_note(viewport: Viewport, root: Window) -> String:
 	if viewport != root or root.can_draw():
 		return ""
-	if viewport.get_visible_rect().size == HEADLESS_VIEWPORT:
+	var size: Vector2 = viewport.get_visible_rect().size
+	if size == HEADLESS_VIEWPORT:
 		return (
 			". This game has no window, and a game with no window has a 64 by 64 viewport whatever "
 			+ "the project settings say: run it with a window to reach this control"
 		)
-	return ". This game has no window: run it with a window to reach this control"
+	return ". This game has no window, and its viewport is %d by %d" % [roundi(size.x), roundi(size.y)]
 
 
 ## What to add to a refusal that found nothing on screen, when the controls saying it are covered.
@@ -771,7 +773,7 @@ static func _where_it_lands(target: Control, point: Vector2) -> Dictionary[Scrol
 ## Whether a click could not reach [param target] however it scrolled: its centre, where the click
 ## would bring it, outside its viewport or the one showing that on the screen, or clipped away by a
 ## container the click does not scroll. A drawer parked off the side of the screen, or anything
-## outside the 64 by 64 viewport of a game with no window, was listed among the controls on screen.
+## outside the viewport of a game with no window, was listed among the controls on screen.
 static func _off_screen(target: Control) -> bool:
 	var moves: Dictionary[ScrollContainer, Vector2] = _scrolls_for(target)
 	var point: Vector2 = _centre_of(target) + _moved_by(target, moves)

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

@@ -26,8 +26,13 @@ const LOOKS_APART: int = 9
 ## two looks and a wait for 32 never sees it.
 const COMPARES: Array[String] = ["==", "!=", ">=", "<=", ">", "<"]
 
+## The most signal watches kept at once; arming one past this lets the oldest go.
+const MOST_WATCHES: int = 16
+
 var _host: Node
 var _values: Values
+var _watches: Dictionary[int, Watch] = {}
+var _next_watch: int = 1
 
 
 func _init(host: Node, values: Values) -> void:
@@ -56,13 +61,16 @@ func wait_frames(params: Dictionary) -> Dictionary:
 	return {"type": "waited", "frames": frames, "elapsed_ms": Time.get_ticks_msec() - started}
 
 
-## Waits for a signal to fire, and answers with what it carried, or that the time ran out.
+## Waits for a signal to fire, and answers with what it carried, or that the time ran out. Given a
+## watch, collects that instead: see [method watch_signal].
 func wait_signal(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var signal_name: String = str(params.get("signal", ""))
 	var timeout_ms: int = Read.as_int(params.get("timeout_ms", 5000), 5000)
 	if timeout_ms < 1 or timeout_ms > CEILING_MSEC:
 		return _out_of_range("timeout_ms", timeout_ms, 1, CEILING_MSEC)
+	if params.has("watch"):
+		return await _collect(Read.as_int(params["watch"], 0), timeout_ms)
 	if node_path.is_empty() or signal_name.is_empty():
 		return {"type": "error", "message": "Node path and signal name required"}
 
@@ -84,7 +92,7 @@ func wait_signal(params: Dictionary) -> Dictionary:
 	if not catcher.fired and is_instance_valid(node) and node.is_connected(signal_name, callable):
 		node.disconnect(signal_name, callable)
 
-	return {
+	var answer: Dictionary = {
 		"type": "signal",
 		"path": node_path,
 		"signal": signal_name,
@@ -92,6 +100,90 @@ func wait_signal(params: Dictionary) -> Dictionary:
 		"args": _values.serialize(catcher.args),
 		"elapsed_ms": Time.get_ticks_msec() - started,
 	}
+	if not catcher.fired:
+		answer["note"] = (
+			"If a call meant to set the signal off was sent beside this wait, it may have run only after"
+			+ " the wait answered, as a client can run its calls in turn: arm runtime_wait watch first,"
+			+ " make the call, then wait with signal and that watch"
+		)
+	return answer
+
+
+## Starts recording a signal and answers at once with the watch to collect it by.
+##
+## A wait sent beside the call meant to set its signal off does not see it when the client runs the
+## two in turn: Claude Code ran a key press only after the signal wait beside it had answered, so the
+## wait ran out and the press landed after it. A watch is armed before the call and collected after.
+func watch_signal(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	var signal_name: String = str(params.get("signal", ""))
+	if node_path.is_empty() or signal_name.is_empty():
+		return {"type": "error", "message": "Node path and signal name required"}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
+	var node: Node = standing["node"]
+	if not node.has_signal(signal_name):
+		return {"type": "error", "message": "%s has no signal %s" % [node_path, signal_name]}
+	var watch: Watch = Watch.new(node, node_path, signal_name)
+	var listening: Error = node.connect(signal_name, watch.catcher._on_fired)
+	if listening != OK:
+		return {"type": "error", "message": "Could not listen to signal: " + signal_name}
+	while _watches.size() >= MOST_WATCHES:
+		var oldest: int = _watches.keys().min()
+		_let_go(oldest)
+	var id: int = _next_watch
+	_next_watch += 1
+	_watches[id] = watch
+	return {"type": "watching", "watch": id, "path": node_path, "signal": signal_name}
+
+
+## Answers at once with the first emission recorded since watch [param id] was armed, otherwise
+## waits for the next until the time runs out. The watch goes either way.
+func _collect(id: int, timeout_ms: int) -> Dictionary:
+	if not _watches.has(id):
+		return {
+			"type": "error",
+			"message":
+			(
+				(
+					"No watch %d is armed in this game: it was collected already, %d armed after it let it"
+					+ " go, or the game started again since"
+				)
+				% [id, MOST_WATCHES]
+			),
+		}
+	var watch: Watch = _watches[id]
+	var started: int = Time.get_ticks_msec()
+	var before: bool = watch.catcher.fired
+	while not watch.catcher.fired and Time.get_ticks_msec() - started < timeout_ms:
+		await _host.get_tree().process_frame
+	_let_go(id)
+	var answer: Dictionary = {
+		"type": "signal",
+		"path": watch.node_path,
+		"signal": watch.signal_name,
+		"watch": id,
+		"fired": watch.catcher.fired,
+		"times": watch.catcher.times,
+		"args": _values.serialize(watch.catcher.args),
+		"elapsed_ms": Time.get_ticks_msec() - started,
+	}
+	if before:
+		answer["fired_before_wait"] = true
+	return answer
+
+
+func _let_go(id: int) -> void:
+	var watch: Watch = _watches.get(id)
+	var _gone: bool = _watches.erase(id)
+	if watch == null:
+		return
+	var held: Object = watch.node.get_ref()
+	var node: Node = held as Node
+	var callable: Callable = watch.catcher._on_fired
+	if node != null and node.is_connected(watch.signal_name, callable):
+		node.disconnect(watch.signal_name, callable)
 
 
 ## Waits until a property reads as the value given, or until something under the path says what
@@ -492,8 +584,26 @@ func _anything_says(node_path: String, said: String, include_hidden: bool) -> bo
 class SignalCatcher:
 	extends RefCounted
 	var fired: bool = false
+	## How many times it fired; [member args] holds what the first carried.
+	var times: int = 0
 	var args: Array = []
 
 	func _on_fired(...carried: Array) -> void:
+		if not fired:
+			args = carried
 		fired = true
-		args = carried
+		times += 1
+
+
+## A signal recorded from when it was armed until it is collected.
+class Watch:
+	extends RefCounted
+	var node: WeakRef
+	var node_path: String
+	var signal_name: String
+	var catcher: SignalCatcher = SignalCatcher.new()
+
+	func _init(watched: Node, path: String, named: String) -> void:
+		node = weakref(watched)
+		node_path = path
+		signal_name = named

package/build/godot/operations/classdb_queries.gd

@@ -21,6 +21,17 @@ const CATEGORY_BASES: Dictionary = {
 	"visual": ["VisualInstance3D"],
 	"animation": ["AnimationMixer"],
 }
+## The engine's MethodFlags, each by the name an answer gives it.
+const METHOD_FLAG_NAMES: Dictionary[int, String] = {
+	METHOD_FLAG_NORMAL: "normal",
+	METHOD_FLAG_EDITOR: "editor",
+	METHOD_FLAG_CONST: "const",
+	METHOD_FLAG_VIRTUAL: "virtual",
+	METHOD_FLAG_VARARG: "vararg",
+	METHOD_FLAG_STATIC: "static",
+	METHOD_FLAG_OBJECT_CORE: "object_core",
+	METHOD_FLAG_VIRTUAL_REQUIRED: "virtual_required",
+}
 
 var _log: Log
 var _values: Serialisation = Serialisation.new()
@@ -333,6 +344,7 @@ func _methods_of(class_name_str: String, include_inherited: bool) -> Array[Dicti
 						"class_name": return_info.get("class_name", "")
 					},
 					"flags": m.get("flags", 0),
+					"flag_names": _flag_names(Read.as_int(m.get("flags", 0))),
 					# As values, tagged the way every other answer tags one: JSON writes a Vector2i it is
 					# handed as its text, so TileMapLayer.set_cell's default atlas coords read "(-1, -1)".
 					"default_args": _values.serialize_value(m.get("default_args", []))
@@ -343,6 +355,16 @@ func _methods_of(class_name_str: String, include_inherited: bool) -> Array[Dicti
 	return methods
 
 
+# The MethodFlags set in [param flags] by name, beside the number the engine reports, which reads as
+# nothing without its enum: 1 is normal, and a const method is 5.
+static func _flag_names(flags: int) -> Array[String]:
+	var named: Array[String] = []
+	for flag: int in METHOD_FLAG_NAMES:
+		if flags & flag:
+			named.append(METHOD_FLAG_NAMES[flag])
+	return named
+
+
 # What [param info]'s type is called: its class for an object of one, and otherwise the engine's own
 # name for the type, beside the number the engine reports, which reads as nothing without its enum.
 # Nil is a value that can be anything when the usage says so, and [param nil_name] otherwise: void

package/build/godot/operations/dependencies.gd

@@ -23,6 +23,11 @@ const REFERENCE_PATTERNS: Array[String] = [
 
 var _log: Log
 var _files: FileWalk = FileWalk.new()
+## The project's class names and the scripts declaring them, read the first time a script is walked
+## and kept for the call: walking every resource starts a walk per root, and each reading every
+## script again made the whole-project answer quadratic in the number of scripts.
+var _classes_declared: Dictionary = {}
+var _classes_read: bool = false
 
 
 # Everything one dependency walk carries: the settings it was started with, and the state it
@@ -91,12 +96,14 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 
 		total_resources = all_resources.size()
 
-	var dep_count: int = 0
+	var references: int = 0
+	var distinct: Dictionary = {}
 	for key: String in dependencies:
 		# Through a typed local: what comes out of a Dictionary is Variant, and a project that
 		# errors on handing one to a typed parameter will not compile this script at all.
 		var walked: Array[Dictionary] = dependencies[key]
-		dep_count += _count_recursive(walked)
+		references += _count_recursive(walked)
+		_gather_paths(walked, key, distinct)
 
 	return {
 		"dependencies": dependencies,
@@ -104,7 +111,10 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 		"summary":
 		{
 			"total_resources": total_resources,
-			"total_dependencies": dep_count,
+			# The files depended on, each once. The tree names a file again under everything that
+			# loads it, and counting its entries answered 11 for a scene with six dependencies.
+			"total_dependencies": distinct.size(),
+			"total_references": references,
 			"circular_count": circular_references.size()
 		}
 	}
@@ -332,9 +342,24 @@ func _regex_escaped(text: String) -> String:
 	return escaped
 
 
+# [param root] is left out: a cycle leads back to it, and it is not one of its own dependencies.
+func _gather_paths(deps: Array[Dictionary], root: String, into: Dictionary) -> void:
+	for dep: Dictionary in deps:
+		var path: String = str(dep.get("path", ""))
+		if path != root:
+			into[path] = true
+		if dep.has("dependencies"):
+			var deeper: Array[Dictionary] = dep["dependencies"]
+			_gather_paths(deeper, root, into)
+
+
+# A circular entry is not counted: it marks that the entry holding it was reached again, which that
+# entry already counts as one reference.
 func _count_recursive(deps: Array[Dictionary]) -> int:
-	var count: int = deps.size()
+	var count: int = 0
 	for dep: Dictionary in deps:
+		if not dep.get("circular", false):
+			count += 1
 		if dep.has("dependencies"):
 			var deeper: Array[Dictionary] = dep["dependencies"]
 			count += _count_recursive(deeper)
@@ -390,29 +415,74 @@ func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -
 				if not walk.include_built_in and dep_path.begins_with("res://."):
 					continue
 
-				if dep_path == path:
-					continue
-
-				var dep_info: Dictionary = {"path": dep_path, "exists": FileAccess.file_exists(dep_path)}
-
-				if dep_info["exists"] and current_depth + 1 < walk.max_depth:
-					var sub_deps: Array[Dictionary] = _analyze_resource(dep_path, current_depth + 1, walk)
-					if sub_deps.size() > 0:
-						dep_info["dependencies"] = sub_deps
+				_depend(deps, path, dep_path, "", current_depth, walk)
 
-				var already_added: bool = false
-				for existing: Dictionary in deps:
-					if existing.get("path", "") == dep_path:
-						already_added = true
-						break
-				if not already_added:
-					deps.append(dep_info)
+		# A script uses another by its class_name as surely as by a preload, and only the reverse walk
+		# looked for that: asked what a script depends on, the answer left out the script it typed a
+		# variable with, while asking what used that script named this one.
+		if path.get_extension() == "gd":
+			var classes: Dictionary = classes_declared()
+			for used: String in classes_used_in(content, classes):
+				_depend(deps, path, str(classes[used]), used, current_depth, walk)
 
 	walk.path_stack.pop_back()
 	walk.visited[path] = {"deps": deps, "remaining": remaining}
 	return deps
 
 
+# Adds [param dep_path] to [param deps], what [param path] depends on, walked as far as the depth left
+# allows, once however many times it is named. [param by_class] is the class name it was named by,
+# or empty for a path.
+func _depend(
+	deps: Array[Dictionary],
+	path: String,
+	dep_path: String,
+	by_class: String,
+	current_depth: int,
+	walk: DependencyWalk
+) -> void:
+	if dep_path == path:
+		return
+	for existing: Dictionary in deps:
+		if existing.get("path", "") == dep_path:
+			return
+	var dep_info: Dictionary = {"path": dep_path, "exists": FileAccess.file_exists(dep_path)}
+	if not by_class.is_empty():
+		dep_info["by_class"] = by_class
+	if dep_info["exists"] and current_depth + 1 < walk.max_depth:
+		var sub_deps: Array[Dictionary] = _analyze_resource(dep_path, current_depth + 1, walk)
+		if sub_deps.size() > 0:
+			dep_info["dependencies"] = sub_deps
+	deps.append(dep_info)
+
+
+## Every class_name the project's scripts declare, with the script declaring it.
+func classes_declared() -> Dictionary:
+	if _classes_read:
+		return _classes_declared
+	_classes_read = true
+	for script: String in _files.find_files("res://", ".gd"):
+		var declared: String = _declared_class_name(script)
+		if not declared.is_empty():
+			_classes_declared[declared] = script
+	return _classes_declared
+
+
+## The names in [param classes] that the code in [param content] uses, in the order first used: words
+## outside strings and comments, so a class named in prose or in a message is not a use of it.
+static func classes_used_in(content: String, classes: Dictionary) -> Array[String]:
+	var used: Array[String] = []
+	if classes.is_empty():
+		return used
+	var word: RegEx = Patterns.compiled("[A-Za-z_][A-Za-z0-9_]*")
+	for line: String in content.split("\n"):
+		for m: RegExMatch in word.search_all(_code_of(line)):
+			var name: String = m.get_string()
+			if classes.has(name) and not name in used:
+				used.append(name)
+	return used
+
+
 # [param written] as the res:// path the engine would load from [param from]: a uid:// by what the
 # project's uid cache says it names, and a relative path against the referring file's directory.
 # Both were passed over as not being res:// paths, so a script's `preload("sibling.gd")` was no