godot-cli-control 0.2.1__tar.gz → 0.2.2__tar.gz

{godot_cli_control-0.2.1 → godot_cli_control-0.2.2}/.gitignore

@@ -8,6 +8,10 @@ dist/
 .venv/
 venv/
 .pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
 
 # hatch-vcs generated
 python/godot_cli_control/_version.py

{godot_cli_control-0.2.1 → godot_cli_control-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.1
+Version: 0.2.2
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Author: kesar
 License: MIT
@@ -9,6 +9,10 @@ Requires-Python: >=3.10
 Requires-Dist: websockets<16,>=14
 Provides-Extra: pytest
 Requires-Dist: pytest>=7; extra == 'pytest'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
+Requires-Dist: pytest-cov>=4; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
 Description-Content-Type: text/markdown
 
 # godot-cli-control
@@ -161,6 +165,18 @@ fi
 
 The port is read from `.cli_control/port` if you don't pass `--port`, so RPC calls just work after `daemon start`.
 
+## Testing
+
+```bash
+# Python unit tests + coverage (fails if below 80%)
+pip install -e ".[test]"
+coverage run -m pytest python/tests/
+coverage report
+
+# GUT tests for the Godot plugin (needs GODOT_BIN env var)
+GODOT_BIN=/path/to/godot ./addons/godot_cli_control/tests/run_gut.sh
+```
+
 ## Documentation
 
 See the [Godot plugin README](https://github.com/ClaymanTwinkle/godot-cli-control/blob/main/addons/godot_cli_control/README.md) for the full RPC reference, activation modes, security model, and known limitations.

{godot_cli_control-0.2.1 → godot_cli_control-0.2.2}/addons/godot_cli_control/bridge/game_bridge.gd

@@ -46,7 +46,12 @@ func _ready() -> void:
 	# 安全：显式绑 127.0.0.1，避免 Godot TCPServer 默认 "*" 暴露到 LAN
 	var err: Error = _tcp_server.listen(_port, "127.0.0.1")
 	if err != OK:
-		push_error("GameBridge: Failed to listen on port %d: %s" % [_port, error_string(err)])
+		# push_error 在 headless 下只进 Godot 内部 log，不上 stderr。daemon
+		# subprocess 看不到 root cause，超时 30s 后只能报 "GameBridge not ready"。
+		# printerr 直接写 stderr，subprocess 默认透传 → 用户立刻看到端口冲突。
+		var msg: String = "GameBridge: Failed to listen on port %d: %s" % [_port, error_string(err)]
+		push_error(msg)
+		printerr(msg)
 		return
 	print("GameBridge: Listening on ws://127.0.0.1:%d" % _port)
 
@@ -176,8 +181,14 @@ func _handle_message(raw: String) -> void:
 
 
 func _run_async(id: String, handler: Callable, params: Dictionary) -> void:
-	var result: Dictionary = await handler.call(params)
-	_dispatch_result(id, result)
+	# 不能直接 `as Dictionary` —— handler 返回 null 或非 dict 会强转成 null，
+	# 后续 `result.has("error")` 在 null 上引擎错误，**响应永远不会发出**，
+	# 客户端 await 挂死到 timeout。先收原 Variant 自己 type-check。
+	var raw: Variant = await handler.call(params)
+	if not raw is Dictionary:
+		_send_error(id, -32603, "internal: async handler returned non-dict")
+		return
+	_dispatch_result(id, raw as Dictionary)
 
 
 func _dispatch_result(id: String, result: Dictionary) -> void:

{godot_cli_control-0.2.1 → godot_cli_control-0.2.2}/addons/godot_cli_control/bridge/input_simulation_api.gd

@@ -48,6 +48,8 @@ func handle_action_press(params: Dictionary) -> Dictionary:
 	if _combo_active:
 		return _err(1004, "combo in progress")
 	var action: String = params.get("action", "") as String
+	if not InputMap.has_action(action):
+		return _err(1003, "Unknown action: %s" % action)
 	_do_press(action)
 	_pressed_actions[action] = true
 	return {"success": true}
@@ -57,6 +59,8 @@ func handle_action_release(params: Dictionary) -> Dictionary:
 	if _combo_active:
 		return _err(1004, "combo in progress")
 	var action: String = params.get("action", "") as String
+	if not InputMap.has_action(action):
+		return _err(1003, "Unknown action: %s" % action)
 	_do_release(action)
 	_pressed_actions.erase(action)
 	_held_actions.erase(action)
@@ -69,6 +73,8 @@ func handle_action_tap(params: Dictionary) -> Dictionary:
 	if _combo_active:
 		return _err(1004, "combo in progress")
 	var action: String = params.get("action", "") as String
+	if not InputMap.has_action(action):
+		return _err(1003, "Unknown action: %s" % action)
 	var duration: float = params.get("duration", 0.1) as float
 	_do_press(action)
 	_held_actions[action] = duration
@@ -100,6 +106,8 @@ func handle_hold(params: Dictionary) -> Dictionary:
 	if _combo_active:
 		return _err(1004, "combo in progress")
 	var action: String = params.get("action", "") as String
+	if not InputMap.has_action(action):
+		return _err(1003, "Unknown action: %s" % action)
 	var duration: float = params.get("duration", 0.0) as float
 	_do_press(action)
 	_held_actions[action] = duration
@@ -188,6 +196,11 @@ func _begin_combo_step() -> void:
 		_combo_timer = step["wait"] as float
 	elif step.has("action"):
 		var action: String = step["action"] as String
+		if not InputMap.has_action(action):
+			_abort_combo_with_error(
+				1003, "Unknown action at combo step %d: %s" % [_combo_index, action]
+			)
+			return
 		var duration: float = step.get("duration", 0.1) as float
 		_do_press(action)
 		_held_actions[action] = duration

{godot_cli_control-0.2.1 → godot_cli_control-0.2.2}/addons/godot_cli_control/bridge/low_level_api.gd

@@ -3,6 +3,10 @@ extends Node
 ## 低层 API：通用节点操作（click、属性、场景树等）
 
 const _BUILD_TREE_HARD_LIMIT: int = 50
+# 总节点数上限：宽场景（1000+ 子项的 Grid/Container）会构造极大 JSON，
+# 超 outbound buffer（默认 10 MB）后客户端拿到截断包 → STATE_CLOSED 断连。
+# 5000 节点对应 ~500 KB JSON，留足余量。
+const _BUILD_TREE_NODE_LIMIT: int = 5000
 # wait_game_time_async 防呆上限：防止误传 1e9 之类的数值挂死 session
 const _MAX_WAIT_SECONDS: float = 3600.0
 
@@ -99,7 +103,12 @@ func handle_set_property(params: Dictionary) -> Dictionary:
 	var property: String = params.get("property", "") as String
 	if property.is_empty():
 		return _err(-32602, "Missing 'property' parameter")
-	if property in _property_blacklist:
+	# Godot Object.set() 接受 NodePath 形式的子属性（如 "position:x"）。
+	# 精确字符串黑名单会漏掉 "script:source_code" / "texture:resource_path" 这类
+	# 嵌套写入向量 —— 拿 ":" 前的 top-level 名重新过一次黑名单。
+	# 同时整串也走一次（防御深度，万一未来加非冒号语法的反射子路径）。
+	var top_level: String = property.split(":", true, 1)[0]
+	if property in _property_blacklist or top_level in _property_blacklist:
 		return _err(-32602, "Blocked property: %s" % property)
 	var value: Variant = params.get("value", null)
 	node.set(property, value)
@@ -169,7 +178,15 @@ func handle_get_scene_tree(params: Dictionary) -> Dictionary:
 	var root: Node = get_tree().current_scene
 	if root == null:
 		root = get_tree().root
-	var tree: Dictionary = _build_tree(root, max_depth, 0)
+	# counter 用 Array[int] 当 by-ref 计数器：GDScript 没指针/inout，
+	# Array 是引用类型，递归子调用对 counter[0] 的写入对调用方可见。
+	var counter: Array[int] = [0]
+	var tree: Dictionary = _build_tree(root, max_depth, 0, counter)
+	if counter[0] > _BUILD_TREE_NODE_LIMIT:
+		return _err(
+			1004,
+			"scene tree too large (>%d nodes); lower 'depth' or query a subtree" % _BUILD_TREE_NODE_LIMIT,
+		)
 	return {"tree": tree}
 
 
@@ -237,8 +254,11 @@ func _has_property(node: Node, property: String) -> bool:
 	return false
 
 
-## depth=0 表示"无限深度"，使用硬限制 _BUILD_TREE_HARD_LIMIT (50) 防止无限递归
-func _build_tree(node: Node, max_depth: int, current_depth: int) -> Dictionary:
+## depth=0 表示"无限深度"，使用硬限制 _BUILD_TREE_HARD_LIMIT (50) 防止无限递归。
+## counter 是 by-ref 计数器：超过 _BUILD_TREE_NODE_LIMIT 时短路（不再递归子节点），
+## 调用方读 counter[0] > LIMIT 决定是否走 1004 错误路径。
+func _build_tree(node: Node, max_depth: int, current_depth: int, counter: Array[int]) -> Dictionary:
+	counter[0] += 1
 	var entry: Dictionary = {
 		"name": node.name,
 		"type": node.get_class(),
@@ -248,10 +268,13 @@ func _build_tree(node: Node, max_depth: int, current_depth: int) -> Dictionary:
 		entry["visible"] = (node as CanvasItem).visible
 	if "text" in node:
 		entry["text"] = str(node.get("text"))
+	if counter[0] > _BUILD_TREE_NODE_LIMIT:
+		# 超限：不再下递归，但当前 entry 已计入；调用方一次性走错误返回
+		return entry
 	var effective_max: int = _BUILD_TREE_HARD_LIMIT if max_depth == 0 else max_depth
 	if current_depth < effective_max:
 		var children: Array[Dictionary] = []
 		for child: Node in node.get_children():
-			children.append(_build_tree(child, effective_max, current_depth + 1))
+			children.append(_build_tree(child, effective_max, current_depth + 1, counter))
 		entry["children"] = children
 	return entry

godot_cli_control-0.2.2/addons/godot_cli_control/tests/gut/test_game_bridge.gd

@@ -0,0 +1,346 @@
+## GUT 单元测试：GameBridge JSON-RPC 路由器
+##
+## 策略：测试覆盖 _handle_message 的 dispatch 全部分支 —— 不起 TCPServer / WebSocket，
+## 不进 scene tree（避免 _ready 跑 listen()/queue_free）。
+##   1. TestableGameBridge.new() 是 orphan Node；_ready 不触发。
+##   2. 手动塞 _low_level_api / _input_sim_api（StubLowLevelApi / StubInputSimulationApi）
+##      并调 _register_methods()，让方法表指向 stub 的 handler。
+##   3. 子类 override _send_json 把出站帧捕获到 captured_frames，
+##      跳过 _active_peer 状态检查这一现实依赖。
+##   4. 直接调 _handle_message(raw_json_string) 触发路由；async 路径用
+##      await get_tree().process_frame 等待 stub 通过 callback 回响。
+##
+## 这套测试用来拦的回归（最近三个 commit 都改这一带，黑盒测了但缺单测）：
+##   - b1f2ec9: NodePath 子属性黑名单（实际由 LowLevelApi 测 —— bridge 只测路由）
+##   - e7b9768: async type-check（async handler 返回 null/非 dict 必须发 -32603 而非挂死）
+##   - b654259: id/method/params 类型严校验
+extends GutTest
+
+const GameBridgeScript := preload("res://addons/godot_cli_control/bridge/game_bridge.gd")
+const LowLevelApiScript := preload("res://addons/godot_cli_control/bridge/low_level_api.gd")
+const InputSimulationApiScript := preload("res://addons/godot_cli_control/bridge/input_simulation_api.gd")
+
+
+# ── 子类：捕获 _send_json 出站 + 跳过 peer 状态检查 ──────────────────
+
+class TestableGameBridge:
+	extends GameBridge
+	var captured_frames: Array = []
+
+	func _send_json(data: Dictionary) -> void:
+		# 不检查 _active_peer —— 测试场景里它就是 null。直接把帧记下来。
+		captured_frames.append(data)
+
+
+# ── 桩 LowLevelApi：sync / async handler 各覆盖 1 个，返回值由测试预置 ──
+
+class StubLowLevelApi:
+	extends LowLevelApi
+	# 每个 handler 的预置返回值 + 调用记录
+	var click_return: Dictionary = {"success": true}
+	var click_calls: Array = []
+	# 父类签名 -> Dictionary 是静态类型契约，override 不能放宽到 Variant；
+	# async type-guard（返回非 dict）由测试通过外部 Callable 注入到 _methods。
+	var wait_for_node_return: Dictionary = {"found": true}
+	var wait_for_node_calls: Array = []
+
+	func handle_click(params: Dictionary) -> Dictionary:
+		click_calls.append(params)
+		return click_return
+
+	func wait_for_node_async(params: Dictionary) -> Dictionary:
+		wait_for_node_calls.append(params)
+		# 推一帧让调用方真的走 await 路径
+		await get_tree().process_frame
+		return wait_for_node_return
+
+
+# ── 桩 InputSimulationApi：sync handler + async_with_id（combo） ──
+
+class StubInputSimulationApi:
+	extends InputSimulationApi
+	var press_return: Dictionary = {"success": true}
+	var press_calls: Array = []
+	# combo 控制：测试通过 finish_combo() 决定何时回响 + 返回什么
+	var combo_calls: Array = []  # [{params, request_id}]
+	var combo_callback: Callable = Callable()
+
+	func setup(send_response: Callable) -> void:
+		# GameBridge._ready 调 setup() 时不会跑（orphan 实例），但
+		# _register_methods 之前测试会手动调一次。
+		combo_callback = send_response
+
+	func handle_action_press(params: Dictionary) -> Dictionary:
+		press_calls.append(params)
+		return press_return
+
+	func handle_combo(params: Dictionary, request_id: String) -> void:
+		# 不立刻回响 —— 把 (params, request_id) 记下来；测试通过 finish_combo
+		# 显式触发 callback，模拟真实 combo 完成路径。
+		combo_calls.append({"params": params, "request_id": request_id})
+
+	func finish_combo(index: int, result: Dictionary) -> void:
+		var entry: Dictionary = combo_calls[index]
+		combo_callback.call(entry["request_id"], result)
+
+
+# ── 测试夹具 ────────────────────────────────────────────────────────
+
+var _bridge: TestableGameBridge
+var _low: StubLowLevelApi
+var _input: StubInputSimulationApi
+
+
+func before_each() -> void:
+	_bridge = TestableGameBridge.new()
+	# orphan：不 add_child 到 tree → _ready 不触发 → 跳过 listen() / queue_free
+	autofree(_bridge)
+
+	# 但 stub APIs 需要在 tree 内才能 await get_tree().process_frame
+	_low = StubLowLevelApi.new()
+	_low.name = "LowLevelApi"
+	add_child_autofree(_low)
+	_input = StubInputSimulationApi.new()
+	_input.name = "InputSimulationApi"
+	add_child_autofree(_input)
+
+	_bridge._low_level_api = _low
+	_bridge._input_sim_api = _input
+	# InputSim 的 callback：bridge 的 _on_async_response 把 (id, result) 转回 dispatch
+	_input.setup(_bridge._on_async_response)
+	_bridge._register_methods()
+
+
+# ── helper ──
+
+func _send(raw: String) -> void:
+	_bridge._handle_message(raw)
+
+
+func _last_frame() -> Dictionary:
+	assert_true(_bridge.captured_frames.size() > 0, "应该至少有一个出站帧")
+	return _bridge.captured_frames[-1]
+
+
+# ── JSON / 协议层校验：-32600 ──────────────────────────────────────
+
+func test_invalid_json_emits_minus_32600_with_empty_id() -> void:
+	_send("not valid json {{")
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.get("id", "MISSING")), "")
+	assert_has(f, "error")
+	assert_eq(int(f.error.code), -32600)
+	assert_string_contains(str(f.error.message), "Invalid JSON")
+
+
+func test_non_dict_root_emits_minus_32600() -> void:
+	# 合法 JSON 但顶层是 array —— 不是 RPC 请求
+	_send("[1, 2, 3]")
+	var f: Dictionary = _last_frame()
+	assert_eq(int(f.error.code), -32600)
+
+
+func test_id_non_string_emits_minus_32600_with_empty_id() -> void:
+	# id 是数字时无法回响给客户端正确的 id，强制空串 + 协议错
+	_send('{"id": 42, "method": "click", "params": {}}')
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.get("id")), "", "id 非字符串时响应必须用空串而非数字")
+	assert_eq(int(f.error.code), -32600)
+	assert_string_contains(str(f.error.message), "id must be string")
+
+
+func test_method_non_string_emits_minus_32600() -> void:
+	_send('{"id": "x", "method": 123, "params": {}}')
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.id), "x")
+	assert_eq(int(f.error.code), -32600)
+	assert_string_contains(str(f.error.message), "method must be string")
+
+
+func test_method_empty_emits_minus_32600() -> void:
+	_send('{"id": "x", "method": "", "params": {}}')
+	var f: Dictionary = _last_frame()
+	assert_eq(int(f.error.code), -32600)
+	assert_string_contains(str(f.error.message), "Missing method")
+
+
+func test_params_non_dict_emits_minus_32600() -> void:
+	# params 是 array —— handler 内 .get 会崩，必须在路由层挡住
+	_send('{"id": "x", "method": "click", "params": [1, 2]}')
+	var f: Dictionary = _last_frame()
+	assert_eq(int(f.error.code), -32600)
+	assert_string_contains(str(f.error.message), "params must be object")
+
+
+func test_params_missing_treated_as_empty_dict() -> void:
+	# params 缺失 → handler 拿到空 dict（合法），不应报协议错
+	_send('{"id": "x", "method": "click"}')
+	var f: Dictionary = _last_frame()
+	assert_does_not_have(f, "error")
+	assert_eq(_low.click_calls.size(), 1)
+	assert_eq(_low.click_calls[0].size(), 0, "params 缺失应等价空 dict")
+
+
+func test_id_missing_defaults_to_empty_string() -> void:
+	# 客户端用 "" 当 fire-and-forget id；缺省也走这条路径，响应 id 也是 ""
+	_send('{"method": "click", "params": {}}')
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.get("id")), "")
+	assert_does_not_have(f, "error")
+
+
+# ── 方法层校验：-32601 ────────────────────────────────────────────
+
+func test_unknown_method_emits_minus_32601() -> void:
+	_send('{"id": "x", "method": "no_such_method", "params": {}}')
+	var f: Dictionary = _last_frame()
+	assert_eq(int(f.error.code), -32601)
+	assert_string_contains(str(f.error.message), "Unknown method")
+
+
+# ── sync 路径 ─────────────────────────────────────────────────────
+
+func test_sync_handler_success_emits_result_frame() -> void:
+	_low.click_return = {"success": true, "node_class": "Button"}
+	_send('{"id": "abc", "method": "click", "params": {"path": "/root/Btn"}}')
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.id), "abc")
+	assert_has(f, "result")
+	assert_does_not_have(f, "error")
+	assert_eq(f.result.success, true)
+	assert_eq(str(f.result.node_class), "Button")
+	# 参数透传到 stub
+	assert_eq(_low.click_calls[0].get("path"), "/root/Btn")
+
+
+func test_sync_handler_error_dict_emits_error_frame() -> void:
+	# handler 主动返回 {"error": {...}} —— _dispatch_result 应识别并发 error 帧
+	_low.click_return = {"error": {"code": 1001, "message": "Node not found"}}
+	_send('{"id": "x", "method": "click", "params": {"path": "/missing"}}')
+	var f: Dictionary = _last_frame()
+	assert_has(f, "error")
+	assert_does_not_have(f, "result", "error 路径不应同时带 result")
+	assert_eq(int(f.error.code), 1001)
+	assert_eq(str(f.error.message), "Node not found")
+
+
+# ── async 路径 ────────────────────────────────────────────────────
+
+func test_async_handler_success_emits_result_frame() -> void:
+	_low.wait_for_node_return = {"found": true}
+	_send('{"id": "wait1", "method": "wait_for_node", "params": {"path": "/X", "timeout": 1.0}}')
+	# stub 的 await get_tree().process_frame 让响应延后一帧；推两帧足够
+	await get_tree().process_frame
+	await get_tree().process_frame
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.id), "wait1")
+	assert_has(f, "result")
+	assert_eq(f.result.get("found"), true)
+
+
+func _async_returning_null(_params: Dictionary) -> Variant:
+	# 故意返回非 Dictionary 触发 _run_async 的 type-guard。
+	# 父类 LowLevelApi.wait_for_node_async 签名锁死 -> Dictionary，没法在 stub 里
+	# 直接 override 类型放宽，绕道：测试通过 Callable 注入 _methods 项。
+	await get_tree().process_frame
+	return null
+
+
+func _async_returning_string(_params: Dictionary) -> Variant:
+	await get_tree().process_frame
+	return "oops"
+
+
+func test_async_handler_returning_non_dict_emits_minus_32603() -> void:
+	# 关键回归（commit e7b9768）：async handler 返回 null / 字符串 → 必须发
+	# -32603，不能让响应永远不发，否则客户端 await 挂死到 30s timeout。
+	_bridge._methods["wait_for_node"] = {
+		"callable": _async_returning_null,
+		"kind": "async",
+	}
+	_send('{"id": "wait_null", "method": "wait_for_node", "params": {}}')
+	await get_tree().process_frame
+	await get_tree().process_frame
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.id), "wait_null")
+	assert_has(f, "error", "async handler 返回 null 必须落到 -32603 错误")
+	assert_eq(int(f.error.code), -32603)
+	assert_string_contains(str(f.error.message), "non-dict")
+
+
+func test_async_handler_returning_string_emits_minus_32603() -> void:
+	# 防御性：handler 不小心 return "" 也走 type-guard
+	_bridge._methods["wait_for_node"] = {
+		"callable": _async_returning_string,
+		"kind": "async",
+	}
+	_send('{"id": "wait_str", "method": "wait_for_node", "params": {}}')
+	await get_tree().process_frame
+	await get_tree().process_frame
+	var f: Dictionary = _last_frame()
+	assert_eq(int(f.error.code), -32603)
+
+
+# ── async_with_id 路径（input_combo） ──────────────────────────────
+
+func test_async_with_id_routes_request_id_to_handler() -> void:
+	_send('{"id": "combo1", "method": "input_combo", "params": {"steps": [{"action": "a", "duration": 0.1}]}}')
+	# handler 不立即响应：captured_frames 应为空
+	assert_eq(_bridge.captured_frames.size(), 0, "input_combo 是 async_with_id，不应同步发响应")
+	assert_eq(_input.combo_calls.size(), 1)
+	assert_eq(str(_input.combo_calls[0].request_id), "combo1")
+	# 触发 callback 回响
+	_input.finish_combo(0, {"success": true, "completed_steps": 1})
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.id), "combo1")
+	assert_has(f, "result")
+	assert_eq(int(f.result.completed_steps), 1)
+
+
+func test_async_with_id_error_callback_emits_error_frame() -> void:
+	# combo handler 通过 callback 回 error dict → bridge 应转成 error 帧
+	_send('{"id": "combo_err", "method": "input_combo", "params": {"steps": []}}')
+	_input.finish_combo(0, {"error": {"code": 1004, "message": "combo in progress"}})
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.id), "combo_err")
+	assert_has(f, "error")
+	assert_eq(int(f.error.code), 1004)
+
+
+func test_async_with_id_id_isolation_across_concurrent_requests() -> void:
+	# 三个 combo 请求并发，回调乱序触发：每条响应必须用对应的原始 id
+	_send('{"id": "c1", "method": "input_combo", "params": {"steps": []}}')
+	_send('{"id": "c2", "method": "input_combo", "params": {"steps": []}}')
+	_send('{"id": "c3", "method": "input_combo", "params": {"steps": []}}')
+	assert_eq(_input.combo_calls.size(), 3)
+	# 乱序回响
+	_input.finish_combo(1, {"success": true, "marker": "second"})
+	_input.finish_combo(0, {"success": true, "marker": "first"})
+	_input.finish_combo(2, {"success": true, "marker": "third"})
+	# 收集 (id, marker) 对，验证配对正确
+	var pairs: Dictionary = {}
+	for f in _bridge.captured_frames:
+		pairs[str(f.id)] = str((f.result as Dictionary).get("marker", ""))
+	assert_eq(pairs.get("c1"), "first")
+	assert_eq(pairs.get("c2"), "second")
+	assert_eq(pairs.get("c3"), "third")
+
+
+# ── 边界：空 id 仍是合法的 fire-and-forget ─────────────────────────
+
+func test_empty_id_fire_and_forget_still_routes() -> void:
+	# id="" 是合约：客户端不等响应，但 bridge 仍按协议发响应（带 id=""）
+	_send('{"id": "", "method": "click", "params": {"path": "/x"}}')
+	var f: Dictionary = _last_frame()
+	assert_eq(str(f.id), "")
+	assert_has(f, "result")
+
+
+# ── 注册表完整性：断 sync 实际有路由（防 _register_methods 退化） ────
+
+func test_sync_input_action_press_routes_to_input_sim_api() -> void:
+	_send('{"id": "p1", "method": "input_action_press", "params": {"action": "jump"}}')
+	var f: Dictionary = _last_frame()
+	assert_does_not_have(f, "error")
+	assert_eq(_input.press_calls.size(), 1)
+	assert_eq(str(_input.press_calls[0].action), "jump")

