feat: Add flutter integration driver commands and tests

.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_integration/__init__.py

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

appium/options/flutter_integration/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_integration.flutter_element_wait_timeout_option import FlutterElementWaitTimeOutOption
+from appium.options.flutter_integration.flutter_enable_mock_camera_option import FlutterEnableMockCameraOption
+from appium.options.flutter_integration.flutter_server_launch_timeout_option import FlutterServerLaunchTimeOutOption
+from appium.options.flutter_integration.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_integration/flutter_element_wait_timeout_option.py

@@ -0,0 +1,51 @@
+# 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 datetime import timedelta
+from typing import Optional, Union
+from appium.options.common.supports_capabilities import SupportsCapabilities
+
+
+FLUTTER_ELEMENT_WAIT_TIMEOUT= 'flutterElementWaitTimeout'
+
+
+class FlutterElementWaitTimeOutOption(SupportsCapabilities):
+
+    @property
+    def flutter_element_wait_timeout(self) -> Optional[timedelta]:
+        """
+        Maximum timeout to wait for element for Flutter integration test
+
+        Returns:
+            Optional[timedelta]: The timeout value as a `timedelta` object if set, or `None` if the timeout is not defined.
+        """
+        return self.get_capability(FLUTTER_ELEMENT_WAIT_TIMEOUT)
+
+    @flutter_element_wait_timeout.setter
+    def flutter_element_wait_timeout(self, value: Union[timedelta, int]) -> None:
+        """
+        Sets the maximum timeout to wait for a Flutter element in an integration test.
+        Default timeout is 5000ms
+
+        Args:
+            value (Union[timedelta, int]): The timeout value, either as a `timedelta` object or an integer in milliseconds.
+                If provided as a `timedelta`, it will be converted to milliseconds.
+        """
+        self.set_capability(
+            FLUTTER_ELEMENT_WAIT_TIMEOUT, 
+            int(value.total_seconds() * 1000) if isinstance(value, timedelta) else value
+        )

appium/options/flutter_integration/flutter_enable_mock_camera_option.py

@@ -0,0 +1,46 @@
+# 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) -> bool:
+        """
+        Get state of the mock camera for Flutter integration test
+
+        Returns:
+            bool: A boolean indicating whether the mock camera is enabled (True) or disabled (False).
+        """
+        return self.get_capability(FLUTTER_ENABLE_MOCK_CAMERA)
+
+    @flutter_enable_mock_camera.setter
+    def flutter_enable_mock_camera(self, value: bool) -> None:
+        """        
+        Setter method enable or disable the mock camera for Flutter integration test
+        Default state is `False`
+
+        Args:
+            value (bool): A boolean value indicating whether to enable (True) or disable (False) the mock camera.
+        """
+        self.set_capability(FLUTTER_ENABLE_MOCK_CAMERA, value)

appium/options/flutter_integration/flutter_server_launch_timeout_option.py

@@ -0,0 +1,52 @@
+# 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 datetime import timedelta
+from typing import Optional, Union
+from appium.options.common.supports_capabilities import SupportsCapabilities
+
+
+FLUTTER_SERVER_LAUNCH_TIMEOUT= 'flutterServerLaunchTimeout'
+
+
+class FlutterServerLaunchTimeOutOption(SupportsCapabilities):
+
+    @property
+    def flutter_server_launch_timeout(self) -> Optional[timedelta]:
+        """
+        Gets the current timeout for launching the Flutter server in a Flutter application.
+
+        Returns:
+            Optional[timedelta]: The timeout value as a `timedelta` object if set, or `None` if the timeout is not defined.
+
+        """
+        return self.get_capability(FLUTTER_SERVER_LAUNCH_TIMEOUT)
+
+    @flutter_server_launch_timeout.setter
+    def flutter_server_launch_timeout(self, value: Union[timedelta, int]) -> None:
+        """
+        Sets the timeout for launching the Flutter server in Flutter application.
+        Default timeout is 5000ms
+
+        Args:
+            value (Union[timedelta, int]): The timeout value, either as a `timedelta` object or an integer in milliseconds. 
+                If provided as a `timedelta`, it will be converted to milliseconds.
+        """
+        self.set_capability(
+            FLUTTER_SERVER_LAUNCH_TIMEOUT, 
+            int(value.total_seconds() * 1000) if isinstance(value, timedelta) else value
+        )

appium/options/flutter_integration/flutter_system_port_option.py

@@ -0,0 +1,46 @@
+# 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]:
+        """
+        Get flutter system port for Flutter integration tests.
+
+        Returns:
+            int: returns the port number
+        """
+        return self.get_capability(FLUTTER_SYSTEM_PORT)
+
+    @flutter_system_port.setter
+    def flutter_system_port(self, value: int) -> None:
+        """
+        Sets the system port for Flutter integration tests.
+        By default the first free port from 10000..11000 range is selected
+
+        Args:
+            value (int): The port number to be used for the Flutter server.
+        """
+        self.set_capability(FLUTTER_SYSTEM_PORT, value)

appium/webdriver/common/appiumby.py

@@ -25,3 +25,8 @@ class AppiumBy(By):
     ACCESSIBILITY_ID = 'accessibility id'
     IMAGE = '-image'
     CUSTOM = '-custom'
+    FLUTTER_INTEGRATION_SEMANTICS_LABEL = '-flutter semantics label'
+    FLUTTER_INTEGRATION_TYPE = '-flutter type'
+    FLUTTER_INTEGRATION_KEY = '-flutter key'
+    FLUTTER_INTEGRATION_TEXT = '-flutter text'
+    FLUTTER_INTEGRATION_TEXT_CONTAINING = '-flutter text containing'