What's Cooking in Appium 4

What Changes

If your suite runs clean on Appium 3.8 with no deprecation warnings, your test code probably needs no edits. The changes below are the ones that can surface in a real suite, with what you will see and what to do.

One cross-driver detail is worth knowing. The server no longer validates locale, language, autoWebview, orientation, udid, or autoLaunch itself. The XCUITest, UiAutomator2, and Android drivers declare the ones they support, so the capabilities keep working. A capability a driver never supported will now be rejected rather than silently accepted.

What You Gain

The feature list is deliberately short, but several changes improve day-to-day reliability.

• Health checks answer during long commands. GET /status no longer waits in the driver's command queue, so a grid or orchestrator polling status sees the server, not the slowest running command.
• Idle timeouts stop misfiring. The newCommandTimeout timer is now suspended throughout the plugin chain during BiDi commands and until session setup is complete. Sessions will no longer die mid-command due to a plugin taking too long, and a failing cleanup can no longer bring down the server process.
• Errors are more honest. Driver selection failures report as session-not-created rather than a generic 500. A failed session init rolls back cleanly rather than leaving a ghost session. All timeout values are validated before any are applied. Queued commands get the correct invalid session error when the session times out rather than just hanging.
• BiDi works the way the spec says. Unsubscribe actually unsubscribes. Global and module-level subscriptions match correctly. Every current BiDi command is defined in the server for validation.
• You can restrict where apps download from. The new --app-url-rules option takes allow and deny lists for appium:app URLs, can force HTTPS, and caps redirects.
• A corrupt extension manifest resets with a warning instead of a confusing crash later, and concurrent appium driver commands lock the manifest so they cannot clobber each other. appium driver install now picks the newest version that is compatible with your server when the latest one is not.
• Windows gets a maintained driver. WinCore directly drives the Windows UI Automation APIs, supports UWP, WinForms, WPF, and Win32, and adds WebView2 support via the Chrome DevTools Protocol.
• Screen capture went native on both platforms. iOS simulator video recording, optional audio, and live JPEG streaming no longer shell out to simctl. On Android, the Appium Settings app can stream JPEG or H.264 video over an adb forward socket and follows device rotation. These landed in the shared libraries and benefit Appium 3 users too.
• iPhone Duo and multi-display support arrived in the XCUITest driver: mobile: getScreens, simulated hinge angle commands, and screenshot routing to the selected display. Simulator-verified so far.
• WebDriverAgent got faster. Page source is streamed straight to a buffer, XML serialization no longer rescans siblings, and accessibility-id lookups use native XCTest predicates. Memory no longer grows across abandoned sessions.

Real iOS Devices From Windows and Linux

The most consequential iOS change of the year is not in the Appium 4 server at all. It is appium-ios-remotexpc, a Node.js library that speaks Apple's Remote XPC protocol to real devices directly, with no Xcode in the path. The XCUITest driver uses it for every real device on iOS or tvOS 18 and later, which makes the driver's Non-macOS Hosts guide possible: a Windows or Linux machine driving a physical iPhone.

Why Apple Forced the Issue

On iOS and tvOS 18 and later, Apple routes many device services, including the XCTest ones the driver depends on, over IPv6-only interfaces and Remote XPC endpoints behind its CoreDevice stack. On a Mac, Xcode and devicectl hide all of that. On a Mac, there was nothing. The library reimplements the chain in Node:

• Talk to usbmuxd to find paired devices, over USB or over WiFi.
• Open a lockdown session and start Apple's CoreDeviceProxy service.
• Hand the resulting TLS socket to appium-ios-tuntap, which creates a virtual TUN interface on the host and routes an IPv6 tunnel through it. On Windows, it uses WinTun.
• Discover the device's RSD service catalog over the tunnel and expose it to the driver.

The RemoteXPC Tunnels guide lists what rides on top of it: general device communication on Windows and Linux, wireless Apple TV, log retrieval, network monitoring, certificate management, and native XCTest execution. The library's own README adds system log, diagnostics, and AFC file-system services, pair-record management, and Apple TV pairing over WiFi.

What Running It Looks Like

The tunnel runs as a separate, long-lived process because creating a TUN interface requires root privileges. You start it once per host, before any Appium server:

sudo appium driver run xcuitest tunnel-creation

It enumerates every paired device, builds a tunnel for each, and starts a small HTTP registry at http://localhost:<port>/remotexpc/tunnels that the driver reads automatically. No capability is needed to switch it on. If the package is installed, the registry is reachable, and the target is a real device on iOS or tvOS 18 or later, the driver uses it.

