Configure the behavior of momentic by using a momentic.config.yaml file in your project root directory. Each configuration file represents a project. Paths are relative to the location of momentic.config.yaml or absolute paths. Globs are relative to the location of momentic.config.yaml.

​
Global options

​
name

momentic.config.yaml
name: my-project-name
The name of your project. This is used in reports and other places to identify your project.

​
include

momentic.config.yaml
include:
  - "**/*.test.yaml"
  - "**/*.module.yaml"
A list of globs for test and module files to include. Momentic will automatically include all files that match these globs when starting the Momentic Local App or running tests.

​
exclude

momentic.config.yaml
exclude:
  - "out/**/*"
A list of globs for files to exclude. Folders such as node_modules, .git, and .venv are always excluded. The default directory Momentic will write to when creating a new module.

​
goldenFileDir

momentic.config.yaml
goldenFileDir: golden/visual-diff
The default directory Momentic will write to storing golden files for Visual diff.

​
reporterDir

momentic.config.yaml
reporterDir: reports
The default directory for storing test reports when using reporters.

​
retries

momentic.config.yaml
retries: 2
The number of times to retry a test if it fails. This is useful for flaky tests that may fail due to network issues or other transient problems. This will override the retries option set on the test.

​
parallel

momentic.config.yaml
parallel: 1
Default: 1 The number of tests to run in parallel. This is useful for speeding up test execution, especially for large test suites. Set to 1 to run tests sequentially.

​
gitMainBranch

momentic.config.yaml
gitMainBranch: main
The name of the main branch in your repository. When running tests on a brand new branch, Momentic will seed the cache entries from the nearest commit on the main branch. Additionally, when running Momentic in non-CI environments, the main branch is excluded from cache saving. Please see cache saving eligibility for more information.

​
gitProtectedBranches

momentic.config.yaml
gitProtectedBranches:
  - staging
A list of branches that by default are considered ineligible for cache saving when running tests in a non-CI environment. This prevents accidental cache overwriting on shared branches. Please see cache saving eligibility for more information.

​
Defining environments

​
environments

Each object in the environments list defines a different environment for running tests. Each environment defines a set of key-value pairs which are available to tests as variables. In the example below, we’ve defined three environments: dev, staging, and production.
momentic.config.yaml
environments:
  - name: dev
    baseUrl: https://dev.example.com
    envVariables:
      USERNAME: devUser
      PASSWORD: devPassword
  - name: staging
    baseUrl: https://staging.example.com
    envVariables:
      USERNAME: stagingUser
      PASSWORD: stagingPassword
  - name: production
    baseUrl: https://www.example.com
    envVariables:
      USERNAME: prodUser
      PASSWORD: prodPassword

​
Environment options

​
name

momentic.config.yaml
environments:
  - name: dev
The name of the environment. This is used to identify the environment when running tests. It is also available as env.ENV_NAME in tests.

​
baseUrl

momentic.config.yaml
environments:
  - name: dev
    baseUrl: https://dev.example.com
The starting URL for the environment. This is used as the base URL for all tests using this environment. It is also available as env.BASE_URL in tests.

​
envVariables

momentic.config.yaml
environments:
  - name: dev
    baseUrl: https://dev.example.com
    envVariables:
      USERNAME: devUser
      PASSWORD: devPassword
      API_KEY: ${VAR_FROM_SHELL:-default_value}
A list of key-value pairs that define environment variables for the environment. These variables are available to tests as env.VARIABLE_NAME. They can be used to store sensitive information like API keys or credentials. Interpolation is supported, so you can reference shell variables. You cannot reference other variables defined in the same environment.

​
inheritFromShell

momentic.config.yaml
environments:
  - name: dev
    baseUrl: https://dev.example.com
    inheritFromShell: true
    envVariables:
      USERNAME: devUser
      PASSWORD: devPassword
Default: false Include all values from the enclosing shell as environment variables at runtime.

​
envFile

momentic.config.yaml
environments:
  - name: dev
    baseUrl: https://dev.example.com
    envFile: .dev.env
    envVariables:
      USERNAME: devUser
      PASSWORD: devPassword
The path to a file containing environment variables. This file should be in the format of a .env file, with each line containing a key-value pair. Momentic will load these variables and make them available to tests as env.VARIABLE_NAME.

​
JSON file

momentic.config.yaml
environments:
  - name: dev
    baseUrl: https://dev.example.com
    envVariables:
      VAR_FROM_FILE:
        fromFile: package.json
        json: true
You can also load environment variables from a JSON file. The fromFile option specifies the path to the file, and the json option indicates that the file is in JSON format. The variables will be available as env.VAR_FROM_FILE.

​
Browser options

​
browser

