---
name: tester
description: >-
  维护并执行项目黑盒测试目录（.pouch/tester）：列出/增改用例，按分类或
  id 跑脚本、浏览器或移动模拟器；支持用 Orca project id、项目名称或 terminal id
  定位 Agent 执行环境并创建临时 terminal。触发词：/tester、列出测试、完善测试用例、
  按分类测、跑 smoke、现场复测。
  默认风险最低档；local 配置的 HOST 默认是 127.0.0.1。
---

# Tester：项目测试目录

开始时解析本 `SKILL.md` 所在目录为 `<skill-dir>`。项目根用
`git rev-parse --show-toplevel`。目录固定为 `<root>/.pouch/tester/`。

用脚本读写目录，不要把 `cases/` 整库灌进上下文。术语与命名理由见 [references/concepts.md](references/concepts.md)：

```bash
python3 <skill-dir>/scripts/catalog.py <list|select|show|validate|next-id|run-script> \
  --root <project-root> [参数]
```

运行目标可用 `resolve_agent.py` 按 Orca project id/名称或 terminal id 自动解析并写入
`.pouch/tester/local.yaml` 的 `agent` 配置；配置更新完成后输出生效配置列表。该列表是
更新结果，不是测试启动前的人工确认门槛。

## 选择模式

- 还没有 `.pouch/tester/catalog.yaml`，或用户说初始化 tester：执行「初始化」。
- 列出、有哪些测试、一共多少条：执行「列出」。
- 看某一条怎么测：执行「查看」。
- 加一条 / 完善 / 改验证 / 退役：执行「维护」。
- 检查目录是否完整：执行「检查」。
- 跑测试、按分类测、按 id 测、跑 smoke：执行「运行」。

## 边界（所有模式）

- `local.yaml.example` 的 HOST 默认是 `127.0.0.1`；如果目标不是本机，必须在
  `local.yaml` 或环境变量中显式覆盖。`local.yaml` 不存在且没有环境变量时仍不猜
  HOST，停下并记 environment-fail。
- 默认风险上限是 catalog 里的 `default_max_risk`。超出上限的条目标 `skipped`，禁止执行。
- `risk` 只能是 `readonly` / `mutating` / `destructive`，默认只跑 `readonly`。`tag=smoke` 只能配 `risk=readonly`。规则见 [levels.md](references/levels.md)。
- `driver=browser` 必须开真实页面；`driver=mobile` 必须挂模拟器 session。二者都不得改成只打 API。
- `automation=assisted|manual` 需要人在场：无人值守时记 `not-run`，不要自己代跑人工步骤。见 [concepts.md](references/concepts.md)。
- 浏览器、移动模拟器按 catalog `sessions` 初始化一次，同一次运行内复用。
- Agent、环境、项目目录和 Orca terminal 生命周期见 [execution.md](references/execution.md)：可以从 project id/名称或 terminal id 自动解析，更新后输出配置列表；每轮都新建 terminal，结束后关闭本轮创建的 terminal，不复用或关闭已有 terminal。
- `HOST` 只表示被测服务地址；远程执行目标使用 `agent` 配置。目标目录必须已有项目内容，找不到 Orca 项目记录时直接登记已有目录；目录本身不存在时停止，不创建空项目。
- 环境失败（连不上、缺浏览器、下游超时、session 挂了）不是产品失败。
- 移动端运行必须先通过 [run.md](references/run.md) 的平台环境闸门；Android 与 iOS 分开探测。目标平台没有可用设备/模拟器时，先停止移动用例，记 `environment-fail`，并按 run.md 的模板引导用户补齐环境，不能只报一个失败状态。
- 环境引导必须写明平台、具体缺失项、用户可执行的修复动作、验证命令和重跑方式。不得用 API 调用替代真实 Android/iOS session，也不得把环境缺失判成产品 `fail`。
- 不改产品代码，不提交，不把成绩单当操作手册。
- 禁止把完整 `cases/` 贴进 prompt。筛选用 `select`，单条用 `show`。

## 初始化

用户点名才跑。已有 `catalog.yaml` 则不覆盖，转入「检查」。

1. 建 `.pouch/tester/{cases,runs}/`。
2. 若不存在，从 `<skill-dir>/templates/` 拷 `catalog.yaml` 和 `local.yaml.example`。
3. 从模板生成的 `local.yaml` 默认使用 `HOST: "127.0.0.1"`；不要根据项目内容猜远程地址。
4. 跑 `catalog.py validate --root <root>`。无用例是「部分完成」，不是失败。

```text
## tester 初始化：完成 | 部分完成 | 阻塞

已具备: …
待配置: 路径 + 字段 + 缺了会挡住哪步
下一步: 一句话
```

## 列出

```bash
python3 <skill-dir>/scripts/catalog.py list --root <project-root>
```

把脚本打印的分类表原样给用户。不要手算条数。清单 CSV 由独立脚本从 `cases/*.yaml` 生成：

```bash
python3 <skill-dir>/scripts/generate_cases_csv.py --root <project-root>
```

`list` 结束时也会跑它。告诉用户路径 `.pouch/tester/cases.csv`。不要手改 CSV，改用例走「维护」后再生成。该 CSV 只包含用例定义；运行结果只写入独立的 `.pouch/tester/runs/<run-id>.yaml`，不会回写清单。

## 查看

```bash
python3 <skill-dir>/scripts/catalog.py show --root <project-root> --id <CASE_ID>
```

只展示这一条的 how / expected / risk / driver / automation。字段对不上时再读 [schema.md](references/schema.md)。

## 检查

只读。跑 `validate`。HOST 是否已配置只报「已设 / 未设」，不要把 `local.yaml` 全文贴出来。用初始化同一套报告，标题改为 `## tester 检查：…`。

## 维护

读 [maintain.md](references/maintain.md)。写 `tag`/`risk`/`automation` 时读 [levels.md](references/levels.md) 与 [concepts.md](references/concepts.md)。先 `show` 或 `next-id`，拟好条目给用户确认再写文件，然后 `validate`。

## 运行

读 [run.md](references/run.md) 和 [execution.md](references/execution.md)。先 `select` 得到命中列表，再按 agent 解析目标项目、目录和 Agent，更新配置并输出生效列表，随后创建临时 terminal 并按 driver 分流。未指定范围时等同「tag=smoke 且风险上限=默认且 automation=automated」。`select` 的 `run_together` 组按 [run.md](references/run.md) 整组执行。移动端还要先识别目标平台并完成 Android 或 iOS 环境闸门；闸门未通过时输出对应的用户引导，不继续猜测或代跑。无论运行结果如何，结束前关闭本轮创建的 terminal。