AI自动跑测试与截屏验证Godot AI test_run测试框架入门到进阶【免费下载链接】godot-aiProduction-grade MCP server and AI tools for the Godot engine. A Snap to install. Totally free and fun.项目地址: https://gitcode.com/gh_mirrors/go/godot-aiGodot AI 是一款面向 Godot 引擎的 MCP 服务器与 AI 工具集其核心工具test_run让 AI 能在运行中的 Godot 编辑器里自动编写、运行测试并做截屏验证。你只需说一句“跑一下测试把失败的修好”AI 就会自动发现测试文件、执行断言、汇总失败详情——无需再手动 F5 盯着屏幕看结果。一、什么是 test_run 测试框架test_run 是 Godot AI 的官方编辑器内 GDScript 测试入口它扫描当前打开项目中res://tests/下所有test_*.gd文件自动实例化继承自McpTestSuite的测试类运行全部test_*方法并返回包含通过/失败/跳过统计的结构化结果。与传统 CI 不同test_run 直接跑在编辑器里因此能验证场景、节点、EditorInterface甚至编辑器撤销栈。典型工作流对 AI 说“给玩家控制器写一个测试套件并运行”AI 通过script_create创建res://tests/test_player.gdAI 调用test_run读取失败列表并修改代码循环直到全部通过0 failures。上面这个演示由 AI 在编辑器内完成test_run 正是这类成果构建后的自动化验证手段。二、三步写出你的第一个测试第 1 步写测试类。继承McpTestSuite提供suite_name()每个测试方法以test_开头按字母序执行。框架自带一套断言assert_true、assert_eq、assert_gt、assert_contains、assert_is_error等。tool extends McpTestSuite func suite_name() - String: return player func test_speed_positive() - void: var player track(preload(res://player/player.tscn).instantiate()) assert_gt(player.speed, 0.0, 速度必须为正数)第 2 步放对路径。文件必须命名为test_*.gd并直接放在res://tests/顶层不扫描子目录。加载失败的文件会进入load_errors不会拖垮其余套件。第 3 步调用 test_run。对 AI 说“跑一下 player 测试套件”它会自动执行test_run(suiteplayer)。⚠️ 两条重要规则测试方法必须同步不能用await——否则测试会在第一个 await 处挂起后续断言永远不执行前置条件不满足时调用skip(reason)。以 0 个断言完成的测试会被判定为失败。完整 API生命周期钩子suite_setup/setup/teardown、track()自动清理、editor_undo编辑器撤销等见 docs/testing.md基类源码在 test_suite.gd。三、test_run 参数进阶精准控制测试范围test_run不只是“全量跑一遍”官方定义在 tools/testing.py参数作用典型用法suite只跑指定套件精确匹配suite_name()suitescenetest_name只跑名称包含该子串的测试test_namespeedexclude_test_name跳过匹配逗号分隔子串的测试exclude_test_nameslow,flakyverbose返回每个测试的明细含duration_ms定位慢测试session_id多编辑器连接时指定目标多 worktree 场景结果解读。默认返回紧凑摘要只含失败项{ passed: 12, failed: 1, skipped: 2, total: 15, duration_ms: 240, failures: [ {suite: player, test: test_speed_positive, passed: false, message: Expected 0.0 0.0} ], edited_scene: res://main.tscn }不重跑也能取回上次结果test_manage(opresults_get)或直接读资源godot://test/results。两个聪明的防误报提示。scene_warning若编辑器当前打开的场景不是项目主场景且有失败响应会明确警告——很多套件假设主场景已打开先用scene_open切回去重跑再判断是否真回归cache_warning源码编辑后 preload 的 GDScript 依赖可能过期此时应重启编辑器再信任结果。四、300 秒超时预算与长测试套安全机制长测试套件是经典坑编辑器主线程被占满、AI 会话断线。Godot AI 的解法300 秒总预算随命令下发插件在临期前 10 秒自动于测试之间中止返回TEST_RUN_TIMEOUT错误并附带已跑出的部分摘要完整部分结果仍可通过test_manage(opresults_get)取回实时运行期间会在测试之间服务 WebSocket 传输长套件不会饿死连接单个测试体请控制在 20 秒内用verbosetrue的duration_ms揪出慢测试test_run不允许出现在batch_execute里——批处理是同步执行、没有传输服务直接调用即可。中止、部分结果、场景标注等处理逻辑都在 test_handler.gd 中实现。五、截屏验证让 AI “看见”游戏画面测试验证状态截屏验证外观。editor_screenshot支持四种捕获源source捕获内容适用场景viewport默认编辑器 3D 视口3D 场景取景、相机机位viewport_2d编辑器 2D 视口当前平移/缩放2D 场景布局cinematic用激活的Camera3D渲染特定相机视角无编辑器 Gizmogame运行中游戏的帧缓冲运行时菜单、粒子、游戏内 UI 动画运行时 UI 截屏的典型流程比如验证主菜单project_run(modecurrent)启动游戏轮询editor_state等is_playingtrue且game_capture_readytrue——该标志只会在游戏内助手完成握手后变 true不要盲目 sleep按需交互点击、改属性editor_screenshot(sourcegame)截图project_manage(opstop)停止游戏。 官方建议能用状态断言就别用像素——node_get_properties、node_find、游戏print日志logs_read sourcegame可读比截图更快更稳。截图只留给真正视觉性的断言布局、颜色、粒子爆发、动画姿态。截图超时的完整排查autoload 未注册、游戏不是经project_run启动等见 docs/screenshot-testing.md。六、进阶接入 CI 的完全自动化验证仓库内置了开箱即用的自动化 runnerscript/ci-godot-tests等待插件连接 → 打开主场景 → 执行test_run→ 逐条打印{suite}.{test}: {message}失败详情一条命令完成整套 GDScript 测试script/ci-game-capture-smokeCI 版截图冒烟测试断言已知坐标的像素颜色script/ci-reload-test插件重载 会话持续性验证。提交前的完整验证流程见 docs/verification.md测试分层策略见 docs/testing-strategy.md。快速上手小结目标操作首次运行res://tests/test_xxx.gd继承McpTestSuite调用test_run只跑单套件test_run(suiteplayer)取上次结果不重跑test_manage(opresults_get)或读godot://test/results3D / 2D 场景截图editor_screenshot(sourceviewport / viewport_2d)运行中游戏截图project_run→ 等game_capture_ready→editor_screenshot(sourcegame)→stopCI 自动化script/ci-godot-tests现在你可以直接对 AI 说“为存档系统写测试套件、跑一遍、修复所有失败再截屏验证 UI”——这条完整的自动化闭环正是 Godot AI test_run 框架的设计初衷。【免费下载链接】godot-aiProduction-grade MCP server and AI tools for the Godot engine. A Snap to install. Totally free and fun.项目地址: https://gitcode.com/gh_mirrors/go/godot-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考