docs: split inbox test plans into case files
This commit is contained in:
@@ -1,91 +1,9 @@
|
||||
# Inbox `watch` Test Plan
|
||||
# Inbox `watch` Test Plan Index
|
||||
|
||||
## Scope
|
||||
## Case Files
|
||||
|
||||
This document covers blocking thread-activity wait behavior via `inbox watch`.
|
||||
|
||||
Shared conventions live in [../_shared/README.md](../_shared/README.md).
|
||||
|
||||
## case: watch-wakes-on-matching-thread
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证 `watch` 在新匹配线程到达时会被唤醒，并返回线程、消息与事件信息。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- `worker-d` 当前没有匹配 `pending` 线程
|
||||
- `watch` 先于 `send` 启动
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json watch --agent worker-d --status pending --timeout-seconds 2
|
||||
inbox --db TMPDIR/coord.db --json send --from leader --to worker-d --subject "Build admin editor" --summary "Create the first editor screen"
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- `watch` 退出码为 `0`
|
||||
- `watch.data.woke == true`
|
||||
- 返回 `thread`、`message`、`event`
|
||||
|
||||
### 断言结论
|
||||
|
||||
- `watch` 唤醒结果不仅说明“醒了”，还提供触发该唤醒的具体事件上下文
|
||||
|
||||
## case: watch-respects-status-filter
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证 `watch --status` 只会对匹配状态的后续事件唤醒。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- 存在一个会被推进到 `blocked` 的线程 `THREAD_ID`
|
||||
- `watch` 以 `--status blocked` 先启动
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json watch --agent worker-c --status blocked --timeout-seconds 2
|
||||
inbox --db TMPDIR/coord.db --json update --agent worker-c --thread THREAD_ID --status blocked --summary "Need policy decision"
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- `watch` 只在线程进入 `blocked` 后返回
|
||||
- 返回的 `thread.status == "blocked"`
|
||||
|
||||
### 断言结论
|
||||
|
||||
- `watch` 的状态过滤作用在“事件发生后的线程状态”上
|
||||
|
||||
## case: watch-times-out-with-no-activity
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证在超时时间内没有匹配活动时，`watch` 返回稳定超时契约。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- 没有新匹配事件会发生
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json watch --agent worker-d --status pending --timeout-seconds 1
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- 退出码为 `10`
|
||||
- JSON 错误码为 `no_matching_work`
|
||||
|
||||
### 断言结论
|
||||
|
||||
- `watch` 超时被归类为“无匹配工作”，而不是内部错误
|
||||
|
||||
## Notes
|
||||
|
||||
- 未传 `--after-event` 时，`watch` 默认从“当前时刻之后”开始等待，不会回放既有事件
|
||||
| Case Slug | File | Coverage Note |
|
||||
| --- | --- | --- |
|
||||
| `watch-wakes-on-matching-thread` | [watch-wakes-on-matching-thread.md](./watch-wakes-on-matching-thread.md) | wakes when a matching post-start event arrives and returns event context |
|
||||
| `watch-respects-status-filter` | [watch-respects-status-filter.md](./watch-respects-status-filter.md) | wakes only when thread transitions into requested status |
|
||||
| `watch-times-out-with-no-activity` | [watch-times-out-with-no-activity.md](./watch-times-out-with-no-activity.md) | returns timeout contract when no matching activity arrives |
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# case: watch-respects-status-filter
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证 `watch --status` 只会对匹配状态的后续事件唤醒。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- 存在一个会被推进到 `blocked` 的线程 `THREAD_ID`
|
||||
- `watch` 以 `--status blocked` 先启动
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json watch --agent worker-c --status blocked --timeout-seconds 2
|
||||
inbox --db TMPDIR/coord.db --json update --agent worker-c --thread THREAD_ID --status blocked --summary "Need policy decision"
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- `watch` 只在线程进入 `blocked` 后返回
|
||||
- 返回的 `thread.status == "blocked"`
|
||||
|
||||
### 断言结论
|
||||
|
||||
- `watch` 的状态过滤作用在“事件发生后的线程状态”上
|
||||
- `--status` 默认值为 `pending,blocked,done,failed`；未显式传入时，`watch` 不是只观察 `pending`
|
||||
- 显式传入 `--after-event` 时，`watch` 会从该事件游标之后恢复，允许调用方断点续看
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# case: watch-times-out-with-no-activity
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证在超时时间内没有匹配活动时，`watch` 返回稳定超时契约。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- 没有新匹配事件会发生
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json watch --agent worker-d --status pending --timeout-seconds 1
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- 退出码为 `10`
|
||||
- JSON 错误码为 `no_matching_work`
|
||||
|
||||
### 断言结论
|
||||
|
||||
- `watch` 超时被归类为“无匹配工作”，而不是内部错误
|
||||
- `--timeout-seconds 0` 表示无限等待，而不是立即超时
|
||||
- 未传 `--after-event` 时，`watch` 默认从“当前时刻之后”开始等待，不会回放既有事件
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# case: watch-wakes-on-matching-thread
|
||||
|
||||
### 用例意义
|
||||
|
||||
验证 `watch` 在新匹配线程到达时会被唤醒，并返回线程、消息与事件信息。
|
||||
|
||||
### 前置条件
|
||||
|
||||
- `worker-d` 当前没有匹配 `pending` 线程
|
||||
- `watch` 先于 `send` 启动
|
||||
|
||||
### 输入
|
||||
|
||||
```bash
|
||||
inbox --db TMPDIR/coord.db --json watch --agent worker-d --status pending --timeout-seconds 2
|
||||
inbox --db TMPDIR/coord.db --json send --from leader --to worker-d --subject "Build admin editor" --summary "Create the first editor screen"
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
- `watch` 退出码为 `0`
|
||||
- `watch.data.woke == true`
|
||||
- 返回 `thread`、`message`、`event`
|
||||
|
||||
### 断言结论
|
||||
|
||||
- `watch` 唤醒结果不仅说明“醒了”，还提供触发该唤醒的具体事件上下文
|
||||
- `--agent` 未显式提供时，可以回退使用根级 `--agent`；如果两者都未提供，则 `watch` 变为不按 `assigned_to` 过滤的全局观察
|
||||
- 成功唤醒时返回的 `next_event_id` 应等于触发唤醒的 `event.event_id`
|
||||
|
||||
Reference in New Issue
Block a user