Skip to content
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.
TypeScript Dart JavaScript Objective-C Java
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode 0.0.8: forceGC Jul 23, 2019
driver fix(package): update appium-base-driver to version 4.0.1 (#17) Sep 25, 2019
finder/nodejs fix build Aug 26, 2019
.gitignore first working prototype with android and ios Jul 21, 2019
LICENSE npm publish Jul 21, 2019 Update Aug 27, 2019
greenkeeper.json chore: add Greenkeeper config file Jul 29, 2019
saucelabs.svg update README and add saucelabs as testing sponsor Jul 23, 2019

Appium Flutter Driver

Build Status Greenkeeper badge NPM version Downloads Dependency Status devDependency Status

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.

⚠️ pre-0.1.x version

This package is in early stage of exprienment, 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 simultanously
  • running integration test on device farms, such as Saucelabs, 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).


In order to use appium-flutter-driver, we need to use a patched version of appium (see PR#12945)

npm i -g appium-flutter-driver git://


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.

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

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

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

} : {};

const opts = {
  port: 4723,
  capabilities: {
    automationName: 'Flutter'

(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');




Icon Description
integrated to CI
🆗 manual tested without CI
⚠️ availalbe without manual tested


Flutter Driver API Status WebDriver example
ancestor 🆗
bySemanticsLabel 🆗
byTooltip 🆗
byType 🆗
byValueKey 🆗 byValueKey('counter')
descendant 🆗
pageBack 🆗 pageBack()
text 🆗 byText('foo')


Flutter API Status WebDriver example Scope
FlutterDriver.connectedTo 🆗 wdio.remote(opts) Session
checkHealth 🆗 driver.execute('flutter:checkHealth') 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)
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 Session
runUnsynchronized 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}) Widget
scrollUntilVisible 🆗 driver.execute('flutter:scrollUntilVisible', find.byType('ListView'), {item:find.byType('TextField'), dxScroll: 90, dyScroll: -400}); Widget
setSemantics Session
setTextEntryEmulation 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) Widget
waitForAbsent 🆗 driver.execute('flutter:waitForAbsent', buttonFinder) Widget
waitUntilNoTransientCallbacks Widget
🆗 setContext Appium
⚠️ getCurrentContext Appium
⚠️ getContexts Appium
longTap Widget


  • iOS Real device
  • CI (unit test / integration test with demo app)
  • CD (automatic publish to npm)
  • finder as a seperate package
  • switching context between Flutter and AndroidView
  • switching context between Flutter and UiKitView
  • switching context between Flutter and webview
  • Flutter-version-aware API
  • Error handling

Test Status

Saucelabs Test Status

Powered by Saucelabs

You can’t perform that action at this time.