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

# Goal-based testing

> Build resilient tests around user outcomes, combining AI actions with precise preset steps and assertions.

Goal-based tests describe the product outcome a user must reach without fixing
the test to one sequence of interactions. They work best when the outcome is
stable but the path can change.

An AI action is how Momentic executes a goal-based step. It divides the goal
into sub-goals, observes the current page or screen, executes the next steps,
and evaluates the result. It repeats this process until the overall goal is
complete. If a product bug or fatal execution error prevents the next sub-goal,
the action stops and reports the blocker. It also stops if it exhausts its
execution budget.

Use a string for a straightforward goal. Use `act:` when the action needs a
precondition, postcondition, cache control, or other step options.

<Tabs>
  <Tab title="Shorthand">
    ```yaml checkout.test.yaml theme={null}
    fileType: momentic/test/v2
    id: golden-cloud-compass
    steps:
      - Add a "Gravity Blanket" to the cart and complete checkout as a guest
    ```
  </Tab>

  <Tab title="Explicit options">
    ```yaml checkout.test.yaml theme={null}
    fileType: momentic/test/v2
    id: golden-cloud-compass
    steps:
      - act:
          goal: Add a "Gravity Blanket" to the cart and complete checkout as a guest
          precondition: The storefront is open and the cart is empty
          postcondition:
            An order confirmation shows the purchased item and order number
    ```
  </Tab>
</Tabs>

## Write bounded goals

A strong goal has one user intent, enough context to remove ambiguity, and a
clear stopping point.

* Prefer `Add the cheapest in-stock blanket to the cart and open checkout`.
* Avoid `Browse the store and make sure everything works`.
* Include data constraints that matter, such as using a fresh email or choosing
  an in-stock item.
* Split a long test by user outcome instead of asking one goal to cover an
  entire product journey.

If the flow must repeat, state a finite bound or use a
[while loop](/docs/core-concepts/steps#while-loops) with `maxIterations`.

<span id="use-postconditions-to-define-success" />

## Postconditions

The goal tells the AI action what to accomplish. A `postcondition` defines the
product state that must be true before the action can pass. Add one to every
meaningful or state-changing AI action:

```yaml theme={null}
steps:
  - act:
      goal: Delete the current draft report
      postcondition: The draft is absent from the reports table
```

Describe a durable outcome, not a brief animation, spinner, or toast. Use a
standalone assertion or element check when the checkpoint is independent of the
AI action. For transient web UI, use a
[run assertion](/docs/core-concepts/writing-assertions#run-assertions).

<span id="cache-successful-paths" />

## Caching

After a successful run, Momentic caches the steps generated by the AI action.
Later runs replay that path instead of planning it again, making repeated runs
faster and more consistent. If the cached path no longer works, failure recovery
clears the cache so the action can plan a new path.

Set `cache: false` when the route should be planned again on every run:

```yaml theme={null}
steps:
  - act:
      goal: Open one of the currently featured products
      cache: false
```

The shorthand and explicit forms use the same cache behavior. See
[Step caching](/docs/reliability/step-cache) for cache invalidation, branching, and
failure recovery.

## Choose the right level of control

Use an AI action when the outcome matters more than the exact interactions. Use
a preset step when the interaction itself is part of the behavior under test.

| Use                           | When                                                     |
| ----------------------------- | -------------------------------------------------------- |
| An AI action goal             | The outcome is stable but the exact sequence can vary    |
| An AI action postcondition    | The action must prove a durable outcome before it passes |
| A preset step such as `click` | The exact interaction is important or already known      |
| An assertion or element check | A separate checkpoint must verify product state          |

These forms can coexist in one test. For example, an AI action can navigate a
checkout flow while a preset step verifies a specific consent control and the
postcondition verifies the final order.

<span id="customize-ai-actions-with-the-knowledge-base" />

## Knowledge base integration

Use the [Knowledge base](/docs/ai/knowledge-base) to give every AI action consistent
product context:

* Add **Terminology** entries for product-specific names, internal aliases, and
  words that have a special meaning in your interface.
* Add an **Agent rule** for the AI action agent when it should follow an
  organization-wide interaction convention or expected product behavior.
* Add a **Flow** when a reusable journey has a known sequence and success state.

AI actions retrieve relevant approved knowledge before they start and can look
up more context while they run. When an action discovers a reusable term or flow
that is not already captured, it can suggest a Knowledge base entry. The
suggestion stays inactive until someone reviews and approves it, so future AI
actions learn from shared product knowledge without silently changing global
behavior.

## Related

* [AI action reference](/docs/reference/commands/act)
* [Step caching](/docs/reliability/step-cache)
* [Writing assertions](/docs/core-concepts/writing-assertions)
* [Knowledge base](/docs/ai/knowledge-base)