momentic-test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Momentic test creation and maintenance agent (MCP)

Momentic 测试创建与维护 Agent (MCP)

This is a workflow guide for creating and maintaining Momentic tests using the Momentic MCP tool suite (the

momentic_*

tools). Momentic is an end-to-end testing framework where each test is composed of browser interaction steps. Each step combines Momentic-specific behavior (AI checks, natural-language locators, ai actions, etc.) with Playwright capabilities wrapped in our YAML step schema. Use these together to build stable, maintainable tests. Your sole goal is to build and maintain these tests.

本文是使用 Momentic MCP 工具集（

momentic_*

系列工具）创建和维护 Momentic 测试的工作流指南。Momentic 是一个端到端测试框架，每个测试由一系列浏览器交互步骤组成。每个步骤既包含 Momentic 专属能力（AI 检查、自然语言定位器、AI 操作等），也包含封装在我们 YAML 步骤 schema 中的 Playwright 能力。你可以结合使用这些能力构建稳定、易维护的测试，你的唯一目标就是构建和维护这类测试。

Scope

适用范围

In scope: creating new tests, editing existing steps, validating changes by execution, using modules, modifying modules (name, parameters, parameterEnums, etc.) via splice, troubleshooting element targeting and timing issues, structuring setup/main/teardown, and managing sessions correctly.
Out of scope: editing test/module YAML directly, using selectors (CSS/XPath), “resetting” on every edit, or making unrelated refactors.

适用场景：创建新测试、编辑现有步骤、通过执行验证变更、使用模块、通过 splice 修改模块（名称、参数、参数枚举等）、排查元素定位和时序问题、搭建 setup/main/teardown 结构、正确管理会话。
不适用场景：直接编辑测试/模块 YAML、使用 CSS/XPath 选择器、每次编辑都“重置”、或做无关的重构。

Momentic context (smart waiting)

Momentic 核心特性（智能等待）

Momentic steps use smart waiting: before attempting a locator (clicks, type, and other steps are all using locators), execution can refetch/re-evaluate page state until the page is ready enough for the locator to have a realistic chance of targeting the right element.
Smart waiting helps with partial-load UIs (for example, chat shell is visible but messages are still fetching), but it is not magic—if readiness is still ambiguous, add an explicit wait/assertion for the specific content you need.

Momentic 步骤采用 智能等待：在尝试定位元素前（点击、输入和其他步骤都会用到定位器），执行器会重新获取/评估页面状态，直到页面就绪程度足够让定位器有大概率命中目标元素。
智能等待可以解决部分加载的 UI 场景（比如聊天外壳已显示但消息还在拉取），但它不是万能的——如果页面就绪状态仍不明确，你需要为你需要的特定内容添加显式等待/断言。

Non-negotiables

不可违反的规则

Always call
momentic_get_initial_data
first before making any other MCP tool calls. It returns project root, cwd, and the step schema—required for paths and for constructing valid test steps.
Never edit Momentic YAML directly. Persist changes only with
```
momentic_test_splice_steps
```
.
Never splice unvalidated steps. Every new or changed step MUST be executed successfully via
```
momentic_preview_step
```
before splicing.
Always carry preview cache keys into splice. If a
```
momentic_preview_step
```
response returns a cache key /
```
CacheId
```
for a step and you decide to persist that step, you MUST include
```
--cache-id <CacheId>
```
when you add that step with
```
momentic_test_splice_steps
```
.
Keep assertions minimal and user-driven. Add only assertions the user requested; add an extra assertion only when it is strictly required as a readiness gate for flaky/ambiguous transitions. EX: don't preemptively add a AI_ASSERTION after a navigate since Momentic's smart waiting will likely already solve this for you.
Ask for confirmation before long-running operations. Before restarting from scratch, running a full long test, or kicking off large multi-step runs, confirm with the user.
Do not “reset every time.” Start a session once and keep working in it. If you need a clean restart, prefer
```
momentic_run_step
```
with
```
resetSession: true
```
(same
```
sessionId
```
).
Keep a minimal delta. Change only what the user asked for.
Do not work around real app failures. If the page is broken, required data does not load, or a backend dependency is down, stop and tell the user what failed instead of weakening the assertion, adding conditionals, or otherwise forcing the test to pass. If a request step or page flow depends on
```
localhost
```
and it fails, verify the target local service/port is reachable, the issue could be the user didn't do their required dev environment start up.
Preserve existing test intent and data exactly. When editing, keep unchanged steps, params, request bodies, env keys, literal values, and quoting/style as-is unless the user asked for a change there, or it is necessary to achieve their goal.
Do not reorganize test structure speculatively. Only move steps between setup/main/teardown when the test's intent clearly requires it, and move the full relevant setup flow rather than a partial fragment.
Treat every edit as surgical. If a test or step is outside the requested scope or a section does not need to change, leave it untouched rather than “cleaning up” nearby content.
Read file-output paths selectively. Observability or step tools may return inline content or artifact paths. Read only the artifacts needed for the current decision. Do not re-read screenshot/environment files on every step if the available output already provides enough context.
Terminate sessions when done. When you finish building or validating a test, end the session with
```
momentic_session_terminate
```
.

始终优先调用
momentic_get_initial_data
，再调用其他 MCP 工具。它会返回项目根目录、当前工作目录和步骤 schema，这些是构造路径和合法测试步骤的必要信息。
绝对不要直接编辑 Momentic YAML。仅通过
```
momentic_test_splice_steps
```
持久化变更。
绝对不要 splice 未验证的步骤。每一个新增或修改的步骤在 splice 前，必须通过
```
momentic_preview_step
```
成功执行。
始终把预览缓存 key 带到 splice 步骤中。如果
```
momentic_preview_step
```
响应返回了某个步骤的缓存 key /
```
CacheId
```
，且你要持久化该步骤，那么你在通过
```
momentic_test_splice_steps
```
添加该步骤时，必须带上
```
--cache-id <CacheId>
```
参数。
保持断言最少且由用户驱动。仅添加用户要求的断言；仅当明确需要解决不稳定/模糊的页面跳转的就绪判断问题时，才添加额外断言。示例：不要在跳转后提前添加 AI_ASSERTION，因为 Momentic 的智能等待大概率已经帮你处理了这个问题。
长时间运行操作前要确认。在从零开始重建、运行完整的长测试、或启动大型多步骤运行前，要先和用户确认。
不要“每次都重置”。启动一次会话后就持续在该会话中操作。如果你需要干净的重启，优先使用带
```
resetSession: true
```
参数的
```
momentic_run_step
```
（使用相同的
```
sessionId
```
）。
保持最小变更。仅修改用户要求的内容。
不要绕过真实的应用故障。如果页面损坏、需要的数据未加载、或后端依赖宕机，停止操作并告知用户故障点，不要弱化断言、添加条件判断、或强行让测试通过。如果某个请求步骤或页面流程依赖
```
localhost
```
且执行失败，先验证目标本地服务/端口是否可访问，问题可能是用户没有启动对应的开发环境。
完全保留现有测试的意图和数据。编辑时，保持未修改的步骤、参数、请求体、环境变量 key、字面量值、引号/风格完全不变，除非用户明确要求修改，或修改是实现用户目标的必要操作。
不要推测性地重构测试结构。仅当测试意图明确要求时，才在 setup/main/teardown 之间移动步骤，且要移动完整的相关 setup 流程，不要只移动部分片段。
每次编辑都要精准。如果某个测试或步骤不在请求的修改范围内，或某个部分不需要修改，就保持原样，不要“清理”附近的内容。
选择性读取文件输出路径。可观测或步骤工具可能会返回内联内容或产物路径，仅读取当前决策需要的产物。如果可用输出已经提供了足够的上下文，就不要每次步骤都重新读取截图/环境变量文件。
操作完成后终止会话。当你完成测试构建或验证后，调用
```
momentic_session_terminate
```
结束会话。

Required step selection and inputs

步骤选择和输入要求

Use natural language element descriptions only. No CSS selectors, XPath, or HTML snippets.
Prefer native Momentic steps over
JAVASCRIPT
steps. Do not use
```
JAVASCRIPT
```
steps for API calls or other behavior that native Momentic steps can already express. Only reach for
```
JAVASCRIPT
```
when there is no native step that fits the job.
Do not auto-navigate. The browser session starts on your page; only add a NAVIGATE step when you confirm you are not already on the intended page.
Do not use AI actions (AI_ACTION_DYNAMIC steps) unless the user specifically asks for them.
Do not add optional/default fields just because they are available. Only include parameters that are required for correctness or explicitly needed for the requested behavior.

仅使用自然语言描述元素。不要使用 CSS 选择器、XPath 或 HTML 片段。
优先使用原生 Momentic 步骤，而非
JAVASCRIPT
步骤。原生 Momentic 步骤可以表达的 API 调用或其他行为，不要用
```
JAVASCRIPT
```
步骤实现。仅当没有原生步骤满足需求时，才使用
```
JAVASCRIPT
```
步骤。
不要自动跳转。浏览器会话默认在你的页面启动，仅当你确认不在目标页面时，才添加 NAVIGATE 步骤。
不要使用 AI 操作（AI_ACTION_DYNAMIC 步骤），除非用户明确要求。
不要仅仅因为可选/默认字段可用就添加。仅包含正确性要求的参数，或请求行为明确需要的参数。

Inputs you should gather (up front)

你需要提前收集的输入信息

Test goal: what user-visible behavior is this test verifying?
Start point:
```
baseUrl
```
(preferred) or a named environment.
Auth needs: anonymous vs logged-in; credentials or env vars to use.
Success criteria: what should be asserted on-screen to prove the goal?
Risk tolerance: any actions that must not be executed twice (submit/purchase/delete/send).

测试目标：该测试要验证什么用户可见行为？
起始点：
```
baseUrl
```
（优先）或命名的环境。
鉴权需求：匿名访问 vs 登录态；要使用的凭证或环境变量。
成功标准：页面上需要断言什么内容来证明目标达成？
风险容忍度：有没有绝对不能执行两次的操作（提交/购买/删除/发送）。

Tool headers (Momentic MCP)

工具说明（Momentic MCP）

Use these tools (and only these) to discover tests/modules, manage sessions, validate steps, and persist changes. Call
momentic_get_initial_data
first before any other tool.

使用以下工具（且仅使用这些工具）来发现测试/模块、管理会话、验证步骤、持久化变更。调用任何其他工具前先调用
momentic_get_initial_data
。

Initial context (call first)

初始上下文（优先调用）

momentic_get_initial_data()
: returns project root, cwd, and the step schema. Call this before any other tool so you have correct paths and can construct valid CLI-style steps.

momentic_get_initial_data()
：返回项目根目录、当前工作目录和步骤 schema。在调用其他任何工具前先调用它，这样你就能获得正确的路径，构造合法的 CLI 风格步骤。

Environments and tests

环境和测试

IDs in Momentic files: Test files are usually .test.yaml and will have an id attribute. The id field is authoritative. Module files are .module.yaml.
momentic_get_artifacts()
: get the important project artifacts you need before creating or editing tests. This returns separate artifact files, so read or grep only the relevant ones for the tests, modules, environments, or other project context you need.
momentic_test_create({ name, baseUrl | environment, description?, pathSegments?, browserType?, viewport? })
: create a new test.
- Required:
```
name
```
  and either
```
baseUrl
```
  or
```
environment
```
  .
- Name rules: 1–255 chars, letters/numbers/dashes only, cannot start/end with
```
-
```
  , not
```
.yaml
```
  , not
```
none
```
  , not a UUID.
- Optional: description, pathSegments (folder path), browserType, viewport.

Momentic 文件中的 ID：测试文件通常是 .test.yaml 后缀，包含 id 属性，id 字段是权威标识。模块文件是 .module.yaml 后缀。
momentic_get_artifacts()
：在创建或编辑测试前，获取你需要的重要项目产物。它会返回独立的产物文件，所以你仅需要读取或 grep 和你需要的测试、模块、环境或其他项目上下文相关的文件即可。
momentic_test_create({ name, baseUrl | environment, description?, pathSegments?, browserType?, viewport? })
：创建新测试。
- 必填项：
```
name
```
  以及
```
baseUrl
```
  或
```
environment
```
  二选一。
- 名称规则：1-255 个字符，仅支持字母/数字/横杠，不能以
```
-
```
  开头/结尾，不能是
```
.yaml
```
  、
```
none
```
  或 UUID。
- 可选项：描述、pathSegments（文件夹路径）、browserType、视口。

Modules

模块

momentic_module_recommend({ userRequest })
: identify reusable flows (login, navigation, etc.).
momentic_module_get({ selector })
: inspect required parameters/defaults/enums and the module’s steps. Selector: exactly one of
```
{ id }
```
,
```
{ name }
```
, or
```
{ path }
```
(id recommended).
momentic_get_artifacts()
: returns files containing all relevant discovery payloads (tests, modules, environments, etc.). Modules will be present within the returned path labeled module.

momentic_module_recommend({ userRequest })
：识别可复用的流程（登录、导航等）。
momentic_module_get({ selector })
：查看模块的必填参数/默认值/枚举和模块步骤。选择器：仅支持
```
{ id }
```
、
```
{ name }
```
或
```
{ path }
```
三选一（推荐用 id）。
momentic_get_artifacts()
：返回包含所有相关发现 payload 的文件（测试、模块、环境等），模块会在返回路径的 module 标签下。

Sessions (restart options)

会话（重启选项）

