DOCUMENTATION · 测试体系

测试体系

本文介绍本项目如何写、如何运行测试。栈是 Vitest（单元测试）+ Playwright（端到端）， 两者分别覆盖「引擎内核逻辑」与「真实浏览器里的整链路」。

同步自 docs/TESTING.md（243 行） · commit b2b4124 · 读源文件 ↗

权威配置：vitest.config 相关（无独立配置时走内置默认）、playwright.config.ts、package.json#scripts。 若与源码冲突，以源码与实际运行结果为准。

1. 总览

命令：

npm test            # vitest run        —— 跑全部单测
npm run test:watch  # vitest            —— 监听模式
npx playwright test # 跑全部 E2E

E2E 首次需要浏览器依赖：

npx playwright install --with-deps chromium

2. 单元测试（Vitest）

2.1 文件分布

当前共 440 个用例 = 417 个功能用例 + 23 个文档一致性检查器（明细：expression 12 / story 18 / plugin-manager 28 / wasm-abi 4 / world-loop 17 / kit 9 / plugin-timers 10 / capabilities 6 / determinism 30 / frame-loop 18 / input-router 13 / intents 10 / observability 10 / permission-scope 13 / runtime-semantics 19 / state-layer 22 / stories-valid 4 / view-and-abi 10 / assets 19 / editor 77 / scaffold 6 / editor-text 25 / embed 9 / host-typewriter 8 / lib 2 / link 5 / mount 5 / stories-shapes 8），npm test 全绿。

2.2 风格约定

• 纯逻辑、无浏览器 API：引擎内核不依赖 DOM，单测直接在 Node 环境跑。 若被测代码触到 localStorage/window，用传入假依赖或 getStorage()-style 的守卫，别引真实的浏览器对象。
• 用真实实例，少 mock：StateStore、EventBus、StoryEngine、PluginManager 都是可 new 的真类， 构造时注入假的 UI（如假 RuntimeUi / 假 renderChoice）即可，尽量不 mock 内部。
• 断言状态而非实现细节：尽量断言 state.get(...) 的返回值、engine.currentId、事件 payload，而不是某函数被调用了几次。

2.3 新增单测的套路

import { describe, expect, it } from 'vitest'
import { StateStore } from '../src/runtime/StateStore'
import { StoryEngine, type StoryUi } from '../src/runtime/StoryEngine'

describe('某能力', () => {
  it('应该做正确的事', async () => {
    const state = new StateStore()
    // ...解构 engine，喂剧情，跑 run()
    expect(state.get('var.gold')).toBe(10)
  })
})

2.4 无头测试套件 @rne/testing

tests/kit/index.ts 把「假 UI + file:// 资源加载 + 微任务泵 + 驱动脚本」收敛成一份， 写一个跑通整条剧情链路的用例只要十几行：

import { createSandbox } from './kit/index'

it('世界事件把剧情拉到旁白节点', async () => {
  const sb = createSandbox()          // 装环境补丁 + 装配 Runtime + 记录轨迹
  try {
    await sb.load('world.json')       // 相对 public/ 的剧情路径
    await sb.begin()                  // 启动（安全版：绝不会 await 到剧情结束）
    await sb.driver.tickWorld(2)      // 手动推进世界节拍（确定性，不依赖真实定时器）
    expect(sb.nodes).toContain('show_extinction_message')
  } finally {
    sb.restore()                      // 还原 location / fetch / document / localStorage
  }
})

它专门替你处理四件麻烦事：

1. loadStory({ autoStart: true }) 的 Promise 直到剧情结束才 resolve —— 直接 await 会永久挂起； sandbox.begin() 用「不 await + 泵宏任务」绕开，这是唯一安全的写法。
2. file:// 下剧情里的 plugins: ['/plugins/x/manifest.json'] 会解析到文件系统根目录 —— 套件的 fetch 补丁会把 plugins[] 重写成资源根下的真实 URL（WASM 按字节读，不会被当文本读坏）。
3. wait 节点会真等、say 会一直等点击 —— 假 UI 把 wait 立即结算；say 排进队列由 driver 控制（advance() / until() / runUntilEnd() / chooseByText()）。
4. 插件里读 document / localStorage 的代码在 node 下会抛 —— 套件默认装极小 DOM 桩与内存版 localStorage（假 UI 不会真正挂载组件，所以插件的渲染器不会被调用）。

驱动脚本不会静默卡死：一旦剧情既没等点击、也没等选项、也没结束，runUntilEnd() / until() 会抛错并说明当前节点，并提示你可能是世界驱动的节点、需要改用 tickWorld()。

假时钟的坑（我连吃三次 30 秒超时才搞清）：如果某个测试文件里用了 vi.useFakeTimers()， 那么 vi.useRealTimers() 的恢复必须放在文件顶层 ✗ 不能塞进某个 describe 里 —— 否则"追加到文件顶层的新测试"会继承上一个测试的假时钟，setTimeout 永不触发， await new Promise((r) => setTimeout(r, 0)) 会永久挂起（表现为测试超时，看起来像引擎挂了 ✗）。 更稳的做法：等待用套件的 ui.waitFor(predicate, turns)，而不是自己 await 定时器。

注意：套件补丁是全局的（location / fetch / document / localStorage）， 每个用例应当 createSandbox() 后 finally { sb.restore() }。vitest 默认按文件隔离进程， 通常不会互相干扰。

2.5 门禁：让检查器真的会红

