setup-change-aware-pr-testing

设置变更感知型 PR 测试

我为项目配置了 CI，用于执行变更感知型 PR 测试。这里介绍流程模型，以及需要与用户确认的决策；具体接入方式取决于项目的测试：

• 手动 — 测试人员会收到一个测试运行，可针对已部署的变更进行测试；无需执行任何操作。
• 自动化 — 必须选择执行方式：在流水线中内联执行、使用 Testomat.io CI 配置文件，或通过其他工作流／仓库执行。
• 混合 — 两种方式兼有，每个 PR 共用一个测试运行。

有两个技能负责具体操作 — 接入前请先阅读：

• run-tests-with-testomatio-reporter — 作业会执行的所有 reporter 命令和环境变量。
• setup-ci-automation — CI 调查、工作流编写规则、图示约定、密钥和 PR 交付。

目标：提交到项目自身 CI 系统的一条可正常运行的流水线。 CI 配置是唯一需要完成的结果。我会在本地运行以编写配置 — 我绝不会成为 CI 的一部分。编写配置时不要执行 reporter 命令；只有两种例外：Testomat.io CI 配置文件检查（步骤 2）和最终实战测试（步骤 6）。

最简设置是一个由部署触发的作业：同时创建测试运行并启动测试。请优先提出这种方案。若用户有需要，也可以将创建和启动拆分到两个作业中 — 此时需在两者之间传递测试运行 ID。

可能的流程

如果环境支持渲染 Mermaid，请在第一个问题之前先将此图作为聊天消息发出 — 不要一上来就提问；它能为后续内容提供框架。如果问题通过表单或工具提出，必须在更早的消息中显示此图。

不要只发送图示 — 紧接着用一段简短文字解释：这是供用户在实施任何内容之前查看的 PR 测试通用方案；变更部署后会创建一次测试运行，接下来用户将选择哪些部署会触发它 — 每个 PR 的预览部署、合并后的部署，或两者都选 — 选择执行哪些类型的测试（手动、自动化或两者兼有），以及自动化测试的运行方式 — 在流水线中内联执行、通过 Testomat.io CI 配置文件执行，或分派到其他仓库执行。

flowchart LR
    DEP([Preview or post-merge<br/>deploy succeeds]) --> WHICH{PR behind<br/>this commit?}
    WHICH -->|none| SKIP([Nothing to test])
    WHICH -->|found| RUN[Create a run scoped<br/>to the deployed changes]
    RUN -->|manual / mixed| TESTERS[Testers execute manual cases<br/>on Testomat.io]
    RUN -->|automated / mixed| MODE{How to execute?}
    MODE -->|via a Testomat.io CI profile| RES
    MODE -->|inline in this pipeline| RES
    MODE -->|by dispatching another repo| RES
    RES[Run the affected automated tests —<br/>results land in the same run]

• 仅手动测试的项目 → 仅采用上方分支：创建后测试运行即完成，测试人员在 Testomat.io 上执行测试，不会启动任何任务。
• 仅自动化测试的项目 → 仅采用下方分支：在一个作业中创建并启动测试运行。
• 混合测试的项目 → 每个 PR 共用一个测试运行，涵盖两个分支。

覆盖率映射决定一切

覆盖率映射将源文件／glob 与测试标识符对应起来；reporter 会根据 diff 过滤映射，因此只会准备并运行受影响的测试。它由 qa-test-code-coverage 技能生成 — 默认文件为 coverage.tests.yml，一个文件同时服务于手动和自动化测试。缺少映射 → 委派给 qa-test-code-coverage；不要在此处手动编写。没有映射，就无法进行过滤，也无法接入流水线。

关键约束

