fix(appium): rename deprecated Appium protocol commands for Appium 3 compatibility#15141
Conversation
…m 3 compatibility Addresses #15124 — Appium 3 removed/deprecated JSONWP-era endpoints. Changes in this commit (protocol layer, first step): - Rename 37 protocol commands that have a `mobile:` replacement by prefixing them with `appium` (e.g. `lock` → `appiumLock`, `getCurrentPackage` → `appiumGetCurrentPackage`). The original clean names are reserved for upcoming mobile command wrappers with Appium 3 try/catch fallback logic. - Add `deprecated` notices to commands that were previously missing them: `startRecordingScreen`, `stopRecordingScreen`, `rotateDevice`, and all five IME commands. - Commands with no known `mobile:` replacement (`rotateDevice`, IME commands, JSONWP touch commands, etc.) keep their original names with an updated generic deprecation message. - Update internal call sites that referenced old protocol command names (`getCurrentPackage`, `stopRecordingScreen`) to the new `appium*` names with TODO comments pointing to the upcoming mobile command implementations. - Update tests accordingly with TODO comments. Next steps (tracked via TODOs): - Implement mobile command wrappers with try/catch fallback for each renamed command so Appium 2 users on older drivers are not broken. - Update `packages/wdio-protocols/src/commands/appium.ts` interface to reflect the renamed commands. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
create-wdio
eslint-plugin-wdio
@wdio/allure-reporter
@wdio/appium-service
@wdio/browser-runner
@wdio/browserstack-service
@wdio/cli
@wdio/concise-reporter
@wdio/config
@wdio/cucumber-framework
@wdio/dot-reporter
@wdio/firefox-profile-service
@wdio/globals
@wdio/jasmine-framework
@wdio/json-reporter
@wdio/junit-reporter
@wdio/lighthouse-service
@wdio/local-runner
@wdio/logger
@wdio/mocha-framework
@wdio/protocols
@wdio/repl
@wdio/reporter
@wdio/runner
@wdio/sauce-service
@wdio/shared-store-service
@wdio/smoke-test-cjs-service
@wdio/smoke-test-reporter
@wdio/smoke-test-service
@wdio/spec-reporter
@wdio/static-server-service
@wdio/sumologic-reporter
@wdio/testingbot-service
@wdio/types
@wdio/utils
@wdio/webdriver-mock-service
@wdio/xvfb
webdriver
webdriverio
commit: |
wswebcreation
added
the
PR: Polish 💅
`/appium/device/app_state` is removed in Appium 3. Rename to `appiumQueryAppState` to reserve the clean `queryAppState` name for the future mobile command wrapper with try/catch fallback. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Implements the `lock` mobile command that tries `mobile: lock` first (Appium 3 / modern drivers) and falls back to the deprecated `appiumLock` protocol endpoint for older Appium 2 drivers, logging a deprecation warning on fallback. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
- new UTs - generic methods
…uards and docs support - Add 37 new mobile command wrappers that call the modern `mobile:` execute API and automatically fall back to the deprecated Appium 2 protocol endpoints for older drivers - Throw platform-specific errors for iOS-only and Android-only commands, with hints to the equivalent command on the other platform (e.g. `touchId` → `fingerPrint` and vice versa) - Add `@support` JSDoc tag to all new commands and update the docs formatter and template to render platform icons (iOS/Android) with a link to the official Appium driver documentation for version details - Add full unit test coverage for all new commands including non-mobile, wrong platform, modern driver, and legacy fallback scenarios - update docs and fix MDX generation errors
…recated-endpoints
|
From the below, does that mean that until people migrate to Appium 3, there will be a non-working call followed by a working one that falls back on Appium 2?
If so, is there any better way to do this so it is not constantly doing "failing request"?
Note:
|
|
Thanks for the feedback. In theory you are right, but...
Hope this makes sense |
wswebcreation
added
PR: New Feature 🚀
|
Hi, I'd love to assist with this from Appium side, especially since Appium Inspector uses WDIO under-the-hood and entirely depends on its supported endpoints and commands. The described implementation approach generally seems good to me. I suppose it may also make sense to drop support for group 3 users in WDIO v10, but that's up to you. One thing I would like to point out is that Claude seems to have made a few mistakes regarding removed commands:
|
|
Hi @eglitise Thanks for looking into this and for the feedback. This wasn't all Claude, it's just so helpful when fixing a lot of commands in the same way 🤣 , but in the analysis part Claude and I missed a few things you pointed out. Here's my feedback
Thanks, the challenge here is that a lot of cloudvendors don't have updated drivers, or they have the old drivers connected to old OS versions. So we want to still be "backwards compatible"
We need to soften the message, but we will proced with introducing the same command names with the `mobile: equivelant so we are ready
will revert this
This is what is in the docs I see that the new command implementation isn't platform specific, so I need to fix that
This was my bad, will fix this |
…ssages - Fix `mobile: fingerPrint` → `mobile: fingerprint` (all lowercase, as registered in appium-android-driver) - Fix `mobile: setNetworkSpeed` → `mobile: networkSpeed` (correct UiAutomator2 command name) - Implement platform-specific screen recording commands - Remove incorrect `deprecated` field from `rotateDevice` — command is still available in Appium 3 - Soften IME deprecated messages: replace incorrect "not supported in Appium 3" claim and `mobile: shell` workarounds with a neutral "deprecated, check driver docs" notice - Update tests
|
See the fixes. This should fix all points there were mentioned by you |
To clarify, these commands are only deprecated in the main Appium server (since they are platform-specific), but they are not deprecated in the UiAutomator2/Espresso drivers (which are the only drivers where these commands are relevant), so the WDIO command will still work the same way once they are removed from the Appium server. That's why I suggest leaving them unchanged for now. If the Appium team decides to later deprecate them in the drivers and add
Yes, it says that the endpoints have been moved to drivers, which includes all the main ones, so they are effectively still supported, and there's no need to change the WDIO implementation. Also, |
This means the endpoint is passed directlty from the server to the driver?
Ok, I'll revert it, thanks |
Essentially, yes. The endpoints supported by the server are actually defined in the Appium base driver, which is a core dependency for all other drivers. As a result, drivers have access to the full set of these base driver endpoints, and can extend it with endpoints with their own. And when a session is started, the supported endpoints are retrieved from the driver directly. |
Thanks! That makes it more clear. I've reverted all commands we discussed and will push it to this branch. If you then don't have any remarks then I'll merge it |
- Restore `startRecordingScreen` and `stopRecordingScreen` - Remove the incorrectly added mobile command wrappers for screen recording - Remove their exports from `browser.ts` and `mobile.ts` - remove deprecated messages for IME commands
|
@wswebcreation sorry, I had missed one more issue - the |
|
ok, I'll remove that one, thanks |
3 participants
Important
After merge and release we should also release the docs
Related issue
Closes #15124
Summary
Appium 3 removed ~90 JSONWP-era endpoints from
base-driver. This PR contains multiple steps/fixes to make WebdriverIO compatible with Appium 3 while keeping backward compatibility with Appium 2 users on older drivers.Research
Most of the research is in #15124. Here's a summary
Backward Compatibility &
mobile:Command AvailabilityAfter further research into the driver changelogs, a clearer picture emerged on how to handle backward compatibility with Appium 2.
When were the
mobile:replacements introduced?For UIAutomator2 (Android), all relevant
mobile:replacement commands (mobile: lock,mobile: unlock,mobile: isLocked,mobile: getCurrentPackage,mobile: getCurrentActivity,mobile: pressKey,mobile: gsmCall,mobile: getPerformanceData,mobile: getSystemBars,mobile: openNotifications, etc.) were available before January 2024 — added progressively in UIAutomator2 v2.17–v2.24 (April–May 2023).For XCUITest (iOS), the same applies for most commands. The one exception is
mobile: startXCTestScreenRecording/mobile: stopXCTestScreenRecording, which landed in XCUITest v7.3.0 (March 2024).What this means
There are three user groups
mobile:would failmobile:mobile:onlyThe group that would break if WDIO switched unconditionally to
mobile:is Appium 2 users on drivers from 2023 or earlier. This is a small and shrinking group, but worth protecting.Chosen approach: try/catch with specific error handling
WDIO will attempt the
mobile:execute path first. If the driver responds with an "unknown command" error (meaning the driver is too old to support it), WDIO falls back to the old endpoint and logs a clear deprecation warning. Any other error (device disconnected, wrong parameters, etc.) is re-thrown immediately and not swallowed by the catch.This means:
mobile:succeeds, no warning, no double callmobile:also succeeds, same as abovemobile:fails with unknown command → caught → falls back to old endpoint → deprecation warning logged onceThe deprecation warning will tell users which driver they need to upgrade to to remove the old endpoint dependency.
What this PR does (protocol layer)
mobile:replacement by prefixing them withappium(e.g.lock→appiumLock,getCurrentPackage→appiumGetCurrentPackage). The original clean names are reserved for upcoming mobile command wrappers with try/catch fallback logic.deprecatednotices tostartRecordingScreen,stopRecordingScreen,rotateDevice, and all five IME commands.mobile:replacement (rotateDevice, IME commands, JSONWP touch commands) keep their original names with a generic deprecation message.getContexts,switchContext,relaunchActiveApp,saveRecordingScreen) that used old protocol names, with TODO comments pointing to the upcoming mobile command implementations.Architecture decision
Two-layer strategy:
appium, marked deprecatedmobile:execute first, catch "unknown command" errors, fall back to theappium*protocol endpoint for Appium 2 backward compat, and log a deprecation warningThis means users calling e.g.
driver.lock()will transparently get the Appium 3-compatible implementation via the mobile command layer, with no breaking changes.Commands renamed (37 total)
shakeappiumShakeshakelockappiumLocklockunlockappiumUnlockunlockisLockedappiumIsLockedisLockedstartRecordingScreenappiumStartRecordingScreenstartRecordingScreenstopRecordingScreenappiumStopRecordingScreenstopRecordingScreengetCurrentPackageappiumGetCurrentPackagegetCurrentPackagegetCurrentActivityappiumGetCurrentActivitygetCurrentActivitypressKeyCodeappiumPressKeyCodepressKeyCodelongPressKeyCodeappiumLongPressKeyCodelongPressKeyCodebackgroundappiumBackgroundbackgroundlaunchAppappiumLaunchApplaunchAppcloseAppappiumCloseAppcloseAppgetStringsappiumGetStringsgetStringsgetSystemBarsappiumGetSystemBarsgetSystemBarsgetDisplayDensityappiumGetDisplayDensitygetDisplayDensityopenNotificationsappiumOpenNotificationsopenNotificationsstartActivityappiumStartActivitystartActivitytouchIdappiumTouchIdtouchIdtoggleEnrollTouchIdappiumToggleEnrollTouchIdtoggleEnrollTouchIdtoggleAirplaneModeappiumToggleAirplaneModetoggleAirplaneModetoggleDataappiumToggleDatatoggleDatatoggleWiFiappiumToggleWiFitoggleWiFitoggleLocationServicesappiumToggleLocationServicestoggleLocationServicestoggleNetworkSpeedappiumToggleNetworkSpeedtoggleNetworkSpeedgsmCallappiumGsmCallgsmCallgsmSignalappiumGsmSignalgsmSignalgsmVoiceappiumGsmVoicegsmVoicepowerCapacityappiumPowerCapacitypowerCapacitypowerACappiumPowerACpowerACsendSmsappiumSendSmssendSmsfingerPrintappiumFingerPrintfingerPrintsetClipboardappiumSetClipboardsetClipboardgetClipboardappiumGetClipboardgetClipboardgetPerformanceDataTypesappiumGetPerformanceDataTypesgetPerformanceDataTypesgetPerformanceDataappiumGetPerformanceDatagetPerformanceDatasendKeyEventappiumSendKeyEventpressKeyCodeTest plan
packages/wdio-protocols/src/commands/appium.tsupdated to new names (follow-up)