72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
# Inbox Markdown Test Plan
|
|
|
|
## Purpose
|
|
|
|
This directory contains the human-readable Markdown test plan for the `inbox` CLI.
|
|
|
|
It complements automated Go tests. The goal is not to restate implementation details, but to preserve the user-visible CLI contract in a form that can be reviewed, extended, and executed manually when needed.
|
|
|
|
## Directory Rules
|
|
|
|
- one folder per command or shared area
|
|
- each folder keeps a `README.md` entrypoint
|
|
- command folders use `README.md` as an index only
|
|
- each command test case lives in its own Markdown file named after the case slug
|
|
- no numeric test IDs
|
|
- each command case is identified by its concrete file path
|
|
|
|
Case file naming pattern:
|
|
|
|
```text
|
|
<case-slug>.md
|
|
```
|
|
|
|
## Authoring Principles
|
|
|
|
- focus on externally visible behavior of the CLI
|
|
- prefer stable command examples that a new agent can replay against a temp database
|
|
- describe both success shape and failure contract
|
|
- when a case already exists in automated Go tests, reuse its scenario rather than inventing a new one
|
|
- keep terminology consistent with command flags and JSON fields exposed by the CLI
|
|
|
|
## Common Execution Model
|
|
|
|
Most cases in this directory assume the same baseline:
|
|
|
|
1. create an isolated temporary directory
|
|
2. choose a database path such as `TMPDIR/coord.db`
|
|
3. run `inbox --db TMPDIR/coord.db --json init`
|
|
4. run the target command sequence against that database
|
|
|
|
Unless a case says otherwise:
|
|
|
|
- commands should use `--json`
|
|
- assertions should check both exit code and JSON payload
|
|
- examples may use explicit `--agent`, or rely on the root `--agent` flag when that is the behavior under test
|
|
|
|
## Folder Map
|
|
|
|
- `README.md`: global conventions and glossary
|
|
- `_shared/README.md`: reusable fixtures, JSON assertions, exit codes, payload rules
|
|
- `workflows/README.md`: cross-command end-to-end scenarios
|
|
- per-command folders: command-specific index `README.md` files plus one case document per test case
|
|
|
|
## Glossary
|
|
|
|
- `thread`: the durable coordination unit tracked by `thread_id`
|
|
- `message`: an event-bearing entry appended to a thread
|
|
- `artifact`: a file attachment associated with a message
|
|
- `read cursor`: the per-agent marker used by unread flows
|
|
- `lease`: the temporary ownership granted by `claim` and extended by `renew`
|
|
- `terminal state`: a thread state such as `done`, `failed`, or `cancelled`
|
|
|
|
## Relationship To Automated Tests
|
|
|
|
The current best executable reference is [integration_test.go](../../../packages/inbox-runtime/internal/cli/inbox/integration_test.go).
|
|
|
|
When this Markdown plan is expanded:
|
|
|
|
- prefer matching an existing automated scenario first
|
|
- record any additional manual-only contract coverage explicitly in the relevant command case file and keep the folder index synchronized
|
|
- keep `docs/tests/inbox/ROADMAP.md` synchronized with authored files and case slugs
|