Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

role= selector vocabulary diverges from snapshot kind

Open
  • Is something wrong?
#3,021 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
45/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
testing

Research direction

Read packages/kernel/src/snapshot.ts and the selector paths in packages/selectors/src/internal/match.ts and find.ts first. Decide the compatibility approach before changing behavior; if a cutover is chosen, update the selectors, the snapshot and client API documentation, and affected recorded-selector fixtures. Done means the rollout decision is documented and role= behavior and vocabulary are consistent with kind.

Written by the indexing model from the issue text.

Description

Context

#2656 added kind: string to structured snapshot nodes — the presenter's platform-neutral role vocabulary (button, text-field, text, switch, ...), computed by formatRole in packages/kernel/src/snapshot.ts and shared by every backend/projection.

Adversarial review of #2656 found that role= selector matching does not use that same vocabulary today, so the two completion conditions below cannot be satisfied without a separate, behavior-changing migration:

  • packages/selectors/src/internal/match.ts (role selector term) and packages/selectors/src/internal/find.ts (find role=... locator) each normalize node.type by stripping XCUIElementType/leaf-segment prefixes and lowercasing — producing raw leaf class names (statictext, edittext, textfield) rather than formatRole's coarse vocabulary (text, text-field).
  • packages/provider-webdriver/src/webdriver-source.ts (roleFromWebDriverType) independently falls back to a similarly-stripped type name when WebDriver's class attribute is absent, to populate the (iOS AX-derived) role field — a different field than kind, but the same kind of ad hoc normalization.
  • packages/contracts/src/snapshot-text.ts (normalizeType) strips the same prefixes for a different purpose (fillable-type/keyboard-occlusion detection), so it is a distinct concern from role classification but shares the pattern.

Why this is its own issue, not folded into #2656

role= selector matching is a released, public selector feature (shipped before 0.21.x). Switching it to formatRole's vocabulary would change matching results for existing selectors and recorded scripts (e.g. role=statictext and role=edittext would stop matching; role=text/role=text-field would start). That is a breaking change to a versioned surface and needs an explicit compatibility/rollout decision (hard fail vs. an aliasing period), which is out of scope for a PR whose job is adding the kind field.

Proposed work

  • Decide whether role= (both the main selector term and the find locator) should match against formatRole(node.type) instead of raw leaf-class normalization, and whether that is a hard cutover or needs a deprecation window.
  • If cutover: update packages/selectors/src/internal/match.ts and packages/selectors/src/internal/find.ts to import and use formatRole from @agent-device/kernel/snapshot, delete the now-redundant normalizeRole in find.ts, update website/docs/docs/snapshots.md and website/docs/docs/client-api.md to state role= shares kind's vocabulary, and sweep recorded-selector/doc fixtures that assume the old raw vocabulary.
  • Leave packages/contracts/src/snapshot-text.ts#normalizeType (fillable/occlusion detection) and packages/provider-webdriver/src/webdriver-source.ts#roleFromWebDriverType (the iOS role field fallback) alone unless the decision above says otherwise — they serve different fields/purposes than kind.

References

  • #2656
Dominant language
TypeScript
Stars
4.7k
Forks
304
Avg merge
11h 6m
Merged PRs (30d)
521

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from callstack/agent-device

All issues in callstack/agent-device

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.