famiclone

测试与验证

本文说明扩展的测试分层、运行方法和用到的环境变量。扩展的测试用 vitest,放在 vscode/test/;vscode/tools/test/ 是维护脚本的测试,apps/sb2000/disk/test/ 是软盘镜像脚本的测试,都用 Node 内置的 node:test,由 npm run test:tools 运行。

1. 运行

在 vscode/ 目录运行:

命令 作用
npm test 运行全部 vitest 测试
npm run typecheck 类型检查(源码与测试)
npm run lint oxlint 检查,有警告即失败
npm run test:tools 运行 vscode/tools/test/ 里维护脚本的测试
npm run check 类型检查、lint、测试、构建与维护脚本的测试
npm run check:package 核对 .vsix 的内容,见 05-发布

结构规则(分层依赖、文件头、注释行宽、vscode 引用范围、功能目录隔离、package.json 与代码的一致性)由 test/structure.test.ts 检查,见 01-软件架构设计 第 5 节。

找不到 cc65 工具链(vscode/toolchain/)时,需要真实工具的用例会跳过,并在跳过说明里写明原因;纯逻辑的用例不受影响。

2. 环境变量

变量 作用
FCDEV_TEST_EMULATOR 指向 Ember 的可执行文件(如 build/ember/win32/app/Release/ember-win.exe 或发布出来的 Ember.exe);设置后额外运行“真实 Ember”的用例(还需要 cc65 工具链),不设置就整组跳过。只在测试里读取,扩展本身只用设置 fcdev.emulator.path
FCDEV_TEST_FIRMWARE 指向 SB2000 的 BIOS 文件,用于“SB2000 程序在 Ember 里运行”的用例;没有设置时用仓库里的 ember/roms/sb2000_bios.bin
FCDEV_TEST_NES_ROM 指向一个 NROM 的 .nes 文件;设置后额外对它做完整反汇编与回读
FCDEV_SKIP_GUI_TESTS 设为 1 时跳过会打开 Ember 窗口的用例

仓库里的 Node 脚本(tools/extension.mjs 的 emberExecutable)用环境变量 EMBER_EXE 指向 Ember,只用于开发脚本,不用于扩展。

3. 测试分层

测试按功能目录放在 vscode/test/<层>/,与源码的层同名:

目录 内容
shared/ 纯函数:ca65 解析与行记号、汇编参考、C/C++ 配置生成、构建文字与源文件 UTF-8 转 GB2312(不在 GB2312 里的字符报错并写出文件、行、列)、C 接口函数的解析、调试客户端的请求目录与参数解析与协议参考、反汇编的指令表与解码(全部 151 条指令)、映像格式、布局、区域、工程模型、十六进制视图、交叉引用与图形数据检测、打包器与 FAT12 镜像、项目配置、新建项目的文件、目标描述、使用文档的主题登记
logic/build/ 构建计划的路径规则、增量与错误提示、真实 cc65 构建(集成)、全部样例项目与五个模板都能构建、构建同时生成磁盘镜像(镜像里有程序与 disk 目录文件、disk 为 false 不生成、子目录与重名报错)、学习机 C 与汇编程序的文件头、大小与内存布局(运行库一个函数一个目标文件、链接只带用到的函数、多页程序的文件页序、库页不够与超过上限的提示、汉字变成 GB2312 字节且错误信息仍指向原文件)
logic/disassembly/ 反汇编的管线(disasm-pipeline)、源码生成与回读(随机字节、换页布局)、操作与输入检查、记录文件的导入、指令轨迹、与构建服务产物的比较、反汇编 skill 八步的工作流(在 apps/disasm-example 上走一遍并断言每步的完成标准,需要 cc65)
logic/emulator/ 开机步骤、启动(端口检查、用户数据目录、就绪等待与超时、提前退出)、程序运行(NES 与学习机方案、缺少固件报错、找不到 Ember 报错)、11 个模拟器工具对应的操作(会话与参数、运行、断点、单步、内存与寄存器、反汇编、截图、输入、记录、载入),都用假的调试客户端
logic/debug-client/ 二进制帧解码、RPC 会话(编号、匹配、超时、关闭)、调试客户端(握手的协议版本、请求、事件)
logic/ 其他 汇编智能感知、C/C++ 配置同步、项目配置读取与描述、目标仓库与目标描述读取、新建项目、使用文档与 C 接口查询
infra/ 工具链定位(缺失与不完整的报错)、端点文件的查找与过期判断、Ember 进程的启动与结束、C/C++ 配置检查
entry/ 汇编语言功能、构建任务(任务定义、问题匹配器、运行)、C/C++ 同步命令、反汇编工具、fcdev 工具的定义与声明一致
real-emulator/ 真实 Ember:调试模式载入 NES 程序、运行 60 帧、截图;“载入 NES 程序、记录 CDL、导入反汇编工程、再追踪”的闭环;SB2000 运行库的测试程序(约 15 个用例,共数百项检查)经调试服务运行整机,需要 Ember、cc65 与 BIOS,缺一就整组跳过,见 sb2000/01-开发指南 第 12 节
syntaxes/ ca65 的 TextMate 语法
根目录 structure.test.ts、chat-contributions.test.ts(智能体、指令、skill 与工具清单的一致性)

仓库根 vscode/tools/test/ 的 6 个文件:cc65-tools(vscode/third_party/cc65/ 里的必要路径与工具链的校验值)、sb2000-api(接口检查:函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因;入库的 api-reference.md 与头文件生成的结果一致)、sb2000-header(入库的 sb2000-symbols.h 与生成结果一致)、sb2000-symbols-doc(入库的 symbols-reference.md 与 sb2000.inc 的生成结果一致、符号个数相符)、sb2000-examples-doc(入库的 examples-source.md 与示例项目的生成结果一致、每个示例都有一节且源码完整)、sb2000-disk-build(apps/sb2000/disk 的磁盘构建)。

4. 模拟器验证

5. 手动验证

下面几项无法自动测试,改动相关代码后手动核对: