momentic-test

Momentic 模型

Momentic 通过分支版 Playwright、CDP 和自定义 Agent，将结构化自然语言转化为浏览器自动化。交互步骤会解析自然语言目标，断言可以使用多模态模型，而 AI 操作可以完成更广泛的目标。

项目文件和格式

测试使用 *.test.yaml；可复用模块使用 *.module.yaml。测试 ID 位于测试文件的 id 字段中。在假定项目默认设置适用之前，请检查 momentic.config.yaml 和测试级元数据。

fileType: momentic/test/v2 和 fileType: momentic/module/v2 用于标识 v2 文件。缺少 fileType 或其值不同，则视为已弃用的 v1。切勿直接编辑 v1 YAML；请通过 momentic_test_splice_steps 保存更改。

v2 测试通过 defaultEnv 选择环境，--env <name> 可覆盖此设置。不会回退到配置中的唯一环境。基础 URL 依次取自 --url-override、测试自身的 url，然后是 env.BASE_URL，因此，设置了 url 的测试会在每个环境中保留该值。如果没有基础 URL，运行将失败，并显示：“Cannot run test with no base URL and no BASE_URL variable defined in its environment”。

v2 可以使用相对路径引用模块、JavaScript 和身份验证状态。路径相对于包含该引用的 YAML 文件解析。请使用 ./... 或 ../...，绝不要使用绝对路径或 ~。在移动、重命名或删除被引用的文件之前，请搜索其路径并更新或移除所有引用。不要向 v2 YAML 添加内部字段或生成的字段。

选择工作流

除非用户另有要求，否则优先采用以下精简工作流：

• 已知的 v2 更改： 检查相邻模式 -> 编辑 YAML -> 语法或引用不确定时进行 lint -> 验证时重新加载或重启 -> 运行相关范围。这种方式最快，也能生成最清晰、便于审查的差异。
• v1、未知 UI 或交互式验证： 启动 MCP 会话 -> 运行任何前置条件 -> 预览一个逻辑检查点 -> splice -> 验证已保存的范围 -> 终止。这能让每次编辑都以实时应用为依据，避免反复运行整个测试。
• 新测试： 使用 momentic_test_create 创建 -> 在一次 YAML 编辑中编写已知的 v2 序列，或在需要探索时通过 MCP 逐步操作。momentic_session_start 只会打开现有测试。

交互时默认使用 MCP：它会返回结构化结果、截图、工件、步骤引用和可轮询的执行状态。预览和运行工具默认等待 30 秒，然后在任务仍继续时返回 stepRunnerId。大多数调用都不要设置 timeoutSeconds，尤其是单个预设步骤。只有当编码 Agent 的工具调用超时时间更短时，才将其设为低于 30 秒。只有在工具调用超时时间更长、且需要等待更久时，才调高该值；请使用 momentic_poll_runner 轮询返回的句柄。

轮询有独立的 timeoutSeconds（默认值为 0，最大值为 30）。请传入返回的 stepRunnerId，并在编码 Agent 的工具调用超时时间内设置非零等待时间，而不是反复进行无等待轮询。

编辑之前

确认测试目标、用户可见的成功标准、起始环境、身份验证和环境要求。任何可能提交、购买、删除、发送、创建或造成其他非幂等副作用的步骤或 AI Action，在预览或运行之前都必须先征求同意。如果获得批准，最多执行一次。编辑共享模块、重启长流程或运行耗时较长的完整测试之前，也必须先征求同意。

编写规则

• 优先使用自然语言描述目标。只有当 AI 无法看到目标，或用户要求精确到选择器的定位时，才使用选择器或坐标。
• 浏览器操作和检查优先使用 Momentic 原生步骤。例外情况请参阅 测试执行行为 下的 JavaScript。
• 不要添加初始导航；会话从测试的基础 URL 开始。
• 断言应精简并以用户需求为导向。导航或状态发生实质性变化后，应先验证约定，再执行依赖该状态的操作。
• URL 约定优先使用 waitForUrl；稳定文本或结构优先使用页面或元素检查；语义层面的视觉状态优先使用 AI 断言。
• 新测试优先使用 AI Action V3。需要单独控制检查点时使用细粒度步骤；需要快速连续操作时，请参阅 有时效性的交互。
• 除非正确性要求，否则不要添加可选字段或带默认值的字段。
• 修改范围应尽量小。保留无关的值、注释、顺序和步骤风格。不要通过弱化测试来掩盖应用或服务故障。
• 除非测试意图要求修改，否则保留现有的 before / steps / after 结构。

