meticulous-test

要使用 Meticulous 测试前端更改，请按照以下工作流逐步操作，并按说明使用 CLI 或 MCP 命令。

开始前，请运行 meticulous-cli-update 技能，确保 Meticulous CLI 和技能均为最新版本——除非本次对话中已运行过该技能；如果已运行，则跳过。

如果已提供测试运行 ID，请跳至步骤 4。

步骤 1 -- 构建前端

1. 检查 CI 配置中的对应步骤，了解 Meticulous 需要哪种构建产物：
   • GitHub：在 .github/workflows/*.yml 中查找 uses: alwaysmeticulous/report-diffs-action/upload-assets@v1（构建资源）或 upload-container@v1（Docker 镜像）
   • GitLab：在 .gitlab-ci.yml（或其引入的 .gitlab/ci/*.yml）中查找 npx @alwaysmeticulous/cli ci upload-assets（构建资源）或 ci upload-container（Docker 镜像）
   • Bitbucket：在 bitbucket-pipelines.yml 中查找相同的 npx @alwaysmeticulous/cli ci upload-assets / ci upload-container 步骤
2. 按照 CI 配置中使用的相同说明构建前端。

步骤 2 -- 上传构建产物

使用 agent upload-build 将构建注册为可重复使用的部署。此操作会上传构建产物，并将 deploymentId 输出到 stdout——但不会触发测试运行。

# CLI
meticulous agent upload-build --appDirectory <path-to-build>     # assets
meticulous agent upload-build --localImageTag <image-tag>        # container

# MCP (not 1:1 — request an upload URL, upload the artifact yourself, then register it)
request_asset_upload(size=<zipByteSize>)      # or request_container_upload() — no required args
# ... upload the zip/image to the returned URL/registry yourself ...
register_asset_build(uploadId="<id>", commitSha="<sha>")      # or register_container_build(uploadId="<id>", commitSha="<sha>")

• --appDirectory 指向构建输出目录（例如 dist/ 子目录）；--localImageTag 是本地 Docker 镜像标签。系统会自动检测构建模式。
• 构建的提交默认是本地 git HEAD。如果工作树有未提交的更改，系统会将其记录为临时提交（输出为 commitSha (local, ephemeral due to dirty working tree): …）——请参阅下方关于未提交更改的说明。
• 不接受未跟踪文件（无法捕获这些文件）——请先用 git add 添加。
• 从 stdout 获取 deploymentId（传入 --verbose 还可在 stderr 中查看进度）。

步骤 3 -- 触发测试运行

为该部署触发一次测试运行，并与一个基准版本进行比较。在仓库目录中运行命令，以自动推断基准版本（与 origin 默认分支的合并基点）和 git 差异：

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

# MCP (never infers `baseSha`/`gitDiffOutput` — pass them explicitly — and always returns immediately without waiting for the run to finish)
trigger_test_run(deploymentId="<deploymentId>", baseSha="<sha>")

• 必须指定基准版本。系统会根据当前目录自动推断，或者传入 --baseSha <sha>（也可选传入 --gitDiffOutput）来明确指定。
• 省略 --deploymentId，即可使用最近上传的、对应本地 HEAD 提交的部署；这要求工作树干净（没有未提交的更改）。
• 默认情况下，命令会一直阻塞，直到测试运行完成，并将 testRunId 输出到 stdout；如果检测到视觉差异，最终状态为 Failure（这是正常的完成判定，不是错误）。传入 --dontWaitForTestRunToComplete，可在触发运行后立即返回。
• **一个构建，多个基准版本：**同一个 deploymentId 可以针对不同基准版本重复触发——只需使用不同的 --baseSha 再次运行 agent trigger-test-run。无需重新构建或上传。

记下输出中的 testRunId。

步骤 4 -- 检查视觉更改

按照 meticulous-review 技能操作，并传入步骤 3 中的 testRunId。该技能会获取差异摘要，检查有代表性的截图、DOM 差异和时间线，并生成最终报告，将每项视觉更改归类为预期或非预期。

**未提交的更改：**如果你在工作树存在未提交更改时进行构建/测试，该次运行会记录到一个临时提交，而不是 HEAD（且不会推送）。通过本地检出解析运行记录的命令——meticulous-review / agent test-run-diffs（未传入 --testRunId 时）——无法根据提交找到它，因此在这种情况下，务必在检查步骤中传入明确的 --testRunId。