gdharness 0.4.1

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

@@ -0,0 +1,292 @@
+extends Node
+
+## The runtime autoload: a TCP server inside the running game that the gdharness server asks
+## about the scene tree, drives with input, and captures. This file is the server and the
+## command table; what each command does lives in a sibling module.
+##
+## The port is whatever the operating system hands out, and the game announces it by writing
+## one file named after its process id into a directory the server derives the same way. Two
+## games can therefore run at once, and a headless operation never takes the port a game
+## wanted. Both directions of the socket carry one JSON object per line. Every request names an
+## id and the reply carries it back.
+
+const Capture = preload("runtime_capture.gd")
+const InputCommands = preload("runtime_input.gd")
+const Queries = preload("runtime_queries.gd")
+const Values = preload("runtime_values.gd")
+const Waits = preload("runtime_waits.gd")
+
+const PROTOCOL: int = 2
+const DEFAULT_BIND_ADDRESS: String = "127.0.0.1"
+const BIND_ADDRESS_SETTING: String = "gdharness/runtime/bind_address"
+## 0 asks the operating system for a free port, which is the default and what the server
+## expects. A fixed port is for a client that cannot read the announcement.
+const PORT_SETTING: String = "gdharness/runtime/port"
+
+var values: Values = Values.new()
+
+# The modules are members and not locals of _init, because a Callable holds its object by id
+# rather than by reference, and a module referenced only by the Callables in the command table
+# would be freed on the way out of _init, leaving every command "unknown".
+var _queries: Queries = Queries.new(self, values)
+var _input: InputCommands = InputCommands.new(self, values)
+var _capture: Capture = Capture.new(self)
+var _waits: Waits = Waits.new(self, values)
+
+var _server: TCPServer
+var _clients: Array[StreamPeerTCP] = []
+## Bytes received from each client that do not yet end in a newline, keyed by the peer.
+var _pending: Dictionary = {}
+var _port: int = 0
+var _enabled: bool = true
+var _announcement: String = ""
+## Every command, by the name a request uses, as the module method that answers it.
+var _commands: Dictionary = {}
+
+
+func _init() -> void:
+	_commands = {
+		"ping": _ping,
+		"get_tree": _queries.get_tree,
+		"find_nodes": _queries.find_nodes,
+		"get_rect": _queries.get_rect,
+		"get_property": _queries.get_property,
+		"set_property": _queries.set_property,
+		"call_method": _queries.call_method,
+		"get_metrics": _queries.get_metrics,
+		"capture_screenshot": _capture.capture_screenshot,
+		"capture_viewport": _capture.capture_viewport,
+		"inject_action": _input.inject_action,
+		"inject_key": _input.inject_key,
+		"inject_mouse_click": _input.inject_mouse_click,
+		"inject_mouse_motion": _input.inject_mouse_motion,
+		"click": _input.click,
+		"wait_frames": _waits.wait_frames,
+		"wait_signal": _waits.wait_signal,
+		"wait_until": _waits.wait_until,
+	}
+
+
+func _ready() -> void:
+	name = "GdharnessRuntime"
+	# The TCP control loop runs in _process. With the default PROCESS_MODE_INHERIT it stops
+	# while the tree is paused, so the runtime silently goes unreachable and the game cannot
+	# 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
+	_start_server()
+
+
+func _exit_tree() -> void:
+	_cleanup()
+
+
+func _process(_delta: float) -> void:
+	if not _enabled or _server == null:
+		return
+
+	if _server.is_connection_available():
+		var client: StreamPeerTCP = _server.take_connection()
+		if client:
+			_clients.append(client)
+			_send_welcome(client)
+
+	var gone: Array[StreamPeerTCP] = []
+	for client: StreamPeerTCP in _clients:
+		client.poll()
+		if client.get_status() != StreamPeerTCP.STATUS_CONNECTED:
+			gone.append(client)
+			continue
+		var available: int = client.get_available_bytes()
+		if available > 0:
+			var received: Array = client.get_data(available)
+			var bytes: PackedByteArray = received[1]
+			_receive(client, bytes)
+
+	for client: StreamPeerTCP in gone:
+		_clients.erase(client)
+		_pending.erase(client)
+
+
+## Bytes arrive in whatever pieces the socket makes of them, so a request is only handled once
+## its newline has arrived, and two that arrive together are handled one after the other.
+func _receive(client: StreamPeerTCP, bytes: PackedByteArray) -> void:
+	var buffered: PackedByteArray = _pending.get(client, PackedByteArray())
+	buffered.append_array(bytes)
+	var start: int = 0
+	var newline: int = buffered.find(10, start)
+	while newline != -1:
+		var line: String = buffered.slice(start, newline).get_string_from_utf8().strip_edges()
+		start = newline + 1
+		newline = buffered.find(10, start)
+		if not line.is_empty():
+			# Through a Callable and not awaited: a request that waits on the game must not stop
+			# the others being read, and the analyser would otherwise insist on the await.
+			_handle_message.call(client, line)
+	_pending[client] = buffered.slice(start)
+
+
+func _start_server() -> void:
+	# The command set includes call_method, set_property and input injection, none of it
+	# authenticated, so a release export must not serve it.
+	if not OS.is_debug_build():
+		_enabled = false
+		return
+
+	_server = TCPServer.new()
+	# listen() defaults bind_address to "*", which exposes the game to the whole network.
+	var bind_address: String = str(ProjectSettings.get_setting(BIND_ADDRESS_SETTING, DEFAULT_BIND_ADDRESS))
+	var wanted_port: int = int(ProjectSettings.get_setting(PORT_SETTING, 0))
+	var error: Error = _server.listen(wanted_port, bind_address)
+	if error != OK:
+		# A warning, not an error: callers treat any ERROR line on stderr as a failed
+		# operation, and a game without a runtime server is a handled condition.
+		push_warning(
+			"[gdharness] runtime port %d is unavailable (%s), running without a server" % [wanted_port, error]
+		)
+		_enabled = false
+		return
+
+	_port = _server.get_local_port()
+	_announce(bind_address)
+	print("[gdharness] runtime listening on %s:%d, announced at %s" % [bind_address, _port, _announcement])
+
+
+## Where the announcement goes. The server derives the same path with the same precedence, so
+## the two only meet if this stays in step with `runtimeDirectory` in src/runtime-client.ts.
+func _announcement_directory() -> String:
+	var explicit: String = OS.get_environment("GDHARNESS_RUNTIME_DIR")
+	if not explicit.is_empty():
+		return explicit
+	var per_user: String = OS.get_environment("XDG_RUNTIME_DIR")
+	var base: String = per_user if not per_user.is_empty() else OS.get_temp_dir()
+	return base.path_join("gdharness")
+
+
+func _announce(bind_address: String) -> void:
+	var directory: String = _announcement_directory()
+	var made: Error = DirAccess.make_dir_recursive_absolute(directory)
+	if made != OK and made != ERR_ALREADY_EXISTS:
+		push_warning(
+			"[gdharness] cannot create %s (%s); the server will not find this game" % [directory, made]
+		)
+		return
+	var path: String = directory.path_join("runtime-%d.json" % OS.get_process_id())
+	var file: FileAccess = FileAccess.open(path, FileAccess.WRITE)
+	if file == null:
+		push_warning(
+			(
+				"[gdharness] cannot write %s (%s); the server will not find this game"
+				% [path, FileAccess.get_open_error()]
+			)
+		)
+		return
+	file.store_string(JSON.stringify(_identity(bind_address)))
+	file.close()
+	_announcement = path
+
+
+## What the announcement file and the welcome both carry: enough to pick this game out of
+## several and to know whether the server speaks its protocol.
+func _identity(bind_address: String) -> Dictionary:
+	return {
+		"protocol": PROTOCOL,
+		"pid": OS.get_process_id(),
+		"port": _port,
+		"address": bind_address,
+		"project":
+		{
+			"name": str(ProjectSettings.get_setting("application/config/name", "")),
+			"path": ProjectSettings.globalize_path("res://").rstrip("/")
+		},
+		"godot": Engine.get_version_info().get("string", ""),
+	}
+
+
+func _send_welcome(client: StreamPeerTCP) -> void:
+	var welcome: Dictionary = _identity(
+		str(ProjectSettings.get_setting(BIND_ADDRESS_SETTING, DEFAULT_BIND_ADDRESS))
+	)
+	welcome["type"] = "welcome"
+	welcome["commands"] = _commands.keys()
+	_send_response(client, welcome)
+
+
+func _handle_message(client: StreamPeerTCP, line: String) -> void:
+	var json: JSON = JSON.new()
+	if json.parse(line) != OK:
+		_send_error(client, null, "Invalid JSON: " + json.get_error_message())
+		return
+
+	var message: Variant = json.get_data()
+	if not message is Dictionary:
+		_send_error(client, null, "A request must be an object")
+		return
+
+	var fields: Dictionary = message
+	var request_id: Variant = fields.get("id", null)
+	if request_id == null:
+		_send_error(client, null, "A request must carry an id")
+		return
+
+	var command: String = str(fields.get("command", ""))
+	var params: Variant = fields.get("params", {})
+	if not params is Dictionary:
+		_send_error(client, request_id, "params must be an object")
+		return
+
+	# A command that waits on the game (a frame, a signal, a condition) suspends here and answers
+	# when it is done, while _process keeps serving the other clients in the meantime. A client
+	# that hung up while its command waited is simply not written to.
+	var result: Dictionary = await _execute_command(command, params)
+	result["id"] = request_id
+	if client.get_status() == StreamPeerTCP.STATUS_CONNECTED:
+		_send_response(client, result)
+
+
+func _execute_command(command: String, params: Dictionary) -> Dictionary:
+	var handler: Callable = _commands.get(command, Callable())
+	if not handler.is_valid():
+		return {
+			"type": "error",
+			"message": "Unknown command: %s. Commands: %s" % [command, ", ".join(_commands.keys())]
+		}
+	var answer: Variant = await handler.call(params)
+	return answer
+
+
+func _ping(_params: Dictionary) -> Dictionary:
+	return {"type": "pong", "timestamp": Time.get_unix_time_from_system()}
+
+
+## One JSON object and a newline. put_data rather than put_utf8_string, which would prefix the
+## bytes with a length the other side is not expecting.
+func _send_response(client: StreamPeerTCP, data: Dictionary) -> void:
+	client.put_data((JSON.stringify(data) + "\n").to_utf8_buffer())
+
+
+## A request that could not be read far enough to find its id is answered with a null one.
+func _send_error(client: StreamPeerTCP, request_id: Variant, message: String) -> void:
+	_send_response(client, {"type": "error", "message": message, "id": request_id})
+
+
+func _notification(what: int) -> void:
+	if what == NOTIFICATION_WM_CLOSE_REQUEST:
+		_cleanup()
+
+
+func _cleanup() -> void:
+	for client: StreamPeerTCP in _clients:
+		client.disconnect_from_host()
+	_clients.clear()
+	_pending.clear()
+
+	if _server:
+		_server.stop()
+		_server = null
+
+	# The announcement is what tells the server this game exists, so it goes before the
+	# process does. A crash leaves it behind, and the server drops one whose process is gone.
+	if not _announcement.is_empty():
+		DirAccess.remove_absolute(_announcement)
+		_announcement = ""

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

