Skip to main content
Momentic locates elements from natural-language descriptions instead of CSS or XPath selectors. Descriptions capture what an element does, so if it moves or its markup changes, Momentic can use AI to find it again and automatically update its cached locator.

​
Write durable descriptions

A good target is the shortest description that uniquely identifies the element for a user. Start with its purpose, accessible name, or role, then add stable context only when you need to distinguish it from another match. Avoid descriptions that depend on implementation details, incidental styling, or earlier steps: Use durable, user-facing details. Add color, exact position, or element order only when that detail is required to find the element or is part of the behavior you are testing. More detail can make a target less reliable when the extra detail changes. Accessible roles and names are usually the strongest signals. Prefer targets such as the Submit button, the People tab, or the Month combobox when those descriptions are unique. In the test editor, open the Accessibility tab in the bottom panel to inspect the tree Momentic uses. Search for the element and check that its role and name describe what a user can do with it. If an interactive element is missing or has no meaningful name, improve the product’s accessibility metadata. Use aria-labelledby when a visible label already exists, or aria-label when it does not. Keep the label truthful to the control’s user-facing purpose. For an automation-only identifier, use a stable data-testid instead of adding misleading ARIA metadata.

​
Require exact text only when it matters

Visible text is useful when it is stable: the Welcome heading or the text area containing Lorem Ipsum. Do not quote text by default. Single quotes make the quoted text a strict requirement, so use them only when an exact value is part of the behavior under test. This is useful for an ID, code, amount, or value created by the test:
Avoid strict matching for copy that may be reworded, localized, truncated, or only partially visible. For example, the control showing that the job is still running is more durable than the 'In progress' badge when either “In progress” or “Processing” is valid.

​
Add visual and positional cues when needed

Momentic can use colors, shapes, sizes, icons, and positions from the screenshot. These cues help when an element does not have a useful accessible name:
  • the thumbs-up icon beside the response
  • the hamburger menu beside the logo
  • the button below the Introduction heading
  • the Submit button inside the user dialog
  • the closest Delete button to the account named Acme
Visual cues are limited to the current viewport. Avoid relying on them for very small targets or rows of similar icons. Prefer relative context such as a dialog, heading, row, or field over absolute positions such as the button in the bottom right corner. Use ordinal descriptions such as the second result only when order is part of the test. If the same description should intentionally resolve to a different element between runs, see Caching.

​
Auto-waiting

Interactive preset steps such as Click and Type automatically wait for their target. Momentic lets the page or screen settle and retries cached targets until the smart-waiting timeout elapses, so do not add an element-exists check only to wait before an interaction. The default smart-waiting timeout is 5 seconds. Configure it separately for web tests and mobile tests. When an asynchronous transition can outlast that timeout, wait on a durable page condition immediately before the interaction. Avoid fixed-duration sleeps and transient targets such as tooltips, toasts, loading spinners, or other elements that may disappear before Momentic resolves them.

​
Caching

On the first successful run, Momentic uses AI to resolve the description and caches the result. The cache stores multiple signals about the target, including its text, accessibility attributes, structure, position, and appearance. On later runs, Momentic validates those signals against the live page and performs the action without another AI call when they still match. If the cached target no longer matches because the element moved or its markup changed, locator auto-healing uses the natural-language description to find the intended element with AI and updates the cache. This is why descriptions should capture the element’s durable purpose instead of its current implementation. Interpolated {{ }} values are part of the cache identity. A description using {{ env.USERNAME }} can reuse its cache while USERNAME stays the same. A description using a value that changes every run, such as {{ Date.now() }}, gets a new cache identity every time, so Momentic resolves it again with AI. See Step caching for cache eligibility, invalidation, storage, and isolation rules. Keep caching enabled unless the same description should intentionally identify a different element on each run, such as today’s calendar cell, the last item in a rotating list, or an ordinal result whose contents change. Disable caching only on that dynamic step. Disabling it does not fix a vague description or a rendering race.

​
Advanced

​
Preserve useful HTML context

Momentic prunes noisy HTML before sending page context to its AI. Common testing attributes such as aria-label and data-test-id are always preserved. If a useful custom attribute is missing, add it to browser.importantAttributes so Momentic keeps it. You can also preserve elements by class with browser.importantClasses. If a framework-generated or frequently changing attribute causes cache misses, exclude it with browser.bannedAttributes. Do not ban an attribute that genuinely identifies the element.

​
Canvas interaction

AI action can handle canvas-based interfaces even when their controls do not exist as distinct DOM elements. It uses visual reasoning and can interact at arbitrary x/y coordinates, which makes it well suited to drawing tools, visual editors, games, maps, and other canvas-heavy UI. Preset steps such as Click and Type still need a distinct element in the DOM or mobile accessibility tree. Use an AI action for a canvas, video, or other custom-rendered surface that does not expose one.
Prefer preset steps for known, targetable UI because they are faster and more deterministic.

​
Choose the right check

Use an element check for one stable, unambiguous element property, such as exact text, an attribute, or enabled state. Use an AI check when element existence must be a separate readiness gate, and for visual appearance, page position, relationships between elements, or other semantic outcomes. See Writing assertions for examples.