meticulous-test

To test a frontend change using Meticulous, follow the workflow below step by step, using the CLI or MCP commands as described.

Before starting, run the meticulous-cli-update skill to ensure the Meticulous CLI and skills are up to date — unless it has already run earlier in this conversation, in which case skip it.

If you are already given a test run id, skip to Step 4.

Step 1 -- Build the frontend

1. Find out what build artefact Meticulous expects by checking your CI config for the corresponding step:

• GitHub: .github/workflows/*.yml for uses: alwaysmeticulous/report-diffs-action/upload-assets@v1 (build assets) or upload-container@v1 (docker image)
• GitLab: .gitlab-ci.yml (or an included .gitlab/ci/*.yml) for npx @alwaysmeticulous/cli ci upload-assets (build assets) or ci upload-container (docker image)
• Bitbucket: bitbucket-pipelines.yml for the same npx @alwaysmeticulous/cli ci upload-assets / ci upload-container step

1. Build the frontend following the same instructions as used in that CI config.

Step 2 -- Upload the build

Register the build as a reusable deployment with agent upload-build. This uploads the artefact and prints a deploymentId to stdout — it does not trigger a run yet.

# 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 points to the build output directory (e.g. a dist/ subfolder); --localImageTag is the local Docker image tag. The build mode is auto-detected.
• The build's commit defaults to the local git HEAD. If the working tree is dirty, it is captured as an ephemeral commit (printed as commitSha (local, ephemeral due to dirty working tree): …) — see the uncommitted-changes note below.
• Untracked files are rejected (they can't be captured) — git add them first.
• Capture the deploymentId from stdout (pass --verbose to also see progress on stderr).

Step 3 -- Trigger a test run

Trigger a run for the deployment, comparing against a base. Run it from the repo directory to infer both the base (merge-base with the origin default branch) and the git diff automatically:

# 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>")

• A base is required. It's auto-inferred from the current directory, or pass --baseSha <sha> (and optionally --gitDiffOutput) to set it explicitly.
• Omit --deploymentId to use the most recent deployment already uploaded for the local HEAD commit instead — this requires a clean working tree (no uncommitted changes).
• The command blocks until the run finishes by default and prints the testRunId to stdout; the final status is Failure when visual differences were detected (a normal completed verdict, not an error). Pass --dontWaitForTestRunToComplete to return as soon as the run is triggered.
• One build, many bases: the same deploymentId can be re-triggered against different bases — just run agent trigger-test-run again with a different --baseSha. No rebuild or re-upload needed.

Note the testRunId from the output.

Step 4 -- Review the visual changes

Follow the meticulous-review skill, passing the testRunId from Step 3. It fetches the diff summary, inspects representative screenshots / DOM diffs / timelines, and produces a final report classifying each visual change as intended or unintended.

Uncommitted changes: if you built/tested with a dirty working tree, the run is recorded against an ephemeral commit that is not your HEAD (and isn't pushed). Commands that resolve a run from the local checkout — meticulous-review / agent test-run-diffs run with no --testRunId — won't find it by commit, so always pass the explicit `--testRunId` to the review step in that case.