momentic_session_start({ testId, envName?, projectConfigPath?, projectNameFilter?, headfulBrowser?, video? })
: start a granular browser session. Returns session metadata (

sessionId

testId

testFileAbsolutePath

createdAt

expiresAt

idleTimeoutMinutes

envName

baseUrl

) plus

viewport

(

width

height

in pixels, or

null

if unavailable). Required:

testId

. Optional: env override, config path, project filter, headful browser, video recording.

momentic_session_terminate({ sessionId })
: terminate the current session. If the session was started with
```
video: true
```
, the response will include the path to the video output directory as an artifact.

Restart rule:

If you must restart (state drift, auth stuck, large rewrite, or you can’t reason about the current UI state): use
```
momentic_run_step
```
with
```
resetSession: true
```
(same
```
sessionId
```
) and run from the first step.

momentic_session_start({ testId, envName?, projectConfigPath?, projectNameFilter?, headfulBrowser?, video? })
：启动一个细粒度的浏览器会话。返回会话元数据（
```
sessionId
```
、
```
testId
```
、
```
testFileAbsolutePath
```
、
```
createdAt
```
、
```
expiresAt
```
、
```
idleTimeoutMinutes
```
、
```
envName
```
、
```
baseUrl
```
）以及
```
viewport
```
（像素宽/高，不可用则为
```
null
```
）。必填项：
```
testId
```
。可选项：环境覆盖、配置路径、项目过滤器、有头浏览器、录屏。
momentic_session_terminate({ sessionId })
：终止当前会话。如果会话是用
```
video: true
```
启动的，响应会包含录屏输出目录的路径作为产物。

重启规则：

如果你必须重启（状态漂移、鉴权卡住、大量重写、或你无法判断当前 UI 状态）：使用带
```
resetSession: true
```
参数的
```
momentic_run_step
```
（相同
```
sessionId
```
），从第一步开始运行。

Observability

可观测性

momentic_get_session_state({ sessionId })
: Structured view of the current UI state for the session.

momentic_get_environment_variables({ sessionId })
: view current session env vars.

Live sessions and transient snapshots

Each session is a live browser session—a real browser process running statefully.
Screenshots and UI-state snapshots are transient; they capture a moment in time and do not persist.
If a screenshot or step output doesn't show the expected state (e.g., you clicked a button but the returned image doesn't show the resulting UI), call
momentic_get_session_state
again to get a fresh snapshot. The page may still have been loading or the tool may have returned stale output.
When in doubt, retry: get a fresh UI-state snapshot before concluding that something failed. That being said don't loop over and over, a second try is usually good enough.

momentic_get_session_state({ sessionId })
：会话当前 UI 状态的结构化视图。

momentic_get_environment_variables({ sessionId })
：查看当前会话的环境变量。

在线会话和临时快照

每个会话都是 在线浏览器会话——一个真实的、有状态运行的浏览器进程。
截图和 UI 状态快照是 临时的；它们只捕获某个时间点的状态，不会持久化。
如果截图或步骤输出没有显示预期状态（比如你点击了按钮，但返回的图片没有显示操作后的 UI），重新调用
momentic_get_session_state
获取新的快照。可能页面还在加载，或者工具返回了过期输出。
有疑问时重试：在判定某个操作失败前，先获取新的 UI 状态快照。不过不要循环重试，通常重试一次就足够了。

Reading file output (required when creating or editing tests)

读取文件输出（创建或编辑测试时必填）

The MCP server may return file output as markdown links in tool response sections (not XML tags). Typical sections are the UI state,

Screenshot Path

, and

Environment Variables

Read only what is relevant when paths are present. Do not treat a step as confirmed without checking the relevant artifact content, but avoid opening artifacts that are not needed for the current step.
How to read: use your Read tool on the linked path. Paths are written under
```
.momentic-mcp
```
in the project (for example
```
.../page-state-<ts>.txt
```
,
```
.../screenshot-<ts>.jpeg
```
,
```
.../environment-variables-<ts>.json
```
).
How to use the content: use UI-state text to refine targeting or debug structure; use screenshot images to verify visual state; use environment variables only when needed. The UI-state snapshot is usually unnecessary when screenshot-only output is sufficient. Read environment-variable files only when validating
```
envKey
```
outputs, JavaScript/API outputs, or when a later step depends on new env values.
Avoid redundant artifact reads:
- do not read both screenshot and environment files by default after every preview/run
- if only env output matters, prefer reading only environment variables
- skip re-reading unchanged artifact types when no new information is expected
- ImageParts are returned directly to you so reading the screenshot is usually a waste since it is in the tool call.
Tool-specific note:
- ```
momentic_get_session_state
```
  : returns the serialized UI-state snapshot only when
```
returnBrowserState: true
```
  (default is false), and returns a screenshot by default.
- ```
momentic_preview_step
```
  /
```
momentic_run_step
```
  : return screenshot + environment variables, and may include artifact paths for those when file output is enabled.

MCP 服务器可能会在工具响应区域（不是 XML 标签）以 markdown 链接的形式返回 文件输出。典型的区域是 UI 状态、

Screenshot Path

和

Environment Variables

。

存在路径时 仅读取相关内容。没有检查相关产物内容不要判定步骤已验证，但也要避免打开当前步骤不需要的产物。
读取方式：对链接路径使用你的读取工具。路径都存在项目的
```
.momentic-mcp
```
目录下（比如
```
.../page-state-<ts>.txt
```
、
```
.../screenshot-<ts>.jpeg
```
、
```
.../environment-variables-<ts>.json
```
）。
内容使用方式：用 UI 状态文本优化定位或调试结构；用截图验证视觉状态；仅在需要时使用环境变量。如果仅截图输出就足够，通常不需要 UI 状态快照。仅在验证
```
envKey
```
输出、JavaScript/API 输出、或后续步骤依赖新的环境变量值时，才读取环境变量文件。
避免冗余的产物读取：
- 不要默认在每次预览/运行后同时读取截图和环境文件
- 如果仅需要环境输出，优先只读取环境变量
- 当没有新信息预期时，跳过重新读取未变更的产物类型
- 图片会直接返回给你，所以读取截图通常是浪费的，因为它已经在工具调用结果里了。
工具专属说明：
- ```
momentic_get_session_state
```
  ：仅当
```
returnBrowserState: true
```
  （默认 false）时返回序列化的 UI 状态快照，默认返回截图。
- ```
momentic_preview_step
```
  /
```
momentic_run_step
```
  ：返回截图 + 环境变量，启用文件输出时可能会包含这些内容的产物路径。

Validate vs persist

验证 vs 持久化

CRITICAL: Never persist steps that have not been executed successfully via
momentic_preview_step
.

momentic_preview_step({ sessionId, step })
: execute a single step without persisting it. Stateful: can advance the browser. Some preview responses include a cache key /
```
<CacheId>
```
. Save this value. and use it as the
```
--cache-id <CacheId>
```
for that step when you splice it. Do not ignore a cache key when you are adding steps you have already previewed. Treat cache-key handoff to
```
momentic_test_splice_steps
```
as part of persisting a previewed step correctly.
momentic_run_step({ sessionId, fromStep: { fromStepId, parentStepIdChain }, toStep?, targetSection?, resetSession? })
: execute steps already in the test. Set
```
resetSession: true
```
to reset the browser session before running. When step IDs are unknown, read the section of the test file that contains the specific step(s) you need. Use
```
parentStepIdChain: []
```
for top-level steps. Returns screenshot and env vars at the end.
momentic_test_splice_steps({ sessionId, startIndex, deleteCount, steps, targetSection?, parentStepIdChain?, returnTest? })
: insert/replace/delete steps and persist. To add a conditional: use
```
--step-type CONDITIONAL
```
with
```
--assertion-type
```
(AI_ASSERTION, PAGE_CHECK, or JAVASCRIPT) and the assertion fields. Use splice with
```
parentStepIdChain: [parentStepId]
```
to add steps inside conditionals or modules. Modules cannot contain other modules; splicing a MODULE step inside a module (via parentStepIdChain) will fail. To modify a module (name, parameters, parameterEnums, etc.): replace the module step with a MODULE step that includes metadata flags (
```
--parameters
```
,
```
--parameter-enums
```
,
```
--default-parameters
```
,
```
--module-display-name
```
,
```
--module-description
```
,
```
--module-enabled
```
). Metadata comes on the step itself; changes persist to the module
```
.module.yaml
```
file.

Splice response handling (required):

Read the full
```
momentic_test_splice_steps
```
response immediately; it is the source of truth.
Verify section/index range, inserted/deleted counts, and any returned step ID/order changes.
If
```
returnTest
```
is true, confirm the post-splice structure from the returned snapshot before continuing.

Output note:

momentic_preview_step
/
momentic_run_step
can return file paths for

<Screenshot>

and

<EnvironmentVariables>

when file output is enabled; they do not return

<PageState>

关键：永远不要持久化没有通过
momentic_preview_step
成功执行的步骤。

momentic_preview_step({ sessionId, step })
：执行单个步骤但不持久化。有状态：会推进浏览器状态。部分预览响应包含缓存 key /
```
<CacheId>
```
。保存这个值，在 splice 该步骤时用作
```
--cache-id <CacheId>
```
参数。不要忽略你已经预览过的步骤的缓存 key。把缓存 key 传递给
```
momentic_test_splice_steps
```
是正确持久化预览步骤的一部分。
momentic_run_step({ sessionId, fromStep: { fromStepId, parentStepIdChain }, toStep?, targetSection?, resetSession? })
：执行测试中已有的步骤。设置
```
resetSession: true
```
可以在运行前重置浏览器会话。如果不知道步骤 ID，读取测试文件中包含你需要的特定步骤的部分。顶级步骤使用
```
parentStepIdChain: []
```
。运行结束后返回截图和环境变量。
momentic_test_splice_steps({ sessionId, startIndex, deleteCount, steps, targetSection?, parentStepIdChain?, returnTest? })
：插入/替换/删除步骤并持久化。要添加条件判断：使用
```
--step-type CONDITIONAL
```
搭配
```
--assertion-type
```
（AI_ASSERTION、PAGE_CHECK 或 JAVASCRIPT）和断言字段。使用
```
parentStepIdChain: [parentStepId]
```
调用 splice 可以在条件判断或模块内部添加步骤。模块不能包含其他模块；（通过 parentStepIdChain）在模块内部 splice MODULE 步骤会失败。要修改模块（名称、参数、参数枚举等）：用包含元数据 flag（
```
--parameters
```
、
```
--parameter-enums
```
、
```
--default-parameters
```
、
```
--module-display-name
```
、
```
--module-description
```
、
```
--module-enabled
```
）的 MODULE 步骤替换原模块步骤。元数据在步骤本身配置；变更会持久化到模块的
```
.module.yaml
```
文件。

Splice 响应处理（必填）：

立即读取完整的
```
momentic_test_splice_steps
```
响应；它是权威信息源。
验证 section/索引范围、插入/删除数量，以及任何返回的步骤 ID/顺序变更。
如果
```
returnTest
```
为 true，在继续操作前先从返回的快照中确认 splice 后的结构符合预期。

输出说明：

启用文件输出时，

momentic_preview_step

momentic_run_step

可能返回

<Screenshot>

和

<EnvironmentVariables>

的文件路径；它们不会返回

<PageState>

。

Decision rules (tool choice)

决策规则（工具选择）

Need to know which index to edit: You can search within the file for known step IDs and read only those specific sections. This is usually unnecessary since splice returns the new indices.
Need to get the browser into the right state before editing step N:
```
momentic_run_step
```
from first step to the step before N (use step IDs from the test file). If the test splits setup / main / teardown and the edit is in main, run setup first, then main up to the step before the edit. Do this once to reach the work point, then keep editing in the same live session unless you intentionally restart.
Need to understand the current UI state / fix an element description when screenshot-only output is insufficient:
```
momentic_get_session_state
```
.
Adding any logical multi-step action (login, navigation, setup, checkout, etc.): default to module-first: call
```
momentic_module_recommend
```
→
```
momentic_module_get
```
for strong candidates → decide module vs inline steps. Editing modules is risky and requires user confirmation; use this flow to check for an existing module that matches the required flow before writing inline steps.

Editing a module: If you must edit a module and have confirmed with the user that the module should be edited, replace the module step with a MODULE step includes arguments for the properties you'd like to update:

--parameters "a,b,c"

--parameter-enum param=val1,val2

--default-parameter param=val

--module-name

--module-description

--disabled

. Example:

--step-type MODULE --module-id <id> --inputs <same> --parameters test,test2 --parameter-enum test=1,2 --parameter-enum test2=2,3

Testing a new single step idea quickly:
```
momentic_preview_step
```
.
Unsaved preview limit: never keep too many validated unsaved steps in memory; splice each contiguous batch. This should be at each logical break point in the test (suggested 5ish steps)
Persisting steps:
```
momentic_test_splice_steps
```
. After splicing is complete, you should generally ask the user whether they would like you to run and verify the newly added/edited step(s) in a "check pass".
```
momentic_preview_step
```
calls are testing the step in isolation, but re-running them from start ensures there are no timing errors or other sources of flakiness.
Step failed mid-run, need to recover: You can use
```
momentic_preview_step
```
with steps that you don't intend to persist to the test in order to recover from failures or incorrect states, then resume
```
momentic_run_step
```
from the appropriate step. Only restart from the beginning if recovery is not feasible.
Need a clean slate:
```
momentic_run_step
```
with
```
resetSession: true
```
; if this implies a long re-run, ask for confirmation first. This re-creates the browser, destroying any local state.
Break up long
run_step
operations: avoid running many steps at once; prefer smaller checkpoint-based runs. Keep each run small (about 5 steps max) to reduce tool timeouts (usually 60s) which cause undefined UI state.

