huishi_tools

Web 应用的前端操控 / 截图工具。用裸 Chrome DevTools Protocol 驱动无头浏览器，完成「注入登录态 → 导航 → 执行 JS → 截图」的自动化验证与取证。

放在被测试项目仓库之外，避免测试脚本污染主仓历史。

cdp-driver/            前端操控 / 截图工具（通用，可跨项目复用）──【入库】
  drive.mjs            交互式 CDP 驱动（主力）
  shot.mjs             纯截图（轻量）
  get-token.sh         登录并写 .token
  README.md            用法 + 踩坑记录（用之前先看）

sessions/              会话存档（本地数据，不入库）──【.gitignore 已忽略】
  <YYYYMMDD>_<主题>/
    README.md          这次查了什么、结论、对应 commit
    actions/           本次运行的前端操控脚本（按执行顺序编号）
    shots/             截图存档

快速开始

cd cdp-driver
./get-token.sh                    # 登录，写 .token（服务重启后需重跑）
node drive.mjs "<页面URL>" <actions.json> [out.png] [waitMs]

actions.json 是声明式用例，加测试 = 加一个 JSON 文件，不用写代码：

[
  {"eval": "document.getElementById('notifBell').click(); 'clicked'"},
  {"sleep": 2500},
  {"eval": "location.pathname + location.search"},
  {"shot": "_rerun/after-click.png"}
]

换测试环境只改环境变量：HUISHI_BASE=http://<host>:8001 node drive.mjs ...

为什么用裸 CDP 而不是 Playwright

零安装：Node 18+ 自带 WebSocket，复用本机 Chrome，不需要 npm install、不需要下载浏览器内核（目标环境常常装不了依赖，或网络受限）
关键能力更直接：Runtime.evaluate 取任意 JS 表达式返回值、Page.captureScreenshot 截图，正是「埋点验证 + 取证」需要的两件事
代价：没有 selector 等待、自动重试等便利封装，页面加载靠 sleep 兜底

维护约定

仓库只收录工具

本仓库只跟踪 cdp-driver/ 与本文档，可跨项目、跨版本长期复用。

会话存档不入库：所有会话统一放在 sessions/ 下，该目录已整体列入 .gitignore，一律留在本地磁盘——里面含被测系统的真实数据与内部信息，不适合随仓库扩散。

看历史结论请在本地打开对应会话目录；需要复现时按其 README 重跑 actions/ 里的用例。

会话存档的两条原则

截图只留本地：体积大、含业务数据，价值在于”当场取证”而非永久保存。
测试用例是版本快照，不追着新版本改：用例里的断言与选择器绑定当时的前端实现，迭代后失效是正常的，不要为了让旧用例继续跑而修改它。它们是开发历史日志，用于回溯”当时验证了什么、结论是什么”。要看新版本表现就新建一个会话目录，而不是改旧的。

已忽略（保留在本地磁盘）

路径	说明
`sessions/`	会话存档（用例 + README + 截图），全部集中于此
`.token`	登录凭据，约 30 分钟失效，不入库不外传
`.chrome-profile/`	Chrome profile 缓存，可随时删除重建
`_rerun/`	重跑产物（保证重跑不覆盖归档截图）