docs: split inbox test plans into case files
This commit is contained in:
@@ -1,117 +1,10 @@
|
||||
# Inbox `fetch` Test Plan
|
||||
# Inbox `fetch` Test Plan Index
|
||||
|
||||
## Scope
|
||||
## Case Files
|
||||
|
||||
This document covers agent-scoped candidate thread retrieval via `inbox fetch`.
|
||||
|
||||
Shared conventions live in [../_shared/README.md](../_shared/README.md).
|
||||
|
||||
## case: fetch-returns-pending-thread-for-target-agent
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证 `fetch` 能按目标执行者拉取待处理线程。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- `leader` 已向 `worker-a` 发送至少一个 `pending` 线程
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-a --status pending
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- 命令退出码为 `0`
|
||||
- 返回 `data.threads`
|
||||
- 至少包含一个 `assigned_to == "worker-a"` 且 `status == "pending"` 的线程
|
||||
|
||||
### 断言结论
|
||||
|
||||
- `fetch` 默认是执行者视角的候选工作列表，不是全局线程扫描
|
||||
|
||||
## case: fetch-respects-status-and-limit-filters
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证 `fetch` 同时遵守状态过滤与返回上限。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- `worker-a` 拥有多个不同状态的线程
|
||||
- 其中至少两个线程满足目标状态过滤条件
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-a --status pending,blocked --limit 1
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- 命令退出码为 `0`
|
||||
- 返回线程数不超过 `1`
|
||||
- 返回的每条线程都满足 `status in ["pending","blocked"]`
|
||||
|
||||
### 断言结论
|
||||
|
||||
- `fetch` 的 `status` 与 `limit` 会同时生效
|
||||
- 返回顺序按 `updated_at` 倒序，优先暴露最新线程
|
||||
|
||||
## case: fetch-unread-uses-read-cursor
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证 `fetch --unread` 基于 agent 的 read cursor 计算未读，而不是仅按线程是否存在新消息。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- `leader` 已向 `worker-e` 发送一个 `pending` 线程 `THREAD_ID`
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
|
||||
inbox --db TMPDIR/coord.db --agent worker-e --json show --thread THREAD_ID --mark-read
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
|
||||
inbox --db TMPDIR/coord.db --json send --from leader --to worker-e --thread THREAD_ID --summary "Use sentence case" --body "Keep the nav labels in sentence case."
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- 第一次 `fetch --unread` 返回该线程
|
||||
- `show --mark-read` 后，第二次 `fetch --unread` 无匹配结果
|
||||
- 新消息追加后，第三次 `fetch --unread` 再次返回该线程
|
||||
|
||||
### 断言结论
|
||||
|
||||
- 未读判断依赖 `thread_reads.last_read_message_id`
|
||||
- 新消息到达会让同线程重新进入未读结果集
|
||||
|
||||
## case: fetch-returns-no-matching-work-when-empty
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证 `fetch` 在没有匹配线程时返回稳定的“无工作”错误契约。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- 空数据库已完成 `init`
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-z --status pending
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- 退出码为 `10`
|
||||
- JSON 错误码为 `no_matching_work`
|
||||
|
||||
### 断言结论
|
||||
|
||||
- 空结果不是成功空数组，而是显式的“无匹配工作”信号
|
||||
| Case Slug | File | Coverage Note |
|
||||
| --- | --- | --- |
|
||||
| `fetch-returns-pending-thread-for-target-agent` | [fetch-returns-pending-thread-for-target-agent.md](./fetch-returns-pending-thread-for-target-agent.md) | returns pending candidate work for the target agent |
|
||||
| `fetch-respects-status-and-limit-filters` | [fetch-respects-status-and-limit-filters.md](./fetch-respects-status-and-limit-filters.md) | enforces status filtering and max row count |
|
||||
| `fetch-unread-uses-read-cursor` | [fetch-unread-uses-read-cursor.md](./fetch-unread-uses-read-cursor.md) | unread filtering depends on per-agent read cursor state |
|
||||
| `fetch-returns-no-matching-work-when-empty` | [fetch-returns-no-matching-work-when-empty.md](./fetch-returns-no-matching-work-when-empty.md) | empty fetch result returns no_matching_work |
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# Case: `fetch-respects-status-and-limit-filters`
|
||||
|
||||
## 用例意义
|
||||
|
||||
验证 `fetch` 同时遵守状态过滤与返回上限。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- `worker-a` 拥有多个不同状态的线程
|
||||
- 其中至少两个线程满足目标状态过滤条件
|
||||
|
||||
## 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-a --status pending,blocked --limit 1
|
||||
```
|
||||
|
||||
## 预期输出
|
||||
|
||||
- 命令退出码为 `0`
|
||||
- 返回线程数不超过 `1`
|
||||
- 返回的每条线程都满足 `status in ["pending","blocked"]`
|
||||
|
||||
## 断言结论
|
||||
|
||||
- `fetch` 的 `status` 与 `limit` 会同时生效
|
||||
- 返回顺序按 `updated_at` 倒序，优先暴露最新线程
|
||||
|
||||
## 补充约束
|
||||
|
||||
- `--limit` 传入 `0` 或负数时，实际会回退到默认上限 `20`
|
||||
@@ -0,0 +1,24 @@
|
||||
# Case: `fetch-returns-no-matching-work-when-empty`
|
||||
|
||||
## 用例意义
|
||||
|
||||
验证 `fetch` 在没有匹配线程时返回稳定的“无工作”错误契约。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- 空数据库已完成 `init`
|
||||
|
||||
## 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-z --status pending
|
||||
```
|
||||
|
||||
## 预期输出
|
||||
|
||||
- 退出码为 `10`
|
||||
- JSON 错误码为 `no_matching_work`
|
||||
|
||||
## 断言结论
|
||||
|
||||
- 空结果不是成功空数组，而是显式的“无匹配工作”信号
|
||||
@@ -0,0 +1,30 @@
|
||||
# Case: `fetch-returns-pending-thread-for-target-agent`
|
||||
|
||||
## 用例意义
|
||||
|
||||
验证 `fetch` 能按目标执行者拉取待处理线程。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- `leader` 已向 `worker-a` 发送至少一个 `pending` 线程
|
||||
|
||||
## 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-a --status pending
|
||||
```
|
||||
|
||||
## 预期输出
|
||||
|
||||
- 命令退出码为 `0`
|
||||
- 返回 `data.threads`
|
||||
- 至少包含一个 `assigned_to == "worker-a"` 且 `status == "pending"` 的线程
|
||||
|
||||
## 断言结论
|
||||
|
||||
- `fetch` 默认是执行者视角的候选工作列表，不是全局线程扫描
|
||||
|
||||
## 补充约束
|
||||
|
||||
- 未显式传 `--status` 时，`fetch` 默认只查询 `pending` 线程
|
||||
- 未显式传命令级 `--agent` 时，可回退到根级 `--agent`
|
||||
@@ -0,0 +1,34 @@
|
||||
# Case: `fetch-unread-uses-read-cursor`
|
||||
|
||||
## 用例意义
|
||||
|
||||
验证 `fetch --unread` 基于 agent 的 read cursor 计算未读，而不是仅按线程是否存在新消息。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- `leader` 已向 `worker-e` 发送一个 `pending` 线程 `THREAD_ID`
|
||||
|
||||
## 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
|
||||
inbox --db TMPDIR/coord.db --agent worker-e --json show --thread THREAD_ID --mark-read
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
|
||||
inbox --db TMPDIR/coord.db --json send --from leader --to worker-e --thread THREAD_ID --summary "Use sentence case" --body "Keep the nav labels in sentence case."
|
||||
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
|
||||
```
|
||||
|
||||
## 预期输出
|
||||
|
||||
- 第一次 `fetch --unread` 返回该线程
|
||||
- `show --mark-read` 后，第二次 `fetch --unread` 无匹配结果
|
||||
- 新消息追加后，第三次 `fetch --unread` 再次返回该线程
|
||||
|
||||
## 断言结论
|
||||
|
||||
- 未读判断依赖 `thread_reads.last_read_message_id`
|
||||
- 新消息到达会让同线程重新进入未读结果集
|
||||
|
||||
## 补充约束
|
||||
|
||||
- 使用 `--unread` 时必须具备 agent 身份，否则会返回 `invalid_input`
|
||||
Reference in New Issue
Block a user