AI Action V3

AI Action V3 接收自然语言目标，并据此确定浏览器步骤。

• 默认缓存： 保存并重放成功的流程，并自动修复重放失败的步骤。适用于可重复的流程。
• 不缓存： 每次都重新运行 Agent。在 v2 中设置 cache: false，或搭配 AI_ACTION_DYNAMIC 使用 --disable-cache。聊天、Agent 式工作流、探索性测试，以及其他动态或非确定性行为，优先使用此方式。

除非用户指定路由，否则应将“确保可以执行 X”视为基于目标的测试。当需要单独控制控件、中间断言、确定性重放或有风险的副作用时，使用细粒度步骤。除非用户要求更改策略，否则已有的细粒度测试应继续保持细粒度。

有时效性的交互

对于连续发送消息或在启动过程中进行中断等快速连续操作，优先使用一个聚焦的 AI Action，明确操作顺序，并指示操作之间不要等待。单独的目标定位步骤可能会超出所测试的时间窗口。将前置设置和稳定的最终检查放在该操作之外；对于瞬时 UI 状态，应结合基于视频的运行断言。

AI Action 无法保证时序。检查操作时间戳和记录的证据，以确认实际执行了预期状态。最终结果成功，或在未观察瞬时状态的情况下通过推断断言，都不能证明测试覆盖了该状态。如果精确的竞争窗口很重要且无法可靠复现，应使用确定性测试或受控测试装置，而不要声称通过最终状态已覆盖该场景。

测试执行行为

缓存和记忆

Momentic 会缓存已解析的选择器、文本、坐标和其他元数据，因此大多数运行都无需重复调用 AI。AI 断言也可能复用先前结果的记忆。过期的缓存或记忆可能导致快速匹配到错误元素，或重复给出临界判定。

缓存按 Git 元数据（包括分支）划分范围。受保护分支可以读取缓存，但不会写入缓存，除非使用 --save-cache 或设置 CI。

• 当细粒度步骤的意图发生变化时，应修改其描述。通常不要在定位器步骤中添加 DANGEROUS_FORCE_DYNAMIC 或 --disable-cache；内置的缓存验证会处理内容变化。禁用缓存不能替代澄清含糊的描述，也不能解决时序或竞争条件。只有在有人要求时，或缓存的定位器已导致失败且其他修复均无效时，才添加这些选项。
• 将成功预览的 CacheId 带入要插入的确切步骤。
• 如果旧记忆已不符合断言的预期条件，应重新表述断言。
• 有关 AI Action V3 的缓存行为，请参阅上文的 AI Action V3。

就绪状态和计时

智能等待会在定位步骤前运行，默认等待五秒。在此时间范围内，不要添加休眠。对于需要更长等待时间或语义就绪状态的情况，请等待 URL，或使用页面、元素或 AI 检查来描述所需的正向状态。检查会持续重试，直到超时；应延长超时时间，而不是使用 JavaScript 轮询 UI。有关项目范围的计时设置，请参阅浏览器配置。

测试上下文

每次运行都有一个测试范围的 env，会在各步骤和模块之间持久保存。

• 在 v2 中，使用 saveAs 保存返回值；在 MCP 步骤字符串中，使用 --env-key。需要保存多个值时，在 JavaScript 中使用 setVariable(name, value)。
• 在 JavaScript 和模块输入表达式中使用 env.NAME。在字符串字段中使用 {{ env.NAME }}，但不要在 JavaScript 源代码中使用。
• 模块输入是以字符串形式存储的 JavaScript 片段。将字面字符串加引号，并使用 env.X 表示变量。

JavaScript

