OCC 星球漫游 · 测试指南

测试全部是 Playwright（node 版）无头浏览器脚本，放在 tools/e2e/，共 58 个。 这份文档说明怎么跑、每个脚本管什么、以及哪些坑会让测试给出错误结论。

核对基线：2026-10-15，tools/e2e/ 目录实测 57 个 .cjs + 1 个 .mjs + _auth.cjs 助手。

0. 总体情况

跑之前先起服务：

python scripts/svc.py start
node tools/e2e/smoke.cjs        # 先跑这条确认链路通

1. 环境（本机三条硬约束）

SwiftShader 软渲染只有 1~2 FPS，所以测试开场会：关阴影、降 pixelRatio、整体隐藏植被。 注意物理障碍物独立于渲染，所以撞树类测试照样有效 —— 但任何依赖帧率的断言都会失真（见 §5）。

2. 身份牌助手 _auth.cjs

所有需要登录的脚本都靠它。它做四件事：

模块导出：{ BASE, freshToken, primeAuth, authedPage, preheatWorld } —— 没有 closeAll 之类的收尾助手，收尾自己写。

⚠️ README.md 里"截图类脚本 look / hpshot / shot 不需要身份牌"的说法已过时：这三个脚本源码里都在用 authedPage。

3. 脚本清单

3.1 基础设施 / 冒烟 / 诊断

3.2 账户 / 会话 / 世界规则

3.3 战斗 / 物理 / 破坏

3.4 机甲 / 动作 / 远程表现

3.5 世界 Boss「天罗」

3.6 采集 / 建造 / 生产 / 科技 / 背包

3.7 社交 / UI / 载具 / NPC

3.8 美术资产 QA（不开作品本体）

3.9 星球视觉主题

theme_shot.cjs 的两个坑（都在脚本注释里写死了）：

• 🔴 URL 必须带 ?w=<worldId>。不带的话 world.js 会把"声明世界"兜底成 battle，

而服务端 hello 的规则是"声明合法就听客户端的" ⇒ 不管怎么预热，浏览器一律落焦土。 拍 home 时中过这招：两张"苗圃"图其实还是焦土。

• 🔴 拍天空要先藏掉机甲整棵子树。相机是绕机身中段转的，只抬 rig.pitch 只会变成

"从机甲两腿之间看天空"；抬过头还会把机壳糊进画面左下角，看着像"天空变蓝了"（误判过一次）。

对生产环境实拍：加 OCC_BASE=http://<生产>:8090 即可（同一条命令，无需改脚本）：

OCC_BASE=http://[服务器地址]:8090 node tools/e2e/theme_shot.cjs battle

⚠️ 三条只在这个场景才会遇到、但很容易误判成"生产坏了"的事：

1. _auth.cjs 的 BASE 读的是 OCC_BASE，页面地址也必须跟着它走。

脚本里曾把地址写死成 127.0.0.1：OCC_BASE=生产 时 token 注册在生产、 浏览器却开本地页 ⇒ 本地拿生产 token 去鉴权必然 401 ⇒ 停在登录界面、 __OCC__ 永不出现。看着像发布把生产搞坏了，其实只是地址写死。

1. 用 curl 手测鉴权端点是 x-occ-token 头、不是 Authorization: Bearer

（写错会拿到 401 invalid token，同样是"假故障"）。/api/me 不存在，是 /api/auth/me。

1. 失败时脚本会把最后看到的状态打出来（occ / keys / auth）——

auth:true 就是"停在登录界面"，一眼能区分"没登录"和"页面没加载"。

4. 关键判据（挑几条代表性的）

combat.cjs：

采集 / 采空链（triple_check.cjs 一类）：

5. 写测试 / 判读结果时的坑（都是踩出来的）

6. 写一条新测试的模板

// tools/e2e/yourfeature.cjs
const fs = require('fs');
const { chromium } = require('playwright');
const { authedPage } = require('./_auth.cjs');

const SHOTS = 'D:/OCC-Game/_logs/shots';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

(async () => {
  fs.mkdirSync(SHOTS, { recursive: true });
  const bad = [];

  const browser = await chromium.launch({
    headless: true,
    args: [
      '--use-gl=angle',
      '--use-angle=swiftshader',
      '--enable-unsafe-swiftshader',
      '--ignore-gpu-blocklist',
      '--disable-gpu-sandbox',
    ],
  });

  const { page, context } = await authedPage(browser, { width: 1440, height: 900 });
  page.on('pageerror', (e) => bad.push(String(e)));

  // 1) 等世界就绪（用 __OCC__ 轮询，别用固定 sleep）
  // 2) 用 __OCC__ 读状态、构造输入
  // 3) 断言 → console.log 结构化 JSON
  // 4) 截图落 _logs/shots/

  console.log(JSON.stringify({ BAD: bad.length }, null, 2));
  await context.close();
  await browser.close();
})();

要点：

• 断言要 print 成结构化 JSON，方便前后对比，而不是只 print PASS/FAIL。
• 失败要能区分"代码错"和"用例错"：本项目反复出现的教训是"用例写错 → 报假 bug"。
• 关键路径做红-绿验证：故意把修复回退，确认用例真的会红（否则它可能一直在假绿）。

相关文档

• 开发与调试：开发指南
• 系统与禁区：系统架构
• 性能标尺与基线数字：性能优化方案