Building with AI

Use your coding agent to start Mo sessions against a running app or to create and maintain repository tests. Mo produces a session report. Repository tests are YAML files you review and run in CI.

Test a running app with Mo

Connect your coding agent to the hosted Momentic MCP at https://mcp.momentic.ai for sessions on deployed apps and PRs. Give it your target, scope, sign-in steps, test-data rules, and expected behavior. Use the qa CLI and mo-qa skill only when Mo needs a tunnel to a local or private target. Mo runs in the cloud with either connection and does not require YAML test files.

Create repository tests

For web tests, paste this prompt into your coding agent. It checks your existing setup, installs missing tools, writes one test against your app, and runs it. You provide the app URL, test account, and expected behavior when asked.

Copy the setup prompt

Help me set up Momentic web testing in this project.

## What to do

1. Find an API key. If `MOMENTIC_API_KEY` is set or `npx --yes momentic whoami` prints your user and Org ID, use it. If not, ask me to create a key at https://app.momentic.ai/settings/api-keys and run `export MOMENTIC_API_KEY=<the key I give you>` — if your shell drops env vars between commands, prefix each `npx` command with `MOMENTIC_API_KEY=<the key>` instead.
2. Install the CLI. If `momentic.config.yaml` already exists, skip to step 3. Otherwise run `npx --yes @momentic/wizard@latest -y --platform web` in the project root — it needs a package.json, so run `npm init -y` first if there is none.
   - It installs `momentic`, writes `momentic.config.yaml`, `web/add-to-cart.test.yaml`, and `AGENTS.md`, ensures Chromium is installed, runs the sample test (which produces `test-results/`), and installs the Momentic skills. npm may print audit warnings during install — expected noise, keep going. It may also print 'Opening this run in your browser' or 'skipping editor validation' — both no-ops on headless agents.
   - If it fails `MWZ_ARGS_MISSING_CREDENTIALS` even with a key set, the env var didn't reach that shell — prefix the same command with `MOMENTIC_API_KEY=<key>` and re-run.
   - Pass `--editor-tools` to pick agent integrations — `all`, `none`, or a comma list like `claude-code,cursor` (`skills` forces the skill install).
3. Install the skills and MCP server: the wizard already installed the skills — confirm `.agents/skills/momentic-test/SKILL.md` exists (re-run `npx momentic skills -y --target codex` if not). For MCP, list your tools for names starting with `momentic_` and try calling one — if you cannot list MCP tools, none are configured, or every call fails to initialize, count them absent and do not try to repair a broken server. Then run `npx momentic install-mcp -y` to set it up — 'Error: No coding agent detected' with a non-zero exit means auto-detection missed you, not that your agent is unsupported: if your client is in the supported list (claude-code, cursor, vscode, codex, opencode, windsurf, devin, zed, gemini-cli, antigravity, claude-desktop), re-run with `--client <name>`; if it isn't, skip MCP and drive the Momentic CLI per the skill instead.
4. Confirm the sample test passed and `momentic.config.yaml` + `web/add-to-cart.test.yaml` exist. If you skipped the wizard, confirm `npx --yes momentic whoami` prints my user and Org ID.
5. Ask me which user flow to test first. The scaffolded sample test points at our demo app — don't touch `environments:` in `momentic.config.yaml` or `defaultEnv:` in tests; a new test needs neither of those keys — just set `url:` on it to the app I give you. Create the new test as `web/<flow-slug>.test.yaml` alongside `web/add-to-cart.test.yaml` — leave the sample untouched. Assert only what is visible on screen when the action finishes — multi-step flows split fields across screens, so one assert for everything will fail. Load the `momentic-test` skill and write the test — with the Momentic MCP tools if they are wired, otherwise author the `*.test.yaml` directly per the skill and validate with `npx momentic lint`.
6. Run it with `npx momentic run <path-to-test.yaml> --upload-results` — a single test can take several minutes, allow a long timeout; it prints 'Uploaded to Momentic. <url>' when it finishes, keep that link. Fixing the test and re-running is the loop, not a violation — only a retry with no changes, or hiding a failure, is off-limits. When a run fails, unzip its `.zip` file under `test-results/runs/` — it has screenshots, the DOM trace, and console output, the fastest way to see what went wrong before editing. If it keeps failing after real fixes, report the failure with the uploaded run link and stop, and show me the result.

## Critical rules

- If `MOMENTIC_API_KEY` disappears between shell commands, prefix each `npx` command with it instead of relying on `export`.
- Do not edit `momentic.config.yaml` unless I ask.
- Do not create an API key for me. Ask me for one when you need it.
- Write tests as `*.test.yaml` files. Do not write Playwright or Appium code.
- Do not place real orders, send emails, or touch shared data while testing.
- Run each new test before you tell me it is done.

## When done, point me to

- Building with AI: https://momentic.ai/docs/coding-agents/building-with-ai
- Test structure: https://momentic.ai/docs/core-concepts/file-format
- Run in CI: https://momentic.ai/docs/running-tests/ci/github-actions

For mobile, use the setup prompt in the iOS or Android quickstart. It also asks for your app build before creating a test.

Review the first test

Review the generated YAML diff and confirm the assertions match the behavior you asked for. Open the run URL the agent returns, check that the run passed, and inspect the screenshot at the assertion step. Resolve a failed or blocked run and rerun the test before adding it to CI.

Install the tools yourself

Use these commands to configure an existing project manually. The setup prompt above checks for these tools and installs them when needed.

Install the MCP server

The MCP server gives the agent a live browser or device and tools to browse, edit, run, and triage tests. install-mcp detects the coding agents on your machine and writes the config for each one.

npx momentic install-mcp

npx momentic-mobile install-mcp

Pass --client to pick agents and --scope user to write your user config instead of the project config. See the MCP page for manual setup per client.

Install the skills

Skills are markdown instructions that tell the agent how to use the MCP tools and the Momentic test format. momentic ships the web skills, and momentic-mobile ships the mobile skills.

npx momentic skills

npx momentic-mobile skills

The command writes skill files to your agent’s skills directory and adds a pointer block that lists this CLI’s skills to its instructions file. After an upgrade, the CLI asks once whether to refresh them. See Coding agent skills for the directories and flags.

Skills and the MCP server

The skills explain the test format and authoring workflow. The MCP server lets the agent inspect your app and try steps while it writes a test. If MCP is unavailable, the setup prompt uses the CLI to validate and run YAML files. The mo-qa skill runs Mo sessions through the hosted MCP server, and through the qa CLI for localhost and private targets.

	Skills	MCP server
What it is	`SKILL.md` files the agent reads	A local process the agent calls
What it does	Teaches the test format, the CLI, and the triage steps	Gives the agent a live browser or device and the tools to use
Installs to	`.claude/skills`, `.cursor/skills`, `.agents/skills`, and others	The MCP config of each client, such as `.mcp.json`
Updates	The CLI asks once after an upgrade, or run `skills` again	Every start uses the CLI version in your project
Works offline	Yes	No, it calls the Momentic API
Best for	Test format and the order of tool calls	Preview, run, and repair steps against your app

Invoke a skill by name in your prompt, for example /momentic-test write a test for checkout. See Use the skills for the skill list and more examples.

Use repository instructions

If you use an agent without the skills or MCP server, add these instructions to AGENTS.md, CLAUDE.md, or .cursor/rules. You still need the Momentic CLI to validate and run the tests:

## Momentic

This repo uses Momentic for end-to-end tests. Tests are `*.test.yaml` files and
shared steps are `*.module.yaml` files under the directory named in
`momentic.config.yaml`. Read https://momentic.ai/docs/llms.txt before you change
a test. Run `npx momentic run <file>` to run a test locally. Do not write
Playwright or Selenium code for end-to-end tests in this repo.

Get started

Author

Run

Learn

Platforms

Integrations

Account

Building with AI

Test a running app with Mo

Create repository tests

Review the first test

Install the tools yourself

Skills and the MCP server

Use repository instructions

​Test a running app with Mo

​Create repository tests

​Review the first test

​Install the tools yourself

​Skills and the MCP server

​Use repository instructions

​Related

Test a running app with Mo

Create repository tests

Review the first test

Install the tools yourself

Skills and the MCP server

Use repository instructions

Related