对于浏览器操作，请使用原生点击、输入、悬停、等待和检查步骤。它们会保留 Momentic 的智能等待、缓存、跟踪记录和重试功能。不要使用浏览器 JavaScript 来点击或输入；如果检查可以持续重试直到超时，也不要轮询 UI。

对于测试设置、数据生成、API、数据库、OTP/电子邮件/SMS 和 Momentic 辅助函数，请使用 Node JavaScript。当没有原生步骤可以表达所需操作时，使用 Browser JavaScript 访问 window、document、客户端状态或注入页面脚本。一次性代码应保持简短；编写可复用的 v2 脚本时，请遵循项目附近的惯例。有关运行时 API 和超时详情，请参阅 JavaScript 指南。

Playwright evaluate 回调在浏览器中运行，无法捕获 Node 值。请将值作为回调参数传入，或使用 customWindow._momentic。

使用 v2 YAML

v2 可供人工编辑。测试使用 before、steps 和 after；模块使用 steps。每个步骤都有一个命令键，选项嵌套在其下。时长以毫秒为单位，步骤 ID 不会存储在 YAML 中。

进行最小限度的编辑，并与附近的语法保持一致。如果语法不明确，在 Momentic 单体仓库中工作时，请查阅生成的 v2 格式参考 infra/scripts/v2-json-schema/build/v2-format-reference.md；在已安装的技能中工作时，请查阅 https://static.momentic.ai/v2-format-reference.md。如果架构或文件引用存在风险，请运行 npx momentic lint；momentic app 和 momentic run 也会自动执行 lint。

修改磁盘文件后，如果工具可用，请重新加载当前 MCP 测试；否则，请终止并重启会话。momentic_test_get 会读取已持久化的状态，但除非其说明中另有说明，否则不会刷新活动会话。

MCP 浏览器工作流

请使用会话启动时返回的工具说明和步骤编写指南，了解当前参数和步骤语法。不要在此技能中重复这些参考材料。

启动并获取上下文

不要将上下文工具调用作为会话启动时的例行步骤。按需使用，并遵循其说明，尤其是提供筛选条件或返回大量项目数据时。

• 如果已知测试 ID，请单独启动 momentic_session_start。其测试内容会提供当前步骤和可运行 ID。
• 仅当项目路径、测试、模块或环境尚不明确时，才使用 momentic_get_artifacts 来发现它们。避免重复刷新。
• 启动前使用 momentic_test_get 检查已持久化的状态，或读取其他测试。优先使用活动会话，并在之后拼接响应。
• 仅当某个步骤需要尚未掌握的环境数据时，才使用经过筛选的 momentic_get_environment_variables。
• 仅在评估复用方案时使用 momentic_module_recommend -> momentic_module_get；推荐操作会调用 AI，启动会话并不需要它。

V2 YAML 没有可运行步骤 ID。请使用会话启动或后续拼接响应返回的 ID。

每个会话只能执行一个浏览器操作。不要对同一会话并发执行预览、运行、状态检查或拼接操作。

预览 -> 拼接 -> 验证

1. 对于测试中途的工作，先通过前置步骤一次，并继续使用同一会话。这样可以避免基于错误的页面状态编写步骤。
2. 按逻辑检查点向前预览，例如登录完成、表单就绪或提交完成。检查点可复用浏览器状态，并使持久化调用更便于审查。
3. 对相邻步骤使用 momentic_preview_steps。它支持与 momentic_preview_step 相同的预设、AI 操作和模块步骤。
4. 将预览和运行截图视为主要结果。只有当截图或定位器结果不足以判断时，才请求浏览器状态；如果页面可能仍在加载稳定，再请求一次。
5. 拼接成功的检查点。每个返回的 CacheId 仅附加到对应的步骤；没有缓存的步骤也很正常。立即读取拼接响应，获取当前步骤引用。
6. 运行下一个依赖它的已保存步骤或范围。如果任何预览或运行返回了 stepRunnerId，请轮询该任务，而不是启动另一个浏览器操作。
7. 完成前，在安全的情况下，运行覆盖前置条件、已更改步骤和下一个依赖契约的最小已保存范围。如果累积状态可能掩盖失败，请先重置。
8. 完成后终止会话。