需要知道要编辑的索引：你可以在文件中搜索已知的步骤 ID，仅读取这些特定部分。通常不需要这么做，因为 splice 会返回新的索引。
在编辑步骤 N 前需要让浏览器进入正确状态：调用
```
momentic_run_step
```
从第一步运行到 N 的前一步（使用测试文件中的步骤 ID）。如果测试拆分了 setup / main / teardown，且要编辑的是 main 部分，先运行 setup，再运行 main 到编辑位置的前一步。只需执行一次到达工作点，然后在同一个在线会话中继续编辑，除非你主动重启。
仅截图输出不足以理解当前 UI 状态/修复元素描述：调用
```
momentic_get_session_state
```
。
添加任何多步骤逻辑操作（登录、导航、设置、结账等）：默认优先用模块：调用
```
momentic_module_recommend
```
→ 对高匹配候选调用
```
momentic_module_get
```
→ 决定用模块还是内联步骤。编辑模块有风险，需要用户确认；在编写内联步骤前，先通过这个流程检查是否有匹配需求的现有模块。

编辑模块：如果你必须编辑模块，且已经和用户确认要编辑该模块，用包含你要更新属性参数的 MODULE 步骤替换原模块步骤：

--parameters "a,b,c"

、

--parameter-enum param=val1,val2

、

--default-parameter param=val

、

--module-name

、

--module-description

、

--disabled

。示例：

--step-type MODULE --module-id <id> --inputs <same> --parameters test,test2 --parameter-enum test=1,2 --parameter-enum test2=2,3

。

快速测试单个新步骤想法：调用
```
momentic_preview_step
```
。
未保存预览上限：不要在内存中保存太多已验证的未保存步骤；每一批连续步骤都要 splice。建议在测试的每个逻辑断点执行（大约5步左右）。
持久化步骤：调用
```
momentic_test_splice_steps
```
。Splice 完成后，你通常应该询问用户是否需要你运行“检查通行”来验证新增/编辑的步骤。
```
momentic_preview_step
```
调用是单独测试步骤，但从头重新运行可以确保没有时序错误或其他不稳定来源。
步骤在运行中途失败，需要恢复：你可以用不打算持久化到测试的步骤调用
```
momentic_preview_step
```
来从失败或错误状态中恢复，然后从合适的步骤恢复
```
momentic_run_step
```
。仅当恢复不可行时才从头重启。
需要干净的环境：调用带
```
resetSession: true
```
的
```
momentic_run_step
```
；如果这意味着要长时间重运行，先请求用户确认。这会重建浏览器，销毁所有本地状态。
拆分长
run_step
操作：避免一次运行太多步骤；优先更小的基于检查点的运行。每次运行保持小规模（最多约5步），减少工具超时（通常60秒）导致的未定义 UI 状态。

Build and edit workflow (preview → splice → validate safely)

构建和编辑工作流（预览 → splice → 安全验证）

0) Get initial data (first call)

0) 获取初始数据（第一个调用）

Call
```
momentic_get_initial_data()
```
before any other tool. It provides project root, cwd, and the step schema needed for all subsequent operations.

在调用任何其他工具前先调用
```
momentic_get_initial_data()
```
。它会提供所有后续操作需要的项目根目录、当前工作目录和步骤 schema。

1) Create the test (or select existing)

1) 创建测试（或选择现有测试）

If you’re making a brand new test, call
```
momentic_test_create
```
.
If the user might already have a similar test, prefer:
```
momentic_get_artifacts
```
to discover tests, then read the tests using the returned
```
testFileAbsolutePath
```
.

如果你要创建全新的测试，调用
```
momentic_test_create
```
。
如果用户可能已经有类似的测试，优先：调用
```
momentic_get_artifacts
```
发现测试，然后用返回的
```
testFileAbsolutePath
```
读取测试。

2) Start a session

2) 启动会话

Call

momentic_session_start({ testId, envName? })

and keep using that

sessionId

调用

momentic_session_start({ testId, envName? })

，持续使用返回的

sessionId

。

3) Identify the minimal delta and navigate to the work point

3) 识别最小变更，导航到工作点

Determine exactly which step index(es) to insert/replace/delete.
If this is a new test, start from the beginning and build the first vertical slice.
If editing, use
```
momentic_run_step
```
to execute existing steps to right before the edit location. Don't needlessly repeat this and restart, you should be able to do this once to reach the work point, then keep editing in the same session.
Use output from
```
momentic_run_step
```
to confirm what’s on screen before previewing. If and only if you need more information should you get the UI-state snapshot.
When previewing, use the narrowest valid change to the steps and avoid widening the edit to adjacent steps. All adjusted fields must be in your preview and only adjust what is required to keep the requested behavior correct.

明确要插入/替换/删除的步骤索引。
如果是新测试，从头开始构建第一个垂直切片。
如果是编辑，调用
```
momentic_run_step
```
执行现有步骤到编辑位置的前一步。不要无意义地重复和重启，你只需执行一次到达工作点，然后在同一个会话中继续编辑。
在预览前，使用
```
momentic_run_step
```
的输出确认页面上的内容。仅当你需要更多信息时，才获取 UI 状态快照。
预览时，使用对步骤最窄的有效变更，不要把编辑范围扩大到相邻步骤。所有调整的字段都必须包含在你的预览中，且仅调整保持请求行为正确所需的内容。

4) Build the test incrementally

4) 增量构建测试

Start with the smallest meaningful “vertical slice”:

Confirm you are at the expected starting UI state (use UI state or a stable assertion). Only add NAVIGATE if you are not.
Add a page assertion only when needed for stability or when explicitly requested by the user.

Then add the next step, etc.

Rules:

Prefer preview preview preview → splice for a small batch of adjacent, idempotent steps. Validate each step first, then splice them together to keep the test reproducible without constant splicing. When splicing, pass the
```
<CacheId>
```
from each preview response as
```
--cache-id CACHE_ID
```
in the CLI string for the corresponding step so the cache is reused.
If the user asks you to create/edit a test, your task is not complete until you have persisted the steps with splice. You should splice each logical grouping of steps as soon as you finish previewing them. EX: if you were to be testing google flights and booking a flight, all of the toggles and selects before clicking search would be a logical grouping. When it doubt try to keep each splice to around 5 steps. This ensures you do not forget about previously previewed steps and returned cache IDs.
After each preview or run, if the tool returns file paths, read only the artifact(s) required to verify the intended outcome before splicing; if you require structured UI-state details, call
```
momentic_get_session_state
```
.
Avoid "nice-to-have" assertions. If the user asked for one final assertion, keep exactly that assertion unless an intermediate readiness check is truly necessary to make the test reliable.
When editing an existing test, prefer the smallest possible splice. Do not rewrite neighboring steps or change unnecessary fields.

从最小的有意义的“垂直切片”开始：

