feat: Fix review comments

Author: MummanaSubramanya

appium/options/flutter/__init__.py renamed to appium/options/flutter_integration/__init__.py

@@ -18,10 +18,10 @@
 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
+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(

appium/options/flutter/base.py renamed to appium/options/flutter_integration/base.py

@@ -15,7 +15,8 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Optional
+from datetime import timedelta
+from typing import Optional, Union
 from appium.options.common.supports_capabilities import SupportsCapabilities
 
 
@@ -25,9 +26,26 @@
 class FlutterElementWaitTimeOutOption(SupportsCapabilities):
 
     @property
-    def flutter_element_wait_timeout(self) -> Optional[int]:
+    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, time_in_millis: int) -> None:
-        self.set_capability(FLUTTER_ELEMENT_WAIT_TIMEOUT, time_in_millis)
+    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/flutter_element_wait_timeout_option.py renamed to appium/options/flutter_integration/flutter_element_wait_timeout_option.py

@@ -25,9 +25,22 @@
 class FlutterEnableMockCameraOption(SupportsCapabilities):
 
     @property
-    def flutter_enable_mock_camera(self) -> Optional[int]:
+    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/flutter_enable_mock_camera_option.py renamed to appium/options/flutter_integration/flutter_enable_mock_camera_option.py

@@ -15,7 +15,8 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Optional
+from datetime import timedelta
+from typing import Optional, Union
 from appium.options.common.supports_capabilities import SupportsCapabilities
 
 
@@ -25,9 +26,27 @@
 class FlutterServerLaunchTimeOutOption(SupportsCapabilities):
 
     @property
-    def flutter_server_launch_timeout(self) -> Optional[int]:
+    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, time_in_millis: int) -> None:
-        self.set_capability(FLUTTER_SERVER_LAUNCH_TIMEOUT, time_in_millis)
+    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/flutter_server_launch_timeout_option.py renamed to appium/options/flutter_integration/flutter_server_launch_timeout_option.py

@@ -26,8 +26,21 @@ 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/options/flutter/flutter_system_port_option.py renamed to appium/options/flutter_integration/flutter_system_port_option.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'

appium/webdriver/common/appiumby.py

@@ -13,26 +13,28 @@
 # limitations under the License.
 
 import base64
+import os
 from typing import Any, Optional, Tuple, Union
+from appium.webdriver.extensions.flutter_integration.scroll_directions import ScrollDirection
 from appium.webdriver.flutter_finder import FlutterFinder
 from appium.webdriver.webdriver import WebDriver
 from appium.webdriver.webelement import WebElement
 
 
-class FlutterCommand():
+class FlutterCommand:
 
     def __init__(self, driver: WebDriver) -> None:
         self.driver = driver
 
      # wait commands   
 
-    def wait_for_visible(self, locator: Union[WebElement, FlutterFinder], time_out: Optional[int] = None) -> None:
+    def wait_for_visible(self, locator: Union[WebElement, FlutterFinder], time_out: Optional[float] = None) -> None:
         """
         Waits for a element to become visible.
 
         Args:
-            locator: The element to wait for; can be a WebElement or a FlutterFinder.
-            time_out: Maximum wait time in seconds. Defaults to a predefined timeout if not specified.
+            locator (Union[WebElement, FlutterFinder]): The element to wait for; can be a WebElement or a FlutterFinder.
+            time_out (Optional[float]): Maximum wait time in seconds. Defaults to a predefined timeout if not specified.
             
         Returns: 
             None: 
@@ -45,13 +47,13 @@ def wait_for_visible(self, locator: Union[WebElement, FlutterFinder], time_out:
         self.execute_flutter_command('waitForVisible', opts)
 
 
-    def wait_for_invisible(self, locator: Union[WebElement, FlutterFinder], time_out: Optional[int] = None) -> None:
+    def wait_for_invisible(self, locator: Union[WebElement, FlutterFinder], time_out: Optional[float] = None) -> None:
         """
         Waits for a element to become invisible.
 
         Args:
-            locator: The element to wait for; can be a WebElement or a FlutterFinder.
-            time_out: Maximum wait time in seconds. Defaults to a predefined timeout if not specified.
+            locator (Union[WebElement, FlutterFinder]): The element to wait for; can be a WebElement or a FlutterFinder.
+            time_out (Optional[float]): Maximum wait time in seconds. Defaults to a predefined timeout if not specified.
             
         Returns:
             None: 