将明显且低风险的字段批量处理。对不确定的定位器逐个预览。对于提交、购买、删除、发送或其他非幂等操作，请先预览设置并拼接检查点，然后最多运行一次已批准的已保存操作。

常规编辑之间不要重置。对于嵌套步骤，请使用活动会话或拼接响应返回的父级链。

模块

对于大约包含 4 个或更多可复用步骤的逻辑流程，请检查 momentic_module_recommend -> momentic_module_get -> 复用或内联。复用可减少重复设置，并让测试聚焦于其独特契约。

模块不能包含其他模块。更改共享模块前请先询问。遵循模块声明的参数、默认值和枚举值；模块输入是 JavaScript 片段，而不是 {{ }} 模板。

故障排查

页面状态与时序

• 页面错误或过期：检查最新截图或会话状态；如果页面仍在稳定过程中，可再尝试捕获一次状态。
• 某个检查点的就绪速度较慢：添加范围最窄的页面、元素或 AI 检查，或增加现有检查的超时时间。检查已具备重试机制；不要使用 JavaScript 轮询。
• 整个项目的定位普遍较慢：考虑增加 browser.smartWaitingTimeoutMs。不要用它来掩盖单个缓慢断言。
• 长时间运行的任务或上传：使用适当的超时时间检查稳定的成功结果，不要使用 sleep。
• 会话状态偏移：使用 resetSession: true 重新运行所需的已保存范围。

浏览器和主机资源压力

发生浏览器、CDP、页面加载、截图或快照超时时，重试或重置一次。如果问题仍然存在，或影响多个浏览器工具，请停止修改测试。不要通过等待、降低断言要求、设置缓存标志或重复调用浏览器来掩盖资源压力。

相关信号包括页面无响应、文档树或页面执行超时、HTML 快照为空、浏览器或检查器崩溃，以及 data-momentic-id 超时。页面加载超时本身也可能是应用或网络问题。

使用可用的主机工具检查 CPU、内存和占用率最高的进程。检查浏览器、Momentic、应用服务器、编译器／打包器、数据库和无关工作负载。对于已完成的运行，请结合 attempts/<n>/assets/resource-usage.ndjson（如果存在）进行分析。

报告错误、步骤、URL、重试结果、资源压力、占用资源最多的对象以及有依据的原因。如果证据无法区分问题来自主机、应用、服务还是 Momentic，请如实说明。

定位和断言

• 找不到元素：调试前置条件。如果元素可见但未找到，请根据可见文本、角色和附近上下文，使用稳定的描述。
• 快速匹配到错误元素：考虑缓存是否过时，然后修正描述。
• 在普通模式下，元素隐藏、禁用、已分离、被遮挡、正在移动或位于视口外等错误，源自 Playwright 的可操作性检查，并由 Momentic 呈现；它们并非 Momentic 定位器 AI 的问题。请修复页面状态或前置条件。仅当预期行为本身需要绕过可操作性检查时才使用 force。
• 对于有意不满足 Playwright 可操作性检查的控件（例如某些富文本编辑器），browser.visualActions: true 会改用基于坐标的操作。它能绕过这些检查，但也会失去相应的稳定性保障。请参阅视觉操作。
• 仅当必须出现完全一致的文本时才使用带引号的文本；否则请描述其含义。断言应明确指出区域、对象、数量或状态。
• 如果条件是视觉性的，且完全位于当前视口内，请使用 assertVisually，例如日历网格中位于 11:30–12:00 时段的事件块，或视频画面或画布绘图中的细节。调用前如有必要，请将目标滚动到视口内；否则请使用 assert。
• 使用步骤断言来断言稳定的最终状态。对于短暂显示的提示，或随时间变化的比较，请使用基于视频的运行断言。

格式和数据

• V2 加载失败：对文件进行 lint 检查，并检查相对引用。
• 模块失败：重新检查参数、默认值、枚举和输入表达式。
• 环境变量值缺失：确认生成该值的保存操作，并检查消费者处使用的是 env.X 还是 {{ env.X }}。
• JavaScript 失败：确认使用的是 Node 还是 Browser 上下文。

同一故障尝试约 3 次后，请停止并询问用户如何处理。