meticulous-simulate-and-diff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Simulate a session and analyze diffs

模拟会话并分析差异

This skill covers running a single simulation and interpreting the results. For the

simulate

command's full option reference see the

meticulous-cli-simulate

skill.

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

本技能涵盖如何运行单次模拟并解读结果。如需

simulate

命令的完整选项参考，请查看

meticulous-cli-simulate

技能。

开始前，请运行
meticulous-cli-update
技能确保Meticulous CLI为最新版本——如果本次对话中已经运行过该技能，则可跳过此步骤。

Prerequisites

前提条件

A
```
sessionId
```
to replay
An
```
appUrl
```
(local dev server, or leave blank to use the original recorded URL)
Optionally: a
```
baseReplayId
```
— the ID of a prior replay to diff screenshots against. Without this, screenshots are stored but not compared.

If you don't have a

baseReplayId

, you can find one from a downloaded test run:

bash

meticulous download test-run --apiToken=$METICULOUS_API_TOKEN

用于回放的
```
sessionId
```
```
appUrl
```
（本地开发服务器地址，留空则使用原始录制的URL）
可选：
```
baseReplayId
```
——用于对比截图的先前回放ID。若无此ID，截图会被存储但不会进行对比。

如果没有

baseReplayId

，可从已下载的测试运行中查找：

bash

meticulous download test-run --apiToken=$METICULOUS_API_TOKEN

Then inspect ~/.meticulous/test-runs/<testRunId>/coverage.json

然后查看 ~/.meticulous/test-runs/<testRunId>/coverage.json

or check the testCases[].replayId fields

或检查 testCases[].replayId 字段

undefined

undefined

Step 1 — Run the simulation

步骤1 —— 运行模拟

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:

undefined

bash

meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --baseReplayId=<baseReplayId> \
  --headless

捕获完整标准输出。重点关注以下内容：

undefined

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 `FAIL!` 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.

======= 查看模拟结果：https://app.meticulous.ai/projects/<org>/<project>/simulations/<headReplayId> 查看与基准的对比：https://app.meticulous.ai/projects/<org>/<project>/simulations/<baseReplayId>/compare-to/<headReplayId>


**如果没有`FAIL!`行：** 会话与基准视觉完全一致——到此为止并报告无回归问题。

若存在差异，请继续执行步骤2至5以定位并分析差异。

Without a base replay (quick-check mode)

无基准回放（快速检查模式）

If no

baseReplayId

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

<replayDir>/screenshots/

to verify the UI looks correct. There are no diff images in this mode — inspection is purely visual. Steps 3–5 do not apply.

若没有

baseReplayId

，可省略该参数。截图仍会存储在本地供直接视觉检查：

bash

meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --headless

然后找到回放目录（步骤2），打开

<replayDir>/screenshots/

下的截图以验证UI显示正常。此模式下无差异图像——仅需纯视觉检查。步骤3至5不适用。

Step 2 — Extract the head replay ID and locate the replay directory

步骤2 —— 提取头部回放ID并定位回放目录

From the

View simulation at:

URL, extract the

<headReplayId>

(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

<replayDir>

从

查看模拟结果：

的URL中提取

<headReplayId>

（最后一个路径段）。

要找到本次运行创建的本地回放目录：

bash

ls -lt ~/.meticulous/replays/ | head -5

最新创建的条目即为头部回放的目录（名称含时间戳，例如

2024-01-15T12-30-45.123Z-abc123/

）。记录此路径——下文将其称为

<replayDir>

。

Step 3 — Identify which screenshots diffed

步骤3 —— 识别存在差异的截图

bash

ls ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/

Each

.png

file here corresponds to a screenshot where a visual difference was detected. The pixel diff image highlights changed pixels in color. There are also

thumb_

prefixed thumbnail versions.

Note the filenames — they match the screenshot identifiers (e.g.

screenshot-after-event-42.png

bash

ls ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/

此处的每个

.png

文件对应检测到视觉差异的截图。像素差异图像会用颜色高亮显示变化的像素，还有带

thumb_

前缀的缩略图版本。

记录文件名——它们与截图标识符匹配（例如

screenshot-after-event-42.png

）。

Step 4 — Analyze the HTML diff for each diffed screenshot

步骤4 —— 分析每张差异截图的HTML差异

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

.metadata.json

files. The relevant fields are:

```
before.dom
```
— full HTML of the page at screenshot time; diff these two strings to understand what changed
```
before.routeData.url
```
— which page/route the screenshot was taken on

When diffing the HTML, focus on tag additions/removals,

class

attribute changes, and text content changes.

The per-screenshot stdout lines also report

mismatchFraction

(proportion of pixels that changed). If there is a pixel diff but the

before.dom

strings are identical, the change is purely visual (e.g. a color shift) rather than structural.

每张截图都有对应的元数据文件，包含截图捕获前一刻页面的完整HTML快照。这些文件已存储在本地：

头部元数据：

~/.meticulous/replays/<replayDir>/screenshots/<screenshotFilename>.metadata.json

基准元数据：

~/.meticulous/replays/<baseReplayId>/screenshots/<screenshotFilename>.metadata.json

基准元数据会在模拟下载基准回放时永久缓存，无需额外下载。

读取两个

.metadata.json

文件，重点关注以下字段：

```
before.dom
```
——截图时页面的完整HTML；对比这两个字符串以了解变更内容
```
before.routeData.url
```
——截图所在的页面/路由

对比HTML时，重点关注标签的添加/移除、

class

属性变更以及文本内容变更。

每张截图的标准输出行还会报告

mismatchFraction

（变更像素的比例）。如果存在像素差异但

before.dom

字符串完全相同，则变更为纯视觉层面（例如颜色偏移）而非结构层面。

Step 5 — Summarize the findings

步骤5 —— 总结发现

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>

本技能的核心输出是关于视觉变更内容及原因的高可读性描述。结合收集到的像素差异计数、路由URL、变更的类名和HTML差异，回答：用户体验发生了什么变化，UI的哪部分导致了该变化？

可根据当前上下文选择合适的格式呈现（对话式回答、结构化报告、调用工作流的输入等）。可参考以下有用信息：

哪些路由受到影响
变更DOM区域中出现的CSS类（通常直接对应组件）
变更是结构性的（DOM添加/移除）还是纯视觉性的（像素偏移但无HTML差异）
同一变更是否出现在多张截图中（表明共享组件发生变更）还是仅出现在单张截图中

标准输出中记录的对比URL值得重点提及，因为它能让人工快速直观地验证差异：

https://app.meticulous.ai/.../simulations/<baseReplayId>/compare-to/<headReplayId>

Notes

注意事项

The pixel diff images at
```
~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/
```
can be opened directly for visual inspection.
If
```
--baseReplayId
```
is omitted, no diff analysis is possible. Screenshots are still stored locally and can be compared later by re-running with
```
--baseReplayId
```
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
```
meticulous-iterative-dev
```
skill.

```
~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/
```
下的像素差异图像可直接打开进行视觉检查。
如果省略
```
--baseReplayId
```
，则无法进行差异分析。截图仍会存储在本地，之后可通过将
```
--baseReplayId
```
设置为首次运行的头部回放ID重新运行来进行对比。
如需完整的迭代开发工作流（会话发现、分步提交、最终云端运行），请查看
```
meticulous-iterative-dev
```
技能。