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

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, run `npx --yes @momentic/wizard@latest -y --platform web --editor-tools skills` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> Mo is the AI QA engineer, a separate product from the YAML test framework: its npm package and CLI are `qa` (not `mo` — `npx mo` is a different project). Install with `npm install -g qa`, authenticate the same MOMENTIC_API_KEY way, install repo skills with `qa skills -y`, and start a session with `qa start "<brief>"` or `qa <url>`. Docs: https://momentic.ai/docs/mo.md.
> You cannot complete the browser sign-in yourself. Read the API key from the exact MOMENTIC_API_KEY environment variable (similarly named vars like BILT_MOMENTIC_API_KEY are ignored), or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx momentic skills --yes` (or `npx momentic-mobile skills --yes` for mobile).
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. Physical devices are not supported.

# Generate a test from a user story

> Paste a user story into a coding agent with the momentic-spec skill and get a Momentic test file your team can edit and run.

A coding agent with the Momentic MCP server and the
[`momentic-spec` skill](/docs/coding-agents/skills#spec-driven-development) turns a
user story into a `.test.yaml` file before anyone writes product code. The agent
reads the story, maps the acceptance criteria to steps and assertions, and
writes the file into your repository. Once the feature is usable in your app,
the agent prepares the test state and runs the smallest affected set at an
end-to-end checkpoint. Long runs require confirmation. The test is plain YAML,
so you edit it in a pull request like any other file.

## Setup

Install the MCP server and the skills with the CLI. Both commands are described
in [Building with AI](/docs/coding-agents/building-with-ai):

```bash theme={null}
npx momentic install-mcp   # detects the coding agents on your machine
npx momentic skills --yes  # includes momentic-spec
```

The agent needs a `MOMENTIC_API_KEY` in its environment and a reachable app to
test: a local dev server, a preview deploy, or staging.

## In your coding agent

Inside Claude Code, Cursor, Codex, or another agent with the Momentic MCP server
and skills installed, paste the story after the skill name:

```text theme={null}
/momentic-spec As a shopper, I want to apply a promo code at checkout so that
the order total reflects the discount. Acceptance criteria: an invalid code
shows an error, a valid code reduces the total, the discount line names the
code.
```

The agent updates existing coverage or creates the smallest test set that
expresses the changed behavior. For a feature that is not implemented yet, it
marks the specification disabled until its checkpoint is ready:

```yaml apply-promo-code.test.yaml theme={null}
fileType: momentic/test/v2
id: apply-promo-code
disabled: true # enable once the promo-code flow is implemented
url: https://shop.example.com
before:
  - module: ../modules/log-in.module.yaml
steps:
  - Add a "Gravity Blanket" to the cart and open the checkout page
  - type:
      text: NOTACODE
      into: Promo code input
  - click: Apply
  - assert: An error says the promo code is not valid
  - fill:
      text: SAVE10
      into: Promo code input
  - click: Apply
  - assert: The order total is lower than the subtotal
  - assert: A discount line names SAVE10
```

The second entry uses `fill`, which replaces the field's current value instead
of appending to it. See [type](/docs/reference/commands/type).

The agent does not run the test right away. Momentic runs are end-to-end checks
against the real UI, so the skill waits until the feature is implemented and a
user can exercise it in the app. At that point the agent prepares the required
data and account state, enables the affected tests, and proposes the smallest
relevant run. It asks for confirmation before a long run; an explicit request to
run those tests counts as confirmation.

## Edit the generated test

The file lives in your repository, so review it in the same pull request as the
feature:

* Rename the `id` to something your team recognizes, then keep it stable. See
  [File format](/docs/core-concepts/file-format#ids).
* Replace a natural-language step with a preset step when the action is exact.
  `click: Apply` gives the runtime one action to perform, where "click the apply
  button" leaves the path to an AI action. [Steps](/docs/core-concepts/steps) lists
  the preset steps.
* Match each check to the contract in the story. If the story fixes an exact
  total, verify it with an element-content or JavaScript check rather than a
  qualitative AI assertion.
* Move shared setup such as log-in into a [module](/docs/core-concepts/modules) so
  every test generated from a story reuses it.

Once the feature is ready, remove `disabled: true` and run the edited file
locally before you push:

```bash theme={null}
npx momentic run tests/apply-promo-code.test.yaml
```

## What to expect

* Give the agent explicit acceptance criteria. Clarify missing expected behavior
  before treating a generated test as the product contract.
* Both AI actions and preset steps can target elements by description. Keep a
  future specification disabled until the required UI and dependencies exist.
* When the UI changes later, locator auto-healing re-resolves a stale target
  during the run, and failure recovery can clear an obstruction and retry. See
  [AI test maintenance](/docs/reliability/auto-maintenance).

<Note>
  For tests scoped to a code change instead of a story, see [Generate tests from
  a pull request
  diff](/docs/guides/use-cases/generate-tests-from-a-pull-request-diff).
</Note>

## Related

* [Coding agent skills](/docs/coding-agents/skills)
* [Steps](/docs/core-concepts/steps)
* [Common CI setups](/docs/guides/common-setups)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.