195 lines
13 KiB
Markdown
195 lines
13 KiB
Markdown
---
|
||
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` 所在目录为 `<skill-dir>`。项目根用
|
||
`git rev-parse --show-toplevel`。目录固定为目标测试项目的 `<root>/.pouch/tester/`；父仓库
|
||
和 Git submodule 可以各自拥有独立目录。
|
||
|
||
## 多测试项目 / 子项目
|
||
|
||
一个仓库可能同时包含后端测试目录和 `app` 等子项目测试目录。用例属于拥有
|
||
`catalog.yaml` 的项目，不能把多个 catalog 的 cases 合并成一份清单或共用一次运行快照。
|
||
|
||
开始列出或运行前，先发现目标仓库下的独立测试根：
|
||
|
||
```bash
|
||
python3 <skill-dir>/scripts/catalog.py roots --root <repo-root>
|
||
```
|
||
|
||
选择规则：
|
||
|
||
- `<repo-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.<name>` 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 <skill-dir>/scripts/catalog.py <roots|list|select|show|validate|next-id|run-script> \
|
||
--root <project-root> [参数]
|
||
```
|
||
|
||
运行目标可用 `resolve_agent.py` 按 Orca project id/名称或 terminal id 自动解析并写入
|
||
`.pouch/tester/local.yaml` 的 `agent` 配置；配置更新完成后输出生效配置列表。该列表是
|
||
更新结果，不是测试启动前的人工确认门槛。
|
||
|
||
用户给出 `tester.<name>` 时，先用共享 `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。
|
||
- 默认风险上限是 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。
|
||
- 环境准备见 [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. 若不存在，从 `<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)、[deployment.md](references/deployment.md) 和 [test-bundle.md](references/test-bundle.md)。运行必须按以下顺序执行：
|
||
|
||
1. 先建立本轮测试矩阵，列出实际要测的产物、平台、commit、包/Bundle 身份、产物路径或下载地址，以及对应的 `tester.<platform>` 执行绑定。用户要求 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.<platform>` binding，并用 `<skill-dir>/tester run --artifact android=<path-or-url> --artifact ios=<path-or-url> --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 <skill-dir>/scripts/catalog.py select --root <root> --suite client-smoke
|
||
python3 <skill-dir>/scripts/catalog.py select --root <root> --suite client-regression --max-risk mutating
|
||
python3 <skill-dir>/scripts/catalog.py select --root <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 阶段阻断，不产生虚假逐条结果。
|
||
前置用例失败后剩余条目写 `not-run`，主动排除/未授权写 `skipped`。成绩仍写现有
|
||
`runs/<run-id>.yaml` 并用 `generate_run_csv.py` 生成同名 CSV；清理失败作为 cleanup 证据
|
||
单独记录，不添加新的 result 值。
|