The script is multi-device aware, can be pinned to specific devices with --udid, can watch for devices attached later, and can retry dropped tunnels. One registry can support several Appium servers on the same host, and --tunnel-registry-port keeps separate containers or CI agents from fighting over it. appium driver run xcuitest list-real-devices shows what usbmuxd can see, wired and wireless.

On Windows and Linux, the guide is explicit about the limits. Only real devices, since simulators need macOS. iOS or tvOS 18 or later. No automatic device selection, so appium:udid and appium:platformVersion are mandatory. And no xcodebuild, so WebDriverAgent cannot be built on the fly.

You either pre-install a signed WDA on the device and set appium:usePreinstalledWDA with appium:updatedWDABundleId, or run WDA yourself and point the driver at it with appium:webDriverAgentUrl. Windows needs Apple's Mobile Device drivers, which come with the standalone iTunes installer. Linux needs the tun kernel module, membership of the tun group, and iproute2.

{
  "platformName": "ios",
  "appium:automationName": "xcuitest",
  "appium:platformVersion": "26.0",
  "appium:udid": "<device udid>",
  "appium:usePreinstalledWDA": true,
  "appium:updatedWDABundleId": "<updated bundle id>"
}

appium driver doctor xcuitest checks that the optional dependency and the tunnel infrastructure are present.

How It Got Here

The library is eighteen months old and has moved fast. It began in April 2025 alongside a sibling package, appium-ios-tuntap, which owns the virtual network interface. The first releases in July 2025 covered lockdown, usbmuxd, and the tunnel itself.

Through early 2026, the service surface grew week by week: installation proxy, crash reports, house arrest, notification proxy, and AFC in January; binary syslog in February; and in March the piece that matters most, a testmanagerd client speaking Apple's DTX protocol so the driver can run XCTest bundles without Xcode. Version 1.0 followed in April 2026.

June 2026 is when Windows and Linux became real. The tunnel implementation moved into the native layer with a statically linked TLS forwarder; Linux worked immediately, and a WinTun backend for Windows was enabled a week later. The driver followed within days: a host-platform gate in the session startup path that, on non-macOS hosts, requires an explicit device, an explicit platform version, iOS or tvOS 18 or later, and one of the two no-Xcode ways of starting WebDriverAgent, while rejecting every Xcode-only capability.

The Non-macOS Hosts guide was published in July. Since then the work has been breadth and hardening: a CoreDevice display service for HEVC screen and audio capture, an accessibility audit service, Developer Mode control, HTTP/2 flow-control fixes in the XPC framing, hot-plug device watching, and in October the move into the appium-ios monorepo. The driver's own architecture page now labels the RemoteXPC path the modern approach and the older libimobiledevice-style path legacy, to be eventually deprecated.

WebDriverAgent plays its part too. Every WebDriverAgent release includes an unsigned real-device runner built with code signing disabled and its XCTest frameworks stripped, so the device's own developer libraries can resolve them. The driver ships scripts to download it, sign it with your own certificate, and mount the developer disk image, which is the toolchain a Linux host needs to get a WDA onto a phone.

Why It Matters

For years, the practical answer to "can I run iOS tests from a Linux CI box" was no, or a cloud vendor. The remaining constraints are real: you need a signed WDA from somewhere, the host still needs Apple's USB drivers or a paired WiFi device, and two steps are not yet documented for non-Mac hosts: the initial pairing and trust handshake, and where to obtain the developer disk image files. But the Xcode dependency, which was the hard wall, is gone for iOS 18 and later.

The package ships as an optional dependency of the XCUITest driver, so most users already have it installed without knowing. It is also the layer that lets the driver add wireless Apple TV support and the usbmuxd based wireless iPhone discovery. On the Appium 4 side, its only involvement is logistical: it moved into the appium-ios monorepo in October along with the rest of the iOS libraries, and the driver's Appium 4 beta consumes it the same way the stable line does.

Client Libraries

The releases below occurred for their own reasons and are listed because they are the ones you will be running when you upgrade. Appium 4 does not change the wire protocol for anything a modern client sends. Your current client major will keep working against it for standard WebDriver commands, mobile: extensions, and BiDi. The only breakage is the legacy helpers listed in the table above, and the fix is the same in every language: call the mobile: extension instead.

Java Client 11

