appium_driver #

Dart CI

An Appium client for writing UI tests in Dart, including interactions outside Flutter views.

Getting started
Appium compatibility
API notes and migration
Supported commands
Development
Release

Getting started #

Requirements and installation #

Requires Dart 3.4 or later (before Dart 4).

Add the package to your Dart project:

dart pub add appium_driver

Server URL #

The default server URL is http://127.0.0.1:4723/, matching Appium 2 and 3. For a server configured with another base path, pass its URL explicitly, including the trailing slash (for example, http://127.0.0.1:4723/wd/hub/).

Examples and session cleanup #

See the example and functional tests for usage.

Call driver.quit() to end the session and close the client's connection, or driver.quit(closeSession: false) to disconnect while keeping the server session.

Appium compatibility #

Protocol #

The client uses the W3C protocol (WebDriverSpec.W3c or Auto). WebDriverSpec.JsonWire is unsupported and throws UnsupportedError.

Session discovery and logs #

Session discovery and log retrieval use /appium/sessions, /se/log/types, and /se/log, with fallback to the older endpoints only when the server reports an unknown command or method. Appium 3 session discovery requires starting the server with --allow-insecure='*:session_discovery'.

Legacy device endpoints #

Other legacy device endpoints depend on the installed Appium driver and version. Appium 3 removed several of these endpoints; use the corresponding driver mobile: execute methods where needed, for example:

await driver.execute('mobile: pressKey', [{'keycode': 66}]);

See the Appium 3 endpoint migration guide.

API notes and migration #

Nullable attributes #

Element attribute lookups return String?: an absent attribute is null, distinct from the literal string 'null'.

Android keycode modifiers #

pressKeycodeWithBitmasks and longPressKeycodeWithBitmasks accept integer metastate and flags bitmasks:

await driver.device.pressKeycodeWithBitmasks(66, metastate: 1 | 2, flags: 32);

The original pressKeycode and longPressKeycode methods still accept lists, but are deprecated. Existing calls remain valid:

await driver.device.pressKeycode(66, metastate: [1, 2], flags: [32]);

List entries are combined with bitwise OR before sending. Empty lists produce zero, and omitted or null arguments are not sent.

Supported commands #

WebDriver commands #

See the webdriver.dart API reference.

Some W3C actions
- https://pub.dev/documentation/webdriver/latest/webdriver.io/Mouse-class.html
- https://github.com/google/webdriver.dart/blob/6d7943ef098d3c938b1f4da5a8590fe827f3dd80/lib/src/handler/w3c/mouse.dart

Appium actions #

The client supports W3C commands such as finding elements, clicking, and sending keys. The list below tracks client implementations; availability on the server depends on the Appium version and installed driver. See Appium compatibility for limitations.

Sessions and contexts

✅ directConnectXxxx
✅ batch command
✅ CDP command: [HttpMethod.httpPost, 'session/:session_id/goog/cdp/execute']
✅ [HttpMethod.httpGet, 'appium/sessions'] (legacy fallback: sessions)
✅ [HttpMethod.httpGet, 'session/:session_id/contexts']
✅ [HttpMethod.httpPost, 'session/:session_id/context']
✅ [HttpMethod.httpGet, 'session/:session_id/context']

Legacy element and application commands

~~[x] [HttpMethod.httpPost, 'session/:session_id/appium/element/:id/value']~~ Deprecated.
~~[x] [HttpMethod.httpPost, 'session/:session_id/appium/element/:id/replace_value']~~ Deprecated.
~~[x] [HttpMethod.httpPost, 'session/:session_id/appium/app/launch']~~ Deprecated
~~[x] [HttpMethod.httpPost, 'session/:session_id/appium/app/close']~~ Deprecated
~~[x] [HttpMethod.httpPost, 'session/:session_id/appium/app/reset']~~ Deprecated
✅ [HttpMethod.httpPost, 'session/:session_id/appium/app/background']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/app/strings']

Device and application control

✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/is_locked']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/unlock']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/lock']
✅ [HttpMethod.httpGet, 'session/:session_id/appium/device/system_time']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/install_app']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/remove_app']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/app_installed']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/activate_app']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/terminate_app']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/app_state']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/shake']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/hide_keyboard']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/press_keycode']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/long_press_keycode']

Files and clipboard

✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/push_file']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/pull_file']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/pull_folder']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/get_clipboard']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/set_clipboard']