@@ -0,0 +1,77 @@
+extends RefCounted
+
+## A picture of the running game, as a PNG written where the server asked for it.
+
+var _host: Node
+
+
+func _init(host: Node) -> void:
+	_host = host
+
+
+func capture_screenshot(params: Dictionary) -> Dictionary:
+	return _capture(_host.get_tree().root, params)
+
+
+func capture_viewport(params: Dictionary) -> Dictionary:
+	var viewport_path: String = String(params.get("viewportPath", ""))
+	if viewport_path.is_empty():
+		return capture_screenshot(params)
+
+	var node: Node = _host.get_tree().root.get_node_or_null(viewport_path)
+	if node == null:
+		return {"type": "error", "message": "Viewport not found: " + viewport_path}
+	if not node is Viewport:
+		return {"type": "error", "message": "Node is not a Viewport: " + viewport_path}
+	return _capture(node, params)
+
+
+## The server names the file, so a game cannot point it at a path of its own choosing; a call
+## with no path is a call the server did not make.
+func _capture(viewport: Viewport, params: Dictionary) -> Dictionary:
+	var requested_path: String = String(params.get("output_path", ""))
+	if requested_path.is_empty():
+		return {"type": "error", "message": "output_path required"}
+
+	# Godot draws nothing to a minimised window and nothing at all without one, and the
+	# texture keeps whatever was drawn last. A capture then comes back byte for byte the same
+	# every time, with a success payload, and a game running perfectly well reads as a game
+	# that has frozen. A frame nobody drew is not evidence of anything, so it is refused.
+	if not _host.get_tree().root.can_draw():
+		return {
+			"type": "error",
+			"message":
+			(
+				"Nothing is being drawn to the game's window: it is minimised, or this engine "
+				+ "has no window. The texture still holds the last frame that was drawn, so this "
+				+ "and every capture after it would be that frame. Restore the window and ask again."
+			),
+		}
+
+	var viewport_texture: ViewportTexture = viewport.get_texture()
+	if viewport_texture == null:
+		return {"type": "error", "message": "No viewport texture available"}
+
+	var image: Image = viewport_texture.get_image()
+	if image == null:
+		return {"type": "error", "message": "Failed to capture viewport image"}
+
+	var width: int = int(params.get("width", 0))
+	var height: int = int(params.get("height", 0))
+	if width > 0 and height > 0:
+		image.resize(width, height)
+
+	var screenshot_path: String = requested_path
+	if screenshot_path.begins_with("user://") or screenshot_path.begins_with("res://"):
+		screenshot_path = ProjectSettings.globalize_path(screenshot_path)
+	var save_error: Error = image.save_png(screenshot_path)
+	if save_error != OK:
+		return {"type": "error", "message": "Failed to save screenshot as PNG: " + str(save_error)}
+
+	return {
+		"type": "screenshot_file",
+		"format": "png",
+		"width": image.get_width(),
+		"height": image.get_height(),
+		"path": screenshot_path
+	}

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

