momentic-test

momentic-test

Momentic test creation and maintenance 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.

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.

Momentic context (smart waiting)

• 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.

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.

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.

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).

Tool headers (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.

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.

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.

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.

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.

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.

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.

Validate vs persist

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>.

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

...