跳至内容

06 测试与验收

所属专题:小岛物语 · Godot 游戏开发

这是开发时的验收手记,不是给玩家列的通关步骤。实现方(Codex)交代码与测试;验收方(Claude)另跑、看图、读 diff,有时故意改坏一条规则。下面的数字与“我看见了什么”,都指相应批次。

6.1 每批固定的验收步骤

① 导入       godot --headless --path . --import              无报错,退出码 0
② 冒烟       godot --headless --path . --quit-after 120      输出 READY 行,无脚本错误
③ 逻辑测试   godot --headless --path . -s tests/run_tests.gd  ALL TESTS PASSED,退出码 0
④ 截图       godot --path . -- --screenshot-test --shot-dir=<目录>
⑤ 亲眼看图   逐张打开截图和素材检查图,对照本批要修的问题
⑥ 读 diff    git diff 核对改动范围:没让改的文件不能动
⑦ 暂存       git add -A 作为下一批的基线(不 commit)

第⑤步对这款游戏尤其要紧。断言查得到指定的逻辑错误,不会帮你判断桥像不像桥;甚至人看图也会漏,栅栏的浅绿块就是换了检查底色才看清的。

第 ⑥ 步防止实现方顺手改了不该改的东西。每批任务书都写明哪些文件不能动,比如 Batch D 要求静态素材、地图、台词全部不变,实现方交付时附了 38 个受保护文件的 SHA-256 对照。

6.2 自动化测试

tests/run_tests.gd 是一个 -s 脚本,直接构造游戏对象来测,不需要手动启动游戏。按模块分为:

测试函数覆盖内容
_test_navigation全部 1344 个可走格连通;220 组随机路线及其平滑路线不穿障碍;门口可达;点到不可达位置的处理
_test_map_layout土路比例 < 15%;70 个物件不落在水里;所有门口可达;只能经过桥过河(关掉所有桥后两岸断开);岸线偏移 ≤ 半格
_test_dialogue每位居民每个池的数量;占位符都能解析;居民互相提及;连续抽取不重复
_test_friendship好感阈值 10 / 25;喜欢的礼物 +3、普通 +1;每天每人只能送一次礼、只加一次聊天好感
_test_inventory_and_shop5 种售价、精确结算、20 格容量、99 堆叠
_test_save存档往返;覆盖写入;当天采空的东西读档后不重刷
_test_walk_frames7 套帧;按距离换帧的循环;折线和分段时间步;停下和对话回到待机;尺寸和脚底;左右脚交替;缺数据时回退
_test_interface_and_voice紧凑 HUD;商店空、一行、多行、滚动的高度;打开商店隐藏对话、关闭后恢复;导出 WAV 与游戏 PCM 逐字节一致
_test_voice_proxy代理字符串解析、优先级、NO_PROXY 匹配
_test_tts282 个清单键与显示文本完全对应(也检查多余键);Python 和 GDScript 的哈希及规范化一致;播放、跳过、淡出、回退;按时、迟到、过期的模拟请求;磁盘缓存;真实网络请求次数为 0
_test_music时段切换、等功率曲线、自循环交叉淡化、对话压低和恢复、换曲目路径、缺失资源、设置滑块和静音、存档格式不变
_test_demo_isolation演示模式不碰存档、只用离线语音、固定台词

测试设计上的几条原则

  • 预期值独立定义。 比如走路帧的预期顺序在测试里单独写一份 a/p/b/p2,不从实现代码里读,避免“实现错了,测试跟着一起错”。
  • 跑真实代码路径。 测试调用真实的纹理加载器和角色移动代码,界面测试操作真实的 UI 节点,而不是单测一个孤立函数。
  • 网络全部替身化。 测试只能通过显式注入的本地 MP3 走请求路径,同时断言真实请求次数为 0。tests/fixtures/voice.mp3 是这个 API 的一次真实返回。
  • 测试和真实用户数据隔离。 见 6.5 的“真实存档污染测试”。

断言数量的增长

批次断言数截图数主要新增
v1901517寻路、对话、好感、背包商店、存档
A901517另有单独的灯光检查脚本
B1221018地图布局、桥、岸线
C1226519界面尺寸、WAV 导出
D1256128走路帧,加 8 张走路序列图
E1459528TTS 全链路
E-fix1491528代理解析、在线增益
F1562729音乐、声音设置
F-fix约 15630–1566029存档隔离、多时段开场
G约 15650–1567029演示模式隔离

表里是当次执行过的断言次数,不是独立用例数,更不是覆盖率。F 之后的音乐曲线逐帧采样,同一组用例在不同帧率下也会计出不同次数。

6.3 截图模式

--screenshot-test 是这个项目的“眼睛”。它在真实窗口里运行游戏,用真实注入的鼠标事件走完一套流程,每一步截图:

