qa-test-code-coverage

测试到代码覆盖率

分析项目的测试（包括手动 Markdown 用例和自动化端到端测试）以及源代码。生成 coverage.tests.yml，将源文件（或 glob 模式）映射到测试标识符：套件 ID、测试 ID、标签。Testomat.io 将手动测试和自动化测试放在同一个项目中，因此一份覆盖率文件即可满足两者需求。@testomatio/reporter 会使用该文件，仅运行受差异影响的测试（步骤 6）。

关键约束

• 映射现有测试，包括手动 Markdown 用例、自动化端到端测试，或两者兼有。 不要包含单元测试。不要建议创建新测试。
• 只能写入以下三个位置，不得写入其他位置：
  • 覆盖率文件，默认为 coverage.tests.yml，或用户指定的路径；
  • .testeiya/ 缓存目录，用于克隆自动化测试仓库、从 Testomat.io 拉取手动用例（步骤 1）；
  • .gitignore，如果缺少 .testeiya/ 条目，则添加该条目。
• 绝不要修改源文件或测试文件。
• 绝不要将测试拉取或克隆到已跟踪的目录中，只能放入已加入 Git 忽略规则的 .testeiya/。
• 覆盖率文件中的所有内容都必须来自本项目： 文件键必须来自项目的源代码树，标识符必须来自步骤 2 的清单。绝不要复制此技能文档中的路径或 ID，它们只是占位符。
• 不要编写临时脚本，不要使用解析器，绝不要使用 Python。 只能读取文件和使用 grep；唯一例外是步骤 5 中捆绑的检查器。除此之外，最多只能使用一行 node -e '…'。
• 主动推进，绝不要只做到有代表性的样例就停下。 每个领域只映射几条就算失败。持续映射，不要询问是否继续，直到满足步骤 4 中的完成标准。
• 如果无法写入输出文件，或没有找到任何测试且用户拒绝了步骤 1 中的所有选项，则停止。

工作流程

步骤 1：发现项目

• 运行 scan-automation-project 技能，盘点项目。以其输出为准，不要重复扫描。
• 从结果中提取：
  • Manual Tests — .test.md 文件及其套件和测试标题。
  • Automated Tests — 端到端测试文件及其框架。如果扫描结果不明确，请参阅 E2E Frameworks。
  • Project Overview — 语言、框架、复杂度（用于决定步骤 4 中的子代理拆分方式）。
• 映射所有现有测试：两类测试都映射到同一份覆盖率文件；只有一类也可以。
• ❓ 如果扫描未找到任何测试（它也会检查 .testeiya/ 缓存），请询问用户：
  1. 从 Testomat.io 拉取手动用例——让 sync-test-cases-with-tms 将用例拉取到缓存：npx check-tests pull -d .testeiya/test-cases；如果 .gitignore 缺少 .testeiya/ 条目，则添加该条目，然后重新运行扫描。
  2. 克隆自动化测试仓库：git clone <url> .testeiya/e2e-tests；如果 .gitignore 缺少 .testeiya/ 条目，则添加该条目，然后重新运行扫描。
  3. 指出扫描遗漏的目录，然后在那里重新运行扫描。
  4. 停止。
• ❓ 如果检测到两个自动化框架（例如 Jest 和 Playwright），请询问哪个是端到端测试框架，因为覆盖率筛选是按运行器执行的。

步骤 2：提取测试信息

为两种测试建立一个标识符清单：

• 套件 ID — @S + 8 个字符。
• 测试 ID — @T + 8 个字符。
• 标签 — 其他 @word 标记。
• 上下文 — 标题、步骤、页面对象、访问过的路由。这些内容决定步骤 4 中的映射。

ID 所在位置：

• 手动测试用例遵循 Classical Tests Markdown Format — ID 位于 / 块中，标签位于标题和 tags: 行中。
• 自动化测试会将 ID 放在 describe / it / test / Feature / Scenario 标题中 — 参见 E2E Frameworks。

读取文件，或使用 grep 搜索存放测试的目录：

grep -rnE 'id:[[:space:]]*@[ST]' <dir>          # manual suite/test IDs
grep -rnoE '@[ST][0-9a-f]{8}' <dir>             # IDs in automated test titles
grep -rhoE '@[A-Za-z0-9_-]+' <dir> | sort -u    # every @token, tags included

缺少 ID 表示这些测试从未与 Testomat.io 同步 — 报告器无法选择它们：

• ❓ 没有 ID 的手动测试文件：询问是否先通过 sync-test-cases-with-tms 推送，或跳过这些文件。
• 大多数文件中的自动化测试都没有 ID：停止并指示用户先运行 npx check-tests@latest <Framework> "<glob>" --update-ids（各框架的命令参见 E2E Frameworks）。

步骤 3：按领域规划覆盖映射

不要逐个文件遍历代码库。 先识别应用的领域区域；步骤 4 再逐个区域进行映射。

• 从两方面推导这些区域：
  • 步骤 2 中的套件树 — 套件层级是 QA 团队对产品的自有划分；
  • 源代码结构 — 模块、路由、服务、入口点。
• 将每个区域与测试该区域的套件，以及实现该区域的源代码文件夹对应起来。
• 按重要性排序，最关键的排在最前：支付/账单、身份验证和访问控制、数据完整性、核心业务流程 — 然后是辅助功能，最后是外围 UI。套件规模是一个信号：QA 测试得越多，说明他们认为越关键。
• 开始映射前，先向用户展示排序后的计划。
• 仅处理业务代码：跳过测试代码、手动测试目录、依赖项/构建/供应商文件夹、框架配置、锁文件。
• 模板和视图属于可映射源代码（.vue、.erb、.blade.php，等等）— 测试会检查渲染后的 UI，因此应像代码一样映射它们。
• ❓ 如果无法明确领域区域或其优先级，请询问用户。

