meticulous-use-session-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use this workflow to get structured session data from Meticulous — the recorded user flows and network mocks that cover your code changes.

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.

使用此工作流从Meticulous获取结构化会话数据——涵盖你代码变更的录制用户流程和网络模拟。

开始之前，请运行
meticulous-cli-update
技能以确保Meticulous CLI是最新版本——除非在此对话的早些时候已经运行过，这种情况下可跳过此步骤。

Step 1 — Find relevant sessions and download their data

步骤1 — 查找相关会话并下载其数据

Run the following command from the root of the git repository:

bash

meticulous local relevant-sessions --format=multi-file --minimum-times-to-cover-each-line=1

This will:

Identify which recorded sessions exercise the code paths changed on your current branch.
Download each session's data as a structured directory tree to
```
.meticulous/sessions/
```
.

Options:

Option	Type	Default	Description
`--format`	`multi-file`	—	Set to `multi-file` to download each relevant session's data as a structured directory tree
`--minimum-times-to-cover-each-line`	number	—	Select at least this many sessions to cover each edited line, choosing the most diverse subset when more candidates are available
`--outputDir`	string	`.meticulous/sessions`	Output directory for multi-file format
`--showMaybeRelevant`	boolean	`false`	Also show sessions that may be affected
`--startingPointSha`	string	—	Only consider changes since this commit SHA

从git仓库的根目录运行以下命令：

bash

meticulous local relevant-sessions --format=multi-file --minimum-times-to-cover-each-line=1

此命令将：

识别哪些录制的会话会用到当前分支上变更的代码路径。
将每个会话的数据以结构化目录树的形式下载到
```
.meticulous/sessions/
```
目录中。

选项：

选项	类型	默认值	描述
`--format`	`multi-file`	—	设置为 `multi-file` 可将每个相关会话的数据下载为结构化目录树
`--minimum-times-to-cover-each-line`	数字	—	选择至少这么多的会话来覆盖每一行被编辑的代码，当有更多候选会话时，选择最多样化的子集
`--outputDir`	字符串	`.meticulous/sessions`	多文件格式的输出目录
`--showMaybeRelevant`	布尔值	`false`	同时显示可能受影响的会话
`--startingPointSha`	字符串	—	仅考虑从此提交SHA之后的变更

Step 2 — Understand the output structure

步骤2 — 理解输出结构

The downloaded data is organized as follows:

.meticulous/sessions/
  manifest.json                       # List of all sessions with summary metadata
  sessions/
    <sanitized-session-id>/           # Special characters in session IDs are replaced for filesystem safety
      summary.json                    # Session overview: URL, viewport, duration, event count
      user-events.json                # Sequence of user interactions (clicks, typing, navigation)
      network-requests/
        summary.json                  # All network requests: method, URL, status (no bodies)
        <order>.json                  # Individual request/response pairs (with bodies)
      storage/
        cookies.json                  # Initial cookie state
        local-storage.json            # Initial localStorage state
        session-storage.json          # Initial sessionStorage (if present)
        indexed-db.json               # Initial IndexedDB (if present)
      url-history.json                # Page navigation history with timestamps
      context.json                    # Feature flags, user ID, custom context (if present)
      websockets/                     # WebSocket data (if present)
        summary.json                  # WebSocket connections overview
        <connection-id>.json          # Events for each connection

下载的数据组织方式如下：

.meticulous/sessions/
  manifest.json                       # 包含所有会话及摘要元数据的列表
  sessions/
    <sanitized-session-id>/           # 为了文件系统安全，会话ID中的特殊字符已被替换
      summary.json                    # 会话概览：URL、视口、时长、事件数量
      user-events.json                # 用户交互序列（点击、输入、导航）
      network-requests/
        summary.json                  # 所有网络请求：方法、URL、状态（无请求体）
        <order>.json                  # 单个请求/响应对（包含请求体）
      storage/
        cookies.json                  # 初始Cookie状态
        local-storage.json            # 初始localStorage状态
        session-storage.json          # 初始sessionStorage（如果存在）
        indexed-db.json               # 初始IndexedDB（如果存在）
      url-history.json                # 带时间戳的页面导航历史
      context.json                    # 功能标志、用户ID、自定义上下文（如果存在）
      websockets/                     # WebSocket数据（如果存在）
        summary.json                  # WebSocket连接概览
        <connection-id>.json          # 每个连接的事件