@@ -70,14 +72,14 @@ def perform_double_click(self, element: WebElement, offset: Optional[Tuple[int,
         Performs a double-click on the given element, with an optional offset.
 
         Args:
-            element: The element to double-click on. This parameter is required.
-            offset: The x and y offsets from the element to click at. If not specified, the click is performed at the element's center.
+            element (WebElement): The element to double-click on. This parameter is required.
+            offset (Optional[Tuple[int, int]]): The x and y offsets from the element to click at. If not specified, the click is performed at the element's center.
             
         Returns:
             None:
         """
         opts = {'origin': element}
-        if offset:
+        if offset is not None:
             opts['offset'] = {'x': offset[0], 'y': offset[1]}
         self.execute_flutter_command('doubleClick', opts)
 
@@ -86,14 +88,14 @@ def perform_long_press(self, element: WebElement, offset: Optional[Tuple[int, in
         Performs a long press on the given element, with an optional offset.
 
         Args:
-            element: The element to perform the long press on. This parameter is required.
-            offset: The x and y offsets from the element to perform the long press at. If not specified, the long press is performed at the element's center.
+            element (WebElement): The element to perform the long press on. This parameter is required.
+            offset (Optional[Tuple[int, int]]): The x and y offsets from the element to perform the long press at. If not specified, the long press is performed at the element's center.
             
         Returns:
             None:
         """
         opts = {'origin': element}
-        if offset:
+        if offset is not None:
             opts['offset'] = {'x': offset[0], 'y': offset[1]}
         self.execute_flutter_command('longPress', opts)
 
@@ -102,21 +104,21 @@ def perform_drag_and_drop(self, source: WebElement, target: WebElement) -> None:
         Performs a drag-and-drop operation from a source element to a target element.
 
         Args:
-            source: The element to drag from.
-            target: The element to drop onto.
+            source (WebElement): The element to drag from.
+            target (WebElement): The element to drop onto.
             
         Returns:
             None:
         """
         self.execute_flutter_command('dragAndDrop', {'source': source, 'target': target})
 
-    def scroll_till_visible(self, scroll_to: FlutterFinder, scroll_direction: Optional[str] = 'down', **opts: Any) -> WebElement:
+    def scroll_till_visible(self, scroll_to: FlutterFinder, scroll_direction: Optional[ScrollDirection] = ScrollDirection.DOWN, **opts: Any) -> WebElement:
         """
         Scrolls until the specified element becomes visible.
 
         Args:
-            scroll_to: The Flutter element to scroll to.
-            scroll_direction: The direction to scroll up/down. Defaults to 'down'.
+            scroll_to (FlutterFinder): The Flutter element to scroll to.
+            scroll_direction (Optional[ScrollDirection]): The direction to scroll up or down. Defaults to `ScrollDirection.DOWN`.
                 
         KeywordArgs:
                 scrollView (str): The view of the scroll.
@@ -129,22 +131,21 @@ def scroll_till_visible(self, scroll_to: FlutterFinder, scroll_direction: Option
             Webelement: scrolled element
         """
         opts['finder'] = scroll_to.to_dict()
-        opts['scrollDirection'] = scroll_direction
+        opts['scrollDirection'] = scroll_direction.as_string()
         return self.execute_flutter_command('scrollTillVisible', opts)
 
     def inject_mock_image(self, value: str) -> str:
         """
         Injects a mock image to the device. The input can be a file path or a base64-encoded string.
 
         Args:
-            value: The file path of the image or a base64-encoded string.
+            value (str): The file path of the image or a base64-encoded string.
             
         Returns:
             str: Image ID of the injected image.
         """
-        import os
         if os.path.isfile(value):        
-            with open(value, "rb") as image_file:
+            with open(value, 'rb') as image_file:
                 base64_encoded_image = base64.b64encode(image_file.read()).decode('utf-8')
         else:
             base64_encoded_image = value
@@ -155,12 +156,24 @@ def activate_injected_image(self, image_id: str) -> None:
         Activates an injected image with image ID.
 
         Args:
-            image_id: The ID of the injected image to activate.
+            image_id (str): The ID of the injected image to activate.
 
         Returns:
             None:
         """
-        self.execute_flutter_command("activateInjectedImage", {'imageId': image_id})
+        self.execute_flutter_command('activateInjectedImage', {'imageId': image_id})
 
     def execute_flutter_command(self, scriptName: str, params: dict) -> Any:
+        """
+        Executes a Flutter command by sending a script and parameters to the flutter integration driver.
+
+        Args:
+            scriptName (str): The name of the Flutter command to execute. 
+                This will be prefixed with 'flutter:' when passed to the driver.
+            params (dict): A dictionary of parameters to be passed along with the Flutter command.
+
+        Returns:
+            Any: The result of the command execution. The return value depends on the 
+            specific Flutter command being executed.
+        """
         return self.driver.execute_script(f'flutter: {scriptName}', params)

appium/webdriver/common/flutterby.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+class ScrollDirection(Enum):
+    UP = 'up'
+    DOWN = 'down'
+    
+    def as_string(self):
+        return str(self.value)