Simulate a session and analyze diffs
This skill covers running a single simulation and interpreting the results. For the
command's full option reference see the
skill.
Before starting, run the
skill to ensure the Meticulous CLI is up to date — unless it has already run earlier in this conversation, in which case skip it.
Prerequisites
- A to replay
- An (local dev server, or leave blank to use the original recorded URL)
- Optionally: a — the ID of a prior replay to diff screenshots against. Without this, screenshots are stored but not compared.
If you don't have a
, you can find one from a downloaded test run:
bash
meticulous download test-run --apiToken=$METICULOUS_API_TOKEN
# Then inspect ~/.meticulous/test-runs/<testRunId>/coverage.json
# or check the testCases[].replayId fields
Step 1 — Run the simulation
With a base replay (diff mode)
bash
meticulous simulate \
--sessionId=<sessionId> \
--appUrl=<url> \
--baseReplayId=<baseReplayId> \
--headless
Capture the full stdout. Key things to look for:
# Per-screenshot diff outcomes (one line each):
0.412% pixel mismatch for screenshot screenshot-1234.png (threshold is 0.100%) => FAIL!
0.000% pixel mismatch for screenshot screenshot-5678.png (threshold is 0.100%) => PASS
# Final summary block:
=======
View simulation at: https://app.meticulous.ai/projects/<org>/<project>/simulations/<headReplayId>
View comparison with base: https://app.meticulous.ai/projects/<org>/<project>/simulations/<baseReplayId>/compare-to/<headReplayId>
=======
If there are no lines: the session is visually identical to the base — stop here and report no regressions.
Proceed to Steps 2–5 to locate and analyse any diffs.
Without a base replay (quick-check mode)
If no
is available, omit it. Screenshots are still stored locally for direct visual inspection:
bash
meticulous simulate \
--sessionId=<sessionId> \
--appUrl=<url> \
--headless
Then locate the replay directory (Step 2) and open the screenshots in
to verify the UI looks correct. There are no diff images in this mode — inspection is purely visual. Steps 3–5 do not apply.
Step 2 — Extract the head replay ID and locate the replay directory
From the
URL, extract the
(the last path segment).
To find the local replay directory created by this run:
bash
ls -lt ~/.meticulous/replays/ | head -5
The most recently created entry will be the head replay's directory (named with a timestamp, e.g.
2024-01-15T12-30-45.123Z-abc123/
). Note this path — it's referred to below as
.
Step 3 — Identify which screenshots diffed
bash
ls ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/
Each
file here corresponds to a screenshot where a visual difference was detected. The pixel diff image highlights changed pixels in color. There are also
prefixed thumbnail versions.
Note the filenames — they match the screenshot identifiers (e.g.
screenshot-after-event-42.png
).
Step 4 — Analyze the HTML diff for each diffed screenshot
Each screenshot has a corresponding metadata file containing a full HTML snapshot of the page taken just before the screenshot was captured. These files are already on disk:
- Head metadata:
~/.meticulous/replays/<replayDir>/screenshots/<screenshotFilename>.metadata.json
- Base metadata:
~/.meticulous/replays/<baseReplayId>/screenshots/<screenshotFilename>.metadata.json
The base metadata is permanently cached when the simulation downloads the base replay, so no additional download is needed.
Read both
files. The relevant fields are:
- — full HTML of the page at screenshot time; diff these two strings to understand what changed
- — which page/route the screenshot was taken on
When diffing the HTML, focus on tag additions/removals,
attribute changes, and text content changes.
The per-screenshot stdout lines also report
(proportion of pixels that changed). If there is a pixel diff but the
strings are identical, the change is purely visual (e.g. a color shift) rather than structural.
Step 5 — Summarize the findings
The key output from this skill is a high-level human-readable description of what visually changed and why. Use the pixel diff counts, route URLs, changed class names, and HTML diffs gathered above to answer: what did the user experience change, and which part of the UI is responsible?
Present this in whatever format fits the current context (conversational answer, structured report, input to a calling workflow, etc.). Useful signals to draw on:
- Which routes were affected
- Which CSS classes appeared in the changed DOM regions (these usually map directly to components)
- Whether changes were structural (DOM additions/removals) or purely visual (pixel shift with no HTML diff)
- Whether the same change appears across multiple screenshots (suggesting a shared component changed) vs. isolated to one screenshot
The comparison URL logged to stdout is always worth surfacing, as it lets a human quickly verify the diff visually:
https://app.meticulous.ai/.../simulations/<baseReplayId>/compare-to/<headReplayId>
Notes
- The pixel diff images at
~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/
- If is omitted, no diff analysis is possible. Screenshots are still stored locally and can be compared later by re-running with set to the head replay ID from the first run.
- For the full iterative development workflow (session discovery, per-step commits, and final cloud run), see the skill.