Java client 11 is the biggest client release in years, and the reason is structural rather than cosmetic. Until v10, the client sat on top of five Selenium modules: the remote driver, HTTP, JSON, OS, and support libraries. Every time Selenium reshaped one of those for browser automation, mobile users risked a break. Version 11 keeps only selenium-api and vendors the rest into the client itself. The v10 to v11 migration guide puts it plainly: "changes in the browser-oriented parts of Selenium cannot break Appium sessions anymore."

On the wire, nothing changes. Requests, capabilities, option classes, driver methods, and server-error exceptions are the same as in v10. The work is in your imports and your build file.

What Changed

The Selenium Bridge

If you still need a real RemoteWebDriver, for example to pass the driver to Selenium's BiDi modules or to a library that insists on one, add the optional io.appium:java-client-selenium-bridge artifact. SeleniumBridge.asRemoteWebDriver(driver) returns a Selenium driver that shares the Appium session and HTTP client. It is a separate artifact on purpose: Selenium's BiDi API has been changing in incompatible ways, and the bridge absorbs that churn so the core client does not.

How to Migrate

• Run the OpenRewrite recipe first, while the v10 types are still on the classpath. It rewrites the moved imports and marks every usage it cannot fix with a /*~~>*/ comment.
• Bump the client to 11.x and Selenium to 4.50.0 or newer.
• Declare the Selenium modules your own code uses. selenium-support for WebDriverWait, ExpectedConditions, and Select. selenium-remote-driver only if you use the bridge.
• Fix what the recipe marked. The common cases are casts to RemoteWebDriver, TouchAction usage, and constructors that took Selenium's ClientConfig or HttpCommandExecutor, which now take AppiumClientConfig and AppiumCommandExecutor.

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.activeRecipes=io.appium.java_client.MigrateToV11

The recipe will not touch build files or decide whether a RemoteWebElement reference was meant for a browser, so review those by hand.

Where It Touches Appium 4

Three places, and none of them makes v11 an Appium 4 release. The deprecated-API removal was validated against both Appium 4 driver betas and stable versions. The storage client learned to probe for the base-path layout introduced by the Appium 4 server, so it works with both. The same PR notes that the /location route the client still uses is removed in Appium 4, with a mobile: based replacement to follow. A pending change deprecates eventTimings and a dozen stale driver options, and an open pull request adds a WincoreDriver to match the server's new Windows driver.

Upgrade Checklist

Test authors:

• Upgrade Node.js to 22.22.2, 24.15.0 or newer
• Install the beta alongside your production setup, in a separate APPIUM_HOME, with the beta driver for your platform
• Grep the suite for geolocation, IME, and session-info helpers and move them to mobile: extensions
• Drop appium:eventTimings
• Replace firstMatch: [] with [{}] and pick one of noReset or fullReset
• Java: bump to java-client 11 and Selenium 4.50, run the OpenRewrite recipe, declare selenium-support if you use it, replace any TouchAction with W3C Actions
• Point one existing suite at the beta and read the first failure. It will almost certainly be one of the rows in the table above

Infrastructure owners:

• Replace --allow-cors with --allow-insecure=*:cors
• Remove --nodeconfig and register with Selenium Grid 4 relay instead
• Split extension installation out of npm install -g appium
• Add --log-level debug if your log pipeline expects it
• Point CLI-capturing scripts at stdout
• Drop HTTP/2 against the TLS listener
• Add the base path to storage plugin URLs if you run under one
• Windows: install appium-wincore-driver@^3.0.0 from npm while still on Appium 3, verify, then after upgrading run appium driver update wincore --unsafe and uninstall appium-windows-driver
• Consider --app-url-rules to restrict app download hosts
• Re-tune any alerting that used /status latency as a proxy for driver load. It now answers immediately

Runtime and Packaging

