Capabilities

This page lists various capabilities used and implemented by the Espresso driver. To learn more about capabilities, refer to the Appium documentation.

For other capabilities recognized by the Appium server, see their Appium docs reference page.

Standard

Refer to the W3C WebDriver documentation for more information about these capabilities.

platformName

Name	Type	Default
platformName	string	Not specified

May be set to android. Appium is not strict about this value if the appium:automationName capability is provided, so feel free to assign it to any platform name required, for example, for Selenium Grid compatibility.

pageLoadStrategy

Name	Type	Default
pageLoadStrategy	string	normal

General

automationName

Name	Type	Default
appium:automationName	string	Not specified

Specifies the Appium driver to use. Must be set to Espresso (case-insensitive)

Device Under Test

deviceName

Name	Type	Default
appium:deviceName	string	Not specified

The name of the device under test. Not used to select a device under test - use appium:udid for real devices and appium:avd for emulators.

platformVersion

Name	Type	Default
appium:platformVersion	string	Not specified

The platform version of the device under test. Used for device selection if appium:udid or appium:avd is not provided.

udid

Name	Type	Default
appium:udid	string	Not specified

UDID of the device under test. Can be retrieved by running adb devices. If neither this capability nor appium:avd is set, the driver will automatically try to use the first connected device. Always set this capability if you run parallel tests.

skipDeviceInitialization

Name	Type	Default
appium:skipDeviceInitialization	boolean	false

Whether to skip the device initialization phase of session creation, such as checking if the device is available, installing the Appium Settings helper, adjusting permissions, etc.. Can be useful if a session had already been previously started, and all the device setup steps were already completed.

skipSettingsAppReinstall

Name	Type	Default
appium:skipSettingsAppReinstall	boolean	false

Whether to skip installation of the Appium Settings helper application (io.appium.settings) upon session start. Can be useful for environments where this application is provisioned separately.

Available since driver version 9.0.2.

skipLogcatCapture

Name	Type	Default
appium:skipLogcatCapture	boolean	false

Whether to skip collecting device logcat logs.

clearDeviceLogsOnStart

Name	Type	Default
appium:clearDeviceLogsOnStart	boolean	false

Whether device logs should be cleared upon session start. Maps to the -c flag of adb logcat.

logcatFormat

Name	Type	Default
appium:logcatFormat	string	threadtime

The output format of device logcat logs. Maps to the -v flag of adb logcat. Refer to the logcat documentation for supported values.

logcatFilterSpecs

Name	Type	Default
appium:logcatFilterSpecs	string or Array<string>	Not specified

One or more filter expressions to use for filtering device logcat output. Refer to the logcat documentation for the format of a filter expression.

ignoreHiddenApiPolicyError

Name	Type	Default
appium:ignoreHiddenApiPolicyError	boolean	false

Whether to ignore failures caused by the driver automatically relaxing Android's hidden API access policies, in order to enable access to non-SDK interfaces (such as logging). May be useful on devices where access to these policies has been locked by its vendor.

disableSuppressAccessibilityService

Name	Type	Default
appium:disableSuppressAccessibilityService	boolean	false

Whether the instrumentation process should avoid suppressing accessibility services during the session. Useful if your automated test needs these services.

disableWindowAnimation

Name	Type	Default
appium:disableWindowAnimation	boolean	true

Whether to disable window animations. Google recommends disabling animations when running automated tests, in order to avoid flakiness. The animation state is automatically restored after the session is stopped, unless the session is ended unexpectedly.

Available since driver version 2.17.0.

timeZone

Name	Type	Default
appium:timeZone	string	Not specified

Value used to override the current timezone of the device. Persists until the next override. Must be a valid TZ identifier.

Available since driver version 2.38.0.

hideKeyboard

Name	Type	Default
appium:hideKeyboard	boolean	Not specified

Whether to hide the on-screen keyboard during the session. This is achieved by creating a custom "artificial" input method. It is recommended to use this feature only for special/exploratory cases, as it violates the way a user normally interacts with the application under test.

If explicitly set to false, adb shell ime reset is run on session startup, which resets the currently selected/enabled IMEs to the default ones, as if the device was initially booted with the current locale.

Available since driver version 2.28.0.

gpsEnabled

Name	Type	Default
appium:gpsEnabled	boolean	Not specified

Whether to enable or disable location services (GPS) upon session start. This functionality only works reliably starting from Android 12 (S / API level 31).

Available since driver version 9.1.0.

mockLocationApp

Name	Type	Default
appium:mockLocationApp	string	io.appium.settings

Package identifier of the app to use for mocking device location. Has no effect on emulators. If set to null or an empty string, Appium will skip the setup of the location mocking feature.

skipUnlock

Name	Type	Default
appium:skipUnlock	boolean	true

Whether to skip unlocking the device lockscreen on session startup, if one is present.

unlockType

Name	Type	Default
appium:unlockType	string	Not specified

The type of lockscreen security on the device, which can be used to unlock it. If omitted, the driver assumes no security is used, and the screen can be unlocked without additional details.

Supported values are pin, password, and pattern. Must be provided together with appium:unlockKey, whose value depends on the lockscreen type.

Refer to the Device Lock/Unlock guide for more details.

unlockKey

Name	Type	Default
appium:unlockKey	string	Not specified

The key used to unlock the lockscreen. The expected format depends on the value of appium:unlockType, which must be provided together with this capability. If omitted, the driver assumes no security is used, and the screen can be unlocked without additional details.

Refer to the Device Lock/Unlock guide for more details.

unlockStrategy

Name	Type	Default
appium:unlockStrategy	string	Not specified

The approach to use for unlocking the screen. Supported values are locksettings and uiautomator. The appium:unlockKey and appium:unlockType must be provided in order for this capability to take effect.

By default, or if set to locksettings, unlocking is done using adb-based fast unlock. If set to uiautomator, the unlock approach depends on the appium:unlockType capability.

unlockSuccessTimeout

Name	Type	Default
appium:unlockSuccessTimeout	integer	2000

Maximum number of milliseconds to wait until the device is unlocked.

Emulator (AVD)

avd

Name	Type	Default
appium:avd	string	Not specified

The name of Android emulator to run the test on. The names of currently installed emulators can be listed by running avdmanager list avd. If the specified emulator is not running upon starting a session, the driver will automatically launch it.

avdLaunchTimeout

Name	Type	Default
appium:avdLaunchTimeout	integer	60000

Maximum number in milliseconds to wait until the Android emulator has started.

avdReadyTimeout

Name	Type	Default
appium:avdReadyTimeout	integer	60000

Maximum number of milliseconds to wait until the Android emulator has fully booted and is ready for usage.

avdArgs

Name	Type	Default
appium:avdArgs	string or Array<string>	Not specified

One or more supported command-line arguments to apply when starting the emulator. Only applied if the emulator is not already running.

avdEnv

Name	Type	Default
appium:avdEnv	Record<string, any>	Not specified

One or more environment variables to set when starting the emulator. Only applied if the emulator is not already running.

isHeadless

Name	Type	Default
appium:isHeadless	boolean	false

Whether to start the emulator in headless mode. Maps to the -no-window emulator command-line argument. Only applied if the emulator is not already running.

allowDelayAdb

Name	Type	Default
appium:allowDelayAdb	boolean	true

Whether to wait until the emulator has finished booting before processing ADB packets. Maps to the -delay-adb flag of adb. Requires emulator version 29.0.7 or later, running Android 9 (Pie / API level 28) or later.

Refer to this issue for more details.

networkSpeed

Name	Type	Default
appium:networkSpeed	string	Not specified

The network speed to apply to the emulator. Maps to the -netspeed emulator command-line argument. Only applied if the emulator is not already running.

injectedImageProperties

Name	Type	Default
appium:injectedImageProperties	Record<string, Record<string, number>>	Not specified

Adjusts properties of the image injected using the mobile: injectEmulatorCameraImage execute method. If the emulator is already running, it will be restarted in order to apply the properties.

The value of this capability is an object with the following keys. All keys and sub-keys are optional, with the given defaults used for absent keys.

Key	Description	Default
size	Scale multipliers for X and Y axes	{scaleX: 1, scaleY: 1}
position	Offset coefficients for X/Y/Z axes, where 0 means centered	{x: 0, y: 0, z: -1.5}
rotation	Degrees of rotation for X/Y/Z axes	{x: 0, y: 0, z: 0}

Available since driver version 2.42.1.

ADB

adbPort

Name	Type	Default
appium:adbPort	integer	5037

Number of the port to use for starting ADB. Maps to the -P flag of adb.

