laily
a47e899702
Maintain and run project test catalogs under .pouch/tester, filtered by category, id, and risk (safe/act/harm). Scripts generate the human CSV from cases YAML.
69 lines
2.9 KiB
Markdown
69 lines
2.9 KiB
Markdown
# tester 目录字段
|
||
|
||
项目根 `.pouch/tester/`：
|
||
|
||
```
|
||
catalog.yaml 分类、风险阶梯、session、变量
|
||
local.yaml.example HOST 与授权开关模板
|
||
local.yaml 本机覆盖，不提交
|
||
cases/<category>.yaml 一个分类一个文件（执行源）
|
||
cases.csv 给人看的扁平清单；skill 的 generate_cases_csv.py 读 cases/*.yaml 生成
|
||
runs/ 每次运行快照
|
||
```
|
||
|
||
## catalog.yaml
|
||
|
||
| 字段 | 含义 |
|
||
|------|------|
|
||
| `categories` | `{id, title}` 列表，id 与 `cases/<id小写>.yaml` 对应 |
|
||
| `risks` | 从低到高，只能是 `safe` → `act` → `harm` 的一段，且以 `safe` 开头。含义见 [levels.md](levels.md) |
|
||
| `default_max_risk` | 未指定时的运行上限，必须是 `risks` 里的值 |
|
||
| `vars` | 可替换变量，如 `API_BASE: http://${HOST}:8095` |
|
||
| `auth_env` | 风险名 → 环境变量名。该档执行前变量必须为 `true` |
|
||
| `gates` | 可选。项目细分闸名 → 环境变量。用在用例的 `gate` 上，不要拿它代替 `risk` |
|
||
| `sessions` | 可复用会话。`kind`: `browser` / `mobile`；`reuse`: `run`（本轮结束关掉）或 `persist`（probe 活着就附着） |
|
||
| `id_pattern` | 用例 id 正则 |
|
||
|
||
`local.yaml` 与环境变量覆盖 `HOST` 和授权开关。查找顺序：环境变量 > `local.yaml` > `catalog.yaml` 的 vars。也认 `HX_TEST_HOST` 作为 `HOST`。
|
||
|
||
## 一条用例
|
||
|
||
写在对应分类文件的 `cases:` 列表里。
|
||
|
||
| 字段 | 必填 | 含义 |
|
||
|------|------|------|
|
||
| `id` | 是 | 匹配 `id_pattern` |
|
||
| `category` | 是 | 必须等于文件声明的 category |
|
||
| `title` | 是 | 短名 |
|
||
| `what` | 是 | 一句可观察的「测什么」 |
|
||
| `status` | 是 | `active` / `retired` |
|
||
| `suite` | 是 | `smoke` / `full` / `slow`，判定见 [levels.md](levels.md) |
|
||
| `risk` | 是 | `safe` / `act` / `harm` |
|
||
| `gate` | 否 | 项目细分闸，必须在 catalog `gates` 里 |
|
||
| `surface` | 是 | `script` / `browser` / `mobile` |
|
||
| `session` | browser/mobile 必填 | 指向 catalog `sessions` 的键 |
|
||
| `how` | 是 | 怎么测，见下 |
|
||
| `expected` | 是 | 怎么过，至少一条 `{kind, value}` |
|
||
| `maps_to` | 否 | 对人文档的功能项 id |
|
||
| `requires` | 否 | 前置标签 |
|
||
| `skip_unless` | 否 | 额外跳过条件（环境变量表达式） |
|
||
| `setup` | 否 | 人话前置 |
|
||
| `cleanup` | 否 | 跑完回退 |
|
||
| `notes` | 否 | 备注 |
|
||
|
||
## how
|
||
|
||
- `script`：`how.run` 是一条可在项目根执行的命令（可多行脚本）。没有 `run` 时 Agent 按 `how.steps` 做，仍不得发明未写明的请求。
|
||
- `browser`：`how.url` + `how.steps`。`expected.kind` 用 `visible-text` / `url` / `interaction`。
|
||
- `mobile`：`how.steps`，挂到 `session` 指定的模拟器。`expected` 同样是可观察信号。
|
||
|
||
可选 `how.timeout`，秒，默认 60。
|
||
|
||
## expected.kind
|
||
|
||
`api-status` / `api-field` / `script-exit` / `visible-text` / `url` / `interaction`
|
||
|
||
## 判定
|
||
|
||
`pass` / `fail` / `environment-fail` / `skipped`
|