Skip to main content

Documentation Index

Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

The simplified format makes Momentic YAML easier to review and maintain: no volatile step IDs on disk, shorter command aliases, relative module references, and JSON Schema support in modern editors.
The migration rewrites Momentic test and module files. Back up your repository first, start from a clean Git state, and make sure there are no untracked changes before running it.
Web (momentic) and mobile (momentic-mobile) are separate CLIs with separate migrations. Each command only rewrites files belonging to its own CLI and only flips fileFormat: v2 on its own project’s momentic.config.yaml. If your repo has both web and mobile Momentic projects, run both migrations — one will not touch the other’s files.

​
Before you start

Pick a migration window when teammates are not actively changing Momentic tests. Everyone should move to the simplified format at roughly the same time. If one branch keeps editing legacy YAML while another branch lands the rewrite, later merges can be noisy. Before running the migration: 
git status --short
Commit, stash, or otherwise back up any local changes before continuing. For an extra local backup, create a branch before the migration: 
git branch backup/momentic-v1-format

​
1. Update Momentic

Always invoke the migration through momentic@latest / momentic-mobile@latest so the project config and YAML rewrites are produced by the new CLI’s serializers, not the version currently pinned in your package.json. Running the bare npx momentic upgrade on an older pinned version installs the new CLI but completes the rest of the upgrade with the old one, which means you would need a second invocation to see the new behavior take effect. Check your currently-pinned versions before continuing: 
npx momentic --version          # web
npx momentic-mobile --version   # mobile
If your MCP server is pinned in an editor config, update that command too. The MCP server must run a version that understands simplified format files before agents can create, preview, or edit them. 
npx momentic mcp --config /absolute/path/to/momentic.config.yaml
npx momentic-mobile mcp --config /absolute/path/to/mobile-momentic.config.yaml

​
2. Run the migration

You have two entry points, depending on how much you want to touch:
  • momentic@latest upgrade / momentic-mobile@latest upgrade — overarching. Installs the latest CLI into your project, applies the latest recommended project-config defaults (ai.agentConfig agent versions, ai.useMemory, ai.failureRecovery), sets fileFormat: v2, and rewrites every legacy *.test.yaml / *.module.yaml through the simplified format serializer. Use this when you want one command to bring the whole project current.
  • momentic migrate simplified-format / momentic-mobile migrate simplified-format — file migration only. Rewrites legacy test and module files to the simplified format and flips fileFormat: v2 on the project config, but leaves your CLI version and ai.* defaults alone. Use this when you want a tight, isolated diff with no config-default changes mixed in. Runs against the CLI version already installed in your project; if it is older than the published momentic@latest the command will warn you and point at npx momentic@latest upgrade so you can install the newest serializers.
Both paths share the same simplified format serializer and skip files that already use the simplified format. The first file that fails to migrate aborts the run; the migration is not designed to be resumable, so resolve the surfaced error and rerun the command before continuing.

​
Preview with --dry-run

Both upgrade commands accept --dry-run to preview what would change without writing anything to disk or pushing any snapshots: 
npx momentic@latest upgrade --dry-run
npx momentic-mobile@latest upgrade --dry-run
The output lists how many tests and modules would be migrated, how many already use the simplified format, and which ai.agentConfig entries would be updated.

​
Web

From the web project root, run one of: 
npx momentic@latest upgrade        # everything: CLI version + config + files
npx momentic migrate simplified-format     # just rewrite the YAML files (uses the installed CLI)
A typical web test in the simplified format should start with fileType: momentic/test/v2; a module should start with fileType: momentic/module/v2.

​
Mobile

From the mobile project root, run one of: 
npx momentic-mobile@latest upgrade        # everything: CLI version + config + files
npx momentic-mobile migrate simplified-format     # just rewrite the YAML files (uses the installed CLI)
A typical mobile test in the simplified format should start with fileType: momentic/mobile-test/v2; a mobile module should start with fileType: momentic/mobile-module/v2. If you maintain both a web and a mobile project, run the command in each project root. Neither CLI touches the other’s files, so a single-platform run will silently leave the other platform’s tests in legacy YAML.

​
What to expect

Each migration takes about 1 minute per 50 tests. Existing step caches are preserved across the conversion. Review the diff like application code, then commit all rewritten Momentic YAML files together with the momentic.config.yaml change. Do not split the config change into a separate commit because the project should switch formats as one unit. If your repo already uses the simplified format and the agent config is current, the upgrade command is a clean no-op. It will not rewrite any files.

​
3. Enable editor validation

Momentic publishes static JSON Schemas for simplified format tests and modules. Add them to your editor so YAML mistakes show up while you write. Mobile tests and modules use separate schemas. If your repo has both platforms, point each glob at the correct schema (typically by directory).

​
VS Code

Add this to .vscode/settings.json for a web-only repo: 
{
  "yaml.schemas": {
    "https://static.momentic.ai/momentic-test-v2.schema.json": "*.test.yaml",
    "https://static.momentic.ai/momentic-module-v2.schema.json": "*.module.yaml"
  }
}
For a mobile-only repo, use the mobile schemas: 
{
  "yaml.schemas": {
    "https://static.momentic.ai/momentic-mobile-test-v2.schema.json": "*.test.yaml",
    "https://static.momentic.ai/momentic-mobile-module-v2.schema.json": "*.module.yaml"
  }
}
If the same repo has both web and mobile projects, scope each entry to the project directory so the right schema applies to each file. For example, with web tests under web/ and mobile tests under mobile/: 
{
  "yaml.schemas": {
    "https://static.momentic.ai/momentic-test-v2.schema.json": "web/**/*.test.yaml",
    "https://static.momentic.ai/momentic-module-v2.schema.json": "web/**/*.module.yaml",
    "https://static.momentic.ai/momentic-mobile-test-v2.schema.json": "mobile/**/*.test.yaml",
    "https://static.momentic.ai/momentic-mobile-module-v2.schema.json": "mobile/**/*.module.yaml"
  }
}

​
Cursor

Cursor uses VS Code workspace settings. Commit the same .vscode/settings.json snippet from the VS Code section so everyone opening the repo in Cursor gets the simplified format schemas automatically.

​
Windsurf

Windsurf also reads VS Code-style workspace settings. Commit the same .vscode/settings.json snippet from the VS Code section for shared team validation.

​
Zed

Add this to your Zed settings for a web-only repo: 
{
  "lsp": {
    "yaml-language-server": {
      "settings": {
        "yaml": {
          "schemas": {
            "https://static.momentic.ai/momentic-test-v2.schema.json": [
              "*.test.yaml"
            ],
            "https://static.momentic.ai/momentic-module-v2.schema.json": [
              "*.module.yaml"
            ]
          }
        }
      }
    }
  }
}
For a mobile-only repo, swap in the mobile schema URLs (momentic-mobile-test-v2.schema.json / momentic-mobile-module-v2.schema.json). Mixed repos can list both with directory-scoped globs (web/**/*.test.yaml, mobile/**/*.test.yaml, etc.) the same way as VS Code.

​
4. Use lint for agent edits

Editor schemas catch shape errors early. Momentic also runs simplified format lint automatically before starting the local app and before executing tests, so normal app and test workflows already block invalid YAML. Use the lint command when a coding agent or direct YAML edit changes Momentic test files and you want a quick validation without starting the app or running tests. It checks schema validity, local file references, and entity conflicts. Web: 
npx momentic lint
Mobile: 
npx momentic-mobile lint
Run the matching command once after the migration, then use it as a lightweight guardrail for agent-authored changes. To check one file during review: 
npx momentic lint tests/checkout.test.yaml
npx momentic-mobile lint mobile-tests/login.test.yaml
If coding agents edit tests in your repo, add this to AGENTS.md so they use the same guardrail: 
After changing Momentic `*.test.yaml` or `*.module.yaml` files, run
`npx momentic lint` (web) or `npx momentic-mobile lint` (mobile) before
considering the change complete.

​
5. Author simplified format files

After migration, restart your editor so it launches the updated MCP command when you do need browser-backed authoring. MCP is still the most reliable way to create, preview, and execute steps against a live browser. For lightweight changes, simplified format files are also safe to edit directly. The readable YAML format, static schemas, and editor completions make small updates easier:
  • Prompt coding agents to directly edit *.test.yaml and *.module.yaml for simple changes that do not need a browser.
  • Hand-author tests with YAML tab completions and schema suggestions in your editor.
  • Reference local files from steps. JavaScript steps can point at local JS files, and those JS files can reference other local files with relative paths.
See Test format for the YAML shape and MCP for MCP setup.