name: cli-e2e-testcase-writer
description: 当为编译后的 `lark-cli` 中某个 `tests/cli_e2e/{domain}` 域添加或更新 Go CLI 端到端测试覆盖率时使用，尤其是在需要实时 `--help` 或 `schema` 探索、基于场景的 `clie2e.RunCmd` 工作流以及按域维护 `coverage.md` 的场景下。
metadata:
    requires:
        bins: ["lark-cli"]

CLI E2E 测试用例编写器

每次运行只处理一个领域。为该领域生成两个工件：

• tests/cli_e2e/{domain}/ 下的工作流测试用例文件
• tests/cli_e2e/{domain}/coverage.md

专注于领域测试用例文件。不要更改共享的 E2E 支持代码（如 tests/cli_e2e/core.go），除非用户明确要求。将 tests/cli_e2e/demo/ 仅作为参考。

核心标准

• 测试用例应基于场景且自包含。
• 端到端验证一个工作流：创建加后续读取，或变更加清理。
• 优先每个工作流或紧密相关的功能使用一个文件。
• 对于可变流，通过写入后读取断言来证明持久状态，而不仅仅是退出码。
• 当无法证明依赖前置条件的路径时，保留这些路径不覆盖，并在 coverage.md 中解释原因。

工作流

1. 在编写代码之前探索实时 CLI

lark-cli --help
lark-cli <domain> --help
lark-cli <domain> +<shortcut> -h
lark-cli <domain> <group> --help
lark-cli <domain> <group> <method> -h
lark-cli schema <domain>.<group>.<method>

2. 统计叶子命令作为分母

• 叶子命令是执行操作的命令——它没有进一步的子命令。
• 如果 lark-cli <domain> <group> --help 没有列出子命令，则 <group> 本身就是叶子命令。
• 将 task +create 计为一个叶子命令，将 task tasks get 计为一个叶子命令。
• 不要统计参数组合。
• 重用 tests/cli_e2e/{domain}/ 下已有的覆盖率。不要统计 tests/cli_e2e/demo/。

3. 在编辑之前选择证明面

识别所涉及工作流的可证明风险：无效输入、缺少前置条件、身份或权限、状态转换、输出形状、清理安全性。如果只能测试快乐路径，则在 coverage.md 中记录被阻塞的风险区域。

4. 添加或更新工作流测试用例

• 使用 clie2e.RunCmd(ctx, clie2e.Request{...})。
• 命令路径和普通标志放在 Args 中；JSON 放在 Params（URL/路径参数）和 Data（请求体）中。
• 优先每个工作流一个顶级测试，使用 t.Run 子步骤。
• 在 parentT.Cleanup 上注册清理，使其在子测试失败时仍然执行。
• 当修改现有命令时，先验证 JSON 响应形状是稳定的：在更改断言之前，先断言状态类型、字段路径以及后续步骤使用的标识符。

5. 运行并迭代

在迭代过程中和完成之前，运行 go test ./tests/cli_e2e/{domain} -count=1。如果命令形状或行为不清楚，在更改断言之前重新检查帮助或模式（步骤 1）。

6. 刷新领域输出

• 更新工作流测试用例文件。
• 更新 coverage.md：从实时帮助输出重新计算分母，将每个命令标记为 shortcut 或 api，并为整个领域保留一个命令表。

测试用例规则

• 仅在测试用例真正需要时覆盖 BinaryPath、DefaultAs 或 Format。
• 使用 require.NoError、result.AssertExitCode、result.AssertStdoutStatus、assert 和 gjson。
• 快捷方式响应（{ok: bool}）断言为 true；API 响应（{code: int}）断言为 0。
• 仅在设置或断言辅助函数被多个测试调用时使用 t.Helper()。
• 仅当场景形状在多个输入中重复时使用表格驱动测试。
• 对于预期失败，当环境使其确定时，断言 stderr 内容和退出码。
• 如果身份或外部固定装置无法证明，则让命令不被覆盖并记录前置条件，而不是伪造信心。

coverage.md

保持 coverage.md 简洁且机械化。包括：

• 领域特定的 H1 标题
• 度量部分，包含分母、覆盖计数和覆盖率
• 摘要部分，重新说明每个 Test... 工作流、关键的 t.Run(...) 证明点以及主要阻塞点
• 所有命令的一个命令表

推荐结构：

# <Domain> CLI E2E Coverage

## 度量
- 分母：N 个叶子命令
- 已覆盖：N
- 覆盖率：N%

## 摘要
- TestXxx：... 关键 `t.Run(...)` 证明点 ...
- 阻塞区域：...

## 命令表
| 状态 | 命令 | 类型 | 测试用例 | 关键参数形状 | 注释 / 未覆盖原因 |
| --- | --- | --- | --- | --- | --- |
| ✓ | task +create | shortcut | task_status_workflow_test.go::TestTask_StatusWorkflow | 基本创建；带截止日期创建 | |
| ✕ | task +assign | shortcut |  | 无 | 需要真实用户 open_id |

• 将每个命令标记为 shortcut 或 api。
• 以 go test -run 友好的形式编写测试用例条目。
• 仅在 parentT.Cleanup 清理中执行的命令不计为已覆盖。
• 不要将已覆盖和未覆盖的命令分成不同的部分。

护栏

• 仅以机器人身份运行；不要假设 --as user 有效。
• 不要在 tests/cli_e2e/demo/ 下放置新的真实覆盖率。
• 不要依赖预先存在的远程数据。
• 不要伪造 open_ids、聊天、文档或其他远程固定装置。
• 优先使用确定性的负面情况而不是依赖租户的断言。
• 当帮助或模式可以告知确切形状时，不要猜测 Params 或 Data 字段。
• 除非命令确实需要显式标志，否则不要硬编码明显的默认值。
• 不要在可见的远程测试数据中放置代理、模型或供应商品牌名称；使用中性前缀，如 lark-cli-e2e- 或 <domain>-e2e-。
• 仅当测试用例断言了返回字段或持久状态（而不仅仅是退出码）时，命令才算被覆盖。
• 仅清理执行不是主要覆盖，除非是在同一工作流中创建资源的 delete。