步骤 4：将源文件映射到测试

步骤 2 中的清单就是待办列表。只有当其中每个套件都已出现在覆盖率文件中，或已记录为未映射并注明原因时，映射才算完成。 按步骤 3 的顺序处理各个领域，优先处理最关键的领域，这样即使运行中断，也能覆盖最重要的部分。始终执行两轮：

• 代码 → 测试：对于每个领域，将其源文件和子树映射到检查它们的测试标识符。
• 测试 → 代码：遍历清单；对于仍未出现在映射中的每个套件，找到它所测试的源代码并添加映射，或记录无法映射的原因（此处没有对应功能代码、外部系统、需要用户输入）。

根据项目规模调整两轮的执行方式，参考步骤 1 中的代码库大小和套件数量：

• 代码库较小且套件较少 — 在本次会话中完成两轮。
• 代码库较大或有数十个套件 — 并行启动子 Agent：代码 → 测试这轮按每个领域各启动一个，测试 → 代码这轮则按每批仍未映射的套件各启动一个。为每个子 Agent 提供：
  • 它的处理范围 — 一个领域（其中的套件和源文件夹），或一批套件；
  • 步骤 2 中的完整测试清单 — 子 Agent 不得重新提取清单；
  • 以下映射规则和 覆盖率文件格式；
  • 仅返回其处理范围对应的 YAML 片段这一指示。
• 将各片段合并为一个映射，删除重复键和空条目。只有主会话可以写入文件（步骤 5）。

对于每个候选源文件，选择能在测试套件增长时继续正确筛选测试的标识符：

• 套件（@S）— 默认选项。套件中的大多数测试都与该文件相关。
• 标签（@word）— 相关测试分布在多个套件中。
• 测试（@T）— 例外情况。仅当套件中只有一两个测试与该文件匹配时使用。

规则：

• 同一套件或类别中有多个测试 ID 时，改用套件或标签。 之后添加的测试会自动纳入；测试 ID 列表会过时。
• 如果同一条目中已列出某个套件，绝不要再列出该套件中的测试 ID。
• 键必须是相对于仓库根目录的源文件路径或 glob；如果整个子树映射到相同的标识符，则使用 glob。
• 手动标识符和自动标识符可以在同一条目中混用。
• 不得有空条目。
• 为每个标识符添加 # 注释，注明其套件／测试／标签标题。

YAML 语法：覆盖率文件格式。

步骤 5：保存并验证覆盖率文件

• 将 YAML 写入输出路径，并保留 # 注释。
• 键必须是此仓库中的源文件路径，绝不能是 .testeiya/... 路径。
• 使用随附的检查器进行检查。它位于此技能的 scripts/ 目录中（与此 SKILL.md 同级），而不在项目中；请根据技能的位置解析其路径：

npx js-yaml coverage.tests.yml | node <path-to-this-skill>/scripts/check-coverage.mjs

• 检查器会标记磁盘上不存在的键和空条目，并打印所有引用的标识符；请将它们与步骤 2 的清单交叉核对——只有你知道哪些标识符是真实存在的。
• 还要反向核对：清单中的每个套件都必须出现在文件中，或列入未映射清单中。若有任何套件两处都未出现，则说明测试 → 代码这轮尚未完成；请返回步骤 4。

步骤 6：报告覆盖率完整性

向用户展示：

• 已映射套件数／清单中的套件总数；在有意义时，也提供测试和标签的相同统计。
• 每个未映射套件及其原因。
• 生成的 YAML（若文件较大，则提供其路径和条目数）。

第 7 步：展示后续步骤

告诉用户如何将该文件与 @testomatio/reporter 配合使用：

# Automated tests — the project's runner command must be passed in
npx @testomatio/reporter run "npx playwright test" \
  --filter "coverage:file=coverage.tests.yml,diff=main"

# Manual tests — creates a pending run with only the affected cases
npx @testomatio/reporter run --kind manual \
  --filter "coverage:file=coverage.tests.yml,diff=main"

• 各框架的运行命令和 GitHub Actions 示例：覆盖率文件格式。
• 若要将一个回归周期的手动运行和自动运行归为一组，请在两条命令中设置相同的 TESTOMATIO_RUNGROUP 环境变量。
• 建议提交覆盖率文件，以便 CI 和团队成员使用相同的映射。
• 在 CI 中，与基础分支进行差异比较 — diff=origin/main — 并使用 fetch-depth: 0 执行 checkout。
• 拉取或克隆的测试会保留在被 gitignore 忽略的 .testeiya/ 缓存中，以便重新运行 — 请勿删除，也不要将其移入受版本控制的文件夹。

第 8 步：建议后续操作

• 将映射接入 CI — 为每个 PR 创建运行，并在预览或合并时启动：委派给 setup-change-aware-pr-testing。
• 立即从终端运行受影响的测试：委派给 run-tests-with-testomatio-reporter。
• 覆盖率缺口 — 源代码中存在但没有测试映射的功能。获得批准后，建议新增测试用例（委派给 qa-write-test-cases）。
• 无效测试 — 对应功能已不再存在于源代码中的测试。
• 根据测试清单回答“我们有针对 X 的测试吗？”之类的问题。
• 编辑已拉取的手动测试用例：在 .testeiya/test-cases/ 中编辑，并使用 sync-test-cases-with-tms 推送回去。

参考资料

• 覆盖率文件格式 — 覆盖率 YAML 语法、报告器约定、GitHub Actions 示例。
• E2E 框架 — 框架检测信号、ID 的存放位置、各框架的 check-tests 命令。
• 手动测试 Markdown 格式 — 规范格式，由 qa-write-test-cases 负责维护。