Skip to content

08 测试与质量保障 ​

测试被视为代码库的一等公民:纯逻辑在 Node 环境用 Vitest 做单元测试,产品行为用 Playwright-core 驱动无头浏览器对生产预览做端到端验证,性能与体积则由基线与预算在 CI 中把守。

当前基线(2026-10-12 全量 vitest run 实测):

指标数值
单元测试文件173 个(tests/ 下共 177 个 .ts,其中 4 个是共享辅助 / 类型声明模块:vitest.setup.ts、blocks/fixtures.ts、core/opfs-helpers.ts、fixtures/native-esm.d.ts)
单元测试用例2813 通过 + 2 跳过(共 2815;跳过的 2 个用例依赖无头环境不具备的 GPU 条件)
端到端脚本14 个(1 个冒烟脚本 + 13 个 verify-* 脚本);npm run test:e2e 串联其中 11 套,3 个有独立入口
CI 工作流5 条(ci、bench、security、release、deploy)
类型检查tsc --noEmit 严格模式,零发布;npm run lint 实际执行 eslint . 代码风格检查后再跑 tsc --noEmit(并非 lint 等价于 typecheck)

一、单元测试(Vitest) ​

运行方式:npm test(即 vitest run)执行全部单测;npm run verify 先做类型检查再跑单测,是贡献指引中要求保持绿色的组合检查。

测试文件按主题组织在 tests/ 下,根目录与子目录各占一半:

主题文件数覆盖内容
插件运行时与插件族(根目录)85内置插件、科研 / 地理物理 / 环境 / 生物 / 数据插件、结构与化学插件、电磁特征值与流体耦合、三维可视化、插件增强与缺陷回归、沙箱与 cspkg、文件格式路由、Git 适配器、GPU 服务与 WASM、主题包、i18n、可访问性与对比度、引用元数据、PWA、画廊、课程、清洗、投稿、存储与运行记录、应用状态库;以及科研级插件套件 32 个插件的内核单测(化学:滴定 / 反应级数 / 图灵斑图,物理:量子求解器 / 伊辛 / 热机 / 扩散 / 衍射 / 轨迹,工程:电路 / 桁架 / 控制,生物与环境:药代 / 孟德尔 / 神经元 / 捕食者-猎物,地学:碳定年 / 土壤水 / 水文,数学:傅里叶 / 域着色 / ODE 场,统计:CLT / 马尔可夫 / Zipf,经济与心理:期权 / 演化博弈 / 信号检测论 / 反应时,天文与数据:凌星 / 赫罗图 / 图像处理)
编辑器与 IR(editor/)15共享 IR 校验与往返、Blockly JSON 与 IR 互转、解释器、JS 与 Python 代码生成、三模式 sync-threeway、积木 i18n、编辑器状态库、Studio API、代码示例,以及 roundtrip-all-langs.test.ts 固化的三语言自由往返
区块系统(blocks/)11数据表运算、区块目录、编译器、执行器、几何、统计区块、文件数据、操作符、可视化桥接、单位
统计内核(stats/)7描述统计、假设检验、多重比较校正、效应量、功效分析、特殊函数、结果叙述转写
平台核心(core/)9计算服务与 WGSL 内核、OPFS 与迁移、错误分类法、校验框架、VFS 路径、Worker 池
状态库(stores/)6project / notebook / experiment / chunk / block / aiPanel
I/O(io/)4HDF5 / NetCDF / FITS / Zarr 加载器与辅助
R 运行时(r/)4运行时工厂、完整运行时回落、DSL、webR 桥
可复现性(repro/)4随机数、运行清单、锁文件(含 v2)、快照
不确定度(uncertainty/)3Bootstrap、蒙特卡洛、MCMC 与诊断
模板(templates/)3学科模板目录、插件脚手架、引导流程
插件签名 / 推断 / 扫描 / 组图各 2签名验证与网站包、贝叶斯模板与 ONNX、设计点展开、持久化与组图
其余单文件模块各 1AI 助手意图、分块读取、数据质量、血缘、模型、笔记本、打包、页面、绘图、画像、报告、信号、SQL、单位

值得注意的测试技术:

技术说明
模块级缓存重置像 WASM 加载器这类带模块级状态的模块,每个用例前用 resetModules 加 doMock 重置,再动态导入新实例,避免用例之间互相污染
FakeWorker 驱动真实运行时插件 Worker 的 RPC 用假 Worker 承载真实的运行时实现,在 Node 里完成端到端往返,无需浏览器
严格模式的陷阱有专门说明new Function 在严格模式下无法同时使用 "use strict" 指令与默认参数值,遗留沙箱为此改用普通参数并显式传 undefined——这类"看起来是风格问题、实则是正确性问题"的点都沉淀在测试注释里
回归用例制度化已修复的插件缺陷沉淀为 pluginBugfixes 等回归用例,i18n 键值在测试中校验齐备,避免复发

二、端到端测试(Playwright-core) ​

每套脚本各自启动 vite preview 生产预览(个别套件例外),驱动无头浏览器,断言真实像素与零控制台错误:

套件端口覆盖内容
smoke-test4173启动、自动加载插件、自动建项目、响应式参数、最近项目恢复
verify-ui4173改版后的功能回归与布局几何:尺寸、主题切换、画布可见性、插件列表
verify-fixes4177自动适配、统一等宽字体、Run 控件开关、顶栏分簇
verify-3d4199宿主 Three.js 场景中的三维点云
verify-plugins4198三维与二维视口可见性互斥、等值线渲染涡旋场、散点与龙卷风示例
verify-webgpu4289(dev server)两阶段:tests/e2e/webgpu.html 在无头 Edge(SwiftShader 软件适配器)中申请真实 WebGPU 设备,用 src/core/wgsl.ts 的真实 WGSL 内核驱动原生核心模块接口(缓冲、内核编译、dispatch、mapAsync 回读),对严格场景与边界场景分别比较 GPU 与 CPU 积分器(容差 5e-3 与 0.02);再在应用内加载粒子插件与星系样例、点击"GPU 计算",断言成功提示上报真实引擎与实测 GPU 时间
verify-block-mode4174积木模式:模式切换、编译、运行、积木到代码同步
verify-code-mode4175Monaco 加 Pyodide:运行 Python、变量面板、控制台、绘图画布
verify-lang-modes4176R / JS 代码模式与跨模式切换、R→JS 互译、Flow ⇄ Block ⇄ Code 无损循环
verify-ai-samples4211样例对话框逐个加载四个 AI 训练样本并捕获提示文案,使解析失败可观测而非靠推断
verify-ai-training4199AI 训练器:超参面板、样例加载、TF.js 真实训练与实时损失曲线、模型切换重置默认超参、逻辑回归决策边界、MNIST CNN 数字缩略图
verify-research4173科研工具链路:启动器 → 运行记录 → 血缘 → 图表工作台 → 补充材料打包 → 笔记本
verify-r-runtime自定webR 完整运行时检查:进入代码模式切换 R 语言后引擎徽标须翻转为完整 R 标签,真实 R 程序打印到控制台;回落时捕获原始导入错误供回落提示展示
verify-site—合并部署产物完整性:本地静态服务器逐路径探测,8 条规范路径全部返回 200 且非空

运行器。npm run test:e2e 即 node scripts/e2e-run.mjs,串联 11 套:smoke-test、verify-ui、verify-fixes、verify-3d、verify-plugins、verify-webgpu、verify-block-mode、verify-code-mode、verify-ai-samples、verify-ai-training、verify-research。运行器带 --continue 语义——某个套件失败后继续跑完其余套件,最后打印 pass / fail 汇总表并在任一失败时以非零码退出,替代了旧 npm 链"首个失败即停"的行为;也支持按名筛选(node scripts/e2e-run.mjs smoke ui)与 --parallel <n> 并发(端口冲突由 harness 自动让位)。

链路与链外。不在上述链内的三个脚本各有独立入口:verify-lang-modes 依赖 Monaco 与 Pyodide 的完整加载(耗时较长),verify-r-runtime 需要 webR vendor 产物在场,npm run verify:site 校验的是合并部署产物而非开发预览(--merge 时先跑 merge-deploy.mjs,再对 pages-out 起本地静态服务器,逐路径断言 8 条规范路径——站点根、favicon、/app/ 工作台、/app/docs/ 文档站与其深页——全部 200 且非空)。

共享 harness。所有套件都走 scripts/_harness.mjs,把过去散落在各脚本里、只在某台机器上成立的三件事统一为"从环境解析并带合理默认值":浏览器可执行路径(按平台列出候选,Edge 优先、Chrome 兜底,CI 可用 CHROME_PATH 钉住)、截图目录(系统临时目录)、预览端口(被占用时自动另取)。harness 同时保证清理,断言失败不会泄漏预览服务或浏览器进程。

