本文说明扩展的测试分层、运行方法和用到的环境变量。扩展的测试用 vitest,放在 vscode/test/;vscode/tools/test/ 是维护脚本的测试,apps/sb2000/disk/test/ 是软盘镜像脚本的测试,都用 Node 内置的 node:test,由 npm run test:tools 运行。
在 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/)时,需要真实工具的用例会跳过,并在跳过说明里写明原因;纯逻辑的用例不受影响。
| 变量 | 作用 |
|---|---|
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,只用于开发脚本,不用于扩展。
测试按功能目录放在 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 的磁盘构建)。
real-emulator 的用例把程序载入调试模式的 Ember,运行 60 帧后用 output.screenshot 截图并核对 PNG 文件头。emu_launch、emu_load、emu_record(CDL)、emu_run 得到 CDL 文件,导入由 NES hello 建立的反汇编工程,再追踪得到代码;指令轨迹与调用记录的导入用手工写的记录文件测试(disasm-records)。apps/sb2000/hwtest 实际运行并截图核对;SB2000 运行库的屏幕输出由 sb2000-library 的用例在 Ember 里覆盖。sb_test_stop 设断点),不对函数入口设执行断点,原因见 08-目标运行库维护 第 2.4 节。下面几项无法自动测试,改动相关代码后手动核对:
fcdev.emulator.path 后运行与调试运行,Ember 窗口打开并载入程序;没有设置时提示去设置里填写。.vsix 在干净的 VS Code 里安装后能构建。