feat: add flutter integration driver commands and tests

Author: MummanaSubramanya

.github/workflows/functional-test.yml

@@ -196,3 +196,138 @@ jobs:
       with:
         name: appium-android-${{matrix.test_targets.name}}.log
         path: appium.log
+
+  flutter_e2e_test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: macos-14
+            e2e-tests: flutter-ios
+          - platform: ubuntu-latest
+            e2e-tests: flutter-android
+
+    runs-on: ${{ matrix.platform }}
+
+    env:
+      API_LEVEL: 29
+      ARCH: x86
+      CI: true
+      XCODE_VERSION: 15.4
+      IOS_VERSION: 17.5
+      IPHONE_MODEL: iPhone 15
+      FLUTTER_ANDROID_APP: "https://github.com/AppiumTestDistribution/appium-flutter-server/releases/latest/download/app-debug.apk"
+      FLUTTER_IOS_APP: "https://github.com/AppiumTestDistribution/appium-flutter-server/releases/latest/download/ios.zip"
+
+    steps:
+
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-java@v4
+      if: matrix.e2e-tests == 'flutter-android'
+      with:
+        distribution: 'zulu'
+        java-version: '17'
+
+    - name: Enable KVM group perms
+      if: matrix.e2e-tests == 'flutter-android'
+      run: |
+        echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+        sudo udevadm control --reload-rules
+        sudo udevadm trigger --name-match=kvm
+  
+    - name: AVD cache
+      if: matrix.e2e-tests == 'flutter-android'
+      uses: actions/cache@v3
+      id: avd-cache
+      with:
+        path: |
+          ~/.android/avd/*
+          ~/.android/adb*
+        key: avd-${{ env.API_LEVEL }}
+
+    - name: Create AVD and generate snapshot for caching
+      if: matrix.e2e-tests == 'flutter-android' && steps.avd-cache.outputs.cache-hit != 'true'
+      uses: reactivecircus/android-emulator-runner@v2
+      with:
+        api-level: ${{ env.API_LEVEL }}
+        arch: ${{ env.ARCH }}
+        target: google_apis
+        force-avd-creation: false
+        emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
+        disable-animations: false
+        script: echo "Generated AVD snapshot for caching."
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v3
+      with:
+        python-version: 3.12
+
+    - name: Install Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 'lts/*'
+
+    - name: Install Appium
+      run: npm install --location=global appium
+    
+    - name: Install Android drivers and Run Appium
+      if: matrix.e2e-tests == 'flutter-android'
+      run: |
+        appium driver install uiautomator2
+        appium driver install appium-flutter-integration-driver --source npm
+        nohup appium --allow-insecure=adb_shell --relaxed-security --log-timestamp --log-no-colors 2>&1 > appium_android.log &
+
+    - name: Run Android tests
+      if: matrix.e2e-tests == 'flutter-android'
+      uses: reactivecircus/android-emulator-runner@v2
+      with:
+        api-level: ${{ env.API_LEVEL }}
+        arch: ${{ env.ARCH }}
+        script: |
+          pip install --upgrade pip
+          pip install --upgrade pipenv
+          pipenv lock --clear
+          pipenv install -d --system
+          export PLATFORM=android
+          pytest test/functional/flutter/*_test.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html
+        target: google_apis
+        profile: Nexus 5X
+        disable-spellchecker: true
+        disable-animations: true
+
+    - name: Select Xcode
+      if: matrix.e2e-tests == 'flutter-ios'
+      uses: maxim-lobanov/setup-xcode@v1
+      with:
+        xcode-version: ${{ env.XCODE_VERSION }}
+    - run: defaults write com.apple.iphonesimulator PasteboardAutomaticSync -bool false
+
+    - uses: futureware-tech/simulator-action@v3
+      with:
+        # https://github.com/actions/runner-images/blob/main/images/macos/macos-14-arm64-Readme.md
+        model: ${{ env.IPHONE_MODEL }}
+        os_version: ${{ env.IOS_VERSION }}
+
+    - name: install dependencies
+      if: matrix.e2e-tests == 'flutter-ios'
+      run: brew install ffmpeg
+
+    - name: Install IOS drivers and Run Appium
+      if: matrix.e2e-tests == 'flutter-ios'
+      run: |
+        appium driver install xcuitest
+        appium driver install appium-flutter-integration-driver --source npm
+        appium driver run xcuitest build-wda
+        nohup appium --allow-insecure=adb_shell --relaxed-security --log-timestamp --log-no-colors 2>&1 > appium_ios.log &
+
+    - name: Run IOS tests
+      if: matrix.e2e-tests == 'flutter-ios'
+      run: |
+        # Separate 'run' creates differnet pipenv env. Does them in one run for now.
+        pip install --upgrade pip
+        pip install --upgrade pipenv
+        pipenv lock --clear
+        pipenv install -d --system
+        export PLATFORM=ios
+        pytest test/functional/flutter/*_test.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html

appium/options/flutter/__init__.py

@@ -0,0 +1 @@
+from .base import FlutterOptions

appium/options/flutter/base.py

@@ -0,0 +1,40 @@
+# Licensed to the Software Freedom Conservancy (SFC) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from typing import Dict
+from appium.options.common.automation_name_option import AUTOMATION_NAME
+from appium.options.common.base import AppiumOptions
+from appium.options.flutter.flutter_element_wait_timeout_option import FlutterElementWaitTimeOutOption
+from appium.options.flutter.flutter_enable_mock_camera_option import FlutterEnableMockCameraOption
+from appium.options.flutter.flutter_server_launch_timeout_option import FlutterServerLaunchTimeOutOption
+from appium.options.flutter.flutter_system_port_option import FlutterSystemPortOption
+
+
+class FlutterOptions(
+    AppiumOptions,
+    FlutterElementWaitTimeOutOption,
+    FlutterEnableMockCameraOption,
+    FlutterServerLaunchTimeOutOption,
+    FlutterSystemPortOption
+):
+    
+    @property
+    def default_capabilities(self) -> Dict:
+        return {
+            AUTOMATION_NAME: 'FlutterIntegration',
+        }
+    

appium/options/flutter/flutter_element_wait_timeout_option.py

@@ -0,0 +1,33 @@
+# Licensed to the Software Freedom Conservancy (SFC) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from typing import Optional
+from appium.options.common.supports_capabilities import SupportsCapabilities
+
+
+FLUTTER_ELEMENT_WAIT_TIMEOUT= 'flutterElementWaitTimeout'
+
+
+class FlutterElementWaitTimeOutOption(SupportsCapabilities):
+    
+    @property
+    def flutter_element_wait_timeout(self) -> Optional[int]:
+        return self.get_capability(FLUTTER_ELEMENT_WAIT_TIMEOUT)
+
+    @flutter_element_wait_timeout.setter
+    def flutter_element_wait_timeout(self, time_in_millis: int) -> None:
+        self.set_capability(FLUTTER_ELEMENT_WAIT_TIMEOUT, time_in_millis)

appium/options/flutter/flutter_enable_mock_camera_option.py

@@ -0,0 +1,33 @@
+# Licensed to the Software Freedom Conservancy (SFC) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from typing import Optional
+from appium.options.common.supports_capabilities import SupportsCapabilities
+
+
+FLUTTER_ENABLE_MOCK_CAMERA = 'flutterEnableMockCamera'
+
+
+class FlutterEnableMockCameraOption(SupportsCapabilities):
+    
+    @property
+    def flutter_enable_mock_camera(self) -> Optional[int]:
+        return self.get_capability(FLUTTER_ENABLE_MOCK_CAMERA)
+
+    @flutter_enable_mock_camera.setter
+    def flutter_enable_mock_camera(self, value: bool) -> None:
+        self.set_capability(FLUTTER_ENABLE_MOCK_CAMERA, value)

appium/options/flutter/flutter_server_launch_timeout_option.py

@@ -0,0 +1,33 @@
+# Licensed to the Software Freedom Conservancy (SFC) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from typing import Optional
+from appium.options.common.supports_capabilities import SupportsCapabilities
+
+
+FLUTTER_SERVER_LAUNCH_TIMEOUT= 'flutterServerLaunchTimeout'
+
+
+class FlutterServerLaunchTimeOutOption(SupportsCapabilities):
+    
+    @property
+    def flutter_server_launch_timeout(self) -> Optional[int]:
+        return self.get_capability(FLUTTER_SERVER_LAUNCH_TIMEOUT)
+
+    @flutter_server_launch_timeout.setter
+    def flutter_server_launch_timeout(self, time_in_millis: int) -> None:
+        self.set_capability(FLUTTER_SERVER_LAUNCH_TIMEOUT, time_in_millis)

appium/options/flutter/flutter_system_port_option.py

@@ -0,0 +1,33 @@
+# Licensed to the Software Freedom Conservancy (SFC) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from typing import Optional
+from appium.options.common.supports_capabilities import SupportsCapabilities
+
+
+FLUTTER_SYSTEM_PORT = 'flutterSystemPort'
+
+
+class FlutterSystemPortOption(SupportsCapabilities):
+    
+    @property
+    def flutter_system_port(self) -> Optional[int]:
+        return self.get_capability(FLUTTER_SYSTEM_PORT)
+
+    @flutter_system_port.setter
+    def flutter_system_port(self, value: int) -> None:
+        self.set_capability(FLUTTER_SYSTEM_PORT, value)

appium/webdriver/common/flutterby.py

@@ -0,0 +1,25 @@
+# Licensed to the Software Freedom Conservancy (SFC) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from selenium.webdriver.common.by import By
+
+class FlutterBy(By):
+    FLUTTER_SEMANTICS_LABEL = '-flutter semantics label'
+    FLUTTER_TYPE = '-flutter type'
+    FLUTTER_KEY = '-flutter key'
+    FLUTTER_TEXT = '-flutter text'
+    FLUTTER_TEXT_CONTAINING = '-flutter text containing'