Improve CSS selector quality — prefer semantic selectors over nth-child chains

[BraedenBDev]

Problem

css-selector-generator produces fragile positional selectors like:

:root > :nth-child(2) > :nth-child(5) > :nth-child(2) > :nth-child(2)

These are useless for an AI coding agent — they break on any DOM change and convey no meaning.

Proposed Selector Priority

1. data-testid or data-cy attributes (test frameworks)
2. aria-label or role attributes (accessibility)
3. React component name (already captured in reactComponent.name)
4. ID-based selector (#submit-btn)
5. Text content match (for buttons/links with unique text)
6. Class-based selector (.hero-section .cta-button)
7. nth-child chain (last resort, current behavior)

Implementation

• Replace or configure css-selector-generator in src/content/element-selector.ts
• Use the React component name as the primary identifier when available
• Add a humanReadableSelector field alongside the existing selector
• Formatter should prefer humanReadableSelector in output

Related

• Enhances Resolve CSS selectors to source file paths #20 (resolve CSS selectors to source file paths)

🤖 Generated with Claude Code

[m13v]

this is such a real problem. nth-child chains are basically useless the moment someone adds a div wrapper. your priority order is solid, but I'd bump aria-label above data-testid in practice. reason being, data-testid requires the developer to have added it intentionally, and most apps don't have great coverage. aria-label exists more often than you'd expect because accessibility linters nudge developers to add them. for the React component name approach, be careful with minified production builds where component names get mangled. displayName survives minification but anonymous arrow components don't. also worth considering generating a composite selector that combines multiple strategies with OR logic, so if one breaks you still have fallbacks at runtime.

[m13v]

fwiw we built the composite selector with OR fallback logic into an element resolution system. the implementation that handles the priority chain with accessible name, role, and structural fallbacks: https://github.com/mediar-ai/terminator/blob/main/crates/terminator/src/element.rs

[BraedenBDev]

Thanks m13v, this is useful.

Good call on flipping aria-label above data-testid. Accessibility linters catch devs who wouldn't think to add a testid, so the hit rate is better in the wild. I'll reorder those.

Minification caveat on React component names is the gap I hadn't thought through. The inspector at src/content/react-inspector.ts already reads displayName || name, which covers half the story. If the production build strips .name down to a1 or c the chain has to fall through instead of emitting garbage. That branch needs to exist.

Composite OR-logic is what I want. Picking one strategy and praying is the wrong shape for this problem. Right now we dynamic-import css-selector-generator in src/content/index.ts and ship its single output, which is the brittle path you're describing.

Reading through your element.rs now. Quick question on the consumer side: when you emit composite selectors, is the API an array ordered by confidence, or a single string with OR syntax the consumer parses at resolution time? For PointDev the consumer is an LLM agent reading structured output, so I'm weighing "array of candidates with scores" against "one readable string the agent can reason about end-to-end." Curious which shape has held up better in practice.

[riyajath-ahamed]

react-unique-id-generator (v2.3.0) now ships a generateSelector() function that implements most of this priority list directly:

Stable id (skips dynamic-looking ones via a configurable ignoreIdPattern)
Data attributes — data-testid, data-test-id, data-cy (configurable list)
ARIA role (+ aria-label when present)
Semantic attributes — name, href, aria-label, placeholder, alt, title, etc.
CSS classes (single, then pairwise combinations)
Landmark tags (nav, header, main, etc.)
Ancestor-chain traversal as a last resort, walking up to maxDepth (default 5) and combining with the target's partial selector — each candidate checked for document uniqueness before being returned

It doesn't currently cover priority #3 (React component name) or #5 (text content match) from this issue, but the rest of the chain — including the "last resort" ancestor traversal instead of raw nth-child — lines up closely. There's also a useStableSelector(ref, options) hook that computes this once on mount. Source: lib/selector.ts. Could be worth a look as a reference implementation or direct dependency.