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.

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).

Appium Flutter Driver or Appium UiAutomator2/XCUITest driver

• Appium Flutter driver manages the application under test and the device under test via Appium UiAutomator2/XCUITest drivers
  • FLUTTER context sends commands to the Dart VM directly over the observatory URL
    • Newer Flutter versions expose its accessibility labels to the system's accessibility features. It means you can find some Flutter elements and can interact with them over accessibility_id etc in the vanilla Appium UiAutomator2/XCUITest drivers, although some elements require over the Dart VM
  • NATIVE_APP context is the same as regular Appium UiAutomator2/XCUITest driver
    • Please refer to each client documentation about available command.
    • Each driver documentation also may help.
      • https://github.com/appium/appium-uiautomator2-driver
      • https://appium.github.io/appium-xcuitest-driver/latest
  • WEBVIEW context manages the WebView contents over Appium UiAutomator2/XCUITest driver
• Appium UiAutomator2/XCUITest drivers must be sufficient to achieve automation if the application under test had semanticLabel properly. Then, accessibility mechanism in each OS can expose elements for Appium though OS's accessibility features
  • For example, Key does not work in the Appium UiAutomator2/XCUITest drivers, but can work in the Appium Flutter Driver

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

As a local:

appium driver install --source local /path/to/appium-flutter-driver/driver

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

Appium 1.x could have flutter driver, but the version is deprecated.

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

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 checking that an element, known to be present on the widget tree, is visible. Using waitFor to wait element
• scrollUntilTapable command : An expectation for checking an element is visible and enabled such that you can click it. Using waitTapable to wait element
• driver.activateApp(appId) starts the given app and attaches to the observatory URL in the FLUTTER context. The method may raise an exception if no observaotry URL was found. The typical case is the appId is already running. Then, the driver will fail to find the observatory URL.
• getClipboard and setClipboard depend on each NATIVE_APP context behavior
• Launch via 3rd party tool and attach for an iOS real device (debug/profile build)
  1. Do not set app nor bundleId to start a session without launching apps
  2. Start the app process via 3rd party tools such as go-ios to start the app process with debug mode in the middle of the new session process in 1) the above.
     • Then, the appium flutter session establish the WebSocket and proceed the session

Desired Capabilities for flutter driver only

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 driver 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();
})();

Several ways to start an application

You have a couple of methods to start the application under test with establishing the Dart VM connection as below:

1. Start with app in the capabilities
   1. The most standard method. You may need to start a new session with app capability. Then, appium-flutter-driver will start the app, and establish a connection with the Dart VM immediately.
2. Start with activate_app
   1. Start a session without app capability
   2. Install the application under test via driver.install_app or mobile:installApp command
   3. Activate the app via driver.activate_app or mobile:activateApp command
      • Then, appium-flutter-driver establish a connection with the Dart VM
3. Launch app outside the driver
   1. Start a session without app capability
   2. Install the application under test via driver.install_app or mobile:installApp command etc
   3. Calls flutter:connectObservatoryWsUrl command to keep finding an observatory URL to the Dart VM
      • appium:retryBackoffTime and appium:maxRetryCount will control the duration to keep finding an observatory URL to the Dart VM
   4. (at the same time) Launch the application under test via outside the appium-flutter-driver
      • e.g. Launch an iOS process via ios-go, iproxy or tidevice
   5. Once flutter:connectObservatoryWsUrl identify the observatory URL, the command will establish a connection to the Dart VM

Changelog

• appium-flutter-driver
• each finder

API

Legend:

Finders

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.

Change the flutter engine attache to

1. Get available isolate ids
   • id key in the value of isolates by flutter:getVMInfo
2. Set the id via setIsolateId

# ruby
info = driver.execute_script 'flutter:getVMInfo'
# Change the target engine to "info['isolates'][0]['id']"
driver.execute_script 'flutter:setIsolateId', info['isolates'][0]['id']

Check current isolate, or a particular isolate

1. Get available isolates
   • driver.execute('flutter:getVMInfo').isolates (JS)
2. Get a particular isolate or current isolate
   • Current isolate: driver.execute('flutter:getIsolate') (JS)
   • Particular isolate: driver.execute('flutter:getIsolate', 'isolates/2978358234363215') (JS)

TODO?

Items which may be worth to add.

• CD (automatic publish to npm)
• switching context between Flutter and AndroidView
• switching context between Flutter and UiKitView
• Web: FLUTTER_WEB context?
• macOS: with https://github.com/appium/appium-mac2-driver
• Windws?
• Linux?

Test Status

Release appium-flutter-driver

$ cd driver
$ sh release.sh
$ npm version <major|minor|patch>
$ git commit -am 'chore: bump version'
$ git tag <version number> # e.g. git tag v0.0.32
$ git push origin v0.0.32
$ git push origin main
$ npm publish

Java implementation

https://github.com/ashwithpoojary98/javaflutterfinder