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 the community. Feel free to create PRs to fix issues/improve this driver.
Even though Flutter comes with superb integration test support, Flutter Driver, it does not fit some specific use cases, such as
- Writing tests 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 tests on multiple devices simultaneously
- Running integration tests on device farms that offer Appium support (Please contact the availability for each vendor)
Under the hood, Appium Flutter Driver uses 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 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 the regular Appium UiAutomator2/XCUITest driver- Please refer to each client's documentation about available commands.
- Each driver's documentation also may help.
WEBVIEW
context manages the WebView contents over Appium UiAutomator2/XCUITest driver
- (Recommended if possible) Appium UiAutomator2/XCUITest drivers must be sufficient to achieve automation if the application under test had
semanticLabel
properly. Then, the accessibility mechanism in each OS can expose elements for Appium through OS's accessibility features. Then, this driver is not necessary.- For example, Key does not work in the Appium UiAutomator2/XCUITest drivers, but can work in the Appium Flutter Driver
- Flutter 3.19 may have
identifier
forSemanticsProperties
(introduced by flutter/flutter#138331). It setsresource-id
andaccessibilityIdentifier
for Android and iOS, then UiAutomator2/XCUITest drivers also can handleKey
without this driver"appium:disableIdLocatorAutocompletion": true
would be necessary to makeresource-id
idea work without any package name prefix like Android compose.- e.g. flutter/flutter#17988 (comment)
Appium Flutter Driver version 1.0 and higher require Appium 2.0.
appium driver install --source=npm appium-flutter-driver
As a local:
appium driver install --source local /path/to/appium-flutter-driver/driver
If you are unfamiliar with running Appium tests, start with Quickstart Intro first.
Your Flutter application must be compiled in debug
or profile
mode. The dependency must have flutter_driver
package like the below pubspec.yaml
example with enableFlutterDriverExtension
configuration in the main.dart
.
# pubspec.yaml
dev_dependencies:
flutter_driver:
sdk: flutter
This snippet, taken from example directory, 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
This means this driver depends on
flutter_driver
.
Each client needs each finder module to handle Finders. Appium Flutter Driver communicates with the Dart VM directory in the FLUTTER
context.
Note Expand deprecation policy to package:flutter_driver potentially means this driver will no longer work by the future Flutter updates. They do not cover all cases that can cover the flutter_driver, such as permission dialog handling, thus we're not sure when the time comes though.
Since driver version 2.4.0 you can automate the validation for the most of the above requirements as well as various optional ones needed by driver extensions by running the appium driver doctor flutter
server command.
The check runs for Android for UIAutomator2 driver and iOS for XCUITest driver.
- 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- Launch via
flutter:launchApp
or 3rd party tool (via instrument service) and attach to the Dart VM for an iOS real device (profile build)- Do not set
app
norbundleId
to start a session without launching apps - 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
- Do not set
- keyboard interaction may not work in Android because of flutter/flutter#15415 that is caused by
flutter_driver
Capability | Description | Example Values |
---|---|---|
appium:retryBackoffTime | The time wait for socket connection retry to get flutter session (default 3000ms) | 500 |
appium:maxRetryCount | The count for socket connection retry for get flutter session (default 10) | 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:isolateId | The isolate id to attach to as the initial attempt. A session can change the isolate with flutter:setIsolateId command. The default behavior finds main isolate id and attaches it. |
isolates/2978358234363215 , 2978358234363215 |
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 |
appium:remoteAdbHost | The IP/hostname of the remote host ADB is running on. This capability only makes sense for Android platform. Providing it will implicitly override the host for the Observatory URL if the latter is determined from device logs. localhost be default | 192.168.1.20 |
appium:adbPort | The port number ADB server is running on. This capability only makes sense for Android platform. 5037 by default | 9999 |
appium:forwardingPort | The port number that will be used to forward the traffic from the device under test to locahost. Only applicable if skipPortForward is falsy. Not applicable if the test is executed on iOS Simulator. By default, it is the same as in the provided or autodetected Observatory URL. |
9999 |
Please check each driver's documentation
- https://github.com/appium/appium-uiautomator2-driver
- https://appium.github.io/appium-xcuitest-driver/latest/capabilities/
Appium Flutter Driver allows you to send flutter_driver
commands to the Dart VM in the FLUTTER
context, but it does not support native Android/iOS since the Dart VM can handle in the Dart VM contents. NATIVE_APP
context provides you to use the UIA2 driver for Android and the XCUITest driver for iOS automation. WEBVIEW_XXXX
context helps WebView testing over the UIA2/XCUITest driver that is not available via the flutter_driver.
Thus, you need to switch proper contexts, FLUTTER
, NATIVE_APP
or WEBVIEW_XXXX
, to automate a proper application target.
# webdriverio
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',
'appium: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();
})();
Please check example in this repository for more languages.
You have a couple of methods to start the application under test by establishing the Dart VM connection as below:
- Start with
app
in the capabilities- 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.
- The most standard method. You may need to start a new session with
- Start with
activate_app
: for users who want to start the application under test in the middle of a session- Start a session without
app
capability - Install the application under test via
driver.install_app
ormobile:installApp
command - Activate the app via
driver.activate_app
ormobile:activateApp
command- Then, appium-flutter-driver establish a connection with the Dart VM
- Start a session without
- Launch the app outside the driver: for users who want to manage the application under test by yourselves
- Start a session without
app
capability - Install the application under test via
driver.install_app
ormobile:installApp
command etc - Calls
flutter:connectObservatoryWsUrl
command to keep finding an observatory URL to the Dart VMappium:retryBackoffTime
andappium:maxRetryCount
will control the duration to keep finding an observatory URL to the Dart VM
- (at the same time) Launch the application under test via outside the appium-flutter-driver
- Once
flutter:connectObservatoryWsUrl
identify the observatory URL, the command will establish a connection to the Dart VM
- Start a session without
- Launch the app with
flutter:launchApp
for iOS and attach to the Dart VM: for users whom application under test do not print the observatory url via regular launch/activate app method- Start a session without
app
capability - Install the application under test via
driver.install_app
ormobile:installApp
command etc - Calls
flutter:launchApp
command to start an iOS app via instrument servicedriver.execute_script 'flutter:launchApp', 'com.example.bundleId', {arguments: ['arg1'], environment: {ENV1: 'env'}}
is example usage- This launching method is the same as the above 3rd party method, but does the same thing only via the appium flutter driver.
- Start a session without
Please make sure the target app process stops before starting the target app with the above.
Please check each driver's documentation
- https://github.com/appium/appium-uiautomator2-driver
- https://appium.github.io/appium-xcuitest-driver/latest
Legend:
Icon | Description |
---|---|
β | integrated to CI |
π | manual tested without CI |
available without manual tested | |
β | unavailable |
Flutter Driver API | Status | WebDriver example |
---|---|---|
ancestor | π | |
bySemanticsLabel | π | |
byTooltip | π | byTooltip('Increment') |
byType | π | byType('TextField') |
byValueKey | π | byValueKey('counter') |
descendant | π | |
pageBack | π | pageBack() |
text | π | byText('foo') |
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 |
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 |
β | π | driver.execute('flutter:longTap', find.byValueKey('increment'), {durationMilliseconds: 10000, frequency: 30}) |
Widget |
β | π | driver.execute('flutter:waitForFirstFrame') |
Widget |
- | π | (Ruby) driver.execute_script 'flutter:connectObservatoryWsUrl' |
Flutter Driver |
- | π | (Ruby) driver.execute_script 'flutter:launchApp', 'bundleId', {arguments: ['arg1'], environment: {ENV1: 'env'}} |
Flutter Driver |
NOTE
flutter:launchApp
launches an app via instrument service.mobile:activateApp
anddriver.activate_app
are via XCTest API. They are a bit different.
- 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']
- 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:
These Appium commands can work across context
deleteSession
setContext
getCurrentContext
getContexts
activateApp('appId')
/mobile:activateApp
mobile:activateApp
hasskipAttachObservatoryUrl
key to not try to attach to an observatory url. e.g.driver.execute_script 'mobile:activateApp', {skipAttachObservatoryUrl: true, appId: 'com.android.chrome'}
terminateApp('appId')
/mobile:terminateApp
installApp(appPath, options)
getClipboard
setClipboard
- input texts appium#417
- Looks hanging in
click
appium#181 (comment)flutter:setFrameSync
may help
- 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?
$ cd driver
$ sh release.sh
$ npm version <major|minor|patch>
# update changelog
$ 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
https://github.com/ashwithpoojary98/javaflutterfinder
https://github.com/5v1988/appium-flutter-client