本页目录

GUT —— Godot 引擎单元测试框架

Gut · bitwes/Gut

GUT(Godot Unit Test)是面向 Godot 引擎的单元测试框架,让你用 GDScript 为 GDScript 代码编写测试。按仓库说明,9.x 版本对应 Godot 4.x,7.x(当前 7.4.2)对应 Godot 3.x;文档托管在 gut.readthedocs.io。项目以 GDScript 编写,...

其他 Cocos Creator JavaScript 角色控制 游戏状态管理 中级
★ Stars 2,786 Forks 155 License 未明确 更新 2026-11-18

国内开发环境适配

Windows
AI 推断/待核验
Linux
AI 推断/待核验
macOS
AI 推断/待核验
引擎 / 框架:Cocos Creator 暂无中文教程标记 未标记站长实测
README 中的下载链接指向 GitHub Releases 与 GitHub 归档包,Asset Library 链接指向 godotengine.org,文档托管在 readthedocs.io,国内访问这几处可能需要自行处理网络问题;GUT 本身是纯 GDScript 插件,无额外二进制依赖,但需与 Godot 大版本严格匹配(9.x 对 4.x、7.x 对 3.x)。具体网络与版本细节待核验。

中文项目介绍

GUT 全称 Godot Unit Test,是面向 Godot Engine 的单元测试框架。它最大的特点是“用 GDScript 测 GDScript”:测试代码与业务代码使用同一种语言编写,无需引入额外的语言运行时或外部测试工具链,即可在 Godot 项目内部完成测试的编写与执行。

GUT 以 Godot 插件形式存在,在仓库中被归类为 tool(工具)类型:安装后会在编辑器中提供测试运行面板,同时也可以通过命令行方式驱动测试。项目本身使用 GDScript 编写,文档托管在 https://gut.readthedocs.io/ ,并按版本提供对应的文档快照。

版本对应关系是使用 GUT 前必须先确认的一点:

  • GUT 9.x 系列面向 Godot 4.x;
  • GUT 7.x 系列(当前 7.4.2)面向 Godot 3.x。

核心功能

简易安装

可通过 Asset Library 安装,也可以下载 zip 后手动放入项目。

丰富的断言与工具方法

帮助把测试写得简短、清晰。

内部测试类(Inner Test Classes)

在同一个测试脚本内组织多组测试,为测试补充上下文并提升可维护性。

Doubling 体系

支持 Full Doubles(完整替身)与 Partial Doubles(部分替身),并配合 Stubbing(打桩)与 Spies(调用监视)。

命令行界面(CLI)

除了编辑器面板,还能用命令行方式运行测试。

参数化测试

同一段测试逻辑可对多组输入重复执行。

结果导出

可将测试结果导出为标准 JUnit XML 格式,便于接入外部 CI 或报告工具。

编辑器面板

README 中展示了 GUT 面板截图,测试可在编辑器内直接运行与查看。

补充说明

版本与 Godot 对应关系

README 给出了一张版本对照表,方便按自己使用的 Godot 版本挑选合适的 GUT 发行版:

GUT 版本 适用 Godot 版本 备注
9.7.1 4.7.x 对应 godot_4_7 分支
Main 分支 4.6.x 开发主线
9.6.1 4.6.x 已在 Asset Library 上架
9.5.0 4.5.x
9.4.0 4.3.x – 4.4.x
9.3.0 4.2.x
9.1.1 4.1.x
9.0.1 4.0.x
7.4.3 3.5.x 已在 Asset Library 上架

需要注意的是,Godot Asset Library 中只保留两个 GUT 条目(一个给 Godot 3、一个给 Godot 4)。如果你当前使用的 Godot 版本低于 Asset Library 中该 GUT 版本所要求的最低版本,GUT 就不会出现在 Asset Library 的搜索结果里,此时需要按上表的下载链接手动获取对应版本。

安装与快速上手

从 zip 包手动安装的流程在 README 中写得很直接:

  1. 下载 zip 并解压;
  2. 把解压得到的 addons/gut 目录放入你的 Godot 项目;
  3. 在项目中启用 GUT 插件;
  4. 重新启动 Godot。

README 的快速上手部分按“安装 → 快速开始 → 创建测试 → 断言与方法”的顺序给出了四篇文档入口,建议按这个顺序阅读:先完成安装,再跑通第一个测试,然后学习如何组织测试脚本,最后查阅断言与工具方法清单,把常用断言用熟。

命令行与编辑器集成

除了在 Godot 编辑器内通过面板运行测试,GUT 还提供 CLI,可用于脚本化、自动化的测试执行场景。

此外,作者维护了一个 VSCode 扩展:在 VSCode 扩展市场搜索 gut-extension 即可找到,它提供运行整套测试套件、运行单个测试脚本、运行单个测试三类命令,相关资源包括 Visual Studio Marketplace 页面、独立的 GitHub 仓库以及一段安装与使用教程视频。对于习惯在 VSCode 中写 GDScript 的开发者,这是一个减少编辑器来回切换的选择。

文档与支持作者

GUT 的完整文档托管在 https://gut.readthedocs.io/ ,并按发行版本提供独立文档地址(例如 v9.7.1、v9.6.1、v7.4.2 等),升级或回退版本时应对应查阅相同版本的文档,避免 API 差异带来的困惑。README 中也说明,如果希望支持 GUT 的持续开发,可以通过 buy me a coffee 的方式进行赞助。

许可证

GUT 以 MIT 许可证发布,许可证文件位于仓库的 addons/gut/LICENSE.md。在商业或闭源项目中使用时,仍需按 MIT 条款保留版权与许可声明;具体以仓库中的许可证原文为准。

适用场景提示

从定位看,GUT 更适合已经使用 Godot 4.x 或 3.x、并希望为游戏逻辑(数据计算、状态管理、规则判定等)建立回归测试的团队与个人。它解决的是“代码级验证”问题,不能替代手工试玩与关卡体验测试。实际引入时建议先确认 Godot 版本与 GUT 版本的匹配关系,再从少量核心逻辑测试开始,逐步扩展到更完整的测试套件,并结合 JUnit XML 导出接入持续集成流程。

开源许可证与版权说明

许可证标识:未明确。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目