Appium W3C 扩展协议完整指南：会话、设置、上下文与设备操作端点解析

Appium W3C 扩展协议完整指南会话、设置、上下文与设备操作端点解析【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appiumAppium 在标准 W3C WebDriver 协议之外扩展了一组专属端点覆盖会话管理、会话设置、上下文切换、事件日志以及设备级应用/文件/键盘/旋转操作。本文以 packages/appium/docs/zh/reference/api/appium.md 为骨架结合 路由定义源码 与 AppiumDriver 实现 逐端点讲解请求方法、参数与响应结构帮助读者在测试框架或脚本中直接调用这些扩展能力。协议背景W3C WebDriver 之上的 Appium 扩展层Appium 服务端本质上是 W3C WebDriver 协议的一个实现同时叠加了驱动与插件体系。除了标准端点外Appium 扩展层提供了一批以/appium为前缀的专属路由用于处理标准协议未覆盖的场景。这些路由集中定义在 appium.ts会话/设置/内省类与 appium-device.ts设备交互类两个路由表中并由顶层的AppiumDriver伞形驱动及其承载的底层驱动如 fake-driver、uiautomator2、xcuitest实现。按功能可划分为四组分组端点前缀覆盖能力会话管理/appium/sessions、/session/:sessionId/appium/capabilities查看活动会话、读取会话 capabilities会话设置/session/:sessionId/appium/settings读写会话级设置项能力内省/session/:sessionId/appium/commands、/extensions列出当前会话支持的 REST/BiDi 命令与 execute 方法上下文/session/:sessionId/appium/context(s)切换与枚举应用上下文事件日志/session/:sessionId/appium/events、/log_event记录与查询事件时间线设备操作/session/:sessionId/appium/device/*应用安装/启停/状态、键盘、文件传输、旋转与方向、系统时间从源码看路由表通过payloadParams.required/optional声明各端点的参数约束例如/session/:sessionId/appium/device/activate_app要求appId与bundleId二选一必填写成required: [[appId], [bundleId]]options可选。这种声明在请求到达命令处理器之前就完成参数校验。会话管理端点getAppiumSessions枚举所有活动会话GET /appium/sessions返回服务器上所有活动会话的信息。注意该端点默认被安全策略拦截必须显式开启session_discovery这一 insecure feature 才能使用详见 安全指南。响应类型为TimestampedMultiSessionData[]即会话数据对象数组NameDescriptionTypecapabilities会话 capabilitiesobjectcreated会话创建时间Unix 毫秒时间戳numberid会话 IDstring对应实现位于 appium.ts方法先调用this.assertFeatureEnabled(SESSION_DISCOVERY_FEATURE)随后遍历伞形驱动维护的this.sessions表为每个活动会话组装{id, created, capabilities}。SESSION_DISCOVERY_FEATURE的常量定义见 constants.ts值为session_discovery。开启方式以 CLI 为例appium --allow-insecuresession_discovery关于 insecure feature 的完整机制可阅读 insecure-features.ts--allow-insecure传入的条目须满足自动化名:特性名格式*通配符表示作用于所有驱动--relaxed-security会一次性放开全部特性--deny-insecure则显式关闭指定项并拥有最高优先级。getAppiumSessionCapabilities读取会话 capabilitiesGET /session/:sessionId/appium/capabilities返回创建会话时协商确定的 session capabilities。响应为SessionCapabilities对象包含capabilitiesobject会话能力集合一个字段。会话设置端点getSettings读取当前设置GET /session/:sessionId/appium/settings返回当前会话的全部设置项。响应Settings为“设置名 → 值”的映射对象。会话设置是驱动运行时可调的键值对典型如ignoreUnimportantViews、waitForIdleTimeout等详见 settings 指南。updateSettings更新指定设置POST /session/:sessionId/appium/settings更新指定的会话设置未被更新的已有设置保持不变增量更新语义。参数NameDescriptionTypesettings待更新的设置名与值组成的对象object响应为null。路由表中该端点声明payloadParams: {required: [settings]}即settings为必填参数。典型调用示例curl -X POST $APPIUM/session/$SESSION_ID/appium/settings \ -H Content-Type: application/json \ -d {settings: {waitForIdleTimeout: 1000}}能力内省端点这两个端点面向“会话到底支持什么”的运行时发现场景返回值可直接用于构建通用客户端或调试面板。类型定义可参考 基于驱动命令的类型声明实现位于 inspector-commands.ts。listCommands列出会话支持的 REST 与 BiDi 命令GET /session/:sessionId/appium/commands返回当前会话支持的 URL 端点与 WebDriver BiDi 命令并按来源分组。响应类型为ListCommandsResponse结构大致为restREST 端点信息按baseAppium 基础命令、driver驱动特有命令、plugins插件注册的命令分组bidiBiDi 命令同样按base/driver/plugins分组每个命令项包含命令名、是否弃用deprecated、说明info及参数声明params含 required 标记。从实现看listCommands在传入sessionId时会通过this.driverForSession(sessionId)与this.pluginsForSession(sessionId)动态取出该会话绑定的驱动类与插件类再聚合其newMethodMap、newBidiCommands不传 sessionId 时仅返回基础层信息。listExtensions列出会话支持的 execute 方法GET /session/:sessionId/appium/extensions返回当前会话支持的 execute 方法即通过driver.executeScript/ W3C 的execute能力调用的扩展方法按来源分组为driver驱动特有与plugins插件注册。响应类型为ListExtensionsResponse与listCommands的 REST 部分结构一致。实现中聚合的是驱动类与插件类的executeMethodMap。上下文端点上下文context用于区分混合应用中不同的运行环境典型如原生视图与 WebView。三个端点组成完整的上下文查询/切换闭环getCurrentAppiumContext读取当前上下文GET /session/:sessionId/appium/context返回当前活动上下文的名称string。setAppiumContext设置活动上下文POST /session/:sessionId/appium/context将指定上下文设为活动上下文。参数NameDescriptionTypename要激活的上下文名称string响应为null。路由表声明name必填。getAppiumContexts枚举可用上下文GET /session/:sessionId/appium/contexts返回所有可用上下文的名称数组string[]。事件日志端点事件日志用于记录会话生命周期内发生的里程碑事件为耗时分析与性能诊断提供时间线数据相关概念可参考 event-timing 指南。getLogEvents获取会话事件历史POST /session/:sessionId/appium/events返回当前会话已记录的事件。默认情况下只有驱动命令执行会被记录驱动或插件可定义额外事件类型客户端也可通过logCustomEvent端点主动写入事件。参数NameDescriptionTypetype?用于过滤返回事件的一个或多个类型string 或 arraystring响应为EventHistory对象键对应事件类型。事件分为三类示例如下{ commands: [ { cmd: getStatus, startTime: 1756887645447, endTime: 1756887645454 } ], driverevent: [1756887645454], namespace:event: [1756887645454] }commands键始终存在值为对象数组每个对象含三个字段cmd执行的命令名、startTime命令开始时间Unix 毫秒、endTime命令结束时间Unix 毫秒其他非命名空间键为驱动/插件实现特有值是事件时间Unix 毫秒数组命名空间键形如namespace:event可通过logCustomEvent写入也可由驱动/插件直接提供值同样是事件时间数组。实现位于 event.tsgetLogEvents在未传type或传入空值时返回完整事件历史否则只返回与指定类型匹配的条目。logCustomEvent写入自定义事件POST /session/:sessionId/appium/log_event记录一个自定义事件随后可通过getLogEvents检索。参数NameDescriptionTypevendor用于事件前缀的命名空间供应商名stringevent事件名string响应为null。实现中该方法将vendor与event拼接为vendor:event形式写入事件日志event.ts因此最终事件键呈现为命名空间风格。vendor、event均为必填参数。设备操作端点应用生命周期以下端点均以/session/:sessionId/appium/device/为前缀。应用标识参数appIdAndroid 包名与bundleIdiOS Bundle ID在源码路由表中均为“二选一必填”约束。options为驱动特有选项含义由具体驱动定义。activateApp激活应用POST /session/:sessionId/appium/device/activate_app将应用带到前台并激活。NameDescriptionTypeappId或bundleId应用标识Android 包名 / iOS Bundle IDstringoptions?驱动特有的启动选项unknown响应为void。terminateApp终止应用POST /session/:sessionId/appium/device/terminate_app终止正在运行的应用。NameDescriptionTypeappId或bundleId应用标识stringoptions?驱动特有的终止选项unknown响应为void。queryAppState查询应用状态POST /session/:sessionId/appium/device/app_state返回应用当前状态对应的整数NumberApp State0未安装Not installed1未运行Not running2后台挂起Running in background suspended3后台运行Running in background4前台运行Running in foreground参数为appId或bundleId响应为number。installApp安装应用POST /session/:sessionId/appium/device/install_appNameDescriptionTypeappPath应用文件的绝对本地路径或 URLstringoptions?驱动特有的安装选项unknown响应为void。appPath必填。removeApp卸载应用POST /session/:sessionId/appium/device/remove_appNameDescriptionTypeappId或bundleId应用标识stringoptions?驱动特有的卸载选项unknown响应为booleantrue表示卸载成功否则为false。isAppInstalled检查应用是否已安装POST /session/:sessionId/appium/device/app_installed参数为appId或bundleId响应为boolean已安装返回true否则false。设备操作端点键盘、文件与系统hideKeyboard隐藏虚拟键盘POST /session/:sessionId/appium/device/hide_keyboard尝试隐藏被测设备上的虚拟键盘参数均为可选NameDescriptionTypekey?用于隐藏键盘的按键文本stringkeyCode?触发隐藏的键码stringkeyName?用于隐藏键盘的键名stringstrategy?驱动特有的隐藏策略名string响应为boolean操作成功返回true否则false。需要注意部分平台可能永远不会返回false例如该平台对“隐藏”操作总是静默成功。isKeyboardShown检查键盘是否显示GET /session/:sessionId/appium/device/is_keyboard_shown响应为boolean键盘显示返回true否则false。pushFile向设备写入文件POST /session/:sessionId/appium/device/push_fileNameDescriptionTypedata写入文件的 Base64 编码数据stringpath设备上要创建文件的远程路径string响应为void。path与data均必填。pullFile从设备拉取文件POST /session/:sessionId/appium/device/pull_fileNameDescriptionTypepath设备上文件的远程路径string响应为string即文件内容的 Base64 编码。pullFolder拉取目录压缩包POST /session/:sessionId/appium/device/pull_folderNameDescriptionTypepath设备上目录的远程路径string响应为string即目录内容压缩后的 Base64 编码 ZIP。getAppiumRotation / setAppiumRotation空间旋转GET /session/:sessionId/appium/device/rotation POST /session/:sessionId/appium/device/rotationgetAppiumRotation返回设备当前空间朝向响应为Rotation对象NameDescriptionTypex设备绕 X 轴旋转的角度度numbery设备绕 Y 轴旋转的角度度numberz设备绕 Z 轴旋转的角度度numbersetAppiumRotation以同样三个参数x、y、z均必填设置朝向响应为null。这一端点常用于平板、折叠屏等支持多轴旋转的设备。getAppiumOrientation / setAppiumOrientation屏幕方向GET /session/:sessionId/appium/device/orientation POST /session/:sessionId/appium/device/orientationgetAppiumOrientation返回当前屏幕方向响应为string取值PORTRAIT或LANDSCAPE。setAppiumOrientation设置屏幕方向参数NameDescriptionTypeorientation新方向支持PORTRAIT或LANDSCAPEstring响应为null。getDeviceTime获取设备系统时间POST /session/:sessionId/appium/device/system_time返回被测设备的当前系统时间。注意在路由源码中该路径同时注册了GET与POST两种方法见 appium-device.tsPOST支持可选参数format。NameDescriptionTypeDefaultformat?返回时间戳使用的格式stringYYYY-MM-DDTHH:mm:ssZ响应为string设备时间字符串。该端点常用于脚本中校验设备时钟偏差或与宿主机器时间对齐。端点总览与调用建议端点方法核心参数返回值/appium/sessionsGET无需session_discovery特性TimestampedMultiSessionData[]/session/:sessionId/appium/capabilitiesGET无SessionCapabilities/session/:sessionId/appium/settingsGET / POSTsettingsPOST 必填Settings/null/session/:sessionId/appium/commandsGET无ListCommandsResponse/session/:sessionId/appium/extensionsGET无ListExtensionsResponse/session/:sessionId/appium/context(s)GET / POSTnamePOST 必填string/string[]/null/session/:sessionId/appium/eventsPOSTtype?EventHistory/session/:sessionId/appium/log_eventPOSTvendor、event必填null/session/:sessionId/appium/device/activate_appPOSTappId或bundleIdvoid/session/:sessionId/appium/device/terminate_appPOSTappId或bundleIdvoid/session/:sessionId/appium/device/app_statePOSTappId或bundleIdnumber0–4/session/:sessionId/appium/device/install_appPOSTappPathvoid/session/:sessionId/appium/device/remove_appPOSTappId或bundleIdboolean/session/:sessionId/appium/device/app_installedPOSTappId或bundleIdboolean/session/:sessionId/appium/device/hide_keyboardPOSTkey?/keyCode?/keyName?/strategy?boolean/session/:sessionId/appium/device/is_keyboard_shownGET无boolean/session/:sessionId/appium/device/push_filePOSTdata、path必填void/session/:sessionId/appium/device/pull_filePOSTpath必填stringBase64/session/:sessionId/appium/device/pull_folderPOSTpath必填stringBase64 ZIP/session/:sessionId/appium/device/rotationGET / POSTx/y/zPOST 必填Rotation/null/session/:sessionId/appium/device/orientationGET / POSTorientationPOST 必填string/null/session/:sessionId/appium/device/system_timeGET / POSTformat?string实际使用时有几点建议会话级端点都要求有效的sessionId只有/appium/sessions是无会话端点且受session_discovery特性保护appId/bundleId二选一是路由层的硬性校验required: [[appId], [bundleId]]不要同时省略设备操作的具体行为依赖驱动实现同一个端点在不同驱动如 uiautomator2 与 xcuitest下的选项与语义可能有差异options参数请以对应驱动文档为准仓库内置的 fake-driver 的 general.ts 提供了这些命令的最小可运行实现可作为阅读参考能力内省端点适合在编写通用框架时动态探测目标会话支持的命令集与 execute 方法避免硬编码协议表。借助以上端点测试框架可以在标准 WebDriver 能力之外完成会话审计、设置调优、混合应用上下文切换、应用生命周期管理、设备文件交换与事件时间线分析等端到端任务。若需进一步了解 capabilities、settings 与 execute methods 的定义可继续阅读 caps.md、settings.md 与 execute-methods.md。【免费下载链接】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），仅供参考