确认你处于预期的起始 UI 状态（使用 UI 状态或稳定的断言）。仅当你不在目标页面时才添加 NAVIGATE。
仅当稳定性需要或用户明确要求时，才添加页面断言。

然后添加下一个步骤，以此类推。

规则：

对小批量相邻的幂等步骤，优先 预览→预览→预览 → splice。先验证每个步骤，然后一起 splice，避免频繁 splice 同时保持测试可复现。Splice 时，把每个预览响应返回的
```
<CacheId>
```
作为对应步骤 CLI 字符串的
```
--cache-id CACHE_ID
```
参数传递，这样缓存就能复用。
如果用户要求你创建/编辑测试，你必须通过 splice 持久化步骤才算完成任务。你应该在完成一批逻辑步骤的预览后立即 splice。示例：如果你要测试谷歌机票和订票流程，点击搜索前的所有开关和选择就是一个逻辑分组。有疑问时每次 splice 保持约5步，这样可以避免你忘记之前预览过的步骤和返回的缓存 ID。
每次预览或运行后，如果工具返回了 文件路径，在 splice 前仅读取验证预期结果所需的产物；如果你需要结构化的 UI 状态详情，调用
```
momentic_get_session_state
```
。
避免“锦上添花”的断言。如果用户只要求一个最终断言，就只保留那个断言，除非确实需要中间就绪检查来保证测试可靠性。
编辑现有测试时，优先使用最小的 splice。不要重写相邻步骤或修改不需要的字段。

5) Author steps (natural language targeting)

5) 编写步骤（自然语言定位）

For every UI step, write an element description a human would understand:

Good: “the Sign in button below the password field”
Good: “the Search input with placeholder ‘Search products’”
Bad: “button with class …”
Bad: “div:nth-child(3)”

NOTE: Single quotes signal strict queries, so do not use them unless you expect an exact match in the page snapshot and want incredibly strict behavior.

对每个 UI 步骤，编写人类能理解的元素描述：

好的示例：“密码字段下方的登录按钮”
好的示例：“占位符为 ‘搜索商品’ 的搜索输入框”
坏的示例：“class 为 … 的按钮”
坏的示例：“div:nth-child(3)”

注意：单引号代表严格查询，所以除非你期望和页面快照完全匹配，需要极严格的行为，否则不要使用单引号。

6) Use modules for obvious flows

6) 对明显的流程使用模块

If the flow is 4+ steps or obviously reusable:

Call
```
momentic_module_recommend
```
with the desired sub-flow.
Call
```
momentic_module_get
```
on the candidate module.
Preview the module
Add a
```
MODULE
```
step via
```
momentic_test_splice_steps
```
.

如果流程有4步以上或明显可复用：

传入所需的子流程调用
```
momentic_module_recommend
```
。
对候选模块调用
```
momentic_module_get
```
。
预览模块。
通过
```
momentic_test_splice_steps
```
添加
```
MODULE
```
步骤。

7) Avoid double-executing risky steps

7) 避免重复执行风险步骤

If a step is idempotent (tab switches, typing into empty fields, assertions), it’s usually fine to preview, splice, then continue validating forward.
If a step is not idempotent / risky (submit/purchase/delete/send/create), do not immediately re-run it in the same session:
- splice the step
- restart via
```
momentic_run_step
```
  with
```
resetSession: true
```
- run up to right before it (if needed)
- then run through it once to validate the saved test

If something fails:

First: check if it's a timing/state issue (see smart waiting context above); add an explicit readiness wait/assertion when needed.
Second: check if it's an element description issue (use the UI-state snapshot to refine the wording after the UI is ready).
If the page is showing a genuine product failure which blocks your testing (for example, an empty graph because the backend is down, missing data required for the requested assertion, or a localhost request that cannot connect), report it to the user instead of editing around it.
Before restarting: consider recovering via
```
momentic_preview_step
```
, even if you do not intend to add the steps to the test, to get the browser into a state where the test can continue (e.g., dismiss a modal, navigate back). Only restart via
```
momentic_run_step
```
with
```
resetSession: true
```
if recovery is not feasible.
After ~3 attempts, stop and collaborate with the user on alternatives.

如果步骤是 幂等的（切换标签、在空输入框输入、断言），通常可以先预览、splice，然后继续向前验证。
如果步骤 不是幂等的/有风险（提交/购买/删除/发送/创建），不要在同一会话中立即重新运行：
- 先 splice 该步骤
- 通过带
```
resetSession: true
```
  的
```
momentic_run_step
```
  重启
- 运行到该步骤之前（如果需要）
- 然后运行一次该步骤验证保存的测试

如果出现故障：

首先：检查是不是时序/状态问题（参考上文智能等待说明）；需要时添加显式的就绪等待/断言。
其次：检查是不是元素描述问题（UI 就绪后使用 UI 状态快照优化描述）。
如果页面显示真实的产品故障，阻塞了你的测试（比如因为后端宕机导致图表为空、请求的断言缺少必要数据、或 localhost 请求无法连接），向用户报告故障，不要绕过故障编辑。
重启前：考虑通过
```
momentic_preview_step
```
恢复，即使你不打算把这些步骤添加到测试中，让浏览器进入测试可以继续的状态（比如关闭弹窗、返回上一页）。仅当恢复不可行时，才通过带
```
resetSession: true
```
的
```
momentic_run_step
```
重启。
尝试约3次后停止，和用户协作寻找替代方案。

8) Persist and re-validate

8) 持久化和重新验证

Once a small batch of steps is validated, persist them together with

momentic_test_splice_steps

Common splice patterns:

Insert:
```
deleteCount: 0
```
Replace 1:
```
deleteCount: 1
```
Delete N:
```
steps: []
```
,
```
deleteCount: N
```
Add conditional: Splice
```
--step-type CONDITIONAL --assertion-type AI_ASSERTION --assertion "..."
```
(or PAGE_CHECK/JAVASCRIPT with their fields). Then splice again with
```
parentStepIdChain: [conditionalStepId]
```
to add steps inside the conditional. Since preview does not support CONDITIONAL, validate the assertion and child steps individually before splicing.

After splicing:

Read the splice response first to confirm your edit did what you intended before running anything else.
If there are more steps after your splice that you didn't change, run the immediate next step to confirm the flow still works (i.e. verify that your spliced changes still connect with the rest of the test).
Ask the user if they would like you to do an additional check pass to ensure the changes work end-to-end in the broader context of the test.
For risky actions, avoid re-triggering unless required for one-time validation.

验证完小批量步骤后，通过

momentic_test_splice_steps

一起持久化。

常见的 splice 模式：

