Configuring momentic.config.yaml

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

name: my-project-name

The name of your project. This is used in reports and other places to identify your project.

​

include

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

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

goldenFileDir: golden/visual-diff

The default directory Momentic will write to storing golden files for Visual diff.

​

reporterDir

reporterDir: reports

The default directory for storing test reports when using reporters.

​

retries

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

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

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

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.

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

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

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

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

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

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

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.

browser: {}

​

pageLoadTimeoutMs

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.

​

localChromeExtensionPaths

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

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.

​

disableGpu

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

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

browser:
  autoFollowNewTabs: true

Default: false

Automatically switch to new tabs that are opened during test execution.

​

showZeroOpacityElements

browser:
  showZeroOpacityElements: false

Default: false

Filter out elements with zero opacity from the page context that is passed to Momentic’s locator AI agent. This improves AI performance and more closely mimics the behavior of a human user.

This option also prevents interacting with elements that have opacity 0. This does not affect element check steps, which commonly need 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.

​

ignoreHrefForCaching

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

​

hybridSelectorMode

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.

browser:
  hybridSelectorMode: prefer

Default: false

Options:

• false: Disable hybrid selectors altogether.
• 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

browser:
  bustCacheOnBoundingBoxChange: true

Default: false

Whether to bust the cache when the bounding box of an element changes.

​

globalLocatorRedirect

browser:
  globalLocatorRedirect: true

Default: false

Use a heuristic to redirect locators to a more stable and accurate element. This can improve the reliability of tests by ensuring that locators point to the correct element, even if the DOM structure changes.

​

visualActions

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.

​

AI options

​

ai

Configure AI features for the project.

ai: {}

​

agentConfig

ai:
  agentConfig:
    locator: v2
    assertion: v2

Choose which version of prompts and AI models to use for certain AI tasks. Currently, only locator and assertion can be configured and the available options are v1 and v2 for each.

​

failureRecovery

ai:
  failureRecovery: true

Default: false

Enable Failure recovery to automatically recover from certain test failures by proposing and executing step changes.

​

aiAction

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

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

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.

advanced: {}

​

fakerConstantSeed

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.