Locator strategy

Choose locators that survive refactors, and declare what AutoMax may fall back to.

What you'll learn

The order of preference for locators, why test ids beat CSS, how to write heal contexts that are worth healing to, and what never to do.

Role and accessible name (getByRole('button', { name: 'Login' })): stable, accessible, readable.
Label, placeholder, text for forms and content.
Test id (getByTestId) when the DOM offers nothing semantic; keep testIdAttribute in the project YAML in sync with the application.
CSS or XPath only as a last resort and only inside a page object with a heal context.

readonly submit = this.heal.locator(this.page.getByRole('button', { name: 'Login' }), {
  testId: 'login-button', text: 'Login', description: 'login button',
});

Give every heal context a description; it becomes the label in reports and the key for fragility statistics. Avoid contexts that match several elements (text: 'Add' on a product grid); uniqueness lowers the score and can pick the wrong element.

Never heal negative assertions; AutoMax refuses to, because "not visible" is trivially satisfied by a wrong locator.

Run analyze_locators (MCP) or the reviewer agent on a project to find CSS-only locators and strict-mode risks.