--- name: tester description: >- 维护并执行项目黑盒测试目录（.pouch/tester）：列出/增改用例，按分类或 id 跑脚本、浏览器或移动模拟器；支持用 Orca project id、项目名称或 terminal id 定位 Agent 执行环境并创建临时 terminal。触发词：/tester、列出测试、完善测试用例、 按分类测、跑 smoke、现场复测；测试环境由本机触发，正式环境由 app00 Agent terminal 委派部署。 默认风险最低档；local 配置的 HOST 默认是 127.0.0.1。 --- # Tester：项目测试目录 开始时解析本 `SKILL.md` 所在目录为 ``。项目根用 `git rev-parse --show-toplevel`。目录固定为目标测试项目的 `/.pouch/tester/`；父仓库 和 Git submodule 可以各自拥有独立目录。 ## 多测试项目 / 子项目 一个仓库可能同时包含后端测试目录和 `app` 等子项目测试目录。用例属于拥有 `catalog.yaml` 的项目，不能把多个 catalog 的 cases 合并成一份清单或共用一次运行快照。 开始列出或运行前，先发现目标仓库下的独立测试根： ```bash python3 /scripts/catalog.py roots --root ``` 选择规则： - `/.pouch/tester/catalog.yaml` 存在时，它是一个独立测试根； - 同时检查 Git submodule 和一层普通子项目目录； - 只有一个嵌套 catalog 时，可直接用该路径继续 `list/select/run`； - 有多个 catalog 时由 tester 自动 fan-out，逐个项目分别执行，不等待用户选择，也不合并 cases； - 每个测试根单独生成 `.pouch/tester/runs/*.yaml`/`.csv`，交付记录可分别引用这些快照。 如果父仓库没有 catalog 但子项目有 catalog，不能把“父目录无 catalog”报告为环境失败；先用 `roots` 找到子项目并继续。只有发现不到任何 catalog，才按缺少 tester 目录处理。 CLI 也有同样的保护：从父仓库执行 `list/select/validate/run-script` 时，若只发现一个 子 tester 根会自动进入该根；发现多个候选会自动 fan-out，每个根独立输出、独立校验、 独立生成运行记录。不需要、也不能通过在根 `.pouch` 里写一个未定义的 `include` 来拼接 子项目配置。 Agent 执行目标优先来自项目根 `.pouch/agent.yaml` 的 `tester.` binding，由共享 `agent-runtime` 解析 environment、host、project、path 和 profile。`.pouch/tester/local.yaml` 仍是兼容覆盖层：解析 binding 后可 materialize 为旧 `agent` mapping，但不应再维护两套 互相矛盾的主配置；binding 名称不是固定枚举。 用脚本读写目录，不要把 `cases/` 整库灌进上下文。术语与命名理由见 [references/concepts.md](references/concepts.md)： ```bash python3 /scripts/catalog.py \ --root [参数] ``` 运行目标可用 `resolve_agent.py` 按 Orca project id/名称或 terminal id 自动解析并写入 `.pouch/tester/local.yaml` 的 `agent` 配置；配置更新完成后输出生效配置列表。该列表是 更新结果，不是测试启动前的人工确认门槛。 用户给出 `tester.` 时，先用共享 `agent-runtime` 校验并精确解析，再写入兼容的 tester agent 配置。 ## 选择模式 - 先用 `roots` 检查当前仓库及子项目；没有任何 `.pouch/tester/catalog.yaml`，或用户说初始化 tester：执行「初始化」。 - 列出、有哪些测试、一共多少条：执行「列出」。 - 看某一条怎么测：执行「查看」。 - 加一条 / 完善 / 改验证 / 退役：执行「维护」。 - 检查目录是否完整：执行「检查」。 - 跑测试、按分类测、按 id 测、跑 smoke：执行「运行」。 ## 边界（所有模式） - `local.yaml.example` 的 HOST 默认是 `127.0.0.1`；如果目标不是本机，必须在 `local.yaml` 或环境变量中显式覆盖。`local.yaml` 不存在且没有环境变量时仍不猜 HOST，停下并记 environment-fail。 - 默认执行 profile 是 `standard`：风险上限来自 catalog 的 `default_max_risk`，超出上限的条目标 `skipped`，禁止执行。若 catalog 声明 `execution_profile: isolated-full`，只允许用于隔离且可重置的测试环境：所有 active 自动化用例都进入执行矩阵，不因 `AUTHORIZE_MUTATING`、`AUTHORIZE_DESTRUCTIVE`、`AUTHORIZE_ALBUM` 或 `AUTHORIZE_PASSWORD` skipped；原有 `risk` 值必须保留并进入报告。设备、产物、服务和清理契约由 test-preflight 检查；相册、照片权限/测试图片和中文拼音能力在本项目中默认具备，由 journey 用例真实验证。 - `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`，不要自己代跑人工步骤。isolated-full 取消的是风险/授权过滤，不会伪造人工操作。见 [concepts.md](references/concepts.md)。 - 浏览器、移动模拟器按 catalog `sessions` 初始化一次，同一次运行内复用。 - Agent、环境、项目目录和 Orca terminal 生命周期见 [execution.md](references/execution.md)：可以从 project id/名称或 terminal id 自动解析，更新后输出配置列表；每轮都新建 terminal，结束后关闭本轮创建的 terminal，不复用或关闭已有 terminal。 - 环境准备见 [deployment.md](references/deployment.md)：测试环境只调用 deployer 的本机 Compose 路径；正式环境只委派给本机 `~/code/app00` 的 fresh Agent terminal，tester 不直接 SSH 或执行生产 Compose。 - `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. 若不存在，从 `/templates/` 拷 `catalog.yaml` 和 `local.yaml.example`。 3. 从模板生成的 `local.yaml` 默认使用 `HOST: "127.0.0.1"`；不要根据项目内容猜远程地址。 4. 跑 `catalog.py validate --root `。无用例是「部分完成」，不是失败。 ```text ## tester 初始化：完成 | 部分完成 | 阻塞 已具备: … 待配置: 路径 + 字段 + 缺了会挡住哪步 下一步: 一句话 ``` ## 列出 ```bash python3 /scripts/catalog.py list --root ``` 把脚本打印的分类表原样给用户。不要手算条数。清单 CSV 由独立脚本从 `cases/*.yaml` 生成： ```bash python3 /scripts/generate_cases_csv.py --root ``` `list` 结束时也会跑它。告诉用户路径 `.pouch/tester/cases.csv`。不要手改 CSV，改用例走「维护」后再生成。该 CSV 只包含用例定义；运行结果只写入独立的 `.pouch/tester/runs/.yaml`，不会回写清单。 ## 查看 ```bash python3 /scripts/catalog.py show --root --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)、[deployment.md](references/deployment.md) 和 [test-bundle.md](references/test-bundle.md)。运行必须按以下顺序执行： 1. 先建立本轮测试矩阵，列出实际要测的产物、平台、commit、包/Bundle 身份、产物路径或下载地址，以及对应的 `tester.` 执行绑定。用户要求 Android+iOS 时，两行都必须出现；不能因为只拿到 Android 产物就缩小范围。 2. 对所有 tester 根的矩阵行做完整 preflight：先用 `catalog.py select` 校验平台、产物定位和 tester binding，再检查目标 Agent/环境/项目路径、Android/iOS 设备闸门和 HOST 可达。所有根的检查完成前不得创建测试 session 或开始任何测试用例。 3. 有任一根或任一行不可用时，先完成其它根的 preflight，再一次性输出完整不可用清单、观测结果、修复动作和可复制的验证命令，然后停止测试执行；不能先执行已通过 preflight 的根，也不能把缺失平台记成测试通过。 4. 只有矩阵所有行都可用，才创建本轮测试 terminal/session，按 `select` 结果执行并记录成绩。 测试环境由本机 deployer 触发，正式环境由 app00 Agent terminal 委派。随后按 agent 解析目标项目、目录和 Agent，更新配置并输出生效列表。移动端每个平台的产物位置必须由调用方给出，值为本地文件或 URL；缺了就停，不要猜 builder、CI release 或本机旧包。矩阵行记产物位置、身份和 `tester.` binding，并用 `/tester run --artifact android= --artifact ios= --platform android,ios` 下载或取用、安装并准备本轮隔离 worktree。Android 在 `tester.android`、iOS 在 `tester.ios` 节点执行。未指定范围时等同「tag=smoke 且风险上限=默认且 automation=automated」。`select` 的 `run_together` 组按 [run.md](references/run.md) 整组执行。无论部署或测试成功、失败、超时还是中断，都要清理各自本轮创建的 terminal。 ### 客户端用户旅程标准 ### 双层测试与执行顺序 用例顶层类型是 `test_type: integration | journey`。旧目录没有该字段时保持兼容：已有 `client_suite`/`journey` 视为 journey，已有 `integration_suite` 视为 integration。集成 套件至少包括 `api-contract`、`authorization`、`build-contract`；旅程套件仍固定为 `client-smoke`、`client-regression`、`safety`。集成用例不需要客户端 session、platform 或 journey 字段，不能被客户端套件选中。 一次运行严格遵守： ```text test-preflight (blocked/environment-fail -> 不创建 session) -> integration -> journey (integration fail -> not-run，不创建 session) ``` `test-preflight` 的报告是环境证据，不计入 testcase 总数。服务不可达记 `environment-fail`；服务已达但契约断言错误记 integration `fail`；正确测试账号登录失败 仍记 journey `fail`。tester 的 `run`/bundle 入口必须接收 caller 提供的 preflight matrix， 没有 matrix 不得绕过闸门或伪造成功。 声明 `client_suite`（迁移期也接受 `suite`）的用例采用固定的三套客户端集合： `client-smoke`、`client-regression`、`safety`。前两者分别覆盖最短只读主路径和隔离测试 环境中的普通用户回归；`safety` 覆盖危险/权限边界场景，必须显式选择和授权，不能被 默认 smoke/full 扩入。选择某套客户端旅程可用： ```bash python3 /scripts/catalog.py select --root --suite client-smoke python3 /scripts/catalog.py select --root --suite client-regression --max-risk mutating python3 /scripts/catalog.py select --root --suite safety --max-risk destructive ``` 客户端用例必须声明 `journey`、`fixture`、`session`、`cleanup` 和 `platform`。旅程包含 `goal`、`entry_state`、`actions`、`assertions`、`final_state`、`failure_policy`；fixture 至少声明测试账号；session 指向 catalog 中可复用的 browser/mobile session；cleanup 要有 步骤或命令（只读也要显式说明无需清理）；platform 只能是 Android/iOS。具体字段见 `references/schema.md`。平台适配只能改操作层，不能把真实客户端操作换成 API 调用。 客户端运行器统一遵守 `preflight → 启动 → 登录 → 旅程 → 断言 → 清理 → 报告`。正确测试 账号登录失败是产品 `fail`；设备、产物、服务或 session 不可达才是 `environment-fail`。 fixture 或 cleanup 缺失会在 `catalog.py select` 的 preflight 阶段阻断，不产生虚假逐条结果。 能力缺失时 preflight 必须明确 blocked/environment-fail，并为所有选中的 testcase 生成 `not-run` 结果行；不能把缺失的相册、照片权限、测试图片或中文拼音 composition/candidate 能力静默变成 `skipped`。独立用例继续执行，依赖失败的用例写 `not-run` 和 `blocked_by`； 修复后按 targeted rerun，再执行 full integration → journey。成绩仍写现有 `runs/.yaml` 并用 `generate_run_csv.py` 生成同名 CSV；YAML 可带 `defects`/ `test_issues` 与 `feedback`，记录 testcase、product/test issue 类型、expected/observed、 artifact hash、environment、证据路径、复现和下一步，不添加新的 result 值。 PR 触发的失败回流必须先更新 PR/关联 issue，再通知 dispatcher 重新分配开发；需求/bug 触发的失败直接返回开发流程。tester 只生成结构化回流计划，不在本地偷偷修改远端。