appium_driver #

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.flutter-io.cn/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 #

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