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
- 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
NATIVE_APP
context is the same as regular Appium UiAutomator2/XCUITest driverWEBVIEW
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 useappium
version1.16.0
or higher. - The Appium Flutter Driver version 1.0 and higher require Appium 2.0.0.
1.8.0
+ require over Appium2.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
- Please use
- 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 elementscrollUntilTapable
command : An expectation for checking an element is visible and enabled such that you can click it. Using waitTapable to wait elementdriver.activateApp(appId)
starts the given app and attaches to the observatory URL in theFLUTTER
context. The method may raise an exception if no observaotry URL was found. The typical case is theappId
is already running. Then, the driver will fail to find the observatory URL.getClipboard
andsetClipboard
depend on eachNATIVE_APP
context behavior
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 expects 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 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();
})();
Changelog
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}); , driver.execute('flutter:scrollUntilVisible', find.byType('ListView'), {item:find.byType('TextField'), dxScroll: 90, dyScroll: -400, waitTimeoutMilliseconds: 20000}); |
Widget | |
scrollUntilTapable | driver.execute('flutter:scrollUntilTapable', find.byType('ListView'), {item:find.byType('TextField'), dxScroll: 90, dyScroll: -400}); , driver.execute('flutter:scrollUntilTapable', find.byType('ListView'), {item:find.byType('TextField'), dxScroll: 90, dyScroll: -400, waitTimeoutMilliseconds: 20000}); |
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 | |
tap | driver.execute('flutter:clickElement', buttonFinder, {timeout:5000}) |
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 | |
- | installApp(appPath, options) |
Appium | |
- | getClipboard |
Appium | |
- | setClipboard |
Appium |
Change the flutter engine attache to
- Get available isolate ids
id
key in the value ofisolates
byflutter:getVMInfo
- 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
- Get available isolates
driver.execute('flutter:getVMInfo').isolates
(JS)
- Get a particular isolate or current isolate
- Current isolate:
driver.execute('flutter:getIsolate')
(JS) - Particular isolate:
driver.execute('flutter:getIsolate', 'isolates/2978358234363215')
(JS)
- Current isolate:
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