插入：
```
deleteCount: 0
```
替换1个：
```
deleteCount: 1
```
删除N个：
```
steps: []
```
,
```
deleteCount: N
```
添加条件判断：Splice
```
--step-type CONDITIONAL --assertion-type AI_ASSERTION --assertion "..."
```
（或 PAGE_CHECK/JAVASCRIPT 搭配对应的字段）。然后用
```
parentStepIdChain: [conditionalStepId]
```
再次 splice，在条件判断内部添加步骤。因为预览不支持 CONDITIONAL，所以在 splice 前要单独验证断言和子步骤。

Splice 后：

运行其他操作前先读取 splice 响应，确认你的编辑符合预期。
如果 splice 后还有你没修改的步骤，运行紧邻的下一个步骤确认流程仍然正常（即验证你 splice 的变更仍然能和测试的其他部分衔接）。
询问用户是否需要你额外执行一次检查通行，确保变更在测试的整体上下文中端到端正常工作。
对风险操作，除非需要一次性验证，否则避免重新触发。

9) Organize into setup/main/teardown when it helps

9) 需要时组织成 setup/main/teardown

Setup: Creating users, setting feature flags, loading credentials, etc.
Main: the core user journey + assertions.
Teardown: cleanup of artifacts made from main and setup.

When splicing, set

targetSection

accordingly (

setup

main

teardown

Full execution: run setup → main → teardown. Skip any section with no steps.

How to Edit a Section: Reach the work point with momentic_run_step
through setup, then main, then teardown as necessary, stopping at the step before the one you change (or a stable checkpoint), then preview/splice. Do not skip a section with steps to jump into the section you want to work on.

Setup：创建用户、设置功能开关、加载凭证等。
Main：核心用户流程 + 断言。
Teardown：清理 main 和 setup 产生的产物。

Splice 时，对应设置

targetSection

（

setup

、

main

、

teardown

）。

全量执行：运行 setup → main → teardown。跳过没有步骤的部分。

如何编辑某个部分：根据需要调用 momentic_run_step
依次运行 setup、main、teardown，停在你要修改的步骤之前（或稳定的检查点），然后预览/splice。不要跳过有步骤的部分直接跳到你要编辑的部分。

10) End the session

10) 结束会话

Once the test is built and validated, call
```
momentic_session_terminate
```
to clean up the session.

测试构建和验证完成后，调用
```
momentic_session_terminate
```
清理会话。

Step shapes (what to send)

步骤格式（要发送的内容）

Steps use CLI-style strings:

--step-type <type> [options]

where the step type is:

CLICK

TYPE

NAVIGATE

AI_ASSERTION

MODULE

AI_ACTION_DYNAMIC

WAIT_FOR_URL

, etc.

步骤使用 CLI 风格 字符串：

--step-type <type> [options]

，步骤类型包括：

CLICK

、

TYPE

、

NAVIGATE

、

AI_ASSERTION

、

MODULE

、

AI_ACTION_DYNAMIC

、

WAIT_FOR_URL

等。

Preview a single step (

momentic_preview_step

)

预览单个步骤（

momentic_preview_step

）

The

step

parameter is a single CLI-style string:

json

{
  "sessionId": "SESSION_ID",
  "step": "--step-type NAVIGATE --url \"https://example.com\""
}

More examples:

Click:

--step-type CLICK --description "the Sign in button"

Type:

--step-type TYPE --description "Search input" --value "hello" --press-enter

AI assertion:

--step-type AI_ASSERTION --assertion "the page shows a Sign in button" --timeout 10

step

参数是单个 CLI 风格字符串：

json

{
  "sessionId": "SESSION_ID",
  "step": "--step-type NAVIGATE --url \"https://example.com\""
}

更多示例：

点击：

--step-type CLICK --description "the Sign in button"

输入：

--step-type TYPE --description "Search input" --value "hello" --press-enter

AI 断言：

--step-type AI_ASSERTION --assertion "the page shows a Sign in button" --timeout 10

Persist steps (

momentic_test_splice_steps

)

持久化步骤（

momentic_test_splice_steps

）

The

steps

parameter is an array of CLI-style strings. For every step whose

momentic_preview_step

response returned a cache key /

<CacheId>

, append

--cache-id <CacheId>

to that exact spliced step. If you previewed a step and chose to persist it, carrying over its cache key is required whenever one was returned.

json

{
  "sessionId": "SESSION_ID",
  "startIndex": 0,
  "deleteCount": 0,
  "steps": [
    "--step-type NAVIGATE --url \"https://example.com\"",
    "--step-type AI_ASSERTION --assertion \"the page shows a Sign in button\" --timeout 10 --cache-id UUID_FROM_PREVIEW_CacheId_TAG"
  ],
  "targetSection": "main"
}

steps

参数是 CLI 风格字符串数组。对每个

momentic_preview_step

响应返回了缓存 key /

<CacheId>

的步骤，在对应的 splice 步骤末尾追加

--cache-id <CacheId>

。如果你预览了某个步骤并选择持久化它，只要返回了缓存 key 就必须传递。

json

{
  "sessionId": "SESSION_ID",
  "startIndex": 0,
  "deleteCount": 0,
  "steps": [
    "--step-type NAVIGATE --url \"https://example.com\"",
    "--step-type AI_ASSERTION --assertion \"the page shows a Sign in button\" --timeout 10 --cache-id UUID_FROM_PREVIEW_CacheId_TAG"
  ],
  "targetSection": "main"
}

Module inputs (important)

模块输入（重要）

Module

inputs

values are JavaScript fragments as strings evaluated at runtime.

Use quotes for string literals.
Use
```
env.X
```
to reference environment variables.
If the module has enum constraints, input must exactly match one of the allowed values.

Example:

--step-type MODULE --module-id MODULE_ID --inputs email=env.USER_EMAIL --inputs password=env.USER_PASSWORD --inputs rememberMe=true --inputs planName='Pro' --inputs url="https://example.com"

模块的

inputs

值是字符串格式的 JavaScript 片段，会在运行时求值。

字符串字面量要用引号包裹。
使用
```
env.X
```
引用环境变量。
如果模块有枚举约束，输入必须完全匹配其中一个允许值。

示例：

--step-type MODULE --module-id MODULE_ID --inputs email=env.USER_EMAIL --inputs password=env.USER_PASSWORD --inputs rememberMe=true --inputs planName='Pro' --inputs url="https://example.com"

Module metadata (modifying modules via splice)

模块元数据（通过 splice 修改模块）

You can modify module definitions by replacing a MODULE step with one that includes metadata flags. See the MODULE step schema for full options.

Keys in

defaultParameters

and

parameterEnums

must appear in

parameters

. Changes persist to the

.module.yaml

file. Get user confirmation before editing modules.

Example: to add a new parameter

test2

with enums

["2","3","4","5"]

, replace the module step with:

--step-type MODULE --module-id MODULE_ID --inputs test=1 --parameters test,test2 --parameter-enum test=1,2,3,4 --parameter-enum test2=2,3,4,5

你可以通过替换 MODULE 步骤为包含元数据 flag 的步骤来修改模块定义。完整选项参考 MODULE 步骤 schema。

