Flutter Drivers

## The problem this driver is solving A Flutter application does not build a tree of platform widgets. The Flutter engine paints the whole interface onto a single platform surface, so Android's view hierarchy and the element tree the XCUITest driver reads on Apple platforms both see roughly one canvas where a user sees dozens of controls. Automation that works by reading the platform's UI tree therefore starts with almost nothing to match against. Appium's official `appium-flutter-driver` answers that by refusing to work at the platform layer at all. ## What it actually attaches to The driver speaks the **Dart VM Service Protocol**. A Flutter build that carries Flutter's test package publishes a Dart VM Service, and inside that service the test package registers a service extension named **`ext.flutter.driver`**. The driver opens a **WebSocket** to that service and pushes every find, tap and query through the extension, which executes it against the live widget tree inside the app's own Dart isolate. Three consequences follow directly from that choice of channel: - **This driver ships no on-device agent of its own.** On Android the UiAutomator2 driver pushes and starts a helper server before the session; on Apple platforms the XCUITest driver builds, installs and launches WebDriverAgent. The Flutter driver dials a service the app is already publishing and installs nothing. - **Finds are resolved in Dart, not in an accessibility tree.** While the driver is working through the extension, nothing reads Android's `resource-id` or `content-desc`, and nothing reads the `name` attribute the XCUITest driver exposes on Apple platforms. - **The build has to be made attachable.** The extension exists only because the test package is compiled in, and the driver's README says plainly that such an app cannot be released as-is. ## The contexts, and the two locator strategies The driver exposes three contexts: `FLUTTER`, `NATIVE_APP` and `WEBVIEW`. Only `FLUTTER` goes through the Dart VM Service. The other two exist because a real screen is not all Flutter — a system permission dialog, an embedded platform view or a web view is drawn by the platform rather than by the engine, and the ordinary Android and Apple backends own that ground. Inside the Flutter context the driver declares exactly **two** locator strategies: - `key` — the widget key the app author set, which is how Flutter's own test API addresses widgets. - `css selector` — the driver's second declared strategy. That is a far smaller vocabulary than the native drivers offer. Android's UiAutomator2 driver declares six strategies, including `-android uiautomator`; the XCUITest driver declares eight native ones on Apple platforms, including `-ios predicate string` and `-ios class chain`. None of those travel into the Flutter context, so a suite moving onto this driver rewrites its locators rather than porting them. The driver also carries its own `flutter:` execute methods — a namespaced name plus one parameter map — instead of adding endpoints of its own. ## How it compares with the two native drivers | | Official Flutter driver | Android's UiAutomator2 driver | XCUITest driver (Apple platforms) | |---|---|---|---| | Talks to | the Dart VM Service over a WebSocket | a helper server started on the device | WebDriverAgent built and launched on the device | | Installs an agent | no | yes | yes | | Sees | the Dart widget tree | the Android view and accessibility tree | the Apple element tree | | Declared native strategies | two: `key`, `css selector` | six | eight | | Can drive a store build | no | yes | yes | ## Why the channel decides everything else Attaching to the VM Service buys genuine widget-level access: you address the same keys the app's own widget tests address, and you stop fighting a canvas. It costs release parity, because the artifact you can attach to is not the artifact you ship. That single trade explains the rest of the Flutter story in Appium — it is why a second, community driver exists at all (`appium-flutter-integration-driver`, built on Flutter's `integration_test`), and why many teams use neither and drive a release Flutter build with the ordinary Android and Apple drivers against identifiers the app sets in its semantics tree. Both Flutter drivers are installed the way Appium 2 made every driver installable, with `appium driver install`, and a session picks one with `appium:automationName`; the official driver answers to the name `Flutter`. - If an answer stops at *it drives Flutter widgets*, it has said nothing that separates this driver from the alternatives. - If it names the Dart VM Service, `ext.flutter.driver` and the build requirement, it has described the driver's whole shape in one breath.