run-tests-with-testomatio-reporter

使用 Testomat.io Reporter 运行测试

npx @testomatio/reporter 会在 Testomat.io 中创建测试运行，并启动测试组——可在本地运行，也可通过 Testomat.io CI 配置文件在远程运行。每条命令都需要 TESTOMATIO 环境变量（项目 API 密钥，tstmt_*），没有该变量时会以状态码 1 退出。尖括号中的所有值都是占位符。

根据意图选择命令

意图	命令
创建测试运行，不执行任何测试——由测试人员启动	start
在本地执行测试并报告结果	run "<runner command>"
通过 Testomat.io CI 配置文件在远程启动测试	run --remote <profile-name>
列出筛选条件匹配的测试，不运行任何测试	run --filter-list "<filter>" --format ids
关闭之前创建的测试运行	finish（通过 TESTOMATIO_RUN 指定运行 ID）
查找现有测试运行，不创建或更改任何内容	fetch --project <project-slug>

测试运行类型

--kind 用于声明测试运行包含的内容：

类型	标志	行为
manual	--kind manual	仅包含手动用例——立即等待测试人员处理，无需任何启动即可完成
mixed	--kind mixed	在一个测试运行中包含手动和自动化测试——测试人员可处理手动部分，自动化部分则单独启动
automated	（无标志）	仅包含自动化测试
detect	--kind detect	Testomat.io 根据测试运行所限定的测试来选择类型——筛选测试运行时优先使用此类型

使用 start 创建测试运行不会执行任何测试：手动用例会立即处于待处理状态；自动化部分则保持已安排状态，直到启动。--format id 只向 stdout 输出运行 ID（横幅和日志输出到 stderr），因此可干净地捕获结果：

RUN_ID=$(npx @testomatio/reporter start --kind manual --format id)

测试运行包含的内容

如果没有筛选条件，则不会限定测试范围：

• start 会创建一个没有预设测试列表的测试运行——稍后测试使用 TESTOMATIO_RUN=<run-id> 报告时，结果会写入该测试运行。
• run "<runner command>" 会执行完整测试套件并报告每项结果。
• run --remote <profile-name> 会使用默认范围分派 Testomat.io CI 配置文件。

--filter "<pipe>:<criteria>" 会将测试运行范围缩小到匹配的测试。筛选管道有两种——testomatio:（根据项目中存储的测试元数据进行匹配）和 coverage:（根据已更改的源文件进行匹配）；任何其他前缀都会被拒绝。start 和 run 接受相同的筛选条件，因此可以先准备筛选后的测试运行，再稍后启动。

按标签、计划、标记或 Jira 工单筛选（testomatio:）

条件	筛选条件
标签	"testomatio:tag-name=<tag>"
计划（Testomat.io 计划 ID）	"testomatio:plan=<plan-id>"
标记	"testomatio:label=<label>"
带值的标记	"testomatio:label=<label>:<value>"
Jira 工单	"testomatio:jira-ticket=<ticket-id>"

• 值必须与项目中存储的标签名称、计划 ID、标记或工单完全一致。
• 适用于运行器接受 --grep 的所有测试框架（Playwright、CodeceptJS、Cypress 等）——筛选条件会解析为运行器可使用的 grep 模式。

按已更改的源文件筛选（coverage:）

--filter "coverage:file=<path-to-coverage-map>,diff=<git-ref>"

这就是“仅运行受代码更改影响的测试”的实现方式——它需要一份 覆盖率映射表：一个 YAML 文件，用于将源文件／glob 映射到测试 ID 和标签。报告器无法自行得知哪些测试覆盖了哪些代码；映射表提供了这层关联，而差异内容会筛选出受影响的条目。使用 qa-test-code-coverage 技能创建映射表（默认文件名为 coverage.tests.yml，同一文件同时用于手动和自动化测试）。

• file= — 覆盖率映射表的路径。可以是绝对路径；通过 fs 读取，与工作目录无关。
• diff= — 用于比较的 Git 引用；默认为 master。报告器会在 process.cwd() 中运行 git diff <ref> --name-only——请从要检测其更改的仓库内部启动它。
• 已更改的文件会通过 YAML 进行映射；匹配的套件／测试 ID 和标签会成为本次运行的范围。
• 如果没有匹配的测试，则不会创建运行（No tests found.）。退出代码：start 和 --filter-list 返回 1，run 返回 0；--warn 会使它们全部返回 0。

选择差异比较基准

• 分支上的更改 → 与目标分支比较（例如 origin/<default-branch>）。必须提供完整的 Git 历史记录（fetch-depth: 0 或 CI 中的等效设置）。
• 合并后，目标分支与 HEAD 相同，因此与其比较不会得到任何差异——请使用上一个主线提交：squash 合并使用 HEAD~1，merge commit 使用 HEAD^1。

列出匹配的测试而不运行（--filter-list）

--filter-list 会解析筛选条件并打印匹配的测试 ID——不会执行任何操作，也不会创建运行。--format 用于选择编码格式：ids（逗号分隔，默认）、grep（交替模式）、json、newline。至少匹配到一个测试时退出代码为 0，未匹配到时为 1——脚本可以据此分支处理：

GREP=$(npx @testomatio/reporter run --filter-list "coverage:file=<coverage-map>" --format grep)
[ -n "$GREP" ] && npx playwright test --grep "$GREP"

不能与 --remote 组合使用。

命名和分组运行

