data-testid and data-agent Attributes: When Stable Hints Help

Start a browser test with the same role and accessible name a user encounters. A link named View pricing and a button named Run free scan already expose durable intent. If a selector breaks because the intended user-facing name changed, the test may be correctly identifying a product change that deserves review. Native role-and-name selectors also encourage the component to retain keyboard behavior and a programmatic name. Dedicated hints should not be a shortcut around missing labels, clickable divs, or unreported state. [AR3][AR4][AR11]

Add a hint when the semantic contract is intentionally variable or ambiguous for engineering: localized labels, many repeated row controls, a nonvisual container that must anchor diagnostics, or a synthetic fixture that should be independent of editorial copy. Document that reason. Continue asserting that the control has the correct role, a useful name, keyboard behavior, and relevant states. The hint selects the component; it does not prove the component is usable. [AR3][AR9]

Use names such as scan-form, project-delete-confirmation, or resource-source-list rather than blue-button, right-column-3, or a full sentence of current copy. A stable name expresses the product concept and can survive styling or layout changes. Keep a small vocabulary for action, target, state, and consequence instead of inventing a new grammar in every component. When a product concept changes, update the hook and its consumers deliberately rather than maintaining an alias forever. [AR7][AR9]

Treat values as public. They appear in delivered HTML and may be captured in traces, recordings, and logs. Never embed email addresses, account IDs, access tokens, private repository names, or other sensitive context. Avoid exposing internal authorization details. If a test needs a record identity, use a seeded synthetic fixture or an opaque test-only value in an isolated environment, not production user data. [AR7]

A product-specific data-agent-action can describe intent or consequence for a workflow you control, but browsers and authorization systems do not enforce its meaning automatically. Define the vocabulary publicly, version it, and keep the visible control language aligned. An attribute such as data-agent-danger may help a scanner flag review, yet the server must still authenticate the actor, authorize the exact target, validate state, and require confirmation where appropriate. [AR7]

Do not let a page grant itself authority. Untrusted content can add attributes, and indirect instructions can direct a model toward them. Agent policy should treat page declarations as evidence to evaluate, not system commands. Bind actions to allowlisted tools and server-side checks. Log the requested operation and result without capturing sensitive form values. A safe refusal remains a successful outcome when the declared action exceeds scope. [AR7][AR4]

A test that finds an element and clicks it proves very little. Before interaction, assert role, accessible name, current state, and consequence messaging. Perform the supported keyboard or pointer action. Afterward, assert the state transition, network effect if appropriate, focus destination, user-visible receipt, and protection against duplicate execution. For a destructive flow, test cancellation and insufficient authorization as well as the permitted path. [AR3][AR4][AR9]

Keep selectors centralized only when that improves readability; do not build a vast page-object layer that hides user intent. Name tests after the outcome. A useful example is visitor can prepare a public URL scan and preserve content attribution, not scanButton works. When the hint disappears, a clear failure should point to the contract owner and the user journey it supports. [AR9]

Approve a new hook when it solves a named reliability problem, uses a stable purpose, contains no sensitive data, has an owner, and accompanies semantic and safety assertions. Reject it when it merely avoids fixing accessibility, encodes layout or copy, duplicates an existing stable relationship, or implies permission that the server does not enforce. Review public attributes during component changes and remove those no longer used. [AR3][AR7][AR9]

Run the browser task against a production-like preview. Server rendering, hydration, feature flags, and localization can alter the delivered attributes and names. The free AgentReady URL scan reports several automation-hint and semantic signals, but it cannot decide whether a custom attribute is necessary for your specific test. Keep the rationale beside the test and verify the underlying user outcome. [AR3][AR9][AR11]