本文说明仓库的测试分层、常用命令和真实 Cloud 验证规则。具体功能的验收用例随测试代码维护; 逐次验证证据放在 PR 描述或 CI artifact 中,不提交到仓库。
| 层 | 命令 | 覆盖 |
|---|---|---|
| 仓库脚本 | pnpm test:scripts |
首次配置、既有 .env 不变、取消 / 并发保护、依赖构建与服务启动顺序、组件复制 |
| SDK 数据层 | pnpm --filter @openagentpack/kit-sdk test |
SSE 帧编解码、快照归并、event_id 去重、重连与 after 续传、工具审批、确认令牌 |
| chat-ui | pnpm --filter @openagentpack/kit-chat-ui test |
消息渲染、执行过程、附件与快捷指令、审批交互、空态与禁用态 |
| server | pnpm --filter @openagentpack/kit-server test |
路由与权限、身份归属、确认闸门、事件不落库、OpenAPI 一致性 |
| gateway 合同 | 同上(tests/fixtures/) |
Provider HTTP/SSE 映射;Mock 与 SdkGateway 跑同一套契约 |
| Console | pnpm --filter console test |
管理客户端、导航、草稿所有权、资源表单与恢复 |
| Web | pnpm --filter web test |
配置、身份隔离、宿主适配及页面纯逻辑 |
| 文档站 | pnpm --filter storybook test |
接口文档与 Skill 链接;页面内容/预览另由静态构建及浏览器验证 |
| 开发 Skill | pnpm check:skills / pnpm typecheck:skills / pnpm test:skills |
公开 API、生成漂移、示例编译、离线包及浏览器边界 |
| web / console E2E | pnpm e2e |
对话、重连、归档/删除、附件、管理端 plan → 确认 → 执行 |
Provider HTTP/SSE 合同由 gateway 层 fixture 保护;上层 hooks 测试不重复断言同一份映射。
pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm check:architecture
pnpm check:docs
pnpm check:no-inner-deps
pnpm gate # 以上全部
pnpm verify:push # pre-push hook 子集文档站由 GitHub Actions 检查、构建并发布到 GitHub Pages,配置见文档站部署说明。
完整验收在本地执行 pnpm gate 与 pnpm e2e,结果记录在 PR 描述中。
本地 hook 可被 --no-verify 绕过。
Node 与 pnpm 分别遵循根 engines 和 packageManager。检查实际 core.hooksPath,
不能把个人全局 hook 当作仓库检查;需要启用仓库 hook 时使用 pnpm setup。
干净安装后,文档站类型检查和链接测试依赖 .source/server.ts、本包 OpenAPI 输入及 Skill 下载准备。
缺失时执行已有生成入口,不手写空文件或修改测试规避:
pnpm --filter storybook exec fumadocs-mdx
pnpm --filter storybook prebuildprebuild 同步服务端 OpenAPI、检查并准备 Skill 下载,以及构建 SDK / chat-ui 依赖;
pnpm --filter storybook build 生成静态 out/ 和搜索索引。包、页数与版本以当前清单及产物为准,
不以旧 CI 子树、历史包名或固定页数作为验收条件。
Mock 端到端(首次选择 Mock;已有 .env 时先确认 KIT_GATEWAY=mock):
pnpm startPlaywright:
pnpm e2e- 新增测试先写清保护的用户流程、业务不变量、模块/Provider 合同或历史缺陷。
- 通过公开接口或可观察结果验证;删除依赖实现步骤、与其他层重复的测试。
- 负向断言先证明目标路径可达:权限测试显示资源确实存在;异步 UI 测试等待初始化与事件处理完成。
- 闸门测试必须覆盖「无 confirmation token 被拒」与「有 token 通过」两条路径。
- 去重与重连覆盖「历史回放 + 实时流」交叉到达(
event_id重复)与after游标续传。 - 静默断流与显式
done是不同场景,不能用发送done的 mock 证明自然断流。
- 使用仓库
.env,不输出、不修改、不提交凭据;日志与错误消息中的 key 必须脱敏。 - 默认不运行,只在任务明确需要且显式设置
KIT_LIVE=1时执行;后续接入 CI 时由受保护变量启用。 - 资源使用唯一前缀
kit-live-<yyyymmddHHMM>-,并写 metadata{ "kit": "live-validation" }。 - 结束后删除临时 Session;Agent 按 Provider 当前正式删除/归档合同清理。 Environment 因引用关系拒绝删除时按正式协议归档;采用归档时在交付记录说明原因。
- 验证证据写 PR 描述或 CI artifact,包含命令、结果和脱敏后的关键字段;不提交真实资源 ID。
KIT_LIVE=1 pnpm --filter @openagentpack/kit-server exec tsx tests/live/smoke.tspnpm check:docs校验文档中的pnpm <script>存在、每个包有AGENTS.md、docs/interfaces.md的 ✅ 行与apps/server/openapi.json路径一致。pnpm gen:openapi生成 OpenAPI 与 API 类型;pnpm gen:skills生成 Skill 参考与示例。- 构建产物、缓存与
.scratch/不入库。
新增或修改测试前,明确它保护的用户流程、业务不变量、模块/Provider 合同、恢复路径或历史缺陷; 选择最少的代表性成功、拒绝、边界和失败场景。类型保证、简单透传和框架默认行为无需独立测试。
| 修改类型 | 最小验证与扩大条件 |
|---|---|
| 仅 AGENTS.md / 工程规范文字 | 检查路径、命令、权威归属、替代关系和冲突;运行 pnpm check:docs、pnpm lint 与 diff 检查。无运行时或站点内容变化时,无需重跑所有构建、浏览器与 Cloud |
| SDK / UI / 应用运行时代码 | 对应包类型检查与合同回归;公开 API、样式或交互变化再检查实际调用方、构建产物及相关 E2E |
| 接口 / Schema / Provider 合同 | 生成 OpenAPI 与 SDK 类型,校验接口表;在拥有映射的层覆盖代表性成功、拒绝及恢复场景 |
| Skill 源 / 生成器 / 公开示例 | 检查或重新生成产物,编译示例,选择生成、链接、打包或浏览器边界回归 |
| 架构、依赖配置或交付链路 | 检查依赖方向、工作区与任务图,按影响运行完整门禁或相应构建 |
生成物、lockfile 与构建缓存不计入手写文件规模;生产源码超过 800 行、测试或脚本超过 1000 行时, 按变化原因评估职责拆分,不机械切文件。规范维护不能通过删去有效合同来缩短入口文件。 记录真实执行的步骤和环境;取消、跳过或环境失败不计为通过,Mock / 离线结果不能替代 Cloud。