> ## 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` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> You cannot complete the browser sign-in yourself. Read the API key from the MOMENTIC_API_KEY environment variable, 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 proposes a run and executes it after you confirm. 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):

```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 writes one test per acceptance criterion that changes what the user
sees, or one test that covers the story when the criteria form a single journey.
For the story above it produces a file like this:

```yaml apply-promo-code.test.yaml theme={null}
fileType: momentic/test/v2
id: apply-promo-code
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` so the field's value is replaced instead of
appended to. 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 for a durable checkpoint: the promo code
feature is implemented and a user can exercise it in the app. At that point the
agent names the test it proposes to run, asks you to confirm, and runs it once
you agree. If you run it before the feature exists, the assertions fail.

## 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.
* Tighten each `assert` to the contract in the story. "The order total is lower"
  is a weaker check than "The order total is \$89.10" when the story fixes the
  discount.
* Move shared setup such as log-in into a [module](/docs/core-concepts/modules) so
  every test generated from a story reuses it.

Run the edited file locally before you push:

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

## What to expect

* The agent covers the acceptance criteria you give it. A story with no criteria
  produces a test that asserts only the happy path.
* Steps that name UI elements the app does not have yet still run: the AI action
  step finds the element by description once it exists. Preset steps such as
  `click` also target by description.
* 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)