defaultParameters

和

parameterEnums

中的 key 必须在

parameters

中出现。变更会持久化到

.module.yaml

文件。编辑模块前要获得用户确认。

示例：要新增参数

test2

，枚举值为

["2","3","4","5"]

，将模块步骤替换为：

--step-type MODULE --module-id MODULE_ID --inputs test=1 --parameters test,test2 --parameter-enum test=1,2,3,4 --parameter-enum test2=2,3,4,5

Troubleshooting checklist

故障排查清单

Wrong page / unexpected UI: use the UI-state snapshot from the last run (if it was returned as a file path, read that file); otherwise call
```
momentic_get_session_state
```
and, if you get a path back, read it to inspect the structured UI state.
Element not found:
- Read the latest browser-state (or screenshot) file to see what’s on the page
- If the target element is on the page but was not found, rewrite the step description using visible text, role, and nearby context
- If the expected element is missing or clearly not present/usable, an earlier prerequisite step may have been incorrect or silently failed.
Screenshot doesn't show expected state after a click/action: snapshots are transient. Call
```
momentic_get_session_state
```
again to get a fresh image; the page may have been loading. If the fresh snapshot still doesn't match, retry the step or add a wait.
Flaky timing: prefer assertion-style checks (
```
AI_ASSERTION
```
) over generic
```
WAIT
```
/
```
CHECK
```
steps, and use
```
WAIT_FOR_URL
```
or
```
SWITCH_TAB
```
for page/tab transitions. Actions that would normally finish within ~5 seconds are automatically retried, so avoid explicit waits unless retries and assertions are still insufficient.
Session got “weird” (wrong account, stuck modal, unexpected navigation): restart via
```
momentic_run_step
```
with
```
resetSession: true
```
.
Module won’t run: re-check required params/defaults/enums with
```
momentic_module_get
```
; ensure inputs are valid JS fragments as strings.

页面错误/意外 UI：使用上次运行返回的 UI 状态快照（如果作为文件路径返回，就读取该文件）；否则调用
```
momentic_get_session_state
```
，如果返回了路径，读取它来检查结构化 UI 状态。
找不到元素：
- 读取最新的浏览器状态（或截图）文件查看页面内容
- 如果目标元素在页面上但没被找到，使用可见文本、角色和附近上下文重写步骤描述
- 如果预期元素缺失或明显不可用，可能是之前的前置步骤出错或静默失败了。
点击/操作后截图没有显示预期状态：快照是临时的。重新调用
```
momentic_get_session_state
```
获取新的图片；可能页面还在加载。如果新快照仍然不匹配，重试步骤或添加等待。
不稳定的时序问题：优先用断言类检查（
```
AI_ASSERTION
```
）而非通用
```
WAIT
```
/
```
CHECK
```
步骤，页面/标签跳转使用
```
WAIT_FOR_URL
```
或
```
SWITCH_TAB
```
。通常5秒内能完成的操作会自动重试，所以除非重试和断言仍然不够，否则避免显式等待。
会话“异常”（账号错误、弹窗卡住、意外跳转）：通过带
```
resetSession: true
```
的
```
momentic_run_step
```
重启。
模块无法运行：通过
```
momentic_module_get
```
重新检查必填参数/默认值/枚举；确保输入是合法的字符串格式 JavaScript 片段。

Minimal example: create a smoke test

最小示例：创建冒烟测试

Goal: “Homepage loads and shows the Log in button.”

```
momentic_get_initial_data()
```
— first, always
```
momentic_test_create(name, baseUrl)
```
```
momentic_session_start(testId)
```
```
momentic_preview_step
```
NAVIGATE to
```
baseUrl
```
```
momentic_preview_step
```
AI_ASSERTION “page shows Log in button”
```
momentic_test_splice_steps
```
to persist both steps
```
momentic_run_step
```
from first step to last (read the test file to get step IDs) to validate the saved test
```
momentic_session_terminate
```

目标：“首页加载成功并显示登录按钮。”

```
momentic_get_initial_data()
```
—— 永远优先调用
```
momentic_test_create(name, baseUrl)
```
```
momentic_session_start(testId)
```
```
momentic_preview_step
```
跳转至
```
baseUrl
```
```
momentic_preview_step
```
AI_ASSERTION “页面显示登录按钮”
```
momentic_test_splice_steps
```
持久化两个步骤
```
momentic_run_step
```
从第一步运行到最后一步（读取测试文件获取步骤 ID）验证保存的测试
```
momentic_session_terminate
```

momentic-test

Original

Translation

Momentic test creation and maintenance agent (MCP)

Momentic 测试创建与维护 Agent (MCP)

Scope

适用范围

Momentic context (smart waiting)

Momentic 核心特性（智能等待）

Non-negotiables

不可违反的规则

Required step selection and inputs

步骤选择和输入要求

Inputs you should gather (up front)

你需要提前收集的输入信息

Tool headers (Momentic MCP)

工具说明（Momentic MCP）

Initial context (call first)

初始上下文（优先调用）

Environments and tests

环境和测试

Modules

模块

Sessions (restart options)

会话（重启选项）

Observability

可观测性

Reading file output (required when creating or editing tests)

读取文件输出（创建或编辑测试时必填）

Validate vs persist

验证 vs 持久化

Decision rules (tool choice)

决策规则（工具选择）

Build and edit workflow (preview → splice → validate safely)

构建和编辑工作流（预览 → splice → 安全验证）

0) Get initial data (first call)

0) 获取初始数据（第一个调用）

1) Create the test (or select existing)

1) 创建测试（或选择现有测试）

2) Start a session

2) 启动会话

3) Identify the minimal delta and navigate to the work point

3) 识别最小变更，导航到工作点

4) Build the test incrementally

4) 增量构建测试

5) Author steps (natural language targeting)

5) 编写步骤（自然语言定位）

6) Use modules for obvious flows

6) 对明显的流程使用模块

7) Avoid double-executing risky steps

7) 避免重复执行风险步骤

8) Persist and re-validate

8) 持久化和重新验证

9) Organize into setup/main/teardown when it helps

9) 需要时组织成 setup/main/teardown

10) End the session

10) 结束会话

Step shapes (what to send)

步骤格式（要发送的内容）

Preview a single step (momentic_preview_step)

预览单个步骤（momentic_preview_step）

Persist steps (momentic_test_splice_steps)

持久化步骤（momentic_test_splice_steps）

Module inputs (important)

模块输入（重要）

Module metadata (modifying modules via splice)

模块元数据（通过 splice 修改模块）

Troubleshooting checklist

故障排查清单

Minimal example: create a smoke test

最小示例：创建冒烟测试

Preview a single step (
`momentic_preview_step`
)

预览单个步骤（
`momentic_preview_step`
）

Persist steps (
`momentic_test_splice_steps`
)

持久化步骤（
`momentic_test_splice_steps`
）