Apple WebDriver
Introduction
This page is a reference for the available commands, execute methods, and key mappings for the Apple WebDriver integration, which covers iPhone, iPad, and Apple TV.
The Apple WebDriver integration is written by TV Labs for iOS, iPadOS, and tvOS devices. It is an Appium compatible WebDriver that follows appium-xcuitest-driver, so it can be driven from any Appium or WebDriver client. It drives the device through WebDriverAgent, and drives web views on iPhone and iPad through the Web Inspector.
Starting a Session
Select a build with the tvlabs:build capability and it is installed onto the device and launched when the session starts. To launch an app that is already installed, name it with appium:bundleId instead. See the Apple platform guide for how to sign builds for TV Labs devices.
const capabilities = {
'tvlabs:constraints': { platform_key: 'ios' },
'tvlabs:build': 'YOUR_BUILD_ID',
};
When the session ends, WebDriverAgent is stopped and the "Automation Running" overlay is cleared.
Capabilities
| Capability | Description |
|---|---|
appium:bundleId | The bundle ID of the app to launch. Set for you from tvlabs:build when a build is selected |
appium:autoLaunch | When false, no app is launched at session start |
appium:processArguments | { args, env } passed to the app when it is launched |
appium:autoAcceptAlerts, autoDismissAlerts | Accept or dismiss system alerts automatically |
appium:shouldTerminateApp, forceAppLaunch | Forwarded to WebDriverAgent |
appium:settings | WebDriverAgent settings applied when the session starts |
appium:newCommandTimeout | Seconds without a command before the session is ended. Default: 60 |
appium:wdaConnectionTimeout | Milliseconds to wait for each WebDriverAgent request. Default: 240000 |
Contexts
On iPhone and iPad, getContexts returns NATIVE_APP followed by the web views the Web Inspector can see, including Safari tabs. Switch to a web view to drive its page with web commands and run JavaScript.
Apple TV has no web views, so its only context is NATIVE_APP.
Available Commands
The standard WebDriver commands for finding elements, element state, interaction, W3C Actions, alerts, page source, timeouts, and orientation are proxied to WebDriverAgent. In a web context, the web commands for elements, navigation, cookies, and script execution run against the page instead.
The -ios predicate string and -ios class chain locator strategies are supported, and css selector is translated to a class chain. W3C Actions are always performed with a touch pointer.
The following behave differently on Apple devices:
| Command | Behavior |
|---|---|
takeScreenshot | Captured from the device directly, so it shows the whole screen |
execute | In the native context, only mobile: and tvlabs: methods. Raw JavaScript needs a web context |
back | On Apple TV, presses menu. On iPhone and iPad, taps the navigation bar's back button |
refresh | On Apple TV, relaunches the app under test. Not supported in the native context on iPhone and iPad |
getUrl | On Apple TV, the bundle ID of the foreground app |
getTitle | On Apple TV, the name of the foreground app |
minimizeWindow | Presses home |
activateApp | Terminates the app first if it is running, then launches it, so the app's in-memory state is lost |
| Cookies | Only in a web context |
Execute Methods
In addition to the standard WebDriver commands, the following execute methods are available for device interaction. They take the same arguments as the appium-xcuitest-driver methods of the same name.
| Command | Required Arguments | Description |
|---|---|---|
mobile: pressButton | name | Press a hardware or remote button. See the key map. Optional durationSeconds holds it |
mobile: launchApp | bundleId | Launch an app. Optional arguments and environment are passed to it |
mobile: activateApp | bundleId | Terminate the app if it is running, then launch it |
mobile: terminateApp | bundleId | Terminate an app |
mobile: killApp | bundleId | Kill an app's process. Returns false if it wasn't running |
mobile: queryAppState | bundleId | The app's state, from 0 (not installed) to 4 (running in the foreground) |
mobile: backgroundApp | - | Send the app to the background for seconds, or until reactivated if seconds is omitted |
mobile: installApp | app | Install an .ipa from an http(s) URL |
mobile: removeApp | bundleId | Uninstall an app |
mobile: isAppInstalled | bundleId | Whether an app is installed |
mobile: listApps | - | The installed apps. applicationType is User (default), System, or Any |
mobile: activeAppInfo | - | The foreground app's bundleId, name, and pid |
mobile: deepLink | url | Open a URL, optionally in the app named by bundleId |
mobile: source | - | The page source. format is xml (default), json, or description |
mobile: deviceInfo | - | See mobile: deviceInfo |
mobile: deviceScreenInfo | - | The screen's size and scale |
mobile: getDeviceTime | - | The device's time. format is a strftime format |
mobile: setAppearance | style | Switch between light and dark appearance |
mobile: getOrientation, setOrientation | orientation (set only) | Get or set the screen orientation |
mobile: viewportScreenshot | - | A screenshot of the app's viewport, as base64 PNG |
mobile: viewportRect | - | The app's viewport, excluding the status bar |
mobile: keys | keys | Type a list of keys into the focused element |
mobile: hideKeyboard, isKeyboardShown | - | Hide the on-screen keyboard, or check whether it is shown |
mobile: getPasteboard, setPasteboard | content (set only) | Read or write the pasteboard. getClipboard and setClipboard are aliases |
mobile: acceptAlert, dismissAlert | - | Accept or dismiss the current alert. Optional buttonLabel picks the button |
mobile: getContexts | - | The available contexts, including web view details |
mobile: runXCTest | See description | Run an XCTest bundle. See Running Bundled Automations |
Any other mobile: method returns an unknown method or unsupported operation error. File transfer, screen recording, and shell access are not available.
mobile: pressButton
// Apple TV
await driver.executeScript('mobile: pressButton', [{ name: 'right' }]);
await driver.executeScript('mobile: pressButton', [{ name: 'select' }]);
// iPhone or iPad
await driver.executeScript('mobile: pressButton', [{ name: 'home' }]);
Key Map
The following button names are available with mobile: pressButton.
| Device | Button | Description |
|---|---|---|
| Apple TV | up | Up |
| Apple TV | down | Down |
| Apple TV | left | Left |
| Apple TV | right | Right |
| Apple TV | select | Select |
| Apple TV | menu | Menu / Back |
| Apple TV | playpause | Play / Pause |
| Apple TV | home | TV / Home |
| iPhone, iPad | home | Home |
| iPhone, iPad | volumeup | Volume Up |
| iPhone, iPad | volumedown | Volume Down |