@@ -0,0 +1,254 @@
+extends RefCounted
+
+## Input handed to the running game as if a player had given it: actions, keys, the mouse, and
+## a whole click on a Control found by path.
+
+const Values = preload("runtime_values.gd")
+
+var _host: Node
+var _values: Values
+
+
+func _init(host: Node, values: Values) -> void:
+	_host = host
+	_values = values
+
+
+func inject_action(params: Dictionary) -> Dictionary:
+	var action: String = String(params.get("action", ""))
+	var pressed: bool = bool(params.get("pressed", true))
+	var strength: float = float(params.get("strength", 1.0))
+
+	if action.is_empty():
+		return {"type": "error", "message": "Action name required"}
+
+	if not InputMap.has_action(action):
+		return {"type": "error", "message": "Action not found: " + action}
+
+	var event: InputEventAction = InputEventAction.new()
+	event.action = action
+	event.pressed = pressed
+	event.strength = strength
+	Input.parse_input_event(event)
+
+	return {"type": "input_injected", "input_type": "action", "action": action, "pressed": pressed}
+
+
+func inject_key(params: Dictionary) -> Dictionary:
+	var keycode_raw: Variant = params.get("keycode", 0)
+	var pressed: bool = bool(params.get("pressed", true))
+	var key_label: String = String(params.get("key_label", ""))
+
+	if keycode_raw is String:
+		var named: String = keycode_raw
+		if not named.is_empty() and key_label.is_empty():
+			key_label = named
+	var keycode: int = 0 if keycode_raw is String else int(keycode_raw)
+
+	var event: InputEventKey = InputEventKey.new()
+	event.pressed = pressed
+
+	if not key_label.is_empty():
+		event.keycode = OS.find_keycode_from_string(key_label)
+		if event.keycode == KEY_NONE:
+			return {"type": "error", "message": "Invalid key_label: " + key_label}
+	elif keycode > 0:
+		event.keycode = keycode as Key
+	else:
+		return {"type": "error", "message": "keycode or key_label required"}
+
+	# A key event from a real keyboard carries all three, and InputMap consults whichever one
+	# the bound event declares: keycode first, then physical_keycode, then key_label. An
+	# injected event with only keycode set can therefore never match an action bound by
+	# physical key, which is how a rebinding UI normally stores one, so inject_key silently
+	# did nothing for those actions.
+	event.physical_keycode = event.keycode
+	event.key_label = event.keycode
+
+	event.shift_pressed = bool(params.get("shift", false))
+	event.ctrl_pressed = bool(params.get("ctrl", false))
+	event.alt_pressed = bool(params.get("alt", false))
+
+	Input.parse_input_event(event)
+
+	return {
+		"type": "input_injected",
+		"input_type": "key",
+		"keycode": event.keycode,
+		"physical_keycode": event.physical_keycode,
+		"shift": event.shift_pressed,
+		"ctrl": event.ctrl_pressed,
+		"alt": event.alt_pressed,
+		"pressed": pressed
+	}
+
+
+## A point the tool schema sends as two flat numbers, or the older form of one [x, y] value.
+## Answers a Vector2, or the String that says what was wrong with it.
+func _read_point(params: Dictionary, x_key: String, y_key: String, pair_key: String) -> Variant:
+	if params.has(x_key) and params.has(y_key):
+		return Vector2(float(params[x_key]), float(params[y_key]))
+	var raw: Variant = params.get(pair_key, Vector2.ZERO)
+	if raw is Vector2:
+		return raw
+	if raw is Array:
+		var pair: Array = raw
+		if pair.size() < 2:
+			return "%s array must contain [x, y]" % pair_key
+		return Vector2(float(pair[0]), float(pair[1]))
+	return "%s must be Vector2 or [x, y]" % pair_key
+
+
+func inject_mouse_click(params: Dictionary) -> Dictionary:
+	var point: Variant = _read_point(params, "x", "y", "position")
+	if point is String:
+		return {"type": "error", "message": point}
+	var position: Vector2 = point
+	var button: int = _resolve_mouse_button(params.get("button", MOUSE_BUTTON_LEFT))
+	var pressed: bool = bool(params.get("pressed", true))
+	var double: bool = bool(params.get("doubleClick", false))
+
+	Input.parse_input_event(_button(position, button, pressed, double))
+
+	return {
+		"type": "input_injected",
+		"input_type": "mouse_click",
+		"position": [position.x, position.y],
+		"button": button,
+		"pressed": pressed,
+		"double": double
+	}
+
+
+func inject_mouse_motion(params: Dictionary) -> Dictionary:
+	var point: Variant = _read_point(params, "x", "y", "position")
+	if point is String:
+		return {"type": "error", "message": point}
+	var position: Vector2 = point
+	var movement: Variant = _read_point(params, "relativeX", "relativeY", "relative")
+	if movement is String:
+		return {"type": "error", "message": movement}
+	var relative: Vector2 = movement
+
+	Input.parse_input_event(_motion(position, relative))
+
+	return {
+		"type": "input_injected",
+		"input_type": "mouse_motion",
+		"position": [position.x, position.y],
+		"relative": [relative.x, relative.y]
+	}
+
+
+## A whole click on a Control: the pointer moves onto it, the button goes down, a frame passes,
+## the button comes up. BaseButton fires on the release, which is why a single injected press
+## never pressed anything. The position is the control's centre carried into window pixels, so
+## the caller never has to do that arithmetic.
+func click(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	if node_path.is_empty():
+		return {"type": "error", "message": "Node path required"}
+
+	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
+	if node == null:
+		return {"type": "error", "message": "Node not found: " + node_path}
+	if not node is Control:
+		return {"type": "error", "message": "%s is a %s, not a Control" % [node_path, node.get_class()]}
+	var control: Control = node
+	if not control.is_visible_in_tree():
+		return {"type": "error", "message": "%s is not visible, so nothing can click it" % node_path}
+
+	var viewport: Viewport = control.get_viewport()
+	var centre: Vector2 = control.get_global_transform_with_canvas() * (control.size * 0.5)
+	var position: Vector2 = viewport.get_final_transform() * centre
+	# The GUI only delivers to what is inside the viewport, so a centre outside it would be a
+	# click that silently reached nothing.
+	if not viewport.get_visible_rect().has_point(centre):
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s has its centre at %s, outside the viewport %s, so nothing can click it"
+				% [node_path, centre, viewport.get_visible_rect()]
+			)
+		}
+	var button: int = _resolve_mouse_button(params.get("button", MOUSE_BUTTON_LEFT))
+	var double: bool = bool(params.get("double", false))
+
+	# Pushed into the viewport rather than through Input: Input accumulates events and flushes
+	# them at the next frame, so the hovered control read below would be the one from before
+	# the pointer moved. The viewport delivers it to the GUI the same way a real one arrives.
+	viewport.push_input(_motion(position, Vector2.ZERO))
+	# What the engine itself thinks is under the pointer, which is the answer to "did it land",
+	# read before the press so the caller learns about a control on top rather than a click
+	# that went to it. Read in full here, path included, because nothing about that control
+	# is guaranteed to survive the release: a button that opens the next screen takes the
+	# whole menu out of the tree, and a node that has left the tree has no path to give.
+	var hovered: Control = viewport.gui_get_hovered_control()
+	var hovered_path: Variant = null
+	if hovered != null:
+		hovered_path = str(hovered.get_path())
+	var landed: bool = hovered == control or (hovered != null and control.is_ancestor_of(hovered))
+
+	viewport.push_input(_button(position, button, true, double))
+	await _host.get_tree().process_frame
+	viewport.push_input(_button(position, button, false, false))
+	# The release is what a button acts on, and a queue_free it causes lands at the end of
+	# this frame; the frame passes so the answer describes the control as the click left it.
+	await _host.get_tree().process_frame
+
+	# What became of the control: still in the tree, taken out of it, or freed. A button that
+	# opened another screen is the second or the third, and the caller wants to hear that
+	# rather than guess it from a tree that has changed shape. A freed reference cannot be
+	# handed to anything typed, so the question is asked here.
+	var afterwards: String = "freed"
+	if is_instance_valid(control):
+		afterwards = "in_tree" if control.is_inside_tree() else "removed"
+
+	return {
+		"type": "clicked",
+		"path": node_path,
+		"position": _values.serialize(position),
+		"button": button,
+		"double": double,
+		"hovered": hovered_path,
+		"landed": landed,
+		"control_afterwards": afterwards,
+	}
+
+
+func _motion(position: Vector2, relative: Vector2) -> InputEventMouseMotion:
+	var event: InputEventMouseMotion = InputEventMouseMotion.new()
+	event.position = position
+	event.global_position = position
+	event.relative = relative
+	return event
+
+
+func _button(position: Vector2, button: int, pressed: bool, double: bool) -> InputEventMouseButton:
+	var event: InputEventMouseButton = InputEventMouseButton.new()
+	event.position = position
+	event.global_position = position
+	event.button_index = button as MouseButton
+	event.pressed = pressed
+	event.double_click = double
+	return event
+
+
+func _resolve_mouse_button(raw: Variant) -> int:
+	if raw is String:
+		var named: String = raw
+		match named.to_lower():
+			"left":
+				return MOUSE_BUTTON_LEFT
+			"right":
+				return MOUSE_BUTTON_RIGHT
+			"middle":
+				return MOUSE_BUTTON_MIDDLE
+			"wheel_up", "wheelup":
+				return MOUSE_BUTTON_WHEEL_UP
+			"wheel_down", "wheeldown":
+				return MOUSE_BUTTON_WHEEL_DOWN
+			_:
+				return MOUSE_BUTTON_LEFT
+	return int(raw)