Configure default browser settings for all tests in the project. Individual tests can override these settings.
momentic.config.yaml
browser: {}

​
pageLoadTimeoutMs

momentic.config.yaml
browser:
  pageLoadTimeoutMs: 20000
Default: 8000 How long to wait for a page to load before timing out, in milliseconds. This includes new tabs and navigation events.

​
smartWaitingTimeoutMs

momentic.config.yaml
browser:
  smartWaitingTimeoutMs: 10000
Default: 5000 Configure the maximum timeout for smart waiting, in milliseconds. This controls how long Momentic will wait for the page to stabilize before proceeding from one step to the next.

​
localChromeExtensionPaths

momentic.config.yaml
browser:
  localChromeExtensionPaths:
    - /tmp/eimadpbcbfnmbkopoojfekhnkhdbieeh
    - /tmp/bcjindcccaagfpapjjmafapmmgkkhgoa
An list of paths to unpacked Chrome extensions. These extensions will be loaded onto the browser before the test begins.

​
extraHeaders

momentic.config.yaml
browser:
  extraHeaders:
    Authorization: Bearer my-secret-token
    X-Custom-Header: CustomValue
Extra HTTP headers to include in all requests made by the browser. This can be useful for authentication or other custom headers that your application requires.

​
userAgent

momentic.config.yaml
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"
Default: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.7103.25 Safari/537.36 The user agent string to use for all requests made by the browser.

​
disableGpu

momentic.config.yaml
browser:
  disableGpu: true
Default: false Whether to disable intensive graphical operations, such as WebGL and rasterization with hardware acceleration. Disabling can significantly increase performance, however some graphics libraries may require it.

​
autoExpandIframes

momentic.config.yaml
browser:
  autoExpandIframes: true
Default: false Automatically expand iframes. This allows Momentic to interact with elements inside iframes without needing to configure the Act within iframe option.

​
autoFollowNewTabs

This option is deprecated and will be removed in the future. Waiting for new tabs to open is inherently racy, as client-side JavaScript may not open the tab before Momentic continues onto the next step. Please use Switch Tab steps to explicitly switch to new tabs instead.
momentic.config.yaml
browser:
  autoFollowNewTabs: true
Default: false Automatically switch to new tabs that are opened during test execution.

​
allowPartialAccessibilityTree

momentic.config.yaml
browser:
  allowPartialAccessibilityTree: true
Default: false Momentic uses the accessibility tree as context for several AI agents. However, some sites can fail to load the complete accessibility tree due to third-party iframes, embedded videos, or misconfigured script tags. Enable this setting to allow using partial sections of the accessibility tree.

​
ignoreHttpsErrors

momentic.config.yaml
browser:
  ignoreHttpsErrors: true
Default: false Ignore HTTPS errors, such as self-signed certificates and certificate errors. Useful for testing internal or development environments that use self-signed certificates.

​
showZeroOpacityElements

We strongly recommend using hover steps to reveal hidden elements before interacting with them.
momentic.config.yaml
browser:
  showZeroOpacityElements: false | true | inputs-only
Default: false Filter out elements with zero opacity from the page context that is passed to Momentic’s locator AI agent. In addition, prevent interactive steps from targeting elements that have opacity 0. This improves AI performance and more closely mimics the behavior of a human user. This option never affects element check steps, which are commonly used to locate and verify hidden elements. When this option is set to false, users may need to add hover or scroll steps to reveal hidden elements before interacting with them. When this option is set to inputs-only, <input> elements that are zero opacity are still shown. This is useful for sites that use UI frameworks that rely on hidden inputs for styling reasons.

​
ignoreHrefForCaching

momentic.config.yaml
browser:
  ignoreHrefForCaching: true
Default: false Ignore the href attribute when determining whether cache entries can be reused for anchor elements. This can greatly improve speed for sites that use auto-generated or dynamic links. href attributes are only ignored if the anchor element has some text content (either as a direct child or in some nested element).

​
disableSecondaryCacheResolution

momentic.config.yaml
browser:
  disableSecondaryCacheResolution: true
Default: false Disable secondary cache resolution methods, which include using HTML l-dist and template matching. These methods are less accurate and may cause instances where step caches resolve to the wrong element, but can improve test speed.

​
hybridSelectorMode

Hybrid selectors are in beta and subject to be deprecated in the future.
Hybrid selectors combine multiple different pieces of information from the HTML to reliably identify an element, including it’s text content, classes, attributes, parent hierarchy, and more. Hybrid selectors can even pierce shadow DOM roots, unlike traditional selectors. Hybrid selectors place a greater emphasis on text content compared to CSS selectors. As such, if you desire behavior where a specific child in the hierarchy is always chosen, we recommend using nth keywords and turning on Disable cache to ensure the correct element is always targeted.
momentic.config.yaml
browser:
  hybridSelectorMode: prefer
