# 测试说明

本文档回答一个问题：**这个插件的测试分几层、每层测什么、放在哪、怎么跑、什么时候跑。**

## 测试目的

只验证一件事：**两个独立 dsh 会话之间，能不能可靠、安全地互发消息，且消息被正确标记为 relay（不越权）。**

不验证“模型聪不聪明”。模型行为只在“约束”层面测（是否调用正确工具、是否被权限拦下），不测它的自然语言措辞。

## 分层总览

| 层 | 内容 | 确定性 | 依赖 | 归属 | 触发 |
|---|---|---|---|---|---|
| L1 单元 | 纯逻辑（config/mailbox/policy/auth/metrics） | 确定 | 无 I/O | 插件仓库 `tests/unit/` | push 必跑 |
| L2 集成 | 真实 socket + 文件系统（service/registry/transport/outbox） | 确定 | 无模型 | 插件仓库 `tests/integration/` | push 必跑 |
| L3 宿主集成 | 插件在 dsh 里加载、工具注册、agent 绑定、relay 注入 | 确定 | dsh + mock | dsh 仓库（见下） | dsh CI |
| L4 模型行为 | 真实模型协作 / 审批 / 权限继承 | 非确定 | dsh + 真实 key | 插件仓库 `tests/e2e/` | 手动 / 定时 |

分层原则：**确定性测试进门禁（各自仓库的 CI），非确定性模型测试走定时/手动。**

## L1 单元测试

- 位置：`tests/unit/`
- 内容：配置 schema、稳定凭据、身份解析、收件箱队列（持久化/背压）、入站策略、转发防护、token、退避、TLS 指纹/pinning、连接池、指标、审计。
- 命令：`npm test`（vitest 的一部分）。
- 触发：`npm run check` → CI push 必跑。

## L2 集成测试（真实 socket + 文件系统）

- 位置：`tests/integration/`
- 内容：注册/发现/投递/鉴权/身份绑定/去重/限流/同名消歧/并发/spool 恢复/死信/跨机 TLS/健康/消息大小/速率限制。
- 特点：真实 socket + 真实文件系统，但 agent 是 mock 的，不依赖模型。
- 命令：`npm test`（vitest 的一部分）。

## L3 宿主集成（keyless，确定性）

- 内容：插件 apply 后 4 个工具注册、创建 agent 后绑定（registry + socket）、socket 发消息后 relay 事件（`source.form='relay'`）落进 durable log。
- 特点：用 dsh 的 `provider: 'mock'`，**不调真实模型、不需要 key**，但**只覆盖确定性机制，不覆盖“模型调工具”**（那是 L4）。
- 归属：**dsh 仓库**（对 out-of-tree 插件的集成契约，甲方是 dsh），进 dsh 的 CI。
- 落地：测试文件已放 dsh 仓库 `packages/examples/acp-demo/tests/cross-session-messaging.keyless.spec.ts`（1 个 vitest 用例，已本地验证通过）。本地跑用 symlink；进 CI 需在 dsh workspace 里把本插件声明为 `file:` 依赖（部署时配置）。
- 本仓库另存一份可复跑脚本：`tests/e2e/acp-keyless.mts`。

## L4 模型行为（真实 key，非确定）

- 位置：`tests/e2e/acp-e2e.mjs`（8 场景）+ `tests/e2e/` 下的协作流水线。
- 内容：双 session 收发、hold/accept、refuse、三 session 路由、同名消歧、跨进程收发、转发防护、审批链路。
- 命令（在 dsh checkout 内，先 `ln -s` 插件到 dsh 的 node_modules）：
  ```sh
  cd deepseek-harness
  DEEPSEEK_API_KEY=... node <plugin>/tests/e2e/acp-e2e.mjs
  ```
- 触发：`.github/workflows/e2e.yml`（`workflow_dispatch` + `schedule`），**不进 push 门禁**。
  需要仓库 secrets：`DEEPSEEK_API_KEY`，且 dsh 仓库可 checkout（`deepseek-ai/deepseek-harness`）。

## 压测 / 长稳

- `tests/e2e/stress.mjs`：秒级并发压测（peers × messages），验证不丢 + 报峰值内存。
- `tests/e2e/longevity.mjs`：长稳脚本，定期采样 RSS / fd / 队列深度，看资源是否线性增长。
- 命令：先 `npm run build`，再 `node tests/e2e/<script>.mjs`。

## CI 策略

- 插件仓库 `.github/workflows/ci.yml`：`npm ci && npm run check`（L1 + L2），push / PR 必跑。
- 插件仓库 `.github/workflows/e2e.yml`：L4 真实模型验收，`workflow_dispatch` + `schedule`。
- dsh 仓库 CI：L3 keyless 宿主集成（随 dsh 的测试一起跑）。

## 发布流程

1. 更新 `CHANGELOG.md`（记版本变更）。
2. `npm version <patch|minor|major>` 更新版本 + 打 tag。
3. `npm pack --dry-run` 验证 tarball 内容（应为 `lib/`、`cordis.patch.yml`、`README.md`、`README.zh.md`、`LICENSE`、`SECURITY.md`）。
4. 装进一个 dsh profile 验收：`dsh --profile <name> --patch ./cordis.patch.yml --dump-config` 能看到插件行，再跑一个真实任务。

## 已知边界（诚实清单）

- L3 的 `provider: 'mock'` 不真发 prompt，只覆盖确定性机制；“模型调工具”只有 L4 能覆盖。
- L4 依赖真实模型，flaky，只作验收不作门禁。
- 跨机器通信已覆盖 transport/service 层（docker 矩阵 + 真实公网双机），模型主动调工具的宿主端到端尚未验证；`from` 身份不可强验证；无 exactly-once。
- 详见 `docs/limitations.md`。