appium / appium/appium-flutter-driver

Request for guidance: Unreliable Dart Observatory connection when using Appium Flutter Driver + byValueKey locators

Open
#862 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

question
Dominant language
TypeScript
Stars
539
Forks
195
Avg merge
1h 11m
Merged PRs (30d)
4

Description

Dear Appium-Flutter Team,
I am writing to seek technical guidance on a persistent integration issue between Flutter and Appium for UI automation.
Project context:

Flutter version: 3.41.6 (stable channel, managed via FVM)
Appium version: 3.2.2
Automation name: Flutter
Device: Pixel 2 emulator (Android 11)
Host: Ubuntu 25.10 on MacBook Pro (ARM)
We use appium_flutter_finder + FlutterFinder.by_value_key()

Widgets are properly instrumented:
In our login screen (login_page.dart), every interactive widget has both ValueKey and Semantics:

DartSemantics(
identifier: 'email_input',
label: 'email_input',
child: FormBuilderTextField(
key: const ValueKey('email_input'),
...
),
)

(The same pattern is used for password_input and login_button.)
We also call enableFlutterDriverExtension(); as the first statement in main.dart (before WidgetsFlutterBinding.ensureInitialized() and runApp()).
The exact problem:
Even though:

The Appium session successfully starts and reports both NATIVE_APP and FLUTTER contexts,
We can manually launch the app from Android Studio,
We see the Observatory URL in Logcat sometimes,

the command flutter:connectObservatoryWsUrl (and the three retry strategies with different payloads) consistently fails with one of the following:

"Cannot connect to the Dart Observatory URL ws://127.0.0.1:XXXXX/.../ws"
"No observatory URL matching ... was found in the device log"

As a result, we never reach the stage of using byValueKey("email_input"), flutter:waitFor, flutter:tap, or flutter:enterText.
We have tried:

Manual launch outside driver + flutter:connectObservatoryWsUrl
Automatic launch via capabilities
Different timeout/isolate payloads
Full flutter clean + pub get after fixing pubspec conflicts (intl, etc.)

Our goal:
A reliable Flutter-only automation path using Widget Finder / byValueKey / FLUTTER context without falling back to native locators (UiAutomator2, accessibility ID, XPath).
Could the Flutter team please advise on:

Any recent changes in the VM service extension (ext.flutter.driver) or Observatory discovery that might affect Appium Flutter Driver?
Recommended best practices for stable Observatory attachment in emulator environments with FVM?
Whether there are plans to improve the official flutter_driver integration with external tools like Appium (e.g., more robust port discovery or a dedicated extension API)?

Any suggestions, workarounds, or pointers to internal documentation would be greatly appreciated. I am happy to provide a minimal reproducible repository or Logcat/Appium logs if helpful.
Thank you for your continued work on Flutter and for any assistance you can provide.
Best regards,
Nick

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the enableFlutterDriverExtension setup in main.dart and the keyed widgets in login_page.dart, then inspect Logcat/Appium logs around flutter:connectObservatoryWsUrl. Compare the manual and automatic launch attempts and the different timeout/isolate payloads. Done means reliably attaching to the Observatory and reaching the FLUTTER context for byValueKey, waitFor, tap, and enterText.

Written by the indexing model from the issue text.

Assessment

Tech stack
flutter
Domain
mobile-dev, testing-qa
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.