meticulous-test

要使用 Meticulous 测试前端更改，请按以下步骤逐步操作，使用所描述的 CLI 命令。

开始前，运行 meticulous-cli-update 技能以确保 Meticulous CLI 是最新的——除非它已在此对话中较早运行过，在这种情况下跳过。

如果已经提供了测试运行 ID，请跳到第 4 步。

第 1 步 -- 构建前端

1. 通过检查 .github/workflows/ 中的以下步骤之一，找出 Meticulous 期望的构建产物：
   • uses: alwaysmeticulous/report-diffs-action/upload-assets@v1 — 构建资源
   • uses: alwaysmeticulous/report-diffs-action/upload-container@v1 — Docker 镜像
2. 按照 GitHub 工作流中使用的相同指令构建前端。

第 2 步 -- 上传构建

使用 agent upload-build 将构建注册为可重用的部署。这会上传产物并将 deploymentId 打印到标准输出——它不会立即触发运行。

# 资源
meticulous agent upload-build --appDirectory <构建输出路径>

# 容器
meticulous agent upload-build --localImageTag <镜像标签>

MCP 工具：没有 1:1 的对应工具——调用 request_asset_upload（或 request_container_upload），自行上传 zip/镜像，然后使用返回的 uploadId 调用 register_asset_build（或 register_container_build）以获取 deploymentId。

• --appDirectory 指向构建输出目录（例如 dist/ 子文件夹）；--localImageTag 是本地 Docker 镜像标签。构建模式会自动检测。
• 构建的提交默认为本地 git HEAD。如果工作树有未提交的更改，则会被捕获为临时提交（打印为 commitSha (local, ephemeral due to dirty working tree): …）——请参阅下面的未提交更改说明。
• 未跟踪的文件会被拒绝（无法捕获）——请先 git add 它们。
• 从标准输出捕获 deploymentId（传递 --verbose 以在标准错误上查看进度）。

第 3 步 -- 触发测试运行

为部署触发一次运行，与基准进行比较。在仓库目录中运行以自动推断基准（与源默认分支的合并基础）和 git diff：

meticulous agent trigger-test-run --deploymentId <deploymentId>

MCP 工具：trigger_test_run（从不推断 baseSha/gitDiffOutput——显式传递它们——并且总是立即返回而不等待运行完成）。

• 需要基准。从当前目录自动推断，或显式传递 --baseSha <sha>（以及可选的 --gitDiffOutput）来设置。
• 省略 --deploymentId 以使用已为本地 HEAD 提交上传的最新部署——这需要干净的工作树（没有未提交的更改）。
• 默认情况下，该命令会阻塞直到运行完成，并将 testRunId 打印到标准输出；当检测到视觉差异时，最终状态为 Failure（这是正常的完成判定，不是错误）。传递 --dontWaitForTestRunToComplete 以在触发运行后立即返回。
• 一个构建，多个基准： 同一 deploymentId 可以针对不同基准重新触发——只需使用不同的 --baseSha 再次运行 agent trigger-test-run。无需重新构建或重新上传。

从输出中记下 testRunId。

第 4 步 -- 审查视觉变化

遵循 meticulous-review 技能，传递第 3 步中的 testRunId。它会获取差异摘要，检查代表性截图 / DOM 差异 / 时间线，并生成最终报告，将每个视觉变化分类为有意或无意。

未提交的更改： 如果你在脏工作树的情况下构建/测试，运行将记录在一个临时提交上，该提交不是你的 HEAD（也不会被推送）。从本地检出解析运行的命令——meticulous-review / agent test-run-diffs 不带 --testRunId 运行——将无法通过提交找到它，因此在这种情况下，始终向审查步骤传递显式的 --testRunId。