Settings and device information

✅ [HttpMethod.httpGet, 'session/:session_id/appium/settings']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/settings']
✅ [HttpMethod.httpGet, 'session/:session_id/appium/device/is_keyboard_shown']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/open_notifications']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/device/start_activity']
✅ [HttpMethod.httpGet, 'session/:session_id/appium/device/current_activity']
✅ [HttpMethod.httpGet, 'session/:session_id/appium/device/current_package']
✅ [HttpMethod.httpGet, 'session/:session_id/appium/device/system_bars']
✅ [HttpMethod.httpGet, 'session/:session_id/appium/device/display_density']

Screen recording

❌ [HttpMethod.httpPost, 'session/:session_id/appium/stop_recording_screen']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/start_recording_screen']

Status, elements, and location

✅ [HttpMethod.httpGet, 'status']
✅ [HttpMethod.httpGet, 'session/:session_id/element/:id/displayed']
✅ [HttpMethod.httpGet, 'session/:session_id']
✅ [HttpMethod.httpGet, 'session/:session_id/location']
✅ [HttpMethod.httpPost, 'session/:session_id/location']

Input methods

✅ [HttpMethod.httpGet, 'session/:session_id/ime/available_engines']
✅ [HttpMethod.httpGet, 'session/:session_id/ime/active_engine']
✅ [HttpMethod.httpGet, 'session/:session_id/ime/activated']
✅ [HttpMethod.httpPost, 'session/:session_id/ime/deactivate']
✅ [HttpMethod.httpPost, 'session/:session_id/ime/activate']

Logs and events

✅ [HttpMethod.httpGet, 'session/:session_id/se/log/types'] (legacy fallback: log/types)
✅ [HttpMethod.httpPost, 'session/:session_id/se/log'] (legacy fallback: log)
✅ [HttpMethod.httpGet, 'session/:session_id/appium/events']
✅ [HttpMethod.httpPost, 'session/:session_id/appium/log_event']

Orientation and Flutter finders

✅ [HttpMethod.httpGet, 'session/:session_id/orientation']
✅ [HttpMethod.httpPost, 'session/:session_id/orientation']
✅ Add finder for https://github.com/truongsinh/appium-flutter-driver

Not planned or low priority #

Most of the commands below are available via extension commands, starting with mobile: in https://github.com/appium/appium-uiautomator2-driver, for example. Thus, they would not be implemented.

~~[ ] [HttpMethod.httpPost, 'session/:session_id/touch/perform']~~ # W3C actions should be an alternative
~~[ ] [HttpMethod.httpPost, 'session/:session_id/touch/multi/perform']~~ # W3C actions should be an alternative
~~[ ] [HttpMethod.httpPost, 'session/:session_id/appium/device/keyevent']~~ # Only for Selendroid
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/finger_print']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/compare_images']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/toggle_airplane_mode']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/toggle_wifi']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/toggle_data']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/toggle_location_services']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/app/end_test_coverage']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/performanceData/types']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/getPerformanceData']
❌ [HttpMethod.httpGet, 'session/:session_id/network_connection']
❌ [HttpMethod.httpPost, 'session/:session_id/network_connection']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/send_sms']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/gsm_call']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/gsm_signal']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/gsm_voice']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/network_speed']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/power_capacity']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/device/power_ac']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/simulator/touch_id']
❌ [HttpMethod.httpPost, 'session/:session_id/appium/simulator/toggle_touch_id_enrollment']
~~[ ] [HttpMethod.httpGet, 'session/:session_id/timeouts']~~ <= already has
~~[ ] [HttpMethod.httpPost, 'session/:session_id/keys']~~ <= will be deprecated in W3C. Use W3C actions instead.

Development #

Install dependencies #

dart pub get

Analyze and format #

dart analyze
dart format .

Run tests #

Unit tests:

dart test test/unit

Functional tests require a running Appium server and a configured device or emulator. See the setup in test/functional.

dart test test/functional

Check package quality #

dart run pana .

Release #

Bump the version in pubspec.yaml.
Move the changes under Unreleased in CHANGELOG.md to a section with the release version and date.
Verify CI passes on the minimum supported Dart SDK and stable.
Run dart pub publish --dry-run and review files and warnings.
Commit the release changes.
Run dart pub publish.
Tag the release commit and push the tag.