remoteAdbHost

Name	Type	Default
appium:remoteAdbHost	string	localhost

Name of the ADB server host. Maps to the -H flag of adb.

adbExecTimeout

Name	Type	Default
appium:adbExecTimeout	integer	20000

Maximum number of milliseconds to wait for the execution of any single ADB command.

buildToolsVersion

Name	Type	Default
appium:buildToolsVersion	string	Not specified

The version of Android build tools to use (name of a directory located at $ANDROID_HOME/build-tools). By default, the driver uses the most recent available version, but it may be useful to explicitly change this in case of any known bugs.

allowOfflineDevices

Name	Type	Default
appium:allowOfflineDevices	boolean	false

Whether to include offline devices in the list of devices returned by ADB.

suppressKillServer

Name	Type	Default
appium:suppressKillServer	boolean	false

Whether to prevent the driver from ever killing the ADB server. Can be useful if ADB is connected wirelessly.

adbListenAllNetwork

Name	Type	Default
appium:adbListenAllNetwork	boolean	false

Whether to listen on all network interfaces, not only localhost. Maps to the -a flag of adb. The adb_listen_all_network insecure feature must be enabled.

Available since driver version 6.2.0.

Espresso Server

systemPort

Name	Type	Default
appium:systemPort	integer	8300

The port for the Espresso server to listen on. Must be unique for each session - see the Testing in Parallel guide for details. If not provided, Appium will try the first available port in the range [8300, 8399].

espressoBuildConfig

Name	Type	Default
appium:espressoBuildConfig	string	See below

Configuration for building the Espresso server. The value can be either a stringified JSON object, or path to a JSON file that contains the configuration. The configuration supports the following keys, all of which are optional:

composeSupport

Type	Default
boolean	true

Whether to include Jetpack Compose UI test dependencies in the server app. If disabled, the app size will be reduced, but any Compose-only functionality, including changing the driver setting to compose, will return an error.

toolsVersions

Type	Default
Record<string, string>	See below

Map of various tools to their versions that should be used during the build process. The mapping supports the following keys, all of which are optional. For most tools, their default version is automatically kept up-to-date, so each table entry includes a link to the version definition file for that tool.

Name	Description	Default
gradle	Gradle version to build the app with	See gradle-wrapper.properties
compileSdk	Android SDK version to compile the server for	See appiumCompileSdk in gradle.properties
minSdk	Minimum supported Android SDK version	See appiumMinSdk in gradle.properties
targetSdk	Target Android SDK version	See appiumTargetSdk in gradle.properties
buildTools	Android SDK Build-Tools version to build the server with	See appiumBuildTools in gradle.properties
sourceCompatibility	Minimum supported JVM version for the project sources	See appiumSourceCompatibility in gradle.properties
targetCompatibility	Target JVM version for the project sources	See appiumTargetCompatibility in gradle.properties
jvmTarget	Target version of the generated JVM bytecode	See appiumJvmTarget in gradle.properties
androidGradlePlugin	Android Gradle plugin version	See libs.versions.toml
kotlin	Kotlin version to compile the server for	See libs.versions.toml
composeVersion	Version of Jetpack Compose dependencies to compile the server for	See composeUiTest in libs.versions.toml
espressoVersion	Version of Espresso dependencies to compile the server for. Configurable since driver version 2.20.0.	See espresso in libs.versions.toml
annotationVersion	Version of the androidx.annotation:annotation package. Configurable since driver version 2.5.0.	See annotation in libs.versions.toml

additionalAppDependencies

Type	Default
Array<string>	[]

List of one or more Gradle module names and their versions to include as api dependencies.

additionalAndroidTestDependencies

Type	Default
Array<string>	[]

List of one or more Gradle module names and their versions to include as androidTestImplementation dependencies.

Full Example

{
  "composeSupport": false,
  "toolsVersions": {
    "gradle": "9.5.0",
    "compileSdk": "32",
    "minSdk": "22",
    "targetSdk": "30",
    "buildTools": "32.0.0",
    "sourceCompatibility": "VERSION_12",
    "targetCompatibility": "VERSION_12",
    "jvmTarget": "9",
    "androidGradlePlugin": "9.0.0",
    "kotlin": "2.3.0",
    "composeVersion": "1.10.0",
    "espressoVersion": "3.5.0",
    "annotationVersion": "1.9.0"
  },
  "additionalAppDependencies": ["api.package:1.2.3", "api.otherpackage:4.5.6"],
  "additionalAndroidTestDependencies": ["test.package:1.2.3"]
}

espressoServerLaunchTimeout

Name	Type	Default
appium:espressoServerLaunchTimeout	integer	45000

Maximum number of milliseconds to wait until the Espresso server has started.

skipServerInstallation

Name	Type	Default
appium:skipServerInstallation	boolean	false

Whether to skip installation of the Espresso server on the device under test, along with all other related checks. Useful for speeding up session startup if the device already has a compatible Espresso server app installed. Note that unexpected errors may occur if the Espresso server app is not compatible with the driver or the app under test.

Since driver version 3.3.0, the installed server app is always subject to simple compatibility checks - however, minor mismatches are treated as warnings, so a session can still be started.

forceEspressoRebuild

Name	Type	Default
appium:forceEspressoRebuild	boolean	false

Whether to always rebuild the Espresso server when starting a new session. By default, the driver caches the previously built server, and only rebuilds it if it does not match the target application under test.

showGradleLog

Name	Type	Default
appium:showGradleLog	boolean	false

Whether to show Gradle logs during the build process of the Espresso server.

App Management

app

Name	Type	Default
appium:app	string	Not specified

Full path to a file on the host machine, or URL to a remote location, that contains the application under test. Required unless appium:appPackage is specified.

The app file must have either the .apk or .aab extension. Files with the .aab extension are only supported since driver version 2.1.0, and require bundletool.jar to be present on the system PATH.

appPackage

Name	Type	Default
appium:appPackage	string	Not specified

Package identifier of the application under test. Required unless appium:app is specified.

It is allowed to set both appium:app and this capability, but if only appium:app is provided, the package identifier is automatically detected from the app manifest.

Refer to the Activity Startup guide for more details.

appActivity

Name	Type	Default
appium:appActivity	string	Not specified

Launchable activity identifier of the application under test. If not provided, the activity is automatically detected from either appium:app or appium:appPackage, in that order.

Refer to the Activity Startup guide for more details.

appWaitPackage

Name	Type	Default
appium:appWaitPackage	string	Matches the package identifier (see appium:appPackage)

Identifier of the first app package to be launched.

Refer to the Activity Startup guide for more details.

appWaitActivity

Name	Type	Default
appium:appWaitActivity	string	Matches the app main activity (see appium:appActivity)

Identifier of the first app activity to be launched.

Refer to the Activity Startup guide for more details.

appWaitDuration

Name	Type	Default
appium:appWaitDuration	integer	20000

Maximum number of milliseconds to wait until the activity specified by appium:appWaitPackage and appium:appWaitActivity has started.

Refer to the Activity Startup guide for more details.

intentOptions

Name	Type	Default
appium:intentOptions	Record<string, any>	See below

Map of options to be applied for the intent passed to the launchable app activity. Refer to the Android Intent documentation for more details. The mapping supports the following options, all of which are optional:

Name	Type	Description
action	string	Name of the action. Application-specific actions should be prefixed with the vendor's package name. Set to ACTION_MAIN by default.
data	string	Data URI of the intent. Set to null by default.
type	string	MIME type of the intent. Set to null by default.
categories	string	One or more comma-separated intent categories
component	string	Component name with a package name prefix
intFlags	string	Sum of all intent flag integer or hexadecimal values, as a string. Refer to the setFlags documentation for more details.
flags	string	Comma-separated string of additional intent flag names. The FLAG_ prefix can be omitted. Refer to the addFlags documentation for more details.
className	string	Name of a class inside of the application package that will be used as the component for this intent. Set to the fully qualified name of the app activity by default.
e	Record<string, string>	Map of string parameters to apply to the intent. Same as es.
es	Record<string, string>	Map of string parameters to apply to the intent. Same as e.
esn	Array<string>	Array of null parameters to apply to the intent
ez	Record<string, boolean>	Map of boolean parameters to apply to the intent
ei	Record<string, number>	Map of integer parameters to apply to the intent
el	Record<string, number>	Map of long integer parameters to apply to the intent
ef	Record<string, number>	Map of float parameters to apply to the intent
eu	Record<string, string>	Map of URI-data parameters to apply to the intent
ecn	Record<string, string>	Map of component name parameters to apply to the intent
esa	Record<string, Array<string>>	Map of string array parameters to apply to the intent. Available since driver version 2.9.0.
eia	Record<string, string>	Map of integer array parameters (as comma-separated strings) to apply to the intent
ela	Record<string, string>	Map of long integer array parameters (as comma-separated strings) to apply to the intent
efa	Record<string, string>	Map of float array parameters (as comma-separated strings) to apply to the intent

Full Example

{
  "action": "ACTION_VIEW",
  "data": "content://contacts/people/1",
  "type": "image/png",
  "categories": "android.intent.category.APP_CONTACTS",
  "component": "com.example.app/.ExampleActivity",
  "intFlags": "15", // or 0x0F
  "flags": "FLAG_GRANT_READ_URI_PERMISSION, ACTIVITY_CLEAR_TASK",
  "className": "com.example.app.MainActivity",
  "e": {"foo": "bar"},
  "es": {"foo": "bar"},
  "esn": ["foo", "bar"],
  "ez": {"foo": true, "bar": false},
  "ei": {"foo": 1, "bar": 2},
  "el": {"foo": 1L, "bar": 2L},
  "ef": {"foo": 1.ff, "bar": 2.2f},
  "eu": {"foo": "content://contacts/people/1"},
  "ecn": {"foo": "com.example.app/.ExampleActivity"},
  "esa": {"foo": ["bar1","bar2","bar3","bar4"]},
  "eia": {"foo": "1,2,3,4"},
  "ela": {"foo": "1L,2L,3L,4L"},
  "efa": {"foo": "1.1,2.2,3.3,4.4"},
}

activityOptions

Name	Type	Default
appium:activityOptions	Record<string, any>	Not specified

Map of additional options to be applied for the launchable app activity. The mapping supports the following options:

Name	Type	Description
launchDisplayId	integer or string	Identifier of the display to launch the activity on. Useful if the device under test supports multiple displays.

androidInstallTimeout

Name	Type	Default
appium:androidInstallTimeout	integer	90000

Maximum amount of milliseconds to wait until the application under test is installed.

enforceAppInstall

Name	Type	Default
appium:enforceAppInstall	boolean	false

Whether to always reinstall the application under test, even if a newer version already exists on the device under test.

noReset

Name	Type	Default
appium:noReset	boolean	false

Whether to prevent the app from being automatically relaunched and its data cleaned before session startup.

Mutually exclusive with appium:fullReset.

fullReset

Name	Type	Default
appium:fullReset	boolean	false

Whether to always reinstall the app before session startup, and uninstall it after deleting the session.

Mutually exclusive with appium:noReset.

dontStopAppOnReset

Name	Type	Default
appium:dontStopAppOnReset	boolean	false

Whether to skip termination of the app under test upon session deletion.

autoLaunch

Name	Type	Default
appium:autoLaunch	boolean	true

Whether to launch the application under test on session start, and wait until it is ready.

autoGrantPermissions

Name	Type	Default
appium:autoGrantPermissions	boolean	false

Whether to automatically grant all requested application permissions upon session startup.

If the targetSdk of the application under test is below 23, or the device under test is running Android 5 (Lollipop / API level 22), granting permissions requires the application to be reinstalled, for example, using the appium:fullReset capability.

otherApps

Name	Type	Default
appium:otherApps	string or Array<string>	Not specified

One or more application packages (either filepaths on the host machine, or URLs to remote locations) that should be installed on the device along with the application under test. Unlike the app under test, these apps are not additionally signed, and only apps with the .apk extension are supported.

Available since driver version 9.2.0.

uninstallOtherPackages

Name	Type	Default
appium:uninstallOtherPackages	string or Array<string>	Not specified

One or more package identifiers to be uninstalled from the device upon session startup. Always excludes packages required by the driver (io.appium.settings and io.appium.espressoserver.test).

allowTestPackages

Name	Type	Default
appium:allowTestPackages	boolean	false

Whether to allow installation of test-only versions of the application under test. Maps to the -t flag of adb install. Only applied if the application is to be installed or reinstalled.

remoteAppsCacheLimit

Name	Type	Default
appium:remoteAppsCacheLimit	integer	10

Maximum number of application packages to be cached on the device under test. Primarily needed for devices that don't support streamed installs (Android 7 and below), which require adb to push each installable package to the device first, requiring additional time.

If set to 0, the cache is disabled.

App Signing

useKeystore

Name	Type	Default
appium:useKeystore	boolean	false

Whether to use a custom keystore to sign the app under test. By default, apps are signed with the default Appium debug certificate, unless appium:noSign is used.

Used in combination with appium:keystorePath, appium:keystorePassword, appium:keyAlias and appium:keyPassword.

keystorePath

Name	Type	Default
appium:keystorePath	string	Not specified

Full path to the keystore file on the server filesystem.

Used in combination with appium:useKeystore, appium:keystorePassword, appium:keyAlias and appium:keyPassword.

keystorePassword

Name	Type	Default
appium:keystorePassword	string	Not specified

Password of the keystore file specified by appium:keystorePath.

Used in combination with appium:useKeystore, appium:keystorePath, appium:keyAlias and appium:keyPassword.

keyAlias

Name	Type	Default
appium:keyAlias	string	Not specified

Alias of the key in the keystore file specified by appium:keystorePath.

Used in combination with appium:useKeystore, appium:keystorePath, appium:keystorePassword and appium:keyPassword.

keyPassword

Name	Type	Default
appium:keyAlias	string	Not specified

Password of the key in the keystore file specified by appium:keystorePath.

Used in combination with appium:useKeystore, appium:keystorePath, appium:keystorePassword and appium:keyAlias.

noSign

Name	Type	Default
appium:noSign	boolean	false

Whether to skip signing of the application under test, and use it as-is. By default, all apps are signed with the default Appium debug signature. Make sure that the server package is signed with the same signature as the application under test before disabling this capability.

This capability does not affect .apks packages, as they are expected to be already signed.

App Localization

language

Name	Type	Default
appium:language	string	Not specified

Language code to use for setting the locale of the device under test. The code should match the language field for Android's Locale class. Must be provided together with appium:locale.

The language set by this capability is also used by the mobile: getAppStrings execute method, unless explicitly overridden.

In order to set the locale of only the application under test, use appium:appLocale.

locale

Name	Type	Default
appium:locale	string	Not specified

Country code to use for setting the locale of the device under test. The code should match the country field for Android's Locale class. Must be provided together with appium:language.

In order to set the locale of only the application under test, use appium:appLocale.

localeScript

Name	Type	Default
appium:localeScript	string	Not specified

Script code to use for setting the locale of the device under test. The code should match the script field for Android's Locale class. If specified, appium:language and appium:locale must also be provided.

appLocale

Name	Type	Default
appium:appLocale	Record<string, string>	Not specified

Map of language-related identifiers to use for setting the locale of the app under test. The mapping supports the following options:

Name	Description
language	Matches the language field for Android's Locale class
country?	Matches the country field for Android's Locale class
variant?	Matches the variant field for Android's Locale class

In order to set the locale of the entire device under test, use appium:language and appium:locale.

Web Context

autoWebview

Name	Type	Default
appium:autoWebview	boolean	false

Whether to automatically switch to the first available webview context upon session start.

autoWebviewTimeout

Name	Type	Default
appium:autoWebviewTimeout	integer	2000

Maximum number of milliseconds to wait until a webview is available before switching to it. Requires appium:autoWebview to be set.

androidDeviceSocket

Name	Type	Default
appium:androidDeviceSocket	string	Not specified

Name of a Chromium DevTools socket on the device under test. If set, webview discovery will only return webviews running on this socket.

webviewDevtoolsPort

Name	Type	Default
appium:webviewDevtoolsPort	integer	10900

The port to use for communicating with webviews over the DevTools protocol. Must be unique for each session - see the Testing in Parallel guide for details. If not provided, Appium will try the first available port in the range [10900, 11000].

ensureWebviewsHavePages

Name	Type	Default
appium:ensureWebviewsHavePages	boolean	true

Whether to skip web views that have no pages from being included in the list of available contexts. The driver uses the DevTools connection to retrieve information about existing pages.

enableWebviewDetailsCollection

Name	Type	Default
appium:enableWebviewDetailsCollection	boolean	true

Whether to retrieve extended webview information via DevTools. Enabling this capability improves detection of the required ChromeDriver version.

chromeOptions

Name	Type	Default
appium:chromeOptions	Record<string, any>	Not specified

Map of ChromeDriver options to apply. Refer to Google's ChromeOptions documentation for supported values.

chromeLoggingPrefs

Name	Type	Default
appium:chromeLoggingPrefs	Record<string, string>	{"browser": "ALL"}

Map of logging types to their levels that should be applied. Refer to Selenium's Logging documentation for supported type and level values.

chromedriverPort

Name	Type	Default
appium:chromedriverPort	integer	Random

The port to use for ChromeDriver communication. Must be unique for each session - see the Testing in Parallel guide for details. By default, a random free port is used.

chromedriverPorts

Name	Type	Default
appium:chromedriverPort	Array<number | Array<number>>	Not specified

List of possible ports and/or port ranges to use for ChromeDriver communication, for example, [5600, 5610, [5650, 5660]]. An error is thrown if all specified ports are busy.

chromedriverArgs

Name	Type	Default
appium:chromedriverArgs	Array<string>	Not specified

List of command line switches to apply to ChromeDriver. Refer to the links in Selenium's Chrome documentation for more details on supported switches. Note that not all desktop Chrome switches are available on mobile.

chromedriverExecutable

Name	Type	Default
appium:chromedriverExecutable	string	Not specified

Custom path to a ChromeDriver executable on the host file system. Takes priority over appium:chromedriverExecutableDir.

Refer to the Managing ChromeDriver guide for more details.

chromedriverExecutableDir

Name	Type	Default
appium:chromedriverExecutableDir	string	See below

Custom path to a directory on the host file system, containing ChromeDriver executables. If automatic ChromeDriver download is enabled, this folder is also used to store the downloaded executables.

The default value is node_modules/appium-chromedriver/chromedriver/<host os> in the driver's installation directory.

Refer to the Managing ChromeDriver guide for more details.

chromedriverChromeMappingFile

Name	Type	Default
appium:chromedriverExecutableDir	string	See below

Custom path to a JSON file containing a mapping of webview/browser versions to the ChromeDriver versions that are capable of automating them, similarly to the following:

{
  "2.42": "63.0.3239",
  "2.41": "62.0.3202"
}

The default value is node_modules/appium-chromedriver/config/mapping.json in the driver's installation directory.

Refer to the Managing ChromeDriver guide for more details.

chromedriverUseSystemExecutable

Name	Type	Default
appium:chromedriverUseSystemExecutable	boolean	false

Whether to use the ChromeDriver binary bundled with the driver.

This capability is primarily relevant for driver versions 3.3.1 or earlier, which automatically downloaded ChromeDriver upon installation.

chromedriverDisableBuildCheck

Name	Type	Default
appium:chromedriverDisableBuildCheck	boolean	false

Whether to disable the check that requires ChromeDriver and the browser executable to have matching versions. Maps to the --disable-build-check flag of the ChromeDriver binary.

chromedriverForwardBiDi

Name	Type	Default
appium:chromedriverForwardBiDi	boolean	false

Whether to automatically forward the ChromeDriver BiDi web socket to the Espresso driver web socket. This allows sending browser-specific BiDi commands in a webview context. Switching the session context terminates this connection. Requires the BiDi protocol to be enabled (webSocketUrl capability must be true).

Note that older ChromeDriver versions may only have partial to no support for the BiDi protocol.

Available since driver version 6.0.3.

chromedriverGrantPermissions

Name	Type	Default
appium:chromedriverGrantPermissions	boolean	false

Whether to automatically grant all requested runtime permissions for the Chrome/webview package, so that the session is not interrupted by any native runtime permission dialogs.

Available since driver version 9.0.2.

recreateChromeDriverSessions

Name	Type	Default
appium:recreateChromeDriverSessions	boolean	false

Whether the driver should kill the ChromeDriver session upon switching to native context and recreate it upon switching back, instead of merely suspending it.

nativeWebScreenshot

Name	Type	Default
appium:nativeWebScreenshot	boolean	false

Whether to use the screenshoting endpoint provided by the Espresso framework instead of the one provided by ChromeDriver. Can be useful if experiencing issues with the latter.

extractChromeAndroidPackageFromContextName

Name	Type	Default
appium:extractChromeAndroidPackageFromContextName	boolean	false

Whether to instruct ChromeDriver to attach to the Android package included in the context name, rather than the package of the application under test.

showChromedriverLog

Name	Type	Default
appium:showChromedriverLog	boolean	false

Whether to include ChromeDriver logs in Appium server logs.