Appium API 端点参考指南：W3C WebDriver、Appium 协议扩展与官方插件端点体系-北京尧图网络

Appium API 端点参考指南W3C WebDriver、Appium 协议扩展与官方插件端点体系【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appiumAppium 主模块通过其 base driver 对外暴露一套完整的 HTTP API 端点并按协议分组管理。本篇基于 Appium 官方文档中的 API 端点参考index.md整理成文覆盖 WebDriver、WebDriver BiDi、JSON Wire、Mobile JSON Wire、Appium 扩展协议以及官方插件端点的核心定义、参数与响应结构并结合base-driver源码剖析端点路由、参数校验与协议协商的底层实现帮助你在调试自动化服务、开发客户端插件或排查 HTTP 交互问题时建立完整的端点地图。Appium 端点的协议分组Appium 所有 API 端点按其所属协议分组除各协议外还单独为插件端点设立了一个分组协议分组说明文档位置WebDriver ProtocolW3C WebDriver 协议端点是 Appium 的主力协议webdriver.mdWebDriver BiDi Protocol基于 WebSocket 事件的双向协议命令bidi.mdJSON Wire Protocol遗留的 JSON Wire 协议端点多已弃用jsonwp.mdMobile JSON Wire Protocol遗留的移动端 JSON Wire 协议端点mjsonwp.mdAppium ProtocolAppium 对 W3C WebDriver 协议的扩展端点appium.mdOther Protocols其他协议端点others.mdEndpoints Used by Official Plugins官方插件新增/修改的端点plugins.md需要特别强调的是两个使用前提所有 Appium driver 都继承 Appium base driver因此它们天然支持 base driver 的全部端点同时可以各自额外定义私有端点。了解某个 driver 的具体端点请查阅对应 driver 的文档drivers 文档入口。官方推荐通过 Appium client 调用这些端点而不是直接发送裸 HTTP 请求。不同 clientWebdriverIO、Selenium、Appium-Python-Client 等封装的调用方式不同需查阅各自文档clients 文档入口。端点体系的底层实现从源码看请求如何被路由从源码结构看端点定义、路由注册与请求处理集中在base-driver包的 protocol 模块中路由方法映射表各协议的命令与 URL 路由的映射定义在 routes 目录下按协议拆分——w3c.ts 定义 W3C 端点、jsonwp.ts 定义 JSONWP 端点、appium.ts 与 appium-device.ts 定义 Appium 扩展端点。routes/index.ts 汇总为统一的METHOD_MAP并维护NO_SESSION_ID_COMMANDS不需要会话 ID 的命令集合。协议协商在 protocol.ts 中determineProtocol函数会检查 new-session 请求体中是否包含 W3C capabilities通过isW3cCaps判断据此决定按 W3C 还是 MJSONWP 协议处理export function determineProtocol(createSessionArgs: any[]): keyof typeof PROTOCOLS { return createSessionArgs.some(isW3cCaps) ? PROTOCOLS.W3C : PROTOCOLS.MJSONWP; }会话 ID 提取getSessionId从 Express 路由参数中取出sessionId如果路由被误写为通配符/session/*sessionId导致参数变成数组它会取第一个元素并输出告警日志提示修正路由定义——这解释了为什么文档中所有会话级端点都统一写成/session/:sessionId形式。参数校验checkParams依据METHOD_MAP中每个命令声明的required/optional参数表支持多组可选必填参数的形式校验请求体并可挂载自定义validate函数校验失败会抛出InvalidArgumentError。HTTP 层挂载端点最终通过 express/server.ts 注册的 Express 中间件暴露到服务上listCommands类元命令则由 protocol 层直接实现用于向客户端枚举当前会话支持的端点。理解了这套机制后就可以把各协议文档中的端点视为“方法名 → URL 路由参数声明校验规则”的声明式映射。WebDriver 协议核心端点webdriver.md 列出了 Appium 支持的 W3C WebDriver 端点全表。官方文档特别提醒多数 WebDriver 端点并不在 Appium 本体中实现而是直接代理proxy到具体 driver由 driver 负责实际执行。以下为按功能域整理的端点总览会话生命周期端点方法与路径关键参数响应createSessionPOST /sessionW3C capabilities见下方说明sessionIdcapabilitiesdeleteSessionDELETE /session/:sessionId-nullgetStatusGET /status-{build, message, ready}getTimeouts / timeoutsGET/POST /session/:sessionId/timeoutsimplicit?、pageLoad?、script?毫秒null/{command, implicit}createSession 的历史包袱W3C 规范只接受 1 个参数但 Appium 为实现历史兼容允许最多 3 个参数位置携带 capabilities这是遗留 JSONWP 的要求。自 Appium 2 起 JSONWP 格式已不再支持三个位置中的任意一个都可以用来传 W3C capabilities。响应对象CreateResult包含sessionId字符串和capabilitiesdriver 处理后的能力对象。getStatus 的 Appium 定制build字段在 Appium 中是一个包含version键的对象其值即 Appium 服务版本ready表示服务当前是否还能创建新会话message是对ready值的解释。导航与窗口管理端点方法与路径说明setUrl / getUrlPOST/GET /session/:sessionId/url导航到指定 URL / 获取当前 URLback / forward / refreshPOST /session/:sessionId/{back,forward,refresh}浏览器历史前进后退 / 刷新titleGET /session/:sessionId/title获取页面标题getWindowHandle / setWindow / closeWindow / getWindowHandlesGET/POST/DELETEGET /session/:sessionId/window*窗口句柄的获取、切换、关闭与枚举createNewWindowPOST /session/:sessionId/window/new参数typewindow或tab返回{handle, type}getWindowRect / setWindowRectGET/POST /session/:sessionId/window/rect获取/设置窗口尺寸位置返回Rect{x, y, width, height}maximizeWindow / minimizeWindow / fullScreenWindowPOST /session/:sessionId/window/{maximize,minimize,fullscreen}窗口最大化/最小化/全屏均返回RectsetFrame / switchToParentFramePOST /session/:sessionId/frame{,/parent}帧切换frame的参数id可为null、数字或元素元素查找与属性读取元素统一以Element对象表示含两个等价的 ID 键element-6066-11e4-a52e-4f735466cecfW3C 标准键和ELEMENT遗留 MJSONWP 键。端点方法与路径说明findElement / findElementsPOST /session/:sessionId/{element,elements}从根节点查找参数using定位策略value选择器findElementFromElement / findElementsFromElementPOST /session/:sessionId/element/:elementId/{element,elements}以指定元素为起点查找elementShadowRootGET /session/:sessionId/element/:elementId/shadow返回shadow-6066-11e4-a52e-4f735466cecf影子根 IDfindElementFromShadowRoot / findElementsFromShadowRootPOST /session/:sessionId/shadow/:shadowId/{element,elements}以影子根为起点查找activeGET /session/:sessionId/element/active获取当前聚焦元素elementSelected / elementDisplayed / elementEnabledGET /session/:sessionId/element/:elementId/{selected,displayed,enabled}布尔状态查询仅对特定元素类型有意义getAttribute / getProperty / getCssPropertyGET /session/:sessionId/element/:elementId/{attribute,property,css}/:name属性/特性/CSS 计算值不存在时返回nullgetText / getName / getElementRectGET /session/:sessionId/element/:elementId/{text,name,rect}文本含子元素、标签名、尺寸坐标getComputedRole / getComputedLabelGET /session/:sessionId/element/:elementId/{computedrole,computedlabel}WAI-ARIA 计算角色 / 可访问名称元素交互、脚本与提示框端点方法与路径说明click / clear / setValuePOST /session/:sessionId/element/:elementId/{click,clear,value}点击 / 清空 / 输入setValue参数textgetPageSourceGET /session/:sessionId/source获取 HTML/XML 格式的页面/应用源码execute / executeAsyncPOST /session/:sessionId/execute/{sync,async}同步/异步执行 JS参数scriptargs异步脚本额外收到一个完成回调函数其第一个入参即为响应值getCookies / getCookie / setCookie / deleteCookie(s)GET/POST/DELETE /session/:sessionId/cookie*Cookie 增删查Cookie 对象字段含name、value、domain?、path?、expiry?Unix 秒级时间戳、httpOnly?、secure?、sameSite?Lax或StrictperformActions / releaseActionsPOST/DELETE /session/:sessionId/actions执行 W3C 动作序列ActionSequence[]/ 释放所有已按下按键与指针按钮postDismissAlert / postAcceptAlertPOST /session/:sessionId/alert/{dismiss,accept}关闭/接受当前用户提示框getAlertText / setAlertTextGET/POST /session/:sessionId/alert/text获取/设置提示框文本截图与打印端点方法与路径响应getScreenshotGET /session/:sessionId/screenshotbase64 编码的 PNGgetElementScreenshotGET /session/:sessionId/element/:elementId/screenshot元素包围矩形区域截图base64 PNGprintPagePOST /session/:sessionId/printbase64 编码的 PDFprintPage支持丰富的打印参数均为可选并带默认值参数说明默认值orientation?页面方向portrait/landscapeportraitscale?页面缩放范围[0.1, 2]1background?是否包含背景图falsepage?页面尺寸对象PrintPageSizewidth?≥ 2.54/72默认 21.59、height?≥ 2.54/72默认 27.94{}margin?页边距对象PrintPageMarginstop/bottom/left/right?均 ≥ 0默认1{}shrinkToFit?是否按PrintPageSize.width缩放内容truepageRanges?打印页码范围如[1, 4, 8-9][]Appium 协议扩展端点appium.md 定义了 Appium 在 W3C WebDriver 之上扩展出的端点。这些端点是移动自动化场景的核心能力来源会话元信息与设置端点方法与路径说明getAppiumSessionsGET /appium/sessions列出所有活跃会话id、capabilities、created毫秒时间戳。必须启用session_discovery不安全特性才可用getAppiumSessionCapabilitiesGET /session/:sessionId/appium/capabilities获取会话能力返回{capabilities}getSettings / updateSettingsGET/POST /session/:sessionId/appium/settings获取/更新会话设置更新时只改指定项其余保持不变listCommandsGET /session/:sessionId/appium/commands列出当前会话支持的全部 URL 端点与 BiDi 命令按来源分组Appium 基础 / driver / 插件结构见 packages/types/lib/commands/appium.tslistExtensionsGET /session/:sessionId/appium/extensions列出当前会话支持的 execute methods按 driver/插件分组事件日志端点方法与路径说明getLogEventsPOST /session/:sessionId/appium/events获取会话事件历史参数type?字符串或字符串数组可按类型过滤logCustomEventPOST /session/:sessionId/appium/log_event记录自定义事件参数vendor命名空间前缀event事件名getLogEvents默认记录 driver 命令执行driver/插件可定义额外事件类型。响应对象EventHistory的键即事件类型分三类{ commands: [ { cmd: getStatus, startTime: 1756887645447, endTime: 1756887645454 } ], driverevent: [1756887645454], namespace:event: [1756887645454] }commands键始终存在数组元素含cmd命令名、startTime/endTime毫秒 Unix 时间戳其他无命名空间键由 driver/插件实现自定义值为事件时间戳数组命名空间键namespace:event可通过logCustomEvent添加driver/插件也可能自带。上下文Context管理端点方法与路径响应getCurrentAppiumContextGET /session/:sessionId/appium/context当前活跃上下文名setAppiumContextPOST /session/:sessionId/appium/context参数namenullgetAppiumContextsGET /session/:sessionId/appium/contexts可用上下文名数组设备与应用生命周期端点方法与路径关键参数 / 响应getDeviceTimePOST /session/:sessionId/appium/device/system_timeformat?默认YYYY-MM-DDTHH:mm:ssZactivateAppPOST .../appium/device/activate_appappId或bundleIdoptions?terminateAppPOST .../appium/device/terminate_app同上queryAppStatePOST .../appium/device/app_state返回整数0未安装1未运行2后台挂起3后台运行4前台运行installAppPOST .../appium/device/install_appappPath本地绝对路径或 URLoptions?removeAppPOST .../appium/device/remove_app返回booleanisAppInstalledPOST .../appium/device/app_installed返回booleanhideKeyboardPOST .../appium/device/hide_keyboardkey?、keyCode?、keyName?、strategy?返回boolean部分平台可能永不返回falseisKeyboardShownGET .../appium/device/is_keyboard_shown返回booleanpushFilePOST .../appium/device/push_filedataBase64path设备端目标路径pullFilePOST .../appium/device/pull_filepath返回文件内容的 Base64pullFolderPOST .../appium/device/pull_folderpath返回目录打包为 zip 后的 Base64getAppiumRotation / setAppiumRotationGET/POST .../appium/device/rotation三维旋转角x/y/z度数getAppiumOrientation / setAppiumOrientationGET/POST .../appium/device/orientationPORTRAIT或LANDSCAPE以上端点路径均以POST /session/:sessionId/appium/device/...为前缀除特别说明外。WebDriver BiDi 命令bidi.md 列出的 WebDriver BiDi 命令与 URL 端点不同——它们是以 WebSocket 事件形式发送的命令driver 和 client 双方都可以发出或监听命令说明参数session.status获取 Appium 服务当前状态响应结构同 WebDriver 的getStatus-session.subscribe订阅一个或多个 BiDi 事件events事件名数组必填contexts?订阅作用域默认全局[]session.unsubscribe退订一个或多个 BiDi 事件参数同上遗留 JSON Wire 协议端点jsonwp.md 记录了 Appium 仍兼容的 JSONWP 遗留端点。其中大部分已被标记弃用官方给出了明确的迁移替代遗留端点方法与路径弃用替代getSessionGET /session/:sessionId获取能力请用getAppiumSessionCapabilities获取事件历史请用getLogEvents注意若设置appium:eventTimingscapability 为true响应会额外携带events键availableIMEEnginesGET /session/:sessionId/ime/available_engines未来将移入 UiAutomator2/Espresso drivergetActiveIMEEngineGET /session/:sessionId/ime/active_engine同上isIMEActivatedGET /session/:sessionId/ime/activated同上deactivateIMEEnginePOST /session/:sessionId/ime/deactivate同上activateIMEEnginePOST /session/:sessionId/ime/activate参数engine同上getOrientation / setOrientationGET/POST /session/:sessionId/orientationgetAppiumOrientation/setAppiumOrientationgetGeoLocation / setGeoLocationGET/POST /session/:sessionId/locationLocation{altitude, latitude, longitude}driver 专属扩展方法如mobile: getGeoLocation、mobile: setSimulatedLocation新建项目应直接使用 Appium 协议端点或 driver 扩展方法避免再依赖 JSONWP 路由。官方插件提供的端点plugins.md 汇总了官方插件新增或修改的端点Execute Driver 插件executeDriverScriptPOST /session/:sessionId/appium/execute_driver在子进程中执行 driver 脚本参数说明默认值script要执行的脚本-type?执行脚本的库名webdriveriotimeout?脚本进程超时毫秒3600000响应RunScriptResult含result脚本返回值与logs执行日志。Images 插件compareImagesPOST /session/:sessionId/appium/compare_images按三种模式比较图像——matchFeatures判断firstImage是否为secondImage的旋转/缩放/变换版本。options 支持detectorName?OpenCV 特征检测器AKAZE、AgastFeatureDetector、BRISK、FastFeatureDetector、GFTTDetector、KAZE、MSER、ORB默认ORB、goodMatchesFactor?、matchFunc?FlannBased/BruteForce系列默认BruteForce、visualize?默认false。matchTemplate判断firstImage是否包含secondImage的一个或多个实例。options 支持method?TM_CCOEFF、TM_CCOEFF_NORMED、TM_CCORR、TM_CCORR_NORMED、TM_SQDIFF、TM_SQDIFF_NORMED默认TM_CCOEFF_NORMED、threshold?默认0.5、multiple?默认false、matchNeighbourThreshold?默认10、visualize?。getSimilarity对等尺寸图像计算相似度分数0.0–1.0。各模式响应均含匹配点/包围矩形rect{x, y, width, height}、score与可选的visualization图像。修改findElement/findElements为using定位策略参数新增-image取值实现图像定位。修改performActions当动作中的origin是图像元素时会移除origin并把x/y偏移为该图像元素的中心坐标。Relaxed Caps 插件修改createSession对capabilities中的键自动补加appium:前缀除非该键已是标准 W3C 能力或已带任意前缀。Storage 插件所有端点无需创建会话即可调用适合预先准备测试环境。插件 1.2.0 之前的/storage前缀路由如/storage/add仍可用但已弃用将在未来版本移除端点方法与路径说明addStorageItemPOST /appium/storage/add参数name不得含路径分隔符sha1响应含ttlMsWebSocket 存活/上传成功窗口毫秒、ws.stream内容流上传路径、ws.events成功/失败通知路径deleteStorageItemPOST /appium/storage/delete参数name返回boolean文件不存在或请求无效时为falselistStorageItemsGET /appium/storage/list返回{name, path, size}列表resetStoragePOST /appium/storage/reset删除全部已上传文件并中断未完成上传若设置APPIUM_STORAGE_KEEP_ALL环境变量则保留全部文件仅停止未完成上传addStorageItem的响应示例{ ws: { stream: /appium/storage/add/ccc963411b2621335657963322890305ebe96186/stream, events: /appium/storage/add/ccc963411b2621335657963322890305ebe96186/events }, ttlMs: 300000 }Universal XML 插件修改findElement/findElementsvalue选择器参数支持跨平台的通用节点/属性名修改getPageSource在获取页面源码后将节点/属性名转换为通用名称。调用建议与深入阅读优先使用 client 封装直接调用 HTTP 端点主要用于调试与元信息发现如listCommands、getLogEvents日常测试请通过各语言的 Appium client 发起请求。端点能力自省运行时可通过GET /session/:sessionId/appium/commands与/appium/extensions动态枚举当前 driver 插件组合实际暴露的全部端点这是排查“端点不支持”类问题最直接的手段。继续深入端点协议定义细节webdriver.md、appium.md、jsonwp.md、bidi.md会话与能力概念caps 指南、event-timing 指南、context 指南路由与参数校验实现protocol.ts、routes 目录【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Appium API 端点参考指南：W3C WebDriver、Appium 协议扩展与官方插件端点体系

相关推荐

brpc benchmark_http 压测工具：用 brpc 高性能 HTTP 客户端压测 HTTP 服务极限

APQP系统如何通过数字化实现研发降本增效

SLAM回环检测原理与工程实践：从词袋模型到ORB-SLAM应用解析

更多资讯

LangChain4j中文Embedding模型选型与实践指南

CS武器Mod SPR文件制作与图显异常排查全攻略

华为OD Python机试满分实战指南：OJ环境适配与工程化编码

如何使用 spacetime dev 创建 SpacetimeDB 项目并开启热重载开发

4GB显存也能跑70B大模型？AirLLM分层推理原理与实操指南

职场妈妈数字技能提升与变现全攻略

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？