文档/一致性检查器的全部价值建立在会红上。它有两种接线方式：

临时跳过门禁：SKIP_HOOKS=1 git push（会打印醒目警告 —— 逃生门要有，但不能悄悄用）。

3. 端到端测试（Playwright）

E2E 用 Playwright 驱动真实 Chromium，playwright.config.ts 会先起 dev server（http://localhost:5173）。

状态提示（2026-09）：仓库已清理掉非示例组件（entropy-war 剧情、entropy-*/tycoon-*/ashforged/ironworld 插件、scripts/entropy-*、public/entropy-worker.js），完整原始内容归档于 archive/original 分支。 当前可运行的 E2E 是 tests/e2e/reload.spec.ts（剧情重载）与 tests/e2e/world.spec.ts（世界模拟器）。 下述 §3.1 的 entropy.spec.ts 仍保留全部代码， 但已通过 playwright.config.ts 的 testIgnore 停用，默认不运行、不参与 CI；如需复跑，先从 archive/original 分支取回对应剧情/插件放回 public/ 再执行。

3.0 可运行用例

tests/e2e/world.spec.ts —— 世界模拟器 E2E

验证「剧情不再主动推进，而是被动听世界说话」，并确认 JSON / JS / WASM 三路平权：

1. 世界循环每拍驱动 WASM 插件把 var.species_count 递减到 0；
2. 归零时 WASM 发布 ecology:species_extinct，被两处同时接收： a. 剧情 JSON 的 observe 节点 → 被动跳转到「世界」旁白； b. JS 插件的 ctx.world.subscribe → 在 #plugin-ui 弹出 .world-notice 警示；
3. 通过 window.__storyRuntime.state 断言状态真的被 WASM 写进 StateStore。

该用例依赖 world.json 剧情（public/stories/）与示例插件，page.screenshot(...) 留证。

3.1 已停用用例（仅保留文件）：tests/e2e/entropy.spec.ts

⚠️ 此用例依赖已移出的《熵减战争》压测资产，当前不会运行。以下为其历史验收说明，仅供恢复资产后复跑参考。

这是针对《熵减战争》压测剧情的硬核验收，四条用例对应四条硬指标与三路 WASM 集成：

1. 跨域隔离 + 数据正确性：断言 crossOriginIsolated === true（SAB 前提）、mode === 'sab'、 三路 WASM 的 Float64Array 数据长度（nbody.raw_stats=32 / sample=96、cfd.sample=128、ga.sample=178）。
2. pre 输出庞大 JSON + 刷新率：data-bytes > 5000、可被 JSON.parse、~1s/次 刷新（允许 0.5x~2x 抖动）。
3. js-system_switch 启停：表格 3 行、tick 推进、停止后 tick 冻结、再次启动恢复。
4. 主线程不被阻塞：重算下 rAF 2 秒内 ≥30 帧且最大间隔 <500ms，采样器 tick 仍推进。

关键辅助函数 waitForAllSystems()（勿删或跳过）：三个 Worker 各自实例化 WASM 并分配线性内存，初始化节奏不同： N 体（26MB）与 GA（<1MB）先出结果，流体（20MB，1024² 网格）会晚几个采样周期。 它用 expect.poll 等到三路都产出非零物理量 + 都以步进≥1 再继续断言， 否则会把「流体还没上线」误判成「流体数据为 0」。新增数据断言时，务必同样等待「目标子系统已上线」，不要只等某一路上线就断言。

3.2 访问 var.sim 的调试句柄

E2E 通过引擎暴露的 window.__storyRuntime.state.get('var.sim') 直接读插件写入的状态，避免依赖 DOM 文本。

async function readSim(page) {
  return page.evaluate(() => {
    const rt = window.__storyRuntime
    return rt?.state.get('var.sim') ?? null
  })
}

3.3 新增 E2E 的套路

import { expect, test } from '@playwright/test'

test('我的场景', async ({ page }) => {
  await page.goto('/')
  // 选剧情、等节点/组件挂载
  // 交互、断言 data-* 属性（尽量少依赖脆弱的选择器）
})

建议给关键 DOM 打 data-* 属性做稳定锚点（如 data-role="launch"、data-refresh-count）， 别依赖文本/位置这类脆弱定位。

4. 常见问题

• E2E 报 libatk...so.0 等浏览器依赖缺失：执行 npx playwright install --with-deps chromium。
• SharedArrayBuffer 在 E2E 里不可用：本项目默认关闭跨域隔离（见 vite.config.ts）。 需要 SAB 的用例要用 CROSS_ORIGIN_ISOLATION=1 npx playwright test 启动（webServer 会继承该环境变量）； 另注意 reuseExistingServer: true —— 若本机已有未开隔离的 dev server 在跑，会被复用导致隔离失效， 先停掉它。详见 CROSS_ORIGIN.md §3.1。
• 单测用了浏览器 API：把依赖作为构造参数传入，或改用假实现。
• E2E 时有时无（flaky）：多半是三路子系统上线节奏不同，核对是否走了 waitForAllSystems。

相关链接

• ARCHITECTURE.md：引擎内部结构，便于写针对性测试。
• STORY_FORMAT.md：剧情文件格式，E2E 剧情、单测构造剧情都看它。
• EVENTS.md：事件契约，单测里断言事件 payload 时参考。
• CROSS_ORIGIN.md：跨域隔离开关（CROSS_ORIGIN_ISOLATION）—— 用到 SAB 的 E2E 前提。