• 编写配置时绝不能运行 reporter——交付物是已提交的 CI 配置。 两个获批的例外：Testomat.io CI 配置文件检查（步骤 2）和实战测试（步骤 6）。
• 只修改 CI 配置文件——绝不修改源文件或测试文件。
• 图表决定对话流程：提出第一个问题前先展示流程图；接入配置前，先让用户批准所选流程图（步骤 3）。
• 先做发现——在编写任何内容之前，委派给 scan-automation-project。
• 绝不猜测 Testomat.io CI 配置文件名称——从用户确认的列表（Testomat.io MCP）中选择，或询问用户。绝不接入未经验证、无法启动的配置文件。
• 必须完整地说“Testomat.io CI profile”，绝不能只说“profile”；每个问题选项都必须用通俗语言说明自身含义。
• 避免把项目的完整测试清单作为运行范围；绝不打印完整测试列表。
• 没有覆盖率映射就不创建流水线；委派给 qa-test-code-coverage 创建映射。
• 提议创建一个由部署任务成功作为门控条件的任务；只有在用户需要时，才将创建和启动拆分到不同任务，并通过 CI 的值传递机制传递运行 ID。
• 预览部署和合并后的部署同样适合作为触发条件——两者使用相同的任务结构；为项目已有的每种部署都接入该任务。
• 没有 PR 关联的已部署提交不会创建任何内容。
• --kind detect 让 Testomat.io 根据运行范围确定类型——绝不将类型硬编码为 mixed。
• 该任务绝不能导致部署流水线失败。
• PR 评论由 reporter 自己的管道生成——绝不编写 PR 评论 API 调用脚本。
• 运行标题必须使用 PR 自身的标题，原样取自已解析的 PR，并在前面加上 PR 编号。绝不自行追加任何文字——不能加“选择性测试”“受影响的测试”，也不能加框架或范围标签。
• 每次运行都必须使用该标题和一个 rungroup。

工作流程

步骤 1 — 发现

• 委派给 scan-automation-project：是否有手动 .test.md 用例、存在什么端到端测试框架（不包括单元测试／集成测试），自动化测试是在此仓库还是其他位置。
• 结果确定项目类型——手动、自动化或混合——并由此确定适用的流程。
• 使用 setup-ci-automation 调查 CI：哪个 CI 系统运行项目、有哪些工作流，以及其中哪些会部署到哪些环境。
• 定位覆盖率映射（默认文件为 coverage.tests.yml）。如果缺失 → 提议创建，并委派给 qa-test-code-coverage。

步骤 2 — 展示流程并询问未知信息

将可能的流程图裁剪为步骤 1 中发现的类型，作为单独一条消息发送，并附上一段说明（说明架构是什么，以及用户接下来要做哪些选择）——然后只询问适用的问题。先阅读 CI 文件，避免询问已有答案的问题。

发现手动测试 — 无需选择：测试创建后，其运行流程就已完成，测试人员会立即在 Testomat.io 上开始测试。

发现自动化测试 — ❓ 选择执行模式。问题中的每个选项都必须用通俗的语言说明自身含义——在哪里运行什么，以及由谁触发。尤其要明确说明 Testomat.io CI 配置是什么：保存在 Testomat.io 项目中的 CI 工作流配置（Settings → CI），由 Testomat.io 分发以执行测试，并将结果报告回该运行。

模式	适用情况
远程 — Testomat.io CI 配置	已存在用于 e2e 测试套件的 Testomat.io CI 配置（Settings → CI）；运行器、环境和密钥由 Testomat.io 管理
内联 — 此流水线	移动端／模拟器、由此流水线启动的服务，或已在此仓库中正常运行的 e2e 作业
跨仓库分发	e2e 测试套件位于另一个仓库，且没有 Testomat.io CI 配置涵盖它

• 选择远程 → 确认 Testomat.io CI 配置，绝不能猜测：已连接 Testomat.io MCP → 获取列表并展示，❓ 请用户选择（不同配置的工作流和作业名称各不相同）；未连接 MCP → ❓ 请用户提供准确的配置名称；尚无配置 → 必须先在 Testomat.io 中创建配置（Settings → CI）。
• 然后先验证该配置能否启动，再围绕它进行任何接线。 ❓ 请用户批准——这会执行完整测试套件。不加筛选地运行 npx @testomatio/reporter run --remote <profile-name>，然后检查 CI 上是否确实启动了作业。退出代码 0 仅表示 Testomat.io 已接受分发；若配置指向错误的工作流、作业或分支，则会静默失败。没有启动任何作业 → 在 Settings → CI 中修复并重试。
• 任意位置都没有 e2e 测试套件 → 仅接入手动测试流程；绝不虚构 e2e 作业。