贡献指引要求:新插件或新功能必须附带端到端检查。

三、性能基准与体积预算 ​

性能回归靠基线对比而非绝对阈值,且基线按环境分文件:

  • src/core/bench/ 的 runAllBenchmarks() 执行导入 / GPU 内核 / 渲染帧率 / 内存四类关键路径套件,返回含环境信息(Node 版本、平台、架构、CPU 型号、日期)的结构化结果。
  • npm run bench(node --expose-gc scripts/bench-run.mjs && node scripts/bench-compare.mjs && node scripts/bench-report.mjs)在 Node 中无头运行并写入 bench-results.json;scripts/bench-compare.mjs 与基线逐指标比对——bench/baseline.json 面向开发机,bench/baseline.<platform>-<arch>.json(仓库中已有 baseline.linux-x64.json 与 baseline.win32-x64.json)面向 CI,因为共享 Runner 上的数字与开发桌面没有可比性;scripts/bench-report.mjs 产出单文件 HTML 报告。CI 场景用 bench:ci(比对与报告均带 --env-baseline)。
  • 新环境首次运行没有基线时,bench-compare.mjs 记录一份并以 0 退出,由 bench 工作流把该文件提交回仓库,供后续运行真正设门禁。另有两类硬件噪声守卫会重录基线而非误报失败(重录文件故意不提交,避免"每次运行都产生一次提交"的噪声):① Runner 报告的 CPU 型号或 Node 版本与基线不一致;② CPU/Node 字符串相同、但吞吐指标中 ≥75% 同向回归且内存指标全部持平——这是同型号 CPU 被换到不同宿主机(微码/固件/负载不同)的典型签名;选择性或混合方向的真实代码回归不会命中该守卫,仍会正常失败。
  • 体积侧由 scripts/build-budget.mjs 分析构建产物(dist/,合并部署后为 pages-out/app/),对照仓库根的 budget-baseline.json 做门禁(FR-06)。

四、持续集成(5 条工作流) ​

工作流触发关键步骤与门禁
cipush 到 main、所有 PR两个 job。verify:引用元数据检查(FR-10)→ tsc --noEmit → ESLint → npm test → 生成 WASM 存根 → build:web → 性能预算(FR-06)。e2e-smoke:构建后跑 e2e-run smoke ui 两套最快端到端(Runner 自带 Chrome 经 CHROME_PATH 钉住),全套件留在本地。任一步失败即红
benchpush 到 main、发布 Releasenpm run bench:ci(跑基准 + 按环境基线比对)→ 首次运行提交环境基线(该 job 持 contents: write)→ 结果写入 job summary 并上传 artifact;发布时作为附件挂到 Release(FR-23)
securitypush 到 main、PR、每周一 03:00 UTC、手动三个并行 job:OSSF Scorecards(v2.4.4,SARIF 产物留存 30 天)、SBOM 生成(CycloneDX 1.5,由无依赖 Node 脚本从 package-lock.json 生成,留存 90 天)、npm audit(high / critical 阻断合并,带需写明理由与后续 issue 的 AUDIT_ALLOWLIST 豁免机制,豁免项降级为警告)
release推送 v* 标签build:生成 WASM 存根 → build:web → 生成 CITATION.cff → 打包 dist zip;archive:Zenodo 存缴并铸造 DOI,未配置 ZENODO_TOKEN 时显式报错并给出三步配置指引,而不是静默跳过归档;release:发布 GitHub Release,附 zip、CITATION.cff 与 DOI
deploypush 到 main、手动装 Rust(wasm32-unknown-unknown 目标,带缓存)与 wasm-bindgen-cli 0.2.127 → build:wasm 编译真实 WASM → 构建工作台 app/ 与官网根站 → deploy:merge 合并产物 → verify-site 校验 8 条规范路径 → 发布 GitHub Pages

CI 里没有 Rust 工具链(deploy 除外):其余工作流的 dist 由 scripts/make-wasm-stub.mjs 生成模块存根,因为 vite build 会把 src/core/wasm.ts 中的动态导入切成独立 chunk,构建期只需要该 chunk 存在、不需要真实内核。

构建链自带门禁:npm run build = build:wasm && tsc --noEmit && vite build && build-docs,任一步失败即中止;纯前端场景可用 npm run build:web(跳过 WASM 编译,以存根开头)。

五、工程脚本 ​

