# 脚本入口与测试范围

`scripts/` 同时包含回归测试、构建/发布工具和 REA 恢复工具；文件数量不等于测试覆盖数量。**不要遍历目录逐个执行脚本。** 某些工具会连接窗口、调用模型、下载包或发布产物，必须先阅读其用途、参数和隔离要求。

## 默认离线基线

```sh
npm test
# 等同于 npm run test:core
```

包含类型检查、聊天状态/消息顺序、会话存储、持久化和会话渲染回归。使用模拟宿主或临时目录，不启动真实模型或桌面应用。这个入口是跨模块基础检查，**不是全产品、SDK 或 UI 验收**，也不替代构建。

## 按改动选择专项

| 改动范围 | 应选入口 | 重要边界 |
| --- | --- | --- |
| 对话/模型/权限/折叠 | `test:alignment`、`test:conversation`；交互变更加 `test:alignment:dom` | 普通 alignment 无 DOM 依赖时明确 SKIP；严格 DOM 入口缺依赖会失败。授权回归含 mock，非真实 SDK 证明 |
| 推荐技能/安装状态 | `test:recommended-skills`、`test:recommended-skills:dom` | 前者受控安装归档；真实发布包为单列可选检查，不能把 SKIP 算通过 |
| 能力选择/使用草稿 | `test:composer-capabilities` | 不启动真实模型；完整应用事件链另验 |
| 正文/代码/数学/媒体 | `test:markdown`、`test:recovered`、`test:media` | 根据实际变更选取，不代表像素一致 |
| 文件/会话持久化 | `test:resources`、`test:persistence`、`test:sessions` | 先核对脚本临时目录与宿主隔离 |
| 升级/发布 | `test:updates`、`test:release` | 不等于执行 `release` 或 `updates:deploy`；发布命令单独授权 |
| 设计 token/恢复闭包 | `check:tokens`、`test:fold-summary` 等 | 非零退出必须保留；已有失败不能刷新 baseline 掩盖 |

需要 jsdom 的测试使用已安装模块，不自动下载依赖：

```sh
# Unix 示例；替换为实际已安装 jsdom 路径
YCODE_TEST_DOM_MODULE=/absolute/path/to/node_modules/jsdom npm run test:alignment:dom
YCODE_TEST_DOM_MODULE=/absolute/path/to/node_modules/jsdom npm run test:recommended-skills:dom
```

PowerShell 使用 `$env:YCODE_TEST_DOM_MODULE = <绝对路径>`，再运行相同 npm 命令。依赖安装与锁文件变更按项目约定单独处理。

## Windows / 真实窗口验证

`npm run test:permissions:loopback` 是独立的 Linux 本地权限集成验证：实际 ClaudeKernel/SDK/CLI、仅回环假模型、一次性 HOME/userData/workspace。会执行固定测试目录中的读写和 Bash 命令，不使用用户供应商或实际数据，不属于默认离线基线。其他平台明确阻塞；Windows/PowerShell 和真实窗口需另验。建议外层使用 `timeout --signal=TERM --kill-after=5s 120s npm run test:permissions:loopback`，脚本内部另有请求和时间上限。

例如 `test:recommended-skills:ui`、`node scripts/verify-task-menu.cjs`、`node scripts/test-mode-chip-native.mjs`。这些是特定场景，不是统一全量 UI 集。先读脚本并确认临时 userData/工作目录、受控宿主、是否访问模型/网络；不得连接生产数据或原版 WorkBuddy 进行未经允许的操作。

`test:recommended-skills:app`、SDK smoke、网络包验证等可能需要额外资源或有外部行为，不纳入默认离线入口。无 DISPLAY、native 模块或权限导致启动失败，应标为**环境阻塞**，不是通过。`--build-only`、SSR、jsdom、静态 CSS 断言都不等于真实布局或像素验收。

真实 dev 启动遵循 [Dev 启动 SOP](../docs/协作/Dev启动SOP.md)，测试应用另用隔离数据，不能以启动测试窗口代替用户要求的 dev。

## 维护工具，不是产品测试

- `scripts/rea/`：REA 证据解析、源码/样式恢复、可复用采集配置及相应工具自测。必须保留生成物来源与重建依赖；只通过 REA 查看原版。
- `scripts/updates/`：发布、签名和更新维护。自测与实际发布命令分开。
- `shot` 及保留的现场探针：人工诊断工具，不在默认测试中运行；先确认目标应用/端口/数据。
- `scripts/fixtures/`：受测试引用的夹具，不因没有 npm 入口而删除。

历史一次性探针和停用的直接 WorkBuddy CDP 工具已按本次清理清单删除，不复制到另一目录制造第二份。旧文档中的路径可能属于历史提交，请按清单的基线 SHA 从 Git 恢复或查看；不能据此复活已禁用的采集通道。

## 新增与删除规则

1. 优先扩展同模块测试，不为每个 UI 小修复制完整 Electron 启动器。
2. 新脚本注明需求/模块、运行环境、是否联网/模型/真实数据，以及明确的 PASS/FAIL/SKIP；跳过不能冒充通过。
3. 必要断言不能为变绿删除；失败区分产品缺陷与环境缺失。
4. 删除前检查 npm 入口、import/require、runner 动态文件列表、夹具、恢复链及当前文档；仅历史记录引用不等于运行依赖，但须给恢复路径。
5. 提交测试证据时写明受测代码 SHA、实际命令和未验证范围。默认基线通过不自动关闭需求验收。