Web

Use your coding agent to set up Momentic for a web app and run your first test. You can also use the wizard or follow the manual setup below.

Prerequisites

All setup methods need:

Node.js 22.12.0 or later in the 22.x series, or 24.0.0 or later (node -v)
A package.json in your project. Run npm init -y if you do not have one. Commit it with the lockfile, so CI and local runs use the same Momentic version.
A Momentic account. Sign up to create one.

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.

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

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. The wizard has already completed the install, authentication, configuration, and browser steps in the manual setup.

Manual setup

Install

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.

Authenticate

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 and export it:

export MOMENTIC_API_KEY=your-api-key-here

Check which account and organization the CLI uses:

npx momentic whoami

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.

Install browsers

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

npx momentic install-browsers chromium

Write and run your first test

Open the local editor:

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 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 "<test-file>" --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 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 for setup errors.

Verify

Check that the .test.yaml file exists in your project.
Open the dashboard 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.

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. See Building with AI for what each command does.

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. See browsers for the differences between the three.

Next steps

Find elements

Target buttons and fields by their visible labels

Building with AI

Skills, the MCP server, and a prompt for your coding agent

CI/CD

Run Momentic on every pull request

Goal-based testing

Choose actions and assertions for a user flow

Clone momentic-ai/examples for a full working example.

Get started

Building with AI

Author

Run

Learn

Platforms

Integrations

Account

Prerequisites

Setup with coding agent

Set up with the wizard

Manual setup

Browsers

Next steps

Find elements

Building with AI

CI/CD

Goal-based testing

​Prerequisites

​Setup with coding agent

​Set up with the wizard

​Manual setup

​Browsers

​Next steps

Find elements

Building with AI

CI/CD

Goal-based testing

Prerequisites

Setup with coding agent

Set up with the wizard

Manual setup

Browsers

Next steps