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

# Browser configuration

> Reference for the `browser` block in `momentic.config.yaml`. Controls defaults for all browser-based tests in a project.

These defaults apply to every browser-based test in the project. Individual
tests can override any of these values.

```yaml momentic.config.yaml theme={null}
browser:
  defaultBrowserType: Chromium
  smartWaitingTimeoutMs: 5000
  pageLoadTimeoutMs: 8000
  slowMoMs: 250
```

## Identity

<span id="browser-defaultbrowsertype" />

<ParamField path="browser.defaultBrowserType" type="&#x22;Chromium&#x22; | &#x22;Google Chrome&#x22; | &#x22;Chrome for Testing&#x22;">
  Default browser used by all tests in the project.

  ```yaml momentic.config.yaml theme={null}
  browser:
    defaultBrowserType: Chromium
  ```

  * `Chromium`: lightweight, open-source browser with a basic feature set. The
    same engine Playwright and Cypress use.
  * `Google Chrome`: full Google Chrome build with PDF rendering and WebGL.
  * `Chrome for Testing`: a versioned Chrome build for test automation, without
    auto-update.
</ParamField>

<ParamField path="browser.userAgent" type="string | null">
  User agent string sent on every request. Defaults to the current Chrome
  desktop UA. Set to `null` to disable the default override and use the
  browser's native user agent (which then matches the runner's OS).

  ```yaml momentic.config.yaml theme={null}
  browser:
    userAgent:
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML,
      like Gecko) Chrome/138.0.0.0 Safari/537.36"
  ```

  ```yaml momentic.config.yaml theme={null}
  browser:
    userAgent: null # use the browser's native user agent
  ```
</ParamField>

<span id="browser-timezone" />

