企业官网建设流程全解析

WebdriverIO MCP Selectors 全指南：从 Web CSS 到 iOS/Android 原生定位策略的实战手册

【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio

WebdriverIO MCP（Model Context Protocol）服务器为 AI 助手提供了统一的浏览器与移动端自动化接口，而选择器（Selectors）正是它与页面、应用 UI 交互的"触手"。本文以 website/docs/mcp/selectors.md 为骨架，完整梳理 MCP 场景下 Web、iOS、Android 三端的选择器语法与跨平台取舍策略，并结合仓库源码（findStrategy.ts）、Selectors 主文档、MCP Tools 与 MCP Configuration，帮助你掌握"如何写选择器""为什么这么写""底层如何解析"三层能力，进而在 AI 自动化任务中写出稳定、高效、可维护的定位表达式。

Web 端选择器：MCP 支持的标准 WebdriverIO 策略

对于浏览器自动化（platform: "browser"），MCP 服务器支持全部标准 WebdriverIO 选择器。文档总结的常用策略如下：

底层策略识别机制

WebdriverIO 在 findStrategy.ts 中定义了一个DIRECT_SELECTOR_REGEXP，它直接声明了 MCP 服务器所支持的显式策略前缀，包括：

id | css selector | xpath | link text | partial link text | name | tag name | class name | -android uiautomator | -android datamatcher | -android viewmatcher | -android viewtag | -ios uiautomation | -ios predicate string | -ios class chain | accessibility id

当选择器不包含上述显式前缀时，defineStrategy 会按规则自动推断策略：

• 以/、(、../、./、*/开头 →xpath；
• 以=开头 →link text；以*=开头 →partial link text；
• 以id=开头 →id策略；
• 以>>>（即 constants.ts 中的DEEP_SELECTOR）开头 → shadow DOM 策略；
• 以aria/（即 constants.ts 中的ARIA_SELECTOR）开头 →aria策略；
• 以android=开头 →-android uiautomator；以ios=开头 →-ios uiautomation；
• 以~开头 →accessibility id；
• 形如<div>/<div />→tag name；形如[name="..."]→name策略。

ARIA 选择器的实现原理

aria/Submit Button之所以能按"用户感知的名称"定位元素，是因为它在底层被展开为一组 XPath 联合表达式（findStrategy.ts）。根据 Accname 规范，aria策略会依次尝试匹配：

• aria-labelledby/aria-describedby引用的元素；
• 直接aria-label属性；
• 关联<label for>、父级<label>包裹的input/textarea；
• placeholder/aria-placeholder/title属性；
• <img alt>；
• 元素自身的文本内容（normalize-space(text()) = "..."）。

例如aria/Submit会被转换成类似./*[@aria-label = "Submit"] | ./input[@id=(//label[...]/@for)] | ...的 XPath 表达式。这意味着 ARIA 选择器"感知用户"的同时，在大页面上会比普通 CSS 慢——这正是 MCP 文档提醒"该选择器可能比其它选择器慢"的原因。

Web 端最佳实践（来自主文档）

Selectors.md 用同一段<button id="main" class="btn btn-large">{ "total": 42, "showing": 20, "hasMore": true, "elements": [...] }

使用get_accessibility（仅浏览器）

get_accessibility工具为浏览器自动化提供页面元素的语义信息，内部查询浏览器原生的无障碍 API，当get_elements未返回预期元素时尤其有用（对应工具为get_accessibility_tree，详见 tools.md）：

# 获取所有有命名的无障碍节点 Get accessibility tree # 只过滤按钮和链接 Get accessibility tree filtered to button and link roles # 获取下一页结果 Get accessibility tree with limit 50 and offset 50

支持按 ARIAroles（如button、link、textbox、checkbox、radio、heading、img、listitem）过滤，并支持limit/offset分页。这与 WebdriverIO 主框架的[role=...]角色选择器（findStrategy.ts）形成互补：一个走浏览器无障碍树，一个走 CSS/XPath 角色展开。

性能与 Token 优化提示

从 configuration.md 的"性能考虑"一节可知，选择器选择直接影响 MCP 会话的响应体量与 Token 消耗：

• 移动端 XML 页面源解析仅需 2 次 HTTP 调用（传统元素查询需要 600+ 次），Accessibility ID 选择器最快最稳，XPath 最慢只能作为最后手段；
• inViewportOnly: true过滤屏幕外元素，缩小响应体；
• includeContainers: false排除布局元素（如 Android 的ViewGroup、FrameLayout、LinearLayout、RelativeLayout、ConstraintLayout、ScrollView、RecyclerView，以及 iOS 的View、StackView、CollectionView、ScrollView、TableView）；
• includeBounds: false省略坐标数据；
• limit+offset分页分批处理大量元素，而非一次全量返回。

小结

选择器是 MCP 自动化可靠性的根基。Web 端优先data-testid与文本/ARIA 选择器；移动端以 Accessibility ID（~）为跨平台最优解，Android 退而求其次用 UiAutomator 与 Resource ID，iOS 用谓词字符串与 Class Chain，XPath 仅在最后手段使用。理解 findStrategy.ts 底层的策略识别与 ARIA 展开逻辑，能帮助你在调试 AI 自动化失败时快速定位问题；结合get_elements的分页、过滤参数与get_accessibility的无障碍树，可以显著降低 Token 消耗并提升元素定位的稳定性。

【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio