---
description: Godot 测试脚本的 headless、隔离、确定性与退出码规范
globs: "**/*test*.gd"
alwaysApply: false
---

# Godot 测试

## 运行原则

- 领域逻辑应能在无窗口、无 UI 和无渲染依赖的环境中验证。
- 运行前按项目声明确定 Godot 版本、可执行文件和测试入口；不假设固定目录、场景名或脚本命名。
- 项目已有测试框架或统一入口时必须复用。没有时采用最小可执行入口；引入第三方框架前遵守依赖确认规则。
- 自动化测试成功返回退出码 0，失败返回非零；不得仅依赖日志文本判断结果。
- 性能与超时断言应测量被测逻辑本身，避免输出管道、编辑器启动和资源导入污染计时。

## 用例约束

- 每个用例独立设置并清理状态，不依赖执行顺序或前一个用例留下的 autoload、缓存、随机种子和文件。
- 随机、时间和异步流程使用可控种子、可注入时钟或明确超时，避免无限等待。
- 优先断言公开行为、信号参数和持久化结果，不绑定私有实现细节。
- 纯逻辑用例不实例化 UI、3D 或特效场景；只有验证集成边界时才加载必要场景。
- 失败信息包含期望值、实际值和关键实体标识，便于在 headless 日志中定位。

## 变更要求

- 修复缺陷时先补可复现用例，或说明为何无法自动化。
- 新增逻辑系统时覆盖正常路径、边界输入、失败路径和状态重置。
- 数据 schema、存档版本、信号契约或项目配置变化时同步更新相关回归测试。