• TESTOMATIO_TITLE — 运行标题（例如 PR <number>: <title>）。
• TESTOMATIO_RUNGROUP_TITLE — 对相关运行进行分组（按周／版本／里程碑）。
• TESTOMATIO_DESCRIPTION — 自由格式的运行说明，会显示在运行页面和 PR/MR 评论中；请在此处填写更改链接（生成的覆盖率范围会附加在其后）。
• TESTOMATIO_ENV — 可选的环境标签。

查找现有运行（fetch）

fetch 会返回项目现有的运行，按时间从新到旧排列。此操作为只读。

必须提供项目 slug：传入 --project <project-slug> 或设置 TESTOMATIO_PROJECT。两者都未设置时会以代码 1 退出。如果两者都未提供 → 向用户询问项目 slug；绝不猜测。TESTOMATIO_URL 用于覆盖服务地址（默认为 https://app.testomat.io）。

选项	效果
--title <text>	对运行标题进行部分匹配
--tql <query>	Testomat Query Language 筛选条件（例如 "status = failed"）
--rungroup <uid>	该运行组中的运行，也包括嵌套运行组
--limit <number>	返回的运行数上限，按时间从新到旧排列；默认值为 30，上限为 100
--latest	仅返回最近的一次运行（等同于 --limit 1）；可与筛选条件组合使用

输出：

• 不指定 --format：显示易读列表，包含每次运行的 ID、标题、开始／结束时间、通过／失败／跳过的数量、环境以及 CI 构建 URL。
• --format id：仅输出运行 ID，每行一个。
• --format json：以 JSON 数组形式输出每次运行的所有字段。

RUN_ID=$(npx @testomatio/reporter fetch --project <project-slug> --title "<title>" --latest --format id)

报告到现有运行中

• TESTOMATIO_RUN=<run-id> — 命令会报告到该运行中，或在其中启动测试，而不是创建新运行。支持跨流水线，甚至跨仓库使用——将它（以及 TESTOMATIO 和标题环境变量）传给执行测试的进程即可。
• 手头没有 ID → 按共享运行标题匹配。两端都设置：
  • TESTOMATIO_SHARED_RUN=1 — 按 TESTOMATIO_TITLE 匹配运行，而不是创建新运行；
  • TESTOMATIO_TITLE — 匹配键，两端必须相同；
  • TESTOMATIO_SHARED_RUN_TIMEOUT — 标题可用于匹配的分钟数，默认为 20；根据创建与启动之间的预期间隔设置。

远程启动（run --remote）

--remote <profile-name> 会要求 Testomat.io 调度一个 Testomat.io CI profile——即保存在项目中的 CI 工作流配置（Settings → CI）——而不是在本地执行测试。Testomat.io 会触发该工作流，并将结果报告到运行中：

TESTOMATIO_RUN=$RUN_ID npx @testomatio/reporter run --remote <profile-name> \
  --filter "coverage:file=<coverage-map>,diff=<git-ref>"

• 使用 TESTOMATIO_RUN 时，会为该运行触发 Testomat.io CI profile；否则会创建新运行。
• 支持所有筛选形式——解析出的测试 ID 会作为 grep 模式传递给 CI 工作流。没有筛选条件 → 不传递 grep；工作流会运行其默认范围，或运行已准备的运行在创建时保存的范围。启动时新传入的 --filter 会替换已保存的范围。
• --remote-param <key>=<value> 会将参数传递给 Testomat.io CI profile 配置（多个参数可重复使用）——例如预览 URL 或目标分支。
• 限制：不能与 --filter-list 一起使用；任何位置参数命令都会被忽略，并显示警告；缺少 Testomat.io CI profile 时会报错 CI launch failed: <message> 并以退出码 1 结束。

选择 Testomat.io CI profile

不同 profile 的工作流、任务名称和参数各不相同——绝不要猜测。与用户交流时，始终使用完整名称“Testomat.io CI profile”，并解释它是什么；单说“profile”对他们没有意义。

• 已连接 Testomat.io MCP → 获取 Testomat.io CI profiles，列出并请用户选择（参见 testomatio-mcp 以进行连接）。
• 未连接 MCP → 请用户提供 Testomat.io CI profile 名称。
• 尚无 profile → 用户必须先在 Testomat.io 中创建一个（Settings → CI）。

本地执行（run "<runner command>"）

将测试运行器及其结果报告包装到运行中，并随结果生成而报告。没有筛选条件时会运行整个测试套件；有筛选条件时，筛选器会生成供运行器使用的 grep：

TESTOMATIO_RUN=$RUN_ID npx @testomatio/reporter run "<runner command>" \
  --filter "testomatio:tag-name=<tag>"

PR/MR 评论

报告器会自行发布并更新 PR/MR 摘要评论——创建运行后，start 会立即发布一条包含计划测试的待处理评论，结果会在报告时替换该评论。切勿编写评论 API 调用脚本。每个报告器命令（包括 start）都要设置令牌，才能启用此功能：

平台	环境变量	说明
GitHub	GH_PAT	工作流内置令牌可用于 PR 运行
GitLab	GITLAB_PAT	具有 api 范围的访问令牌
Bitbucket	BITBUCKET_ACCESS_TOKEN	仓库访问令牌

平台没有对应的功能（例如 Azure DevOps）→ 不会发布评论；结果仍可在 Testomat.io 中查看。

相关技能

qa-test-code-coverage（创建 coverage: 筛选器所需的覆盖率映射）、setup-change-aware-pr-testing（将这些命令接入 CI 流水线）、qa-e2e-tests-reporting（在自动化项目中安装并配置报告器）。