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.

⚠️ 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 Sauce Labs, 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

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 .

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 retryBackoffTime the time wait for socket connection retry for get flutter session (default 300000ms) 500 maxRetryCount the count for socket connection retry for get flutter session (default 10) 20

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 ' , 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/Runner.zip ' , } : { } ; const opts = { port : 4723 , capabilities : { ... osSpecificOps , automationName : ' Flutter ' , 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 ( ) ; } ) ( ) ;

API

Legend:

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

Finders

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

Commands

TODO

iOS Real device

iOS Real device CI (unit test / integration test with demo app)

CI (unit test / integration test with demo app) CD (automatic publish to npm)

CD (automatic publish to npm) finder as a seperate package

as a seperate package switching context between Flutter and AndroidView

switching context between Flutter and AndroidView switching context between Flutter and UiKitView

switching context between Flutter and UiKitView switching context between Flutter and webview

switching context between Flutter and webview Flutter-version-aware API

Flutter-version-aware API Error handling

Test Status