scripts/ 下 41 个工程脚本(40 个 .mjs + 1 个 .py,另有共享类型声明与基准运行日志)按用途分为七类:

类别脚本
端到端与 harnesse2e-run.mjs(运行器:--continue、汇总表、--parallel)、_harness.mjs(共享 harness)、smoke-test.mjs、verify-*.mjs(13 个:webgpu / 3d / plugins / code-mode / block-mode / lang-modes / r-runtime / ai-samples / ai-training / research / ui / fixes / site)、_line-check.mjs(目检 Monaco 当前行与选区实际渲染色)
性能与预算bench-run.mjs、bench-compare.mjs、bench-report.mjs、build-budget.mjs
构建与部署build-wasm.mjs、make-wasm-stub.mjs、build-docs.mjs、merge-deploy.mjs、gen-sw-precache.mjs、copy-pyodide.mjs、copy-webr.mjs、vendor-blockly-media.mjs
资产与示例生成make-example-data.mjs(重建 distribution.dat、field.json 与图像演示的 base64 测试图案)、make-example-projects.mjs(从样例数据构建示例 .clproj)、gen-ai-examples.mjs(种子化 PRNG,产出确定、可提交、可被学习者检查的 CSV)
合规与签名sign-cspkg.mjs(.cspkg 签名 CLI:--genkey 生成密钥、签名与校验)、gen-sbom.mjs(CycloneDX SBOM)、gen-citation-cff.mjs、check-citation.mjs
领域专项chem-reactmd-validate.mjs(用真实载荷在低 / 高温两端运行目录内全部反应的 Python NumPy 引擎并打印对照表,确认每个反应只在高温下物理完成)、repro-plugins.mjs(两个商赛插件 fluid-cfd-coupler 与 em-eigensolver 的一次性复现与基线核对)、make-qr.py(二维码生成)
技术文档排版build-tech-docs.mjs(md → 分页 HTML → A4 PDF)、build-tech-summary.mjs(从分篇汇编合集,使合集不可能与分篇漂移)

其中 gen-citation-cff.mjs 与 check-citation.mjs 一写一校,共同维护 CITATION.cff(校验脚本比对 src/core/citation.ts 中硬编码的作者 / 许可与 package.json,漂移即以非零码退出并使 CI 变红);gen-sw-precache.mjs 生成 Service Worker 预缓存清单,使离线可用范围与构建产物严格一致;copy-pyodide.mjs 与 copy-webr.mjs 把 Python / R 运行时 vendor 到本地自托管,避免运行时依赖公网 CDN。

技术文档排版链路。docs/technical/ 下的十一份文档由 node scripts/build-tech-docs.mjs 重建:Markdown 经内置的子集解析器转成区块,mermaid 围栏在构建期用无头浏览器渲染为内联 SVG(产物不含任何客户端脚本,PDF 里是可缩放的矢量图),随后在真实页面尺寸下逐块测量高度并按页高装填——固定高度的 .page 配 overflow: hidden,靠目测平衡内容会在任何一节变长时把内容裁掉,因此分页必须由测量驱动。测量结果同时回填目录页码,并在生成后逐页复检"内容是否越过下边距",发现溢出即以缩小后的可用高度重排。技术总结(Ergalics Studio.md)则由 build-tech-summary.mjs 从十一篇分篇源码汇编,因此不可能出现"分篇已改、合集还写着旧数字"的情况。

六、质量原则 ​

  1. 纯函数优先。编译器、统计内核、绘图与组图引擎、代码生成与 IR 转换全部是纯函数,可在 Node 环境直接测试;血缘图的分层布局同样无 React / store / DOM 依赖。
  2. 副作用收口。区块系统里只有渲染桥接一个带副作用的模块,执行器异步但无副作用;研究工具页的胶水层(researchUi.ts)也被刻意写成无 React 依赖的薄层,以便单独测试。
  3. 数值一致性兜底。每个 GPU 内核都有数学一致的 CPU 实现,单测与端到端两层校验二者一致——这是"自动降级"能够被信任的前提。
  4. 边界显式化。边界输入抛结构化错误、空数据启动有守卫提示、环境缺失如实自检报告,而不是静默失败或静默降级;可复现性有专门的门禁文档告知。
  5. 不静默跳过。需要归档就必须归档(Zenodo 未配置即报错并给指引),需要门禁就必须门禁(审计豁免要写明理由),第一次运行没有基线就记录并提交——把"没跑成"和"跑过了"区分清楚。

Released under the MIT License.