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

# Modules

> Extract reusable sequences of steps, parameterize them, and share across tests.

A module is a named sequence of steps you can call from any test. Use modules to
share login flows, setup fixtures, or repeated user journeys.

<Note>Modules can't call other modules.</Note>

<Warning>Editing a module updates every test that uses it.</Warning>

## Example

A module is a YAML file that ends in `.module.yaml`. Call it from any test with
a **Module** step.

```yaml log-in.module.yaml theme={null}
fileType: momentic/module/v2
id: log-in
name: Log in
parameters:
  - name: USERNAME
    default:
      string: test@example.com
  - name: PASSWORD
steps:
  - type:
      text: "{{ env.USERNAME }}"
      into: Username input
  - type:
      text: "{{ env.PASSWORD }}"
      into: Password input
  - click: Log in
```

```yaml checkout.test.yaml theme={null}
fileType: momentic/test/v2
id: checkout-flow
url: https://saucedemo.com
steps:
  - module:
      path: ../modules/log-in.module.yaml
      inputs:
        USERNAME:
          string: test@example.com
        PASSWORD: env.TEST_PASSWORD
  - act: Add a "Gravity Blanket" to the cart and check out
  - assert: The order confirmation page is shown
```

## Parameters

Parameters let a single module handle different inputs. Declare them under
`parameters` on the module, then reference them inside steps via
`{{ env.PARAM_NAME }}` (or `env.PARAM_NAME` in **JavaScript** steps).

```yaml log-in.module.yaml theme={null}
fileType: momentic/module/v2
id: log-in
name: Log in
parameters:
  - name: USERNAME
    default:
      string: test@example.com # used when an invocation omits this input
  - name: ROLE
    enum: [admin, member] # restrict the input to a fixed set of values
  - name: PASSWORD # no default - every invocation must supply it
steps:
  - type:
      text: "{{ env.USERNAME }}"
      into: Email input
```

### Defaults vs instance inputs

Each parameter can have a **default value** on the module and an **instance
input** on a specific **Module** step. Instance inputs take precedence. Each
input value is one of:

* A shorthand string - evaluated as a **JavaScript expression** (e.g.
  `env.PARAM`, `someFn() + 1`).
* `{ string: ... }` - a literal string. Use this for fixed text values.
* `{ javascript: ... }` - the script's return value is bound to the parameter.
  Equivalent to the shorthand but supports multi-line scripts.

```yaml checkout.test.yaml theme={null}
steps:
  - module:
      path: ../modules/log-in.module.yaml
      inputs:
        USERNAME:
          string: alice@example.com # literal, overrides default
        PASSWORD: env.TEST_PASSWORD # JS shorthand reads from the env map
```

## Control flow

### Default retries

Set **Default retries** under the module's **Control flow** tab to retry every
invocation of the module a fixed number of times on failure. Invocations that
set their own `retries` value override the module default.

Use this for flaky setup modules (e.g. a login module that sometimes fails on
slow environments) instead of setting `retries` on every invocation.

## Caching

Modules are uncached by default and always execute. Enable caching to skip a
module when its cache key and inputs are unchanged. The module's return value
(the return value of its last step) is also cached.

Configure caching with module-level fields:

```yaml log-in.module.yaml theme={null}
fileType: momentic/module/v2
id: log-in
name: Log in
defaultCacheAllInvocations: true # cache every invocation of this module
defaultCacheKey: admin-user # invocations sharing a key reuse the same cache entry
defaultCacheTtl: 3600000 # expire the cache entry after 1 hour (milliseconds)
steps:
  -  # ...
```

Override the key or expiry on a single **Module** step with `cacheConfig`:

```yaml checkout.test.yaml theme={null}
steps:
  - module:
      path: ../modules/log-in.module.yaml
      cacheConfig:
        cacheKey: member-user
        cacheExpiryMs: 600000
```

### Authentication modules

Set `autoAuth: true` (the editor's **Treat as auth module**) to save and restore
browser auth state between runs. Momentic persists:

* [Cookies](https://playwright.dev/docs/api/class-browsercontext#browser-context-cookies)
* `localStorage`
* [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)

```yaml log-in.module.yaml theme={null}
fileType: momentic/module/v2
id: log-in
name: Log in
autoAuth: true
defaultCacheAllInvocations: true
defaultCacheKey: admin-user
defaultCacheTtl: 3600000
steps:
  -  # ... login steps, ending with a check of the authenticated state
```

<Info>
  Set the cache expiry shorter than your session's expiry. Add a final step that
  verifies the authenticated state so the cache only saves when login succeeded.
</Info>

See [Authentication strategies](/guides/auth/overview) and
[Cache authenticated sessions](/guides/auth/cached-session) for the full
workflow.