{godot_cli_control-0.2.1 → godot_cli_control-0.2.2}/addons/godot_cli_control/tests/gut/test_input_simulation_api.gd

@@ -8,11 +8,25 @@ const InputSimulationApiScript := preload("res://addons/godot_cli_control/bridge
 
 var _api: Node
 
+# combo / hold 状态机测试用占位 action。InputMap 不预设这些，由 fixture 注册。
+const _FIXTURE_ACTIONS: Array[String] = ["a", "b", "alpha", "beta"]
+
 
 func before_each() -> void:
 	_api = InputSimulationApiScript.new()
 	_api.name = "InputSimulationApi"
 	add_child_autofree(_api)
+	# #25 修复后 handle_action_press/release/hold 会拒未注册 action（1003）。
+	# 状态机测试关心 combo / 互斥语义，不验 InputMap 校验，先把 fixture action 注册。
+	for name in _FIXTURE_ACTIONS:
+		if not InputMap.has_action(name):
+			InputMap.add_action(name)
+
+
+func after_each() -> void:
+	for name in _FIXTURE_ACTIONS:
+		if InputMap.has_action(name):
+			InputMap.erase_action(name)
 
 
 # ── action_press / action_release / action_tap ────────────────────
@@ -34,6 +48,54 @@ func test_tap_uses_held_track_not_pressed() -> void:
 	assert_false("ui_accept" in _api.get_pressed_actions())
 
 
+# ── unknown action 校验（不在 InputMap 内） ─────────────────────────
+
+func test_press_unknown_action_returns_1003() -> void:
+	# 拼错 action 必须立刻返回错误，不能静默成功污染 _pressed_actions
+	var bogus: String = "__definitely_not_an_action__"
+	assert_false(InputMap.has_action(bogus))
+	var result: Dictionary = _api.handle_action_press({"action": bogus})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), 1003)
+	assert_false(bogus in _api.get_pressed_actions(), "失败时不能进 pressed 列表")
+
+
+func test_release_unknown_action_returns_1003() -> void:
+	var bogus: String = "__not_an_action_release__"
+	var result: Dictionary = _api.handle_action_release({"action": bogus})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), 1003)
+
+
+func test_tap_unknown_action_returns_1003() -> void:
+	var bogus: String = "__not_an_action_tap__"
+	var result: Dictionary = _api.handle_action_tap({"action": bogus, "duration": 0.1})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), 1003)
+	assert_false(bogus in _api.get_pressed_actions())
+
+
+func test_hold_unknown_action_returns_1003() -> void:
+	var bogus: String = "__not_an_action_hold__"
+	var result: Dictionary = _api.handle_hold({"action": bogus, "duration": 1.0})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), 1003)
+	assert_false(_api.has_active_holds())
+
+
+func test_combo_unknown_action_aborts_with_1003() -> void:
+	# combo step 引用未注册 action：必须 abort 整盘并通过 request_id 回 1003，
+	# 否则 _combo_active 卡 true 后续全 1004。
+	var probe := _ComboCallbackProbe.new()
+	_api.setup(probe.record)
+	_api._combo_request_id = "req-bogus"
+	_api.start_combo([{"action": "__bogus_action__", "duration": 0.1}])
+	assert_false(_api.is_combo_active())
+	assert_eq(probe.calls.size(), 1)
+	assert_has(probe.calls[0].result, "error")
+	assert_eq(int(probe.calls[0].result.error.code), 1003)
+
+
 # ── combo 状态机 ──────────────────────────────────────────────────
 
 func test_press_blocked_during_combo() -> void: