Web - Momentic

Prerequisites

All setup methods need:

Setup with coding agent

Open Claude Code, Cursor, Codex, Copilot, or another coding agent in your project directory and paste the prompt below. It uses the wizard’s noninteractive API-key setup, then writes your first test.

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.

## Set up with the wizard

Run the wizard in your terminal:

npx @momentic/wizard@latest


The wizard signs you in through the browser, installs \`momentic\`, and writes
\`momentic.config.yaml\` plus a sample test under \`web/\`. The sample runs against
Momentic’s own demo site: a passing run proves the install works. The wizard
then installs Chromium, runs the sample test, and asks which coding agents to
set up. After the sample passes,
[write and run a test against your app](/content/docs/quickstart/web#test-your-app/index.html). The wizard has already
completed the install, authentication, configuration, and browser steps in the
manual setup.

## Manual setup

1. Install

npm

pnpm

yarn

npm install --save-dev momentic

pnpm add --save-dev momentic

yarn add --dev momentic


The examples below use \`npx\`. With pnpm, use \`pnpm exec momentic\`; with yarn,
   use \`yarn momentic\`.

2. Authenticate

Sign in with your browser:

npx momentic login


The CLI saves the credentials to \`~/.momentic/auth.json\` and uses them when
   \`MOMENTIC_API_KEY\` is not set. In CI, or in a shell without a browser, use an API key instead. Create one in
the [dashboard](https://app.momentic.ai/settings/api-keys) and export it:

export MOMENTIC_API_KEY=your-api-key-here


Check which account and organization the CLI uses:

npx momentic whoami


3. Initialize

npx momentic init


This writes \`momentic.config.yaml\` to your project root. In an interactive
   terminal, it also offers to install the coding agent skills and the MCP server.
   \`init --yes\` accepts the defaults without prompts, so it works in agent shells
   and CI. \`init\` does not create tests. You write your first one in the editor below. For
a sample test, use the wizard above instead.

4. Install browsers

Momentic runs your tests in a headless browser. Install Chromium:

npx momentic install-browsers chromium


5. Write and run your first test

Open the [local editor](/content/docs/local-app/index.html):

npx momentic app


Create a test with your app’s URL as the base URL. Choose one flow with an
   observable outcome. Add an action followed by an
   [assertion](/content/docs/reference/commands/assert/index.html) that checks the resulting page. If you have no app running, use
   \`https://practicetestautomation.com/practice-test-login/\`. Add the action
   \`Log in with username "student" and password "Password123"\`, then the assertion
   \`The login success page is visible\`. Save the test. The editor writes the \.test.yaml file to your project. Run it
   from the editor, then run the saved file from the CLI. Replace \`<test-file>\` with its path relative to your current directory:

npx momentic run "" --upload-results


A passing run prints each test, the totals, and the dashboard link:

Momentic CLI v3.57.0 · Running 1 test · parallel=1

[1/1] ✓ login.test.yaml (17s)

Tests 1 passed (1) Duration 18s

Uploaded to Momentic. https://app.momentic.ai/run-groups/0ef862c5-a0ee-4d0f-9a82-899e134f292c


\`--upload-results\` sends the result artifacts to the dashboard. Without it,
   those artifacts stay on your machine. See [AI data use](/content/docs/account/ai-data-use/index.html)
   for the data sent to Momentic while a test runs. If the run fails, inspect its failed step and screenshot in the dashboard. Check
   the app URL, sign-in state, and assertion before editing, then rerun the test.
   See [Common problems](/content/docs/account/common-problems/index.html) for setup errors.

6. Verify

- Check that the \.test.yaml file exists in your project.
- Open the [dashboard](https://app.momentic.ai/) and check **Runs** for the
  result.
- Confirm the run passed and inspect the screenshot at the assertion step to
  check that it matches the expected state.

7. Connect your coding agent (optional)

Skip this step if \`init\` already did it. The two commands are independent:
   skills are local instruction files. The MCP server is a live process that gives
the agent a browser and Momentic tools.

npx momentic skills npx momentic install-mcp


Both commands detect the coding agents on your machine and ask which ones to
   configure. Pass \`--yes\` to skip the prompt.

## Browsers

Momentic runs web tests on Chromium, Google Chrome, or Chrome for Testing.
Firefox and Safari are not supported. Chromium is the default. To use another
browser, install it, then set the project default in \`momentic.config.yaml\`:

npx momentic install-browsers chrome


momentic.config.yaml

browser: defaultBrowserType: Google Chrome


To override the browser for one run, pass \`--browser chromium\`, \`chrome\`, or
   \`chrome-for-testing\`:

npx momentic run --browser chrome-for-testing


The flag overrides the per-test and project defaults.

## Next steps

[**Find elements** \\ \\ Target buttons and fields by their visible labels](/content/docs/core-concepts/finding-elements/index.html)

[**Building with AI** \\ \\ Skills, the MCP server, and a prompt for your coding agent](/content/docs/coding-agents/building-with-ai/index.html)

[**CI/CD** \\ \\ Run Momentic on every pull request](/content/docs/running-tests/ci/github-actions/index.html)

[**Goal-based testing** \\ \\ Choose actions and assertions for a user flow](/content/docs/best-practices/goal-based-testing/index.html)

Clone [momentic-ai/examples](https://github.com/momentic-ai/examples/tree/main/web) for a full working example.