<ParamField path="browser.timezone" type="string">
  Default
  [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
  Defaults to `America/Los_Angeles`. Per-test settings override this.

  ```yaml momentic.config.yaml theme={null}
  browser:
    timezone: America/New_York
  ```
</ParamField>

<span id="browser-usehosttimezone" />

<ParamField path="browser.useHostTimezone" type="boolean">
  Use the host machine's timezone instead. When `true`, all `timezone` settings
  (project- and test-level) are ignored. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    useHostTimezone: true
  ```
</ParamField>

## Timeouts

<ParamField path="browser.pageLoadTimeoutMs" type="number">
  Maximum wait time for a page to load, in milliseconds. Applies to new tabs
  and navigation events. Default: `8000`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    pageLoadTimeoutMs: 20000
  ```
</ParamField>

<ParamField path="browser.ignorePageLoadTimeouts" type="boolean">
  Continue after page-load timeouts instead of failing the test. Default:
  `false`.

  Enable this for applications that render usable content even though the browser
  does not report that the page finished loading. Momentic waits up to
  `pageLoadTimeoutMs` for each new document. If that wait times out, later
  page-state collections for the same document skip it. A new document or tab
  receives its own full wait.

  {" "}

  <Warning>
    This setting does not shorten the initial timeout or mark the page as fully
    loaded. Momentic may collect page state while the page is still loading.
  </Warning>

  ```yaml momentic.config.yaml theme={null}
  browser:
    ignorePageLoadTimeouts: true
  ```
</ParamField>

<span id="browser-smartwaitingtimeoutms" />

<ParamField path="browser.smartWaitingTimeoutMs" type="number">
  Maximum wait time for [smart waiting](/docs/reliability/auto-maintenance#locator-auto-healing)
  between steps, in milliseconds. Default: `5000`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    smartWaitingTimeoutMs: 10000
  ```
</ParamField>

<ParamField path="browser.elementCheckTimeoutSeconds" type="number">
  Default maximum wait time for [element check](/docs/reference/commands/check-element)
  assertions to become true, in seconds. Element check steps with an explicit
  timeout are unaffected. Default: `5`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    elementCheckTimeoutSeconds: 10
  ```
</ParamField>

<ParamField path="browser.typeDelayMs" type="number">
  Default delay between keystrokes for type steps, in milliseconds. Type steps
  with an explicit delay are unaffected. Increase this if your app needs more
  time to react to each keystroke. Default: `25`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    typeDelayMs: 60
  ```
</ParamField>

<ParamField path="browser.pressDelayMs" type="number">
  How long each key stays held between keydown and keyup for press steps, in
  milliseconds. Press steps with an explicit delay are unaffected. Default: `0`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    pressDelayMs: 60
  ```
</ParamField>

## Execution timing

<ParamField path="browser.slowMoMs" type="number">
  Wait between steps in a step list, in milliseconds. The first executed step
  has no delay, including when earlier steps are skipped. A single-step list
  has no delay. Values range from `0` to `10000`. Default: `0`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    slowMoMs: 250
  ```

  Environment browser settings override this value, and the test-level `slowMoMs`
  setting overrides both. For a single run, pass
  [`--slow-mo <milliseconds>`](/docs/cli-reference/momentic/commands/run#slow-mo-milliseconds)
  to override all three without changing your configuration files.
</ParamField>

<span id="headers-storage-and-identity" />

## Headers, storage, and permissions

### Extra headers

<ParamField path="browser.extraHeaders" type="Record<string, string>">
  Set `browser.extraHeaders` to add HTTP headers to browser requests. Headers
  apply to every requested host, including third-party hosts.

  Load credentials from
  [environment variables](/docs/configuration/environment-variables) instead of writing
  tokens into your config:

  ```yaml momentic.config.yaml theme={null}
  name: browser-header-tests
  browser:
    extraHeaders:
      Authorization: "Bearer {{ env.AUTH_TOKEN }}"
      X-Test-Run: momentic
  environments:
    - name: staging
      baseUrl: https://staging.example.com
      inheritFromShell: true
  ```

  Set `AUTH_TOKEN` in your shell or CI secrets, then select this environment with
  `npx momentic run --env staging`. See
  [Secrets](/docs/configuration/environments#secrets) for `.env` files and other
  variable-loading options.
</ParamField>

<ParamField path="browser.initialLocalStorage" type="Record<origin, Record<key, value>>">
  Local storage values to seed per origin before the test starts. Origin must
  include scheme, host, and (if non-default) port. Useful for feature flags or
  cached auth.

  ```yaml momentic.config.yaml theme={null}
  browser:
    initialLocalStorage:
      https://momentic.ai:
        momenticTestKey1: momenticTestValue1
        momenticTestKey2: momenticTestValue2
  ```
</ParamField>

<span id="browser-localchromeextensionpaths" />

<ParamField path="browser.localChromeExtensionPaths" type="string[]">
  Paths to unpacked Chrome extension directories. Each directory must contain
  `manifest.json`. Momentic loads the extensions before the test starts.

  Use `Chromium` with `remoteBrowser: false`. Hosted browsers and the cloud
  dashboard don't support extensions. Google Chrome 137 and later no longer
  support this extension-loading mechanism, and Momentic doesn't support loading
  extensions in `Chrome for Testing`.

  Relative paths resolve from the directory where you launch Momentic. The
  directories must exist on the machine running the test, including in CI.
  Configure one or more extensions in `momentic.config.yaml`:

  ```yaml momentic.config.yaml theme={null}
  browser:
    defaultBrowserType: Chromium
    remoteBrowser: false
    localChromeExtensionPaths:
      - ./extensions/checkout-helper
  ```

  See [Load Chrome extensions](/docs/guides/use-cases/load-chrome-extensions) for
  project setup, local editor steps, and troubleshooting.
</ParamField>

<ParamField path="browser.grantedPermissions" type="string[]">
  Browser permissions to auto-grant during the run. When omitted, all
  permissions are granted.

  ```yaml momentic.config.yaml theme={null}
  browser:
    grantedPermissions:
      - clipboard-read
      - clipboard-write
      - microphone
      - camera
      - geolocation
  ```
</ParamField>

<ParamField path="browser.ignoreHttpsErrors" type="boolean">
  Ignore HTTPS errors like self-signed certificates. Useful for internal or
  development environments. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    ignoreHttpsErrors: true
  ```
</ParamField>

## Performance and stability

<span id="browser-remotebrowser" />

<ParamField path="browser.remoteBrowser" type="boolean">
  Run tests on Momentic hosted browsers instead of a local Chromium. Applies to
  `momentic run` only; the editor and the MCP server always use a local
  browser. See
  [hosted test environments](/docs/running-tests/hosted-test-environments).
  Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    remoteBrowser: true
  ```
</ParamField>

<ParamField path="browser.disableGpu" type="boolean">
  Disable intensive graphical operations (WebGL, hardware-accelerated raster).
  Speeds up runs on machines without a dedicated GPU. May break sites that
  rely on WebGL. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    disableGpu: true
  ```
</ParamField>

<ParamField path="browser.disableZygote" type="boolean">
  Disable Chrome's zygote process. Can reduce process overhead but may break
  features that depend on the zygote. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    disableZygote: true
  ```
</ParamField>

<span id="browser-disablefullstory" />

<ParamField path="browser.disableFullStory" type="boolean">
  Block FullStory scripts from mounting during the run. FullStory's high-volume
  DOM scanning can crash automated pages.

  ```yaml momentic.config.yaml theme={null}
  browser:
    disableFullStory: true
  ```
</ParamField>

## Run-data capture

<ParamField path="browser.disableBrowserMonitoring" type="boolean">
  Disable Momentic's default recording of console logs, network requests, HTML
  snapshots, and element screenshots. The recordings feed the run viewer's
  debug tabs. Disabling can improve performance on sites with high log volume.
  Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    disableBrowserMonitoring: true
  ```
</ParamField>

<ParamField path="browser.disableConsoleLogs" type="boolean">
  Disable console log recording during runs. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    disableConsoleLogs: true
  ```
</ParamField>

<ParamField path="browser.disableNetworkLogs" type="boolean">
  Disable network request recording during runs. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    disableNetworkLogs: true
  ```
</ParamField>

## Page handling

<ParamField path="browser.autoExpandIframes" type="boolean">
  Automatically expand iframes so Momentic can interact with elements inside
  them without configuring **Act within iframe** per step. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    autoExpandIframes: true
  ```
</ParamField>

<ParamField path="browser.autoFollowNewTabs" type="boolean">
  <Warning>
    Deprecated. Waiting for new tabs is inherently racy; use **Switch tab**
    steps instead.
  </Warning>

  Automatically switch to new tabs opened during the run. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    autoFollowNewTabs: true
  ```
</ParamField>

<ParamField path="browser.allowPartialAccessibilityTree" type="boolean">
  Default: `true`. Momentic reads the browser's already-computed accessibility
  data. This is fast and stable, but can be incomplete on pages that never
  finish loading. Set to `false` to force the browser to rebuild the tree from
  scratch on every read (more complete on slow pages, but slower, and can
  crash the browser on very large pages).

  ```yaml momentic.config.yaml theme={null}
  browser:
    allowPartialAccessibilityTree: false
  ```
</ParamField>

<ParamField path="browser.showZeroOpacityElements" type="boolean | &#x22;inputs-only&#x22;">
  Default: `true`. Controls whether zero-opacity elements are exposed to the
  AI locator agent and available to interactive steps.

  {" "}

  <Warning>
    Use `hover` steps to reveal hidden elements before interacting with them.
  </Warning>

  * `true`: show all elements regardless of opacity.
  * `false`: filter zero-opacity elements out of the page context and block
    interactions on them. More closely mimics a human user.
  * `inputs-only`: still show zero-opacity `<input>` elements (useful for UI
    frameworks that style hidden inputs).

  ```yaml momentic.config.yaml theme={null}
  browser:
    showZeroOpacityElements: inputs-only
  ```
</ParamField>

## Locator and cache tuning

<ParamField path="browser.markIneligibleElementsInChecks" type="boolean">
  Default: `false`. Make the V5 locator respect Momentic's element eligibility
  markers during positive [visibility checks](/docs/reference/commands/check-element).
  This helps it select a visible target instead of a matching wrapper that has
  no rendered box, such as an element styled with `display: contents`.

  Enable it in `momentic.config.yaml` with a V5 locator:

  ```yaml momentic.config.yaml theme={null}
  browser:
    markIneligibleElementsInChecks: true
  ai:
    agentConfig:
      locator: v5
  ```

  Without valid [Memory](/docs/ai/memory), the locator uses its existing eligibility
  guidance to find a matching target. Memory-backed checks keep their existing
  behavior. The browser still validates visibility after locating the element.

  This setting does not change other element checks, interactive steps, or older
  locator agents. Set it to `false` or omit it to keep the default behavior. It
  does not invalidate existing step caches.
</ParamField>

<span id="browser-globallocatorredirect" />

<ParamField path="browser.globalLocatorRedirect" type="boolean | &#x22;always&#x22;">
  Default: `always`. Use Momentic's algorithm to find the top-most interactable
  element when a target is covered by another element. Other frameworks throw or
  require a forced click; this redirects to the covering element instead.

  * `false`: disabled.
  * `true`: only redirects on `CLICK` steps (backward compatibility).
  * `always`: redirects on all interactive steps.

  See [Global locator redirect](/docs/reliability/global-locator-redirect) for the full
  algorithm.

  ```yaml momentic.config.yaml theme={null}
  browser:
    globalLocatorRedirect: always
  ```
</ParamField>

<ParamField path="browser.forceClickForMissingRedirectElement" type="boolean">
  When `globalLocatorRedirect` can't find a valid redirect target, force-click
  the original element instead of failing actionability checks.
  Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    forceClickForMissingRedirectElement: true
  ```
</ParamField>

<ParamField path="browser.visualActions" type="boolean">
  Resolve element coordinates with a visual heuristic and use those coordinates
  for clicks, hovers, and typing. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    visualActions: true
  ```
</ParamField>

<ParamField path="browser.ignoreHrefForCaching" type="boolean">
  Ignore the `href` attribute when matching cached anchors. Useful on sites
  with auto-generated or rotating links. Only applies when the anchor has text
  content. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    ignoreHrefForCaching: true
  ```
</ParamField>

<ParamField path="browser.disableLdistCacheValidation" type="boolean">
  Disable Levenshtein distance validation when resolving cached elements. When
  enabled, the cache accepts any element that passes CSS/hybrid selector matching
  and requirements checks without comparing its serialized HTML to the cached
  version. Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    disableLdistCacheValidation: true
  ```
</ParamField>

<ParamField path="browser.disableSecondaryCacheResolution" type="boolean">
  Disable HTML l-dist and template-matching cache fallbacks. Faster but less
  accurate. Cache entries can occasionally resolve to the wrong element.
  Default: `false`.

  ```yaml momentic.config.yaml theme={null}
  browser:
    disableSecondaryCacheResolution: false
  ```
</ParamField>

<ParamField path="browser.hybridSelectorMode" type="&#x22;off&#x22; | &#x22;test&#x22; | &#x22;prefer&#x22; | &#x22;always&#x22;">
  <Warning>Hybrid selectors are in beta and may change.</Warning>

  Default: `prefer`. Hybrid selectors combine text content, classes, attributes,
  parent hierarchy, and shadow DOM piercing to identify elements more reliably
  than CSS selectors.

  * `off`: disabled.
  * `test`: save and resolve hybrid selectors, but report mismatches to Momentic
    without using them.
  * `prefer`: resolve with hybrid selectors first, fall back to CSS.
  * `always`: only use hybrid selectors; fall back to AI on miss.

  Hybrid selectors weigh text content heavily. If you need a specific child in a
  hierarchy, use nth keywords with **Disable cache**.

  ```yaml momentic.config.yaml theme={null}
  browser:
    hybridSelectorMode: prefer
  ```
</ParamField>

## AI context filtering

<span id="browser-importantattributes" />

<ParamField path="browser.importantAttributes" type="string[]">
  Extra HTML attributes that should never be pruned from AI context. Common
  testing attributes (`data-test-id`, `aria-label`, etc.) are always
  important. Suffix with `*` for a prefix match.

  ```yaml momentic.config.yaml theme={null}
  browser:
    importantAttributes:
      - data-topic-id
      - data-test-*
  ```
</ParamField>

<span id="browser-importantclasses" />

<ParamField path="browser.importantClasses" type="string[]">
  CSS class names that mark an element as important. Matching elements are
  never pruned from AI context. Suffix with `*` for a prefix match.

  ```yaml momentic.config.yaml theme={null}
  browser:
    importantClasses:
      - list-controls
      - home-page-*
  ```
</ParamField>

<span id="browser-bannedattributes" />

<ParamField path="browser.bannedAttributes" type="string[]">
  HTML attributes to strip from AI context and ignore when matching cached
  elements. Use this for attributes whose values change between renders (e.g.
  framework-generated `for` IDs) that otherwise invalidate the cache every
  run.
  Suffix with `*` for prefix matches.

  ```yaml momentic.config.yaml theme={null}
  browser:
    bannedAttributes:
      - for
      - aria-controls
      - data-dynamic-*
  ```

  If the attribute is genuinely useful for identifying elements, list it under
  [`browser.importantAttributes`](#browser-importantattributes) instead.
</ParamField>


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