Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

role= selector vocabulary diverges from snapshot kind

Đang mở
  • Có gì không ổn?
#3,021 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
45/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
typescript
Lĩnh vực
testing

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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
Ngôn ngữ chính
TypeScript
Star
4.8k
Fork
315
Merge trung bình
11 giờ 25 phút
Pull request đã merge (30 ngày)
545

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của callstack/agent-device

Tất cả issue của callstack/agent-device

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.