Appium Flutter Driver

To automate different parts of a Flutter application, you must switch between three primary contexts:

1. FLUTTER: Used to send flutter_driver commands to the Dart VM. This is where you interact with Flutter widgets.
2. NATIVE_APP: Used to interact with native Android (via UiAutomator2) or iOS (via XCUITest) elements. Use this for system dialogs or native components surrounding the Flutter app.
3. WEBVIEW_XXXX: Used for testing WebViews that are not accessible via flutter_driver.

You must explicitly call driver.switchContext() to move between these targets.

// Example context switching in WebdriverIO
if (process.env.APPIUM_OS === 'android') {
  await driver.switchContext('NATIVE_APP');
  await (await driver.$('~fab')).click(); // Interact with native element
  await driver.switchContext('FLUTTER'); // Switch back to Flutter widgets
}

The Appium Flutter Driver exposes the underlying Flutter Driver API through the execute command. In most WebDriver clients, you use a command prefix (like flutter: for Android/iOS or mobile: in standard Appium) to invoke these specific Flutter capabilities.

Commands are categorized by their Scope:

• Session: Affects the entire driver session.
• Widget: Acts upon a specific element found via a Finder.
• System: Low-level system or VM information.

Note: The examples below use webdriverio syntax. Replace driver.execute('flutter:...') with the appropriate method for your specific client (e.g., driver.execute_script in Python or driver.execute_script in Ruby).

The Appium Flutter Driver manages three distinct contexts to allow interaction with different layers of the application:

• FLUTTER: Sends commands directly to the Dart VM over the observatory URL. This allows for direct interaction with Flutter elements using the flutter_driver API. Note that page source is not supported in this context; use the getRenderTree command instead.
• NATIVE_APP: Uses the standard Appium UIAutomator2 (Android) or XCUITest (iOS) driver. This is useful for interacting with native OS elements or system dialogs.
• WEBVIEW: Manages WebView contents using the underlying native driver (UIAutomator2 or XCUITest).

As of version 0.3.0, appium-flutter-finder is an ESM-only package. You must use import statements instead of require(). Deep imports from appium-flutter-finder/build/... are no longer supported; always import from the package root.

// Standard ESM import
import * as finder from 'appium-flutter-finder';

// Named imports
import {byText, byValueKey} from 'appium-flutter-finder';

To use Appium Flutter Driver version 3.0.0 or later, you must have Appium 3 installed. You can install the driver via npm or from a local path.

Install via npm:

appium driver install --source=npm appium-flutter-driver

Install from a local path:

appium driver install --source local /path/to/appium-flutter-driver/driver

To use the Kotlin finder elements for the Appium Flutter Driver in your Android project, you can include them via JitPack. You must first configure your settings.gradle to include the JitPack repository, and then add the dependency to your build.gradle file.

Note that the package name for this project is pro.truongsinh.appium_flutter.

// settings.gradle
dependencyResolutionManagement {
	repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
	repositories {
		mavenCentral()
		maven { url 'https://jitpack.io' }
	}
}

// build.gradle
dependencies {
	// Use the specific version or main-SNAPSHOT
	testImplementation 'com.github.appium:appium-flutter-driver:kotlin-finder-0.0.7'
}

To use the Appium Flutter Driver, your Flutter application must meet the following requirements:

1. Build Mode: The app must be compiled in debug or profile mode.
2. Dependencies: The application must include the flutter_driver package in its pubspec.yaml.
3. Configuration: You must use enableFlutterDriverExtension in your main.dart file.

Example pubspec.yaml configuration:

# pubspec.yaml
dev_dependencies:
  flutter_driver:
    sdk: flutter

You can add custom functionality to the Flutter Driver using the CommandExtension class. This requires adding specific Dart files to your project's lib folder and registering them in your app's entry point (main.dart or test_main.dart).

Available Extensions:

• dragAndDropWithCommandExtension: Performs drag-and-drop via coordinates and duration.
• getTextWithCommandExtension: Retrieves text from widgets containing TextSpan.

Implementation Steps:

1. Copy the required .dart files (e.g., drag_commands.dart) to your lib folder.
2. Update your main() function to include the extensions in enableFlutterDriverExtension().

Example Registration:

import 'drag_commands.dart';
import 'get_text_command.dart';

void main() {
  enableFlutterDriverExtension(
      commands: [DragCommandExtension(), GetTextCommandExtension()]);
  runApp(const MyApp());
}