lark-cli 命令 E2E 覆盖率文件（coverage.md）规范：从 demo 模板到真实域落地

CLIAI 技能【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址https://gitcode.com/gh_mirrors/cli414/cli点击查看免费下载本文以tests/cli_e2e/demo/coverage.md为核心骨架系统讲解 lark-cliLark/飞书官方 CLI端到端测试体系中每域一覆盖率文件的维护规范Metrics 指标口径、Summary 工作流摘要、Command Table 命令表格、Notes 注意事项以及覆盖率分母如何从真实lark-cli --help输出重算、哪些执行路径不该计入覆盖、被阻塞命令如何记录原因。读完你可以为任意业务域如task、docs编写或维护一份既机械又可信的coverage.md。一、coverage.md 在 lark-cli E2E 体系中的定位lark-cli 的端到端测试模块位于 tests/cli_e2e其使命是从用户视角验证真实 CLI 工作流编译出二进制、逐条执行命令、捕捉单元测试发现不了的回归。该目录下每个业务域application/、task/、docs/、im/、drive/等都拥有一份独立的coverage.md用来回答三个问题本域共有多少个叶子命令可执行动作的命令无下级子命令其中多少被 E2E 测试用断言真正覆盖未覆盖的每条命令为什么未覆盖缺少真实用户 fixture、清理专用执行、环境不稳等。tests/cli_e2e/demo/coverage.md就是这份文件的示范模板目录本身只含文档和参考用例没有真实的lark-cli demo命令树因此它展示的是即使目录只做文档用途、背后没有真实命令树时如何维护一份每域覆盖率文件的形态。正如文件头部反复强调的demo 是参考素材reference material不计入正式的 CLI E2E 覆盖统计lark-cli demo --help不存在因而该文件无法从实时域帮助输出重算。真实域如 tests/cli_e2e/task/coverage.md、tests/cli_e2e/docs/coverage.md则展示了这套模板在生产中的完整样貌。二、Metrics覆盖率指标的口径模板Metrics一节给出了三个数字这是每份 coverage.md 都必须具备的最小指标集指标demo 示例值含义Denominator分母8 个叶子命令该域全部叶子命令数Covered已覆盖3有测试用例断言、且被计入覆盖的命令数Coverage覆盖率37.5%Covered / Denominator分母如何确定只数叶子命令按 tests/cli_e2e/cli-e2e-testcase-writer/SKILL.md 中的硬性规则叶子命令 执行动作、没有进一步子命令的命令若lark-cli domain group --help没有列出子命令则该group本身就是叶子task create计 1 个叶子task tasks get计 1 个叶子不计算参数组合create带summary和带due仍是同一个命令复用tests/cli_e2e/{domain}/下已有覆盖不计入tests/cli_e2e/demo/。探索实时 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.methoddemo 模板特意标注在真实域中应从实时lark-cli --help探索重算分母而不是照抄本文件正是因为 demo 的数字8/3/37.5%纯属示意、不可复用。三、Summary如何用一句话讲清一个工作流模板Summary部分的要点是每个Test...一条要点讲清证明链路proof surface而不是罗列测试代码。以 demo 的TestDemo_TaskLifecycle为例它被拆成三个要点create执行task create并携带summary、description捕获返回的taskGUID并在父测试注册清理钩子update执行task update --task-id guid同时变更summary与descriptionget对同一任务执行task tasks get断言持久化的guid、更新后的summary与description。这段摘要与参考用例 tests/cli_e2e/demo/task_lifecycle_test.go 一一对应create as bot子测试用gjson.Get(result.Stdout, data.guid)取出任务 GUIDupdate as bot与get as bot分别完成写入与读回校验最终通过assert.Equal比对 GUID、summary、description 三处字段。真实的task域摘要则展示了多工作流 阻塞点的写法例如TestTask_StatusWorkflow证明complete与reopen让status在done/todo间翻转、completed_at先置后清TestTask_GetMyTasksDryRun则只做--dry-run请求形状校验不调用真实 API。清理路径与阻塞点的诚实记录模板明确给出了两条重要的诚实度约定真实域同样遵守清理专用执行不计覆盖task tasks delete执行在parentT.Cleanup中但模板故意将其保持为未覆盖因为工作流断言必须与清理机制保持区分——删除只是清理手段不是被断言证明的测试面。Demo 缺口标注task complete、task reopen、task assign、task get-my-tasks在最小模板中故意留作未覆盖示例其中assign是用户身份敏感命令的典型需要真实用户 fixtureget-my-tasks是当前用户依赖命令的典型bot-only 环境常不可用。四、Command Table命令表格的六列规范模板给出了统一的命令表头这是每个域 coverage.md 都必须保持的列结构StatusCmdTypeTestcaseKey parameter shapesNotes / uncovered reasonStatus✓覆盖 /✕未覆盖Cmd命令路径如task createshortcut或task tasks getapiTypeshortcut快捷命令或apiAPI 直调命令二选一Testcase以go test -run友好的形式写出用例位置格式为文件_test.go::TestXxx/子测试Key parameter shapes关键参数形态如--task-id、summarydescription、task_guid in --paramsNotes / uncovered reason覆盖要点或未覆盖原因。demo 表格完整继承如下八行全部保留StatusCmdTypeTestcaseKey parameter shapesNotes✓task createshortcuttask_lifecycle_test.go::TestDemo_TaskLifecycle/createbasic create; summary; descriptiondemo example✓task updateshortcuttask_lifecycle_test.go::TestDemo_TaskLifecycle/update--task-id; update summary; update descriptiondemo example✓task tasks getapitask_lifecycle_test.go::TestDemo_TaskLifecycle/gettask_guid in --paramsdemo example✕task tasks deleteapinonecleanup exists in parentT.Cleanup清理专用执行视为未覆盖✕task completeshortcutnone最小生命周期示例未展示✕task reopenshortcutnone最小生命周期示例未展示✕task assignshortcutnone用户身份敏感命令需真实用户 fixtures✕task get-my-tasksshortcutnone依赖当前用户bot-only 环境常不可用对比真实域task/coverage.md其 29 个叶子命令中 15 个被覆盖未覆盖行给出了精确到 fixture 层面的原因例如task assignrequires real assignee open_id fixtures; shortcut defaults to--as usertask tasks listUAT did not return the workflow-created user task deterministically in list views——宁可留白也不把 flaky 结果计入覆盖。五、Notes注意事项与可复算原则模板Notes一节约束了 coverage.md 的维护方式包含三条铁律真实域必须重算分母从实时lark-cli --help探索得出而不是复制 demo 文件替换 demo 行用该域真实命令清单替换示例行保持未覆盖命令为未勾选复用t.Skip(...)的原因作为未覆盖原因避免测试跳过原因与 coverage 记录不一致。此外SKILL.md 还补充了两条覆盖计数的边界规则仅在parentT.Cleanup中执行的命令不计为已覆盖唯一例外在同一工作流中创建资源后紧接的delete一条命令只有在测试用例断言了返回字段或持久化状态时才视为已覆盖——仅断言退出码不算。这一口径在 tests/cli_e2e/core.go 的AssertExitCode与AssertStdoutStatus设计中体现为所有用例统一先断言退出码与ok/code状态键再断言字段路径gjson提取二者缺一不可。六、配套机制demo 参考用例与 E2E 测试框架demo 目录只有两个文件构成覆盖率文档 参考测试的最小组合coverage.md本文讲解的模板task_lifecycle_test.go最小任务生命周期参考用例展示标准的clie2e.RunCmd(ctx, clie2e.Request{...})写法。从参考用例可以看到 E2E 测试的基本形态Request结构体把命令参数拆成Args命令路径与普通 flag、ParamsURL/路径参数转为--params json、Data请求体转为--data json以及DefaultAsbot/user、Yes高风险写命令确认等字段。BuildArgs与ResolveBinaryPath分别负责参数组装与二进制查找LARK_CLI_BIN环境变量 → 项目根目录./lark-cli→PATH。对于真实域的测试编写仓库提供了专门的本地 Skill tests/cli_e2e/cli-e2e-testcase-writer/SKILL.md安装方式为npx skills add ./tests/cli_e2e/cli-e2e-testcase-writer随后在 tests/cli_e2e/README.md 列出的工作流下操作先make build再运行go test ./tests/cli_e2e/... -count1。七、为真实域落地 coverage.md 的检查清单综合模板、SKILL.md 与真实域样例为某个新域编写或更新coverage.md时按以下清单执行探索对域执行完整的--help/-h/schema命令序列列出全部叶子命令不数参数组合重算分母只统计真实lark-cli --help输出中的叶子命令数勿照抄 demo写工作流用例一个顶层测试配多个t.Run子步骤create 后紧跟 read-after-write 断言清理钩子注册在parentT.Cleanup上以在子测试失败时仍能执行标注命令类型shortcut与api分行列出全部命令放在同一张表不拆成已覆盖/未覆盖两节诚实记录未覆盖清理专用执行、缺少真实用户 fixture、UAT 不稳定等一律保持✕并写明原因复用t.Skip(...)的理由保持机械与简洁Metrics/Summary/Command Table 三节齐备摘要每个Test...一条突出 keyt.Run(...)证明点与主要阻塞点。遵循这套口径产出的覆盖率文件既能让人类维护者一眼看出哪些命令可证明、哪些被环境阻塞也能让 AI Agent 在扩展测试时快速对齐当前域的覆盖边界避免重复工作或虚构覆盖。赞分享CLIAI 技能【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址https://gitcode.com/gh_mirrors/cli414/cli点击查看免费下载相关推荐lark-cli Contact 通信录命令 E2E 覆盖率解读从覆盖率报告到 get-user / search-bot 的实测验证lark cli Contact 通信录命令 E2E 覆盖率解读从覆盖率报告到 get user / search bot 的实测验证 本篇技术指南以 lCLIAI 技能lark-cli E2E 测试用例编写实战基于 cli-e2e-testcase-writer 技能的分域覆盖指南lark cli E2E 测试用例编写实战基于 cli e2e testcase writer 技能的分域覆盖指南 本文聚焦 lark cli 官方仓库中 tCLIAI 技能Lark CLI 即时通讯IM命令 E2E 覆盖指南32 个叶子命令的验证矩阵、dry-run 与真实工作流Lark CLI 即时通讯IM命令 E2E 覆盖指南32 个叶子命令的验证矩阵、dry run 与真实工作流 tests/cli_e2e/im/coverCLIAI 技能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考