Step 3 — Navigate the data

步骤3 — 浏览数据

Start with
manifest.json
to see all available sessions. Each entry includes the session ID, start URL, event count, duration, and network request count. Pick the session(s) relevant to your task.
Read
summary.json
inside a session directory for a quick overview of that session — the starting URL, viewport size, total duration, and number of events.
Read
user-events.json
to understand the user flow. Each event has:
- ```
type
```
  : the interaction type (e.g.,
```
click
```
  ,
```
input
```
  ,
```
scroll
```
  )
- ```
selector
```
  : the CSS selector of the target element
- ```
timestampMs
```
  : when the event occurred
- ```
coordinates
```
  : click position (if applicable)
Browse
network-requests/summary.json
to see all API calls made during the session. Each entry shows the HTTP method, URL, status code, content type, and response time — without response bodies, so it's quick to scan.
Read individual
network-requests/<order>.json
files for the full request/response data of specific API calls. Use these as mock data when writing tests. The
```
order
```
field in the summary corresponds to the filename.
Check
storage/
files if you need to understand the initial application state (cookies, localStorage, etc.).

从
manifest.json
开始查看所有可用会话。每个条目包含会话ID、起始URL、事件数量、时长和网络请求数量。选择与你的任务相关的会话。
**阅读会话目录中的
```
summary.json
```
**快速了解该会话的概况——起始URL、视口大小、总时长和事件数量。
**阅读
```
user-events.json
```
**了解用户流程。每个事件包含：
- ```
type
```
  ：交互类型（例如
```
click
```
  、
```
input
```
  、
```
scroll
```
  ）
- ```
selector
```
  ：目标元素的CSS选择器
- ```
timestampMs
```
  ：事件发生的时间戳
- ```
coordinates
```
  ：点击位置（如适用）
**浏览
```
network-requests/summary.json
```
**查看会话期间发起的所有API调用。每个条目显示HTTP方法、URL、状态码、内容类型和响应时间——不包含响应体，因此可以快速浏览。
阅读单个
network-requests/<order>.json
文件获取特定API调用的完整请求/响应数据。编写测试时可将这些数据用作模拟数据。摘要中的
```
order
```
字段对应文件名。
查看
storage/
目录下的文件如果需要了解应用的初始状态（Cookie、localStorage等）。

Step 4 — Use the data for testing

步骤4 — 将数据用于测试

Common use cases:

常见用例：

Understanding user flows

理解用户流程

Read

user-events.json

to see the exact sequence of user interactions. This tells you what the user clicked, typed, and navigated, which helps you understand what your code change needs to support.

阅读

user-events.json

查看用户交互的确切序列。这能告诉你用户点击、输入和导航的内容，帮助你了解代码变更需要支持哪些场景。

Creating network mocks

创建网络模拟

Use the network request files to create mock responses for your tests:

Read
```
network-requests/summary.json
```
to find the relevant API endpoints.
Read the individual
```
network-requests/<order>.json
```
files for the full request/response pairs.
Use the
```
response.content.text
```
field as mock response data in your tests.

使用网络请求文件为测试创建模拟响应：

阅读
```
network-requests/summary.json
```
找到相关的API端点。
阅读单个
```
network-requests/<order>.json
```
文件获取完整的请求/响应对。
使用
```
response.content.text
```
字段作为测试中的模拟响应数据。

Verifying coverage

验证覆盖范围

Cross-reference the user events and network requests with your code changes to verify that the session covers the code paths you've modified.

将用户事件和网络请求与你的代码变更进行交叉引用，验证会话是否覆盖了你修改的代码路径。

Alternative: Download specific sessions

替代方案：下载特定会话

If you already know which session IDs you need, you can download them directly:

bash

meticulous download session --sessionId=<id> --format=multi-file

This writes to

.meticulous/sessions/

by default. Use

--outputDir

to change the output location.

如果你已经知道需要哪些会话ID，可以直接下载它们：

bash

meticulous download session --sessionId=<id> --format=multi-file

默认情况下会写入

.meticulous/sessions/

目录。使用

--outputDir

可更改输出位置。