• Every @appium/* package and appium itself is ESM-only, with no CommonJS build. require() fails. Dynamic import() works from CommonJS code.
• Node floor is ^22.22.2 || ^24.15.0 || >=26.0.0, and the drivers match it.
• Default exports are gone. Import {BaseDriver}, {BasePlugin}, and {log} by name.
• The Express server moved out of @appium/base-driver into a new @appium/http-server package. base-driver no longer depends on Express at all. server, normalizeBasePath, and configureServer come from the new package.
• @appium/support lost its deprecated helpers: process, mkdirp, imageUtil, mjpeg, FTP upload, the old UUID and network utilities, readPackageJsonFrom, findRoot, and the npm and env modules, which moved into the appium package. fs.glob is now Node's native glob with a narrower options shape.
• The legacy test fixture routes (/welcome, /test/guinea-pig) are gone. Host your own.
• Linting in the server monorepo moved from ESLint to oxlint via @appium/oxc-config.

The Base Driver API

• createSession takes a single w3cCapabilities argument. The three-argument JSONWP form is gone.
• getSession, reset, and the driverData mechanism are removed. Cross-session coordination goes through IAppiumIpc.
• The idle timer is now shared across the whole command chain. If you override startNewCommandTimeout or executeCommand, delegate to super or wrap the command in runWithCommandTimeout. Appium will not patch your timer methods, and idle timeouts will misfire if you skip this.
• getStatus is exempt from the command queue by default. A new queueExemptCommands getter lets you add more.
• The base capability constraints no longer include locale, language, autoWebview, orientation, udid, or autoLaunch. Declare the ones you support in your own desiredCapConstraints.
• timeouts() on the driver should set script, page-load, and implicit timeouts directly so the W3C GET /timeouts reports them. The implicit type is narrowed to number.
• Plugins: this.logger is this.log, and name and cliArgs are read-only.
• Logger: errorAndThrow is errorWithException.
• ExecuteMethodMap types now check params against the method signature at compile time. The XCUITest driver found a real mismatch this way.

The Protocol Layer

The MJSONWP translation layer in @appium/base-driver is gone. ProtocolError has no jsonwpCode, responses carry only the W3C element key, errorFromCode is errorFromW3CJsonCode, and statusCodes is no longer exported. JWProxy is now WebDriverProxy and will not convert responses from a downstream server speaking the old protocol. If your driver proxies to an automation backend, that backend must speak W3C WebDriver. This is exactly why the WinAppDriver-based Windows driver could not be carried forward.

Shipping for Appium 3 and 4 at Once

The official drivers settled on one pattern, and it is worth copying. The Appium 4 line lives on a beta branch. The release workflow is dispatched by hand with a dist_tag input. When the tag is beta, semantic-release treats the branch as a prerelease channel and produces X.0.0-beta.N from feat!: commits, and the common publish-npm-bundle action in appium-workflows publishes under that npm tag. Pushes to master keep auto-releasing stable versions to the latest, and fixes are backported between the two.

The server changed its dependency policy at the same time. Library packages use ranges, ~ for monorepo siblings and ^ for third parties. Final packages, meaning appium and anything with an appium field in its manifest, keep exact pins. A shared Renovate preset in appium-workflows applies this across the org.

The Platform Libraries Moved

The iOS and Android helper libraries are now two Lerna monorepos, appium-ios and appium-android. Fourteen repos moved in and were archived: Xcode, UICatalog, tuntap, coresim, the simulator library, remotexpc, the remote debugger, and devicectl on the iOS side; adb, chromedriver, Appium Settings, the UiAutomator2 server, ApiDemos, and the Compose playground on the Android side. npm package names are unchanged, and nothing is deprecated on npm. File issues against the monorepo now.

One substitution to know about: @appium/coresim, native bindings to CoreSimulator, is the replacement for node-simctl. The Safari driver already switched, and the native video recording and JPEG streaming APIs live there.

Builder Checklist

• Convert to ESM if you have not, and bump engines.node to the Appium 4 floor
• Switch default imports to named imports for BaseDriver, BasePlugin and log
• Bump the appium peer dependency to ^4.0.0-beta.0 and the @appium/* lockstep packages to their betas
• Collapse createSession to the single-argument form. Remove getSession, reset and driverData overrides
• Delegate startNewCommandTimeout and executeCommand overrides to super, or wrap commands in runWithCommandTimeout
• Declare locale, language, autoWebview, orientation, udid and autoLaunch in your own constraints if you use them
• Import server helpers from @appium/http-server
• Confirm any downstream automation server speaks W3C WebDriver
• Replace errorFromCode, jsonwpCode, statusCodes, MJSONWP_ELEMENT_KEY and determineProtocol references
• Replace removed @appium/support helpers with native Node APIs
• Replace this.logger with this.log and errorAndThrow with errorWithException
• Move test stubs of @appium/support from sinon to node:test mock.module, since ESM namespaces are frozen
• Host your own test fixtures if you used the built-in guinea-pig pages
• Add a beta branch and a dist_tag input to your release workflow so you can ship both lines