Writing element descriptors

Be specific

Playwright recommends locators use accessibility attributes such as placeholders, alt text, and role. Read more here.

Describe the desired element with a specific web accessibility role, such as “the submit button”, “the homepage link”, or “password input”. If you are unsure what type of element you are targeting, you can use the Chrome Dev Tools to find out.

Momentic’s AI by default uses the accessibility tree to understand your application. We are able to view all accessibility attributes and text contents so you can write descriptions like input with placeholder "email" and our AI will be able to find it.

You can be as specific as you desire and our AI will dynamically auto-heal descriptions within a certain threshold.

Include labels

If the desired element has a label, include that in your descriptor, such as “the search button” or “the username textbox”. Our AI web agent will generally attempt to match this label to the “name”, “id”, or “aria-label” attribute of HTML elements on your website. Defining ARIA attributes not only improves the performance of Momentic tests, but also helps your website stay compliant with ADA standards.

Include position cues

When you’re using nth or closest, make sure to turn the cache off for that step. This will ensure that the AI will re-evaluate the page and find the correct element.

In general, Momentic’s AI does an excellent job identifying elements by its name or the text it contains as it appears on the screen; however, in some cases (e.g., when there are multiple instances of the same element on the screen), you will need to specify a relative location to provide a better context to identify it.

You can provide cues such as “…below the ‘Introduction’ header” or “…beside the ‘Back’ button”. Only use positioning cues if they are expected to be stable over time.

You can also use the inside keyword to specify the parent element of another element. For example, “the ‘Submit’ button inside the user dialog”.

You can also use the nth keyword to specify the position of an element in a list. For example, “the second ‘Submit’ button”.

You can also use the closest keyword to specify the closest element to another element. For example, “the closest ‘Submit’ button to the ‘Username’ input”.


  1. By default, our AI uses the accessibility tree of the whole web page, so it can also locate elements not visible in the current viewport.
  2. When an element can’t be found, that is usually a signal that it is missing accessibility attributes such as role or name. For more on web accessibility guidelines, go here. Your users will thank you!
  3. As a last resort, you can open Chrome DevTools and turn on full-page accessibility tree. This is similar to how our AI views your app. For example: “Search… searchbox” or “docs link” will correctly locate it on the page.

chrome a11y tree

Using data-testids and CSS selectors

Using CSS selectors is not recommended as it can lead to test flakiness.

Selectors that resolve to multiple elements will error. Make sure your CSS selectors are specific and only resolve to a single element.

Momentic supports CSS selectors as an escape hatch. We don’t recommend this as it is much more brittle and can lead to test flakiness. You can turn on CSS selector support by toggling the option in the step settings.

You are able to locate elements using data-testid attributes. For example: [data-testid="value"].

You are also able to locate elements by using CSS selectors. For example: input#username or button.mui.primary.