Default: off Options:
  • off: Disable hybrid selectors altogether. Equivalent to omitting this field entirely.
  • test: Enable hybrid selectors for element resolution, and report mismatches to Momentic.
  • prefer: Enable hybrid selectors for element resolution and prefer using them over traditional selectors. If no elements are discovered using hybrid selectors, falls back to CSS selectors.

​
bustCacheOnBoundingBoxChange

momentic.config.yaml
browser:
  bustCacheOnBoundingBoxChange: true
Default: false Whether to force busting locator caches when the bounding box of an element changes.

​
globalLocatorRedirect

momentic.config.yaml
browser:
  globalLocatorRedirect: true
Default: true During interactive steps, use Momentic’s custom algorithm for determining the “top-most” element that should be interacted with. Sometimes, functional HTML elements can be covered by other presentational HTML elements. For example, many UI frameworks employ hidden inputs that are covered by styled <div> or <label> elements that users actually interact with when clicking. While other frameworks such as Playwright throw errors or require users to explicitly bypass stability checks in this case, Momentic’s algorithm can determine the top-most element that still intersects with the original bounding box and interact with that element instead. For customers who desire more manual control over how to handle cases where an element is covered by another element, you can opt out of this feature. The “Disable stability checks” option on interactive steps can also be used to force interactions with covered elements, similar to Playwright’s force setting.

​
visualActions

momentic.config.yaml
browser:
  visualActions: true
Default: false Use a heuristic to determine x, y coordinates of the element and use them to perform actions like clicking, hovering, or typing.

​
importantAttributes

momentic.config.yaml
browser:
  importantAttributes:
    - data-topic-id
Specify additional HTML attributes that should never be pruned from the context passed to AI agents. Common testing attributes such as data-test-id and aria-label are automatically considered important. Values may contain a single * at the end to indicate a prefix match, such as data-test-*.

​
importantClasses

momentic.config.yaml
browser:
  importantClasses:
    - list-controls
Specify important CSS class names. An element with an important class name will never be pruned from the context passed to AI agents. Values may contain a single * at the end to indicate a prefix match, such as home-page-*.

​
importantStyles

Adding common styles to this list will dramatically increase the size of the context passed to AI agents, which slowing down tests significantly and reducing AI performance. We recommend using this setting sparingly.
momentic.config.yaml
browser:
  importantStyles:
    - transition-delay:0.4s
Specify important CSS computed styles. An element with an important computed style will never be pruned from the context passed to AI agents. Styles should be provided in the format property:value, such as width:100px. A value of * matches any value. Note that custom CSS variables (i.e. those starting with --) are not supported.

​
AI options

​
ai

Configure AI features for the project.
momentic.config.yaml
ai: {}

​
agentConfig

momentic.config.yaml
ai:
  agentConfig:
    locator: v2
    assertion: v2
    visual-assertion: v2
    text-extraction: v2
Choose which version of prompts and AI models to use for certain AI tasks. Please see AI configuration for available options.

​
failureRecovery

Failure recovery is in beta and subject to be deprecated in the future.
momentic.config.yaml
ai:
  failureRecovery: true
Default: false Enable Failure recovery to automatically recover from certain test failures by proposing and executing step changes.

​
aiFailureAnalysis

momentic.config.yaml
ai:
  aiFailureAnalysis: true
Default false Enable AI failure analysis for failed test runs. When a run fails, Momentic analyzes the error to classify a likely root cause, summarize previous steps, and generate an error summary. The analysis appears in the Run Viewer under the “AI failure analysis” tab.

​
aiAction

AI action is in beta and subject to be deprecated in the future.
momentic.config.yaml
ai:
  aiAction: true
Default: false Enable AI action as a step in the Momentic Editor. This allows you to use AI to generate actions based on natural language instructions.

​
stepLintSuggestions

momentic.config.yaml
ai:
  stepLintSuggestions: true
Default: true Enable AI step linting suggestions. This will provide suggestions for improving the quality of your test steps, such as removing unnecessary steps or optimizing existing ones.

​
aiPageFiltering

momentic.config.yaml
ai:
  aiPageFiltering: true
Default: false Enables page chunking and filtering if the page is too large. This allows Momentic to handle large pages more efficiently by breaking them into smaller chunks and filtering out unnecessary content.

​
Advanced options

​
advanced

Configure advanced settings for the project.
momentic.config.yaml
advanced: {}

​
fakerConstantSeed

momentic.config.yaml
advanced:
  fakerConstantSeed: true
Default: false Use a constant seed for the Faker library to ensure that random data generated by Faker is consistent across test runs. This can be useful for debugging and ensuring that tests are reproducible.