01 白天全景 → 01b 声音设置 → 02 点地移动 → 03 河与桥 → 03 对话 → 04 选项 → … → 06 背包
→ 07 商店 → 07b 空商店 → … → 12 夜晚 → 居民回家隐藏 → 睡觉提示 → 15/16 树后/树前遮挡
→ 17 全岛总览 → 18 三人同时走路 → walk_sequence_00–07 走路序列
  • 每张截图对应一个具体的验收点。比如 15_y_sort_behind.png 和 16_y_sort_front.png 对照遮挡;walk_sequence_* 是用真实移动代码每次推进 13 px、裁成 200×200 的连续两个走路循环。
  • 截图模式新建独立会话,不读写正常存档,禁止真实网络请求,随机种子固定。
  • 设计上的意义:AI 验收方没法“玩”游戏,但可以看截图。 截图模式把“玩一遍”变成了可重复的命令。

6.4 变异测试

测试全绿不代表测试有效。v1 验收时,我故意改坏了三处逻辑,看测试能不能抓住:

变异结果
喜欢的礼物好感 +3 改成 +2被抓住
好感等级阈值 10 改成 11被抓住
去掉每日送礼次数限制被抓住

三处都被抓住后还原代码,重跑通过。之后夜曲静音检查也用了同样的思路:新加的检查要能拒绝修复前的版本(实测循环静音 1089 ms),才算有效。

6.5 验收中发现的问题

下面这些问题,实现方的报告里都是“通过”,是验收时发现的。

批次问题怎么发现的根因修复
v1栅栏格子里残留浅绿背景看素材检查图抠图只从四边填充;棋盘格底看不出浅绿封闭空隙共用颜色规则;新增深色底检查图(A1)
v1路灯光偏绿看夜景截图加法/乘法光和绿草地、蓝色环境色相乘改用透明混合的径向 sprite(A2)
v1路是矩形、海岸锯齿、桥顺着河铺看全岛总览地形精度只有一格;地图生成规则不对距离场 + 曲线路 + 横跨河面的桥(B)
v1商店面板大片空白,HUD 铃钱位置别扭看截图面板固定尺寸按内容自适应高度,紧凑 HUD(C)
v1--import 偶发崩溃 0xC0000005自己跑命令和 Codex 同时导入同一个工程,互相干扰不和实现方并发跑引擎;重跑两次正常
E截图测试偶发失败,点击被当成拖动多次重跑截图鼠标按下和松开分在两帧;首帧很慢时,按住期间 _process 的 delta 达到 0.15 s,进入拖动重新寻路的分支,覆盖了点击目标按下和松开在同一轮完成;等渲染、布局、相机和寻路都就绪再操作
E截图测试卡死超时截图时窗口被最小化最小化的窗口 Godot 不渲染,frame_post_draw 永远不触发。我专门复现证实了这一点独立计时器每 0.5 秒检查,最小化时恢复窗口;新增故障注入参数 --screenshot-minimize-test(F)
E游戏内在线配音请求不通当批单独做的联网冒烟游戏组件未沿用生成工具的网络设置允许配置连接方式,另验成功与超时(E-fix)
E在线配音比离线配音小声测响度API 原始 MP3 约 -20 ~ -22 LUFS,离线素材归一化到 -16在线片段 +4.5 dB 补偿(E-fix)
F验收环境报43条失败,隔离环境全过对比两次启动时的用户数据旧测试混入已有存档,开场时段与夹具预期不同,引起连锁失败,并非43个音乐缺陷F-fix 注入 save_path,隔离存档、设置、缓存;只有原档可读时才只读比对前后 SHA-256
F夜曲循环点约 1 秒完全静音检查循环接缝夜曲休止多,最后一小节后半刻意不起新音弦乐 pad 跨小节延音;生成脚本加入 > 250 ms 静音即报错的自检(F-fix)

两个重要的认识

1. 同是两种目录,不是同一项证据。 F 批验收方遇到了已有存档影响开场的故障。F-fix 后,直接启动引擎,分别保留正常用户目录和改指空目录,两次测试都通过;测试世界用的是独立夹具。那一轮沙箱却读不到原来的存档,两个日志都提示不能做字节对照。不能把“两次通过”写成“已证实原档一个字节没变”。详见实现与验收记录。

2. 区分“测试问题”和“产品问题”。 F 批 43 条失败看起来很吓人,但根因分析之后,游戏的加载顺序本身是对的(先读档,再初始化音乐),错的是测试读了不该读的数据。修复时没有改 music.gd,而是改测试的隔离方式。给实现方的修复任务书里,我要求先判断问题属于哪一类,再动手。

6.6 验收经验小结

  1. 验收方要自己跑,不能只看报告。 实现方的报告是“它在它的环境里看到的结果”。
  2. 一定要亲眼看图。 美术和布局问题,测试一条都抓不到。
  3. 用变异测试检验测试。 测试全绿时,故意改坏几处关键逻辑,确认会变红。
  4. 检查要能拒绝坏版本。 新加的检查先拿修复前的版本跑一遍,确认会失败。
  5. flaky 测试要找根因,不要靠重跑。 截图偶发失败最后查出了输入时序和窗口最小化两个真实问题。
  6. 读 diff 控制范围。 每批明确哪些文件不许动,交付时核对。

本文写作中使用了 AI 辅助。文字采用 CC BY-NC-SA 4.0 许可。

最后更新于