并且，对每种类型都要询问：

1. ❓ 哪些部署会触发该运行——每个 PR 的预览部署、合并后的 staging／production 部署，还是两者都有。提供步骤 1 中发现的部署流水线。两者都存在 → 接入两者；每个部署都会生成独立的运行，仅涵盖该部署发布的内容以及针对该环境进行的测试。
2. ❓ 运行分组策略 — week / day / release / milestone。

步骤 3 — 确认所选流程

• 根据回答绘制流程图——仅包含选定的类型、部署和执行模式。
• ❓ 展示流程图并取得批准；用户接受前，不要接入任何内容。

示例 — 混合项目、预览和合并后部署、Testomat.io CI 配置：

flowchart LR
    PREV([Preview deploy succeeds]) --> JOB
    STG([Post-merge deploy succeeds]) --> JOB
    JOB[Same job — get the PR, create a run<br/>scoped to what this deploy shipped]
    JOB --> TESTERS[Testers execute manual cases<br/>on Testomat.io]
    JOB --> L1[Launch automated tests via the Testomat.io<br/>CI profile, against this deploy's environment]
    L1 --> RES[Results land in that run]

步骤 4 — 将任务接入 CI

在部署流水线中添加一个任务，通过 CI 原生的任务依赖机制，确保它仅在部署任务成功后运行。同一个任务适用于两种部署，只有三处不同：

部署	PR	差异范围	测试针对的环境
预览部署（每个 PR）	触发部署的 PR	PR 的目标分支	预览 URL
合并后部署	根据已部署的提交解析	已部署推送的提交范围	staging / production

按照 setup-ci-automation 的工作流编写规则编写；所有命令和环境变量均取自 run-tests-with-testomatio-reporter。不要进行 --filter-list 预检查。仅支持手动测试的项目只需执行 (a) 和 (b)。

(a) 获取 PR。 预览部署已包含对应的 PR。合并后，请平台查询包含已部署提交的 PR — 切勿解析提交主题，因为合并提交的主题会给出分支名称。没有 PR 时，记录日志并以 0 退出；直接提交到主线的情况仍按原方式部署，不创建任何内容。

(b) 创建测试运行。

• 执行 start --kind detect --format id --warn --filter "coverage:file=<map>,diff=<range>"，并在同一个 shell 中将打印出的 id 保存到 TESTOMATIO_RUN。
• <range> 是此次部署包含的内容 — 见上表。
• --kind detect — 若差异只涉及手动测试，则会创建手动测试运行，而不是创建自动化部分为空的混合测试运行。
• TESTOMATIO_TITLE 仅使用已解析出的 PR 编号和标题；TESTOMATIO_DESCRIPTION 使用其 URL；TESTOMATIO_RUNGROUP_TITLE 按照步骤 2 设置。
• 提供平台的评论管道令牌，以便 reporter 发布 PR 评论（各平台的令牌见 run-tests-with-testomatio-reporter）。
• 没有变更涉及映射的测试属于正常情况 — --warn 会确保任务保持成功；切勿解析输出。
• 使用完整历史检出已部署的版本 — 覆盖率过滤器需要进行差异比较。

(c) 将自动化测试启动到该测试运行中（仅限自动化 / 混合测试）。

• 使用与 (b) 相同的过滤器和范围，使启动范围与创建测试运行时的范围一致。
• 远程模式：run --remote <profile-name>。内联模式：run "<runner command>"。跨仓库模式：使用 CI 的原生机制触发另一仓库的流水线，并向其传递测试运行 id 和 API 密钥。
• 将此次部署生成的环境 URL 传递给测试 — 远程模式使用远程参数，内联模式使用 runner 自带的 base-URL 环境变量。
• 手动测试用例无需启动 — 测试人员对照已部署的变更手动执行测试。

步骤 5 — 交付：密钥和 PR

按照 setup-ci-automation 的要求配置密钥并创建流水线 PR，同时完成以下特定事项：

• 除 API 密钥外，还要配置 PR 评论管道令牌（各平台的令牌见 run-tests-with-testomatio-reporter）。
• 远程启动所用的 Testomat.io CI 配置文件需在 Testomat.io 中配置（Settings → CI），而不是存储为仓库密钥。
• 在 PR 描述中注明：已批准的流程图、已接入的阶段、选定的执行模式，以及合并前需要配置的密钥 / 前置条件。

步骤 6 — 对设置进行实战验证（经批准后）

在 CI 首次运行这些命令之前，先在真实变更上于本地运行一次，证明流水线命令可用。

• ❓ 请用户提供一个用于验证的 PR，并批准创建真实运行和启动测试；如果已接入预览部署，则使用一个开放的 PR，否则使用一个已合并的 PR。
• 按照步骤 4 的表格，在本地重现该部署对应的差异：开放的 PR → 检出其分支，并与目标分支进行差异比较；已合并的 PR → 检出合并提交，并与合并前的主线状态进行差异比较。
• 完全按照 (b) 创建运行——使用相同的类型、相同的筛选条件，以及由该 PR 标题生成的标题；然后按照 (c) 的方式在其中启动测试。
• 报告创建的运行——包括 id、类型和其范围内的测试，并请用户在 Testomat.io 中检查：测试范围是否符合该差异可能影响的内容？
• 未匹配到任何测试 → 将其报告为一项发现，然后与用户一起选择一个涉及已映射源文件的 PR。

步骤 7 — 总结并交接

再次展示已获批准的流程图，并标明现已接入。报告：目标 CI 和写入的文件；该任务所依附的部署；所选执行模式及 Testomat.io CI 配置检查结果；跳过的内容（没有 e2e / 没有 Testomat.io CI 配置）；标题方案和 rungroup；实战验证结果以及等待用户审核的运行；仍需配置的密钥和前置条件；需要确认的假设。建议将覆盖映射与 CI 配置一起提交。

示例

示例 1 — 混合项目，包含预览部署和合并后部署，以及 Testomat.io CI 配置 探索发现了手动用例、一个 e2e 测试套件、每个 PR 的预览部署，以及主线上的 staging 部署；MCP 列出了 Testomat.io CI 配置，用户选择了运行 e2e 测试套件的配置。→ 通过未筛选的 run --remote 和确认任务已启动来验证该配置，流程图获批后，将同一个任务添加到两个部署流水线中：获取 PR，使用该部署范围的覆盖率筛选条件运行 start --kind detect，再针对该部署的 URL 远程启动。每个 PR 创建两次运行——一次用于预览部署，一次用于 staging。启用评论管道。

示例 2 — e2e 位于另一个仓库，没有 Testomat.io CI 配置 用户从模式表中选择跨仓库触发：同一个任务创建运行，然后通过 CI 的原生机制触发 e2e 仓库的流水线，并传入运行 id，以便将结果写入该运行。指出 Testomat.io CI 配置是未来更简单的方案。

示例 3 — 尚无覆盖映射 未找到 coverage*.yml → 说明没有映射就无法进行筛选；委派给 qa-test-code-coverage；只有映射存在后才接入 CI。

示例 4 — 仅有手动测试的项目 scan-automation-project 找到 .test.md 用例，且没有 e2e 框架 → 流程图仅显示手动测试分支；不询问执行模式。该任务解析 PR 并创建运行，创建后即完成——测试人员在 Testomat.io 中针对已部署的变更开始测试。说明必须先有 e2e 测试套件才能启动测试。

相关技能

setup-ci-automation（CI 调查、编写规则、密钥、PR 交付）、run-tests-with-testomatio-reporter（每个任务都会执行的 reporter 命令）、qa-test-code-coverage（创建此技能使用的覆盖映射）、scan-automation-project（必需的探索）、qa-e2e-tests-reporting（如果项目尚无 Testomat.io 集成，则安装 reporter）、sync-test-cases-with-tms（尚未加入 Testomat.io 的手动用例）。