↓Skip to main content
Dev Blog Dev Blog
  1. All Posts/

appium-flutter-driver

Tools TypeScript

Appium Flutter Driver



Appium Flutter Driver is a test automation tool for Flutter apps on multiple platforms/OSes. Appium Flutter Driver is part of the Appium mobile test automation tool maintained by community. Feel free to create PRs to fix issues/improve this driver.
This package is still experiment, breaking changes and breaking codes are to be expected! All contributions, including non-code, are welcome! See TODO list below.

Flutter Driver vs Appium Flutter Driver

Even though Flutter comes with superb integration test support, Flutter Driver, it does not fit some specific use cases, such as

  • writing test in other languages than Dart
  • running integration test for Flutter app with embedded webview or native view, or existing native app with embedded Flutter view
  • running test on multiple devices simultaneously
  • running integration test on device farms, such as Sauce Labs, HeadSpin, AWS, Firebase

Under the hood, Appium Flutter Driver use the Dart VM Service Protocol with extension ext.flutter.driver, similar to Flutter Driver, to control the Flutter app-under-test (AUT).

Installation

  • In order to use appium-flutter-driver, we need to use appium version 1.16.0 or higher.
  • The Appium Flutter Driver version 1.0 and higher require Appium 2.0.0.
    • 1.8.0+ require over Appium 2.0.0-beta.46

With Appium 2 (appium@next):

appium driver install --source=npm appium-flutter-driver

Note
Please use the latest flutter driver with appium 2 for Flutter v3

With Appium 1:

npm i -g appium-flutter-driver

Usage

If you are unfamiliar with running Appium tests, start with Appium Getting Starting first.
Your Flutter app-under-test (AUT) must be compiled in debug or profile mode, because Flutter Driver does not support running in release mode.. Also, ensure that your Flutter AUT has enableFlutterDriverExtension() before runApp. Then, please make sure your app imported flutter_driver package as its devDependencies as well.
This snippet, taken from example dir, is a script written as an appium client with webdriverio, and assumes you have appium server (with appium-flutter-driver installed) running on the same host and default port (4723). For more info, see example’s README.md

Desired Capabilities for flutter driver only

Capability
Description
Example Values

appium:retryBackoffTime
The time wait for socket connection retry for get flutter session (default 3000ms)
500

appium:maxRetryCount
The count for socket connection retry for get flutter session (default 30)
20

appium:observatoryWsUri
The URL to attach to the Dart VM. The appium flutter driver finds the WebSocket URL from the device log by default. You can skip the finding the URL process by specifying this capability. Then, this driver attempt to establish a WebSocket connection against the given WebSocket URL. Note that this capability espects the URL is ready for access by outside an appium session. This flutter driver does not do port-forwarding with this capability. You may need to coordinate the port-forwarding as well.
‘ws://127.0.0.1:60992/aaaaaaaaaaa=/ws’

appium:skipPortForward
Whether skip port forwarding from the flutter driver local to the device under test with observatoryWsUri capability. It helps you to manage the application under test, the observatory URL and the port forwarding configuration. The default is true.
true, false

Context

Appium Flutter Driver allow you to send flutter_driver commands to the Dart VM in FLUTTER context, but it does not support native Android/iOS automation. Instead, NATIVE_APP context provide you to use UIA2 drier for Android and XCUITest for iOS automation. WEBVIEW_XXXX cntext helps WebView testing.
Thus, you can automate proper application target by switching its context with FLUTTER, NATIVE_APP and WEBVIEW_XXXX.

Example 

const wdio = require('webdriverio');
const assert = require('assert');
const { byValueKey } = require('appium-flutter-finder');

const osSpecificOps = process.env.APPIUM_OS === 'android' ? {
  'platformName': 'Android',
  'appium:deviceName': 'Pixel 2',
  // @todo support non-unix style path
  app: __dirname +  '/../apps/app-free-debug.apk',
}: process.env.APPIUM_OS === 'ios' ? {
  'platformName': 'iOS',
  'appium:platformVersion': '12.2',
  'appium:deviceName': 'iPhone X',
  'appium:noReset': true,
  'appium:app': __dirname +  '/../apps/Runner.zip',

} : {};

const opts = {
  port: 4723,
  capabilities: {
    ...osSpecificOps,
    'appium:automationName': 'Flutter',
    'appium:retryBackoffTime': 500
  }
};

(async () => {
  const counterTextFinder = byValueKey('counter');
  const buttonFinder = byValueKey('increment');

  const driver = await wdio.remote(opts);

  if (process.env.APPIUM_OS === 'android') {
    await driver.switchContext('NATIVE_APP');
    await (await driver.$('~fab')).click();
    await driver.switchContext('FLUTTER');
  } else {
    console.log('Switching context to `NATIVE_APP` is currently only applicable to Android demo app.')
  }

  assert.strictEqual(await driver.getElementText(counterTextFinder), '0');

  await driver.elementClick(buttonFinder);
  await driver.touchAction({
    action: 'tap',
    element: { elementId: buttonFinder }
  });

  assert.strictEqual(await driver.getElementText(counterTextFinder), '2');

  driver.deleteSession();
})();

Changelog

  • appium-flutter-driver
  • each finder

API

Legend:

Icon
Description

✅
integrated to CI

🆗
manual tested without CI

⚠️
available without manual tested

❌
unavailable

Finders

Flutter Driver API
Status
WebDriver example

ancestor
🆗

bySemanticsLabel
🆗

byTooltip
🆗
byTooltip('Increment')

byType
🆗
byType('TextField')

byValueKey
🆗
byValueKey('counter')

descendant
🆗

pageBack
🆗
pageBack()

text
🆗
byText('foo')

Commands

The below WebDriver example is by webdriverio.
flutter: prefix commands are mobile: command in appium for Android and iOS.
Please replace them properly with your client.

Flutter API
Status
WebDriver example (JavaScript, webdriverio)
Scope

FlutterDriver.connectedTo
🆗
wdio.remote(opts)
Session

checkHealth
🆗
driver.execute('flutter:checkHealth')
Session

clearTextbox
🆗
driver.elementClear(find.byType('TextField'))
Session

clearTimeline
🆗
driver.execute('flutter:clearTimeline')
Session

close
🆗
driver.deleteSession()
Session

enterText
🆗

driver.elementSendKeys(find.byType('TextField'), 'I can enter text') (no focus required) driver.elementClick(find.byType('TextField')); driver.execute('flutter:enterText', 'I can enter text') (focus required by tap/click first)
Session

forceGC
🆗
driver.execute('flutter:forceGC')
Session

getBottomLeft
🆗
driver.execute('flutter:getBottomLeft', buttonFinder)
Widget

getBottomRight
🆗
driver.execute('flutter:getBottomRight', buttonFinder)
Widget

getCenter
🆗
driver.execute('flutter:getCenter', buttonFinder)
Widget

getRenderObjectDiagnostics
🆗
driver.execute('flutter:getRenderObjectDiagnostics', counterTextFinder)
Widget

getRenderTree
🆗
driver.execute('flutter: getRenderTree')
Session

getSemanticsId
🆗
driver.execute('flutter:getSemanticsId', counterTextFinder)
Widget

getText
🆗
driver.getElementText(counterTextFinder)
Widget

getTopLeft
🆗
driver.execute('flutter:getTopLeft', buttonFinder)
Widget

getTopRight
🆗
driver.execute('flutter:getTopRight', buttonFinder)
Widget

getVmFlags
❌

Session

getWidgetDiagnostics
❌

Widget

requestData
🆗
driver.execute('flutter:requestData', json.dumps({"deepLink": "myapp://item/id1"}))
Session

runUnsynchronized
❌

Session

setFrameSync
🆗
driver.execute('flutter:setFrameSync', bool , durationMilliseconds)
Session

screenshot
🆗
driver.takeScreenshot()
Session

screenshot
🆗
driver.saveScreenshot('a.png')
Session

scroll
🆗
driver.execute('flutter:scroll', find.byType('ListView'), {dx: 50, dy: -100, durationMilliseconds: 200, frequency: 30})
Widget

scrollIntoView
🆗

driver.execute('flutter:scrollIntoView', find.byType('TextField'), {alignment: 0.1}) driver.execute('flutter:scrollIntoView', find.byType('TextField'), {alignment: 0.1, timeout: 30000})

Widget

scrollUntilVisible
🆗
driver.execute('flutter:scrollUntilVisible', find.byType('ListView'), {item:find.byType('TextField'), dxScroll: 90, dyScroll: -400});
Widget

scrollUntilTapable
🆗
driver.execute('flutter:scrollUntilTapable', find.byType('ListView'), {item:find.byType('TextField'), dxScroll: 90, dyScroll: -400});
Widget

setSemantics
❌

Session

setTextEntryEmulation
🆗
driver.execute('flutter:setTextEntryEmulation', false)
Session

startTracing
❌

Session

stopTracingAndDownloadTimeline
❌

Session

tap
🆗
driver.elementClick(buttonFinder)
Widget

tap
🆗
driver.touchAction({action: 'tap', element: {elementId: buttonFinder}})
Widget

traceAction
❌

Session

waitFor
🆗
driver.execute('flutter:waitFor', buttonFinder, 100)
Widget

waitForAbsent
🆗
driver.execute('flutter:waitForAbsent', buttonFinder)
Widget

waitForTappable
🆗
driver.execute('flutter:waitForTappable', buttonFinder)
Widget

waitUntilNoTransientCallbacks
❌

Widget

–
🆗
driver.execute('flutter:getVMInfo')
System

–
🆗
driver.execute('flutter:setIsolateId', 'isolates/2978358234363215')
System

–
🆗

driver.execute('flutter:getIsolate', 'isolates/2978358234363215') or driver.execute('flutter:getIsolate')

System

–
🆗
setContext
Appium

–
🆗
getCurrentContext
Appium

–
🆗
getContexts
Appium

❓
🆗
driver.execute('flutter:longTap', find.byValueKey('increment'), {durationMilliseconds: 10000, frequency: 30})
Widget

❓
🆗
driver.execute('flutter:waitForFirstFrame')
Widget

–
🆗
activateApp('appId')
Appium

–
🆗
terminateApp('appId')
Appium

Note

  • Flutter context does not support page source
    • Please use getRenderTree command instead
  • You can send appium-xcuitest-driver/appium-uiautomator2-driver commands in NATIVE_APP context
  • scrollUntilVisible command : An expectation for…


↑