flowpilot-mobile 1.1.8__tar.gz

flowpilot_mobile-1.1.8/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: flowpilot-mobile
+Version: 1.1.8
+Summary: Modern, Intelligent Mobile Automation Framework
+Author-email: Niranjan Kumar <niranjan4@outlook.in>
+License: MIT
+Project-URL: Homepage, https://github.com/niranjangs4/flowpilot-mobile
+Project-URL: Documentation, https://github.com/niranjangs4/flowpilot-mobile#readme
+Keywords: mobile,automation,android,smart,testing,pytest
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Testing
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pytest>=8.0.0
+Requires-Dist: pytest-xdist>=3.5.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: cryptography>=41.0.0
+
+# FlowPilot Mobile
+
+Modern, Python-first mobile automation framework. 
+Provides clean Playwright-style APIs for smart mobile automation with AI-assisted test generation.
+
+## 🚀 Quick Start
+
+### 1. Install via pip
+```bash
+pip install flowpilot-mobile
+```
+
+### 2. Initialize your Project
+Initialize a new project folder with all necessary configurations:
+```bash
+flowpilot setup --project_folder my_tests
+```
+
+### 3. Configure Tool Paths
+Open `my_tests/flowpilot.yaml` and specify your manual paths for ADB and Scrcpy if they are not in your system PATH:
+```yaml
+tools:
+  adb_path: "C:\\path\\to\\adb.exe"
+  scrcpy_path: "C:\\path\\to\\scrcpy.exe"
+```
+
+---
+
+## 🌟 The FlowPilot "Smart" Advantage
+
+FlowPilot includes an **Intelligent Layer** that handles the "messy" parts of mobile testing automatically:
+
+- **Auto-Scroll Search**: Automatically swipes and retries if an element is off-screen.
+- **Smart Locator Scoring**: Distinguishes between actual inputs and "distractor" elements (like Search Labs icons).
+- **Nearby Label Matching**: Fills input fields based on the text labels next to them.
+- **Self-Healing**: Uses fuzzy matching for minor UI text changes (e.g., "Log In" vs "Login").
+- **Automatic Device Reset**: Automatically presses the **Home button** before and after every test to ensure a clean baseline.
+- **Zero-Sleep Synchronization**: Built-in polling ensures elements are ready before interaction.
+
+---
+
+## 🤖 AI-Assisted Automation (TEST_GEN_PROMPT)
+
+FlowPilot now supports **Instant Test Generation** via AI. Every project initialized with `flowpilot setup` includes a `TEST_GEN_PROMPT.md` file.
+
+1.  Copy the content of `TEST_GEN_PROMPT.md`.
+2.  Paste it into **Gemini** or **ChatGPT**.
+3.  Provide your manual test steps or describe a screen recording.
+4.  **Result:** The AI will generate a complete FlowPilot Python test script for you.
+
+---
+
+## 🖥️ Live Monitoring & Evidence
+
+### Live Desktop Mirroring
+See your phone's screen in a window on your desktop (Mac/Windows) during execution.
+- **Enable:** Set `mirror_screen: true` in your `flowpilot.yaml`.
+- **Manual Path:** Configure `scrcpy_path` in `flowpilot.yaml` if needed.
+
+### Automated Evidence
+- **Screen Recording (MP4)**: Every test is recorded with hardware encoding (zero performance drop). Includes professional 1s padding.
+- **Retention Policy**: Automatically purges recordings older than **5 days** (configurable) to save disk space.
+- **Smart Screenshots**: Captures specific UI states into `.flowpilot/screenshots/`.
+- **Selective Cleanup**: Wipes temporary flows and recent screenshots before each run while **preserving** your video history.
+
+---
+
+## ⚙️ Configuration (`flowpilot.yaml`)
+```yaml
+project_name: "My Custom App"
+
+# Manual Tool Paths
+tools:
+  adb_path: ""
+  scrcpy_path: ""
+
+# Evidence & Storage
+output_dir: ".flowpilot"
+recordings_dir: ".flowpilot/recordings"
+screenshots_dir: ".flowpilot/screenshots"
+
+# Features
+record_video: true
+mirror_screen: true
+
+# Smart Engine Settings
+auto_scroll: true
+timeout: 30
+```
+
+---
+
+## 📖 Public API Reference
+
+| Category | Method | Description | Example |
+| :--- | :--- | :--- | :--- |
+| **Lifecycle** | `launch_app(pkg)` | Opens a specific app (defaults to Chrome). | `mobile.launch_app()` |
+| | `home()` | Returns to the device Home Screen. | `mobile.home()` |
+| | `back()` | Simulates the hardware Back button. | `mobile.back()` |
+| | `navigate(url)` | Opens a specific URL in the browser. | `mobile.navigate("https://google.com")` |
+| **Interactions** | `tap(target)` | **Smart Tap**: Auto-scrolls and waits for visibility. | `mobile.tap("Settings")` |
+| | `fill(target, val)` | **Smart Fill**: Finds nearest input to a label. | `mobile.fill("Username", "admin")` |
+| | `fill_focused(val)` | **Active Field**: Types into currently focused input. | `mobile.fill_focused("secret")` |
+| | `press_key(key)` | Presses hardware keys (Enter, Home, Back). | `mobile.press_key("Enter")` |
+| **Gestures** | `open_notifications()`| Pulls down the notification shade (Left). | `mobile.open_notifications()` |
+| | `open_quick_settings()`| Pulls down full Quick Settings (Center). | `mobile.open_quick_settings()` |
+| | `scroll_down()` | Performs a smart downward scroll. | `mobile.scroll_down()` |
+| **Media** | `screenshot(name)` | Saves a screenshot to `.flowpilot/screenshots/`. | `mobile.screenshot("step_1")` |
+
+---
+
+## 🤖 CLI Commands
+
+| Command | Description |
+| :--- | :--- |
+| `flowpilot setup` | Initializes a new project folder and generates configurations. |
+| `flowpilot interactive`| Start a live step-by-step automation session. |
+| `flowpilot run` | Executes tests with smart logs. |
+| `flowpilot devices` | Lists all connected physical Android devices. |
+
+---
+
+## 🛡 Engineering Principles
+1. **Hide Complexity**: Zero YAML or runtime engine logic exposed.
+2. **Text-First**: Locators prioritize display text over brittle XPaths.
+3. **Hardware-Accelerated**: Native MP4 capture and Scrcpy mirroring with zero host lag.
+4. **Resilient Reset**: Automated pre/post Home screen logic for repeatability.

flowpilot_mobile-1.1.8/README.md

@@ -0,0 +1,127 @@
+# FlowPilot Mobile
+
+Modern, Python-first mobile automation framework. 
+Provides clean Playwright-style APIs for smart mobile automation with AI-assisted test generation.
+
+## 🚀 Quick Start
+
+### 1. Install via pip
+```bash
+pip install flowpilot-mobile
+```
+
+### 2. Initialize your Project
+Initialize a new project folder with all necessary configurations:
+```bash
+flowpilot setup --project_folder my_tests
+```
+
+### 3. Configure Tool Paths
+Open `my_tests/flowpilot.yaml` and specify your manual paths for ADB and Scrcpy if they are not in your system PATH:
+```yaml
+tools:
+  adb_path: "C:\\path\\to\\adb.exe"
+  scrcpy_path: "C:\\path\\to\\scrcpy.exe"
+```
+
+---
+
+## 🌟 The FlowPilot "Smart" Advantage
+
+FlowPilot includes an **Intelligent Layer** that handles the "messy" parts of mobile testing automatically:
+
+- **Auto-Scroll Search**: Automatically swipes and retries if an element is off-screen.
+- **Smart Locator Scoring**: Distinguishes between actual inputs and "distractor" elements (like Search Labs icons).
+- **Nearby Label Matching**: Fills input fields based on the text labels next to them.
+- **Self-Healing**: Uses fuzzy matching for minor UI text changes (e.g., "Log In" vs "Login").
+- **Automatic Device Reset**: Automatically presses the **Home button** before and after every test to ensure a clean baseline.
+- **Zero-Sleep Synchronization**: Built-in polling ensures elements are ready before interaction.
+
+---
+
+## 🤖 AI-Assisted Automation (TEST_GEN_PROMPT)
+
+FlowPilot now supports **Instant Test Generation** via AI. Every project initialized with `flowpilot setup` includes a `TEST_GEN_PROMPT.md` file.
+
+1.  Copy the content of `TEST_GEN_PROMPT.md`.
+2.  Paste it into **Gemini** or **ChatGPT**.
+3.  Provide your manual test steps or describe a screen recording.
+4.  **Result:** The AI will generate a complete FlowPilot Python test script for you.
+
+---
+
+## 🖥️ Live Monitoring & Evidence
+
+### Live Desktop Mirroring
+See your phone's screen in a window on your desktop (Mac/Windows) during execution.
+- **Enable:** Set `mirror_screen: true` in your `flowpilot.yaml`.
+- **Manual Path:** Configure `scrcpy_path` in `flowpilot.yaml` if needed.
+
+### Automated Evidence
+- **Screen Recording (MP4)**: Every test is recorded with hardware encoding (zero performance drop). Includes professional 1s padding.
+- **Retention Policy**: Automatically purges recordings older than **5 days** (configurable) to save disk space.
+- **Smart Screenshots**: Captures specific UI states into `.flowpilot/screenshots/`.
+- **Selective Cleanup**: Wipes temporary flows and recent screenshots before each run while **preserving** your video history.
+
+---
+
+## ⚙️ Configuration (`flowpilot.yaml`)
+```yaml
+project_name: "My Custom App"
+
+# Manual Tool Paths
+tools:
+  adb_path: ""
+  scrcpy_path: ""
+
+# Evidence & Storage
+output_dir: ".flowpilot"
+recordings_dir: ".flowpilot/recordings"
+screenshots_dir: ".flowpilot/screenshots"
+
+# Features
+record_video: true
+mirror_screen: true
+
+# Smart Engine Settings
+auto_scroll: true
+timeout: 30
+```
+
+---
+
+## 📖 Public API Reference
+
+| Category | Method | Description | Example |
+| :--- | :--- | :--- | :--- |
+| **Lifecycle** | `launch_app(pkg)` | Opens a specific app (defaults to Chrome). | `mobile.launch_app()` |
+| | `home()` | Returns to the device Home Screen. | `mobile.home()` |
+| | `back()` | Simulates the hardware Back button. | `mobile.back()` |
+| | `navigate(url)` | Opens a specific URL in the browser. | `mobile.navigate("https://google.com")` |
+| **Interactions** | `tap(target)` | **Smart Tap**: Auto-scrolls and waits for visibility. | `mobile.tap("Settings")` |
+| | `fill(target, val)` | **Smart Fill**: Finds nearest input to a label. | `mobile.fill("Username", "admin")` |
+| | `fill_focused(val)` | **Active Field**: Types into currently focused input. | `mobile.fill_focused("secret")` |
+| | `press_key(key)` | Presses hardware keys (Enter, Home, Back). | `mobile.press_key("Enter")` |
+| **Gestures** | `open_notifications()`| Pulls down the notification shade (Left). | `mobile.open_notifications()` |
+| | `open_quick_settings()`| Pulls down full Quick Settings (Center). | `mobile.open_quick_settings()` |
+| | `scroll_down()` | Performs a smart downward scroll. | `mobile.scroll_down()` |
+| **Media** | `screenshot(name)` | Saves a screenshot to `.flowpilot/screenshots/`. | `mobile.screenshot("step_1")` |
+
+---
+
+## 🤖 CLI Commands
+
+| Command | Description |
+| :--- | :--- |
+| `flowpilot setup` | Initializes a new project folder and generates configurations. |
+| `flowpilot interactive`| Start a live step-by-step automation session. |
+| `flowpilot run` | Executes tests with smart logs. |
+| `flowpilot devices` | Lists all connected physical Android devices. |
+
+---
+
+## 🛡 Engineering Principles
+1. **Hide Complexity**: Zero YAML or runtime engine logic exposed.
+2. **Text-First**: Locators prioritize display text over brittle XPaths.
+3. **Hardware-Accelerated**: Native MP4 capture and Scrcpy mirroring with zero host lag.
+4. **Resilient Reset**: Automated pre/post Home screen logic for repeatability.

flowpilot_mobile-1.1.8/flowpilot/__init__.py

@@ -0,0 +1,7 @@
+from flowpilot.api.mobile import Mobile
+from flowpilot.runtime.adb_engine import ADBRuntime
+from flowpilot.runtime.executor import RuntimeExecutor
+from flowpilot.utils.setup import SetupManager
+
+__version__ = "1.1.9"
+__all__ = ["Mobile", "ADBRuntime", "RuntimeExecutor", "SetupManager"]

flowpilot_mobile-1.1.8/flowpilot/api/mobile.py

@@ -0,0 +1,284 @@
+from loguru import logger
+from flowpilot.commands.core import *
+from flowpilot.runtime.queue import FlowContext
+from flowpilot.runtime.executor import RuntimeExecutor
+
+class SignatureAPI:
+    def __init__(self, context: FlowContext):
+        self._context = context
+
+    def draw(self):
+        # Internally use coordinate swipe actions
+        self._context.add_command(Command()) # Placeholder for DrawSignatureCommand
+        return self
+
+class RelationalAPI:
+    def __init__(self, anchor: str, relation: str, context: FlowContext, mobile):
+        self.anchor = anchor
+        self.relation = relation
+        self.target_text = None
+        self.target_type = None
+        self._context = context
+        self._mobile = mobile
+
+    def text(self, text: str):
+        """Filters by specific text."""
+        self.target_text = text
+        return self
+
+    def type(self, type_name: str):
+        """Filters by class name (e.g., 'EditText', 'Button')."""
+        self.target_type = type_name
+        return self
+
+    def input(self):
+        """Shortcut to filter for EditText elements."""
+        self.target_type = "EditText"
+        return self
+
+    def tap(self):
+        self._context.add_command(RelationalCommand(
+            anchor=self.anchor,
+            relation=self.relation,
+            target_text=self.target_text,
+            target_type=self.target_type,
+            action="tap"
+        ))
+        return self._mobile
+
+    def fill(self, value: str):
+        self._context.add_command(RelationalCommand(
+            anchor=self.anchor,
+            relation=self.relation,
+            target_text=self.target_text,
+            target_type=self.target_type,
+            action="fill",
+            value=value
+        ))
+        return self._mobile
+
+class ElementAPI:
+    def __init__(self, target: str, context: FlowContext, mobile):
+        self.target = target
+        self._context = context
+        self._mobile = mobile
+
+    def tap(self):
+        self._context.add_command(TapCommand(self.target))
+        return self._mobile
+
+    def fill(self, value: str):
+        self._context.add_command(FillCommand(self.target, value))
+        return self._mobile
+
+    # Relational entry points
+    def below(self, anchor: str):
+        return RelationalAPI(anchor, "below", self._context, self._mobile)
+
+    def above(self, anchor: str):
+        return RelationalAPI(anchor, "above", self._context, self._mobile)
+
+    def left_of(self, anchor: str):
+        return RelationalAPI(anchor, "left_of", self._context, self._mobile)
+
+    def right_of(self, anchor: str):
+        return RelationalAPI(anchor, "right_of", self._context, self._mobile)
+
+class Mobile:
+    """Core Mobile API for the FlowPilot framework."""
+
+    def __init__(self):
+        self._context = FlowContext()
+        self._executor = RuntimeExecutor()
+        self.signature = SignatureAPI(self._context)
+
+    # App Lifecycle
+    def launch_app(self, package: str = None):
+        self._context.add_command(LaunchAppCommand(package=package))
+        return self
+
+    def close_app(self):
+        self._context.add_command(CloseAppCommand())
+        return self
+
+    def restart_app(self):
+        self._context.add_command(RestartAppCommand())
+        return self
+
+    # Relational Selectors (Maestro-style)
+    def below(self, anchor: str):
+        return RelationalAPI(anchor, "below", self._context, self)
+
+    def above(self, anchor: str):
+        return RelationalAPI(anchor, "above", self._context, self)
+
+    def left_of(self, anchor: str):
+        return RelationalAPI(anchor, "left_of", self._context, self)
+
+    def right_of(self, anchor: str):
+        return RelationalAPI(anchor, "right_of", self._context, self)
+
+    def navigate(self, url: str):
+        self._context.add_command(NavigateCommand(url))
+        return self
+
+    # Core Interactions
+    def tap(self, target: str):
+        """
+        Smart Tap: 
+        1. Checks visibility. 
+        2. Auto-scrolls if not found. 
+        3. Retries until timeout.
+        """
+        self._context.add_command(TapCommand(target))
+        return self
+
+    def fill(self, target: str, value: str):
+        """
+        Smart Fill:
+        1. Finds label. 
+        2. Calculates nearby input field. 
+        3. Clears and types safely.
+        """
+        self._context.add_command(FillCommand(target, value))
+        return self
+
+    def fill_focused(self, value: str):
+        """Types text into the currently focused/active input field."""
+        self._context.add_command(FillFocusedCommand(value))
+        return self
+
+    def back(self):
+        self._context.add_command(BackCommand())
+        return self
+
+    def home(self):
+        """Simulates the Home button press."""
+        self._context.add_command(HomeCommand())
+        return self
+
+    def hide_keyboard(self):
+        self._context.add_command(HideKeyboardCommand())
+        return self
+
+    def press_key(self, key: str):
+        self._context.add_command(PressKeyCommand(key))
+        return self
+
+    def clear(self, target: str):
+        self._context.add_command(ClearCommand(target))
+        return self
+
+    # Assertions / State Check
+    def visible(self, target: str):
+        self._context.add_command(VisibleCommand(target))
+        return self
+
+    def not_visible(self, target: str):
+        self._context.add_command(NotVisibleCommand(target))
+        return self
+
+    def contains_text(self, text: str):
+        self._context.add_command(ContainsTextCommand(text))
+        return self
+
+    # Gestures
+    def swipe(self, x1, y1, x2, y2, duration: int = 300):
+        self._context.add_command(SwipeCommand(x1, y1, x2, y2, duration))
+        return self
+
+    def open_notifications(self):
+        """Swipes top-to-bottom from the left/center to open notifications."""
+        self.swipe(200, 10, 200, 1000)
+        return self
+
+    def open_widgets(self):
+        """Swipes top-to-bottom from the right side to open widgets/control center."""
+        self.swipe(800, 10, 800, 1000)
+        return self
+
+    def open_quick_settings(self):
+        """Swipes top-to-bottom from the center to open quick settings/notifications."""
+        self.swipe(540, 10, 540, 1000)
+        return self
+
+    def swipe_right(self):
+        """Performs a left-to-right horizontal swipe."""
+        self.swipe(100, 1000, 900, 1000)
+        return self
+
+    def swipe_left(self):
+        """Performs a right-to-left horizontal swipe."""
+        self.swipe(900, 1000, 100, 1000)
+        return self
+
+    # Discovery
+    def get_screen_text(self) -> list[str]:
+        """
+        Retrieves all visible text strings from the current screen.
+        Forces execution of queued commands first.
+        """
+        self.execute()
+        return self._executor.adb.get_all_text()
+
+    def find_text(self, text: str) -> bool:
+        """Checks if a specific text is currently visible on screen."""
+        all_text = self.get_screen_text()
+        return any(text.lower() in t.lower() for t in all_text)
+
+    def list_elements(self, type: str = "button"):
+        """
+        Returns a list of visible elements of a certain type.
+        Used for discovery and smart assertions.
+        """
+        self.execute()
+        return self._executor.adb.get_all_text()
+
+    # Scrolling
+    def scroll_down(self):
+        self._context.add_command(ScrollCommand("down"))
+        return self
+
+    def scroll_up(self):
+        self._context.add_command(ScrollCommand("up"))
+        return self
+
+    # Waits
+    def wait_for(self, condition: str, timeout: int = 30):
+        self._context.add_command(WaitCommand(condition, timeout))
+        return self
+
+    # Media / Sensors
+    def capture_photo(self):
+        self._context.add_command(CapturePhotoCommand())
+        return self
+
+    def screenshot(self, name: str = None):
+        self._context.add_command(ScreenshotCommand(name))
+        return self
+
+    def visual_assert(self, baseline_name: str):
+        """
+        Smart Visual Assertion: 
+        Compares current screen with a previously saved baseline.
+        """
+        logger.info(f"Visual Assertion requested: {baseline_name}")
+        return self
+
+    # Fluent Smart Element APIs
+    def button(self, name: str) -> ElementAPI:
+        return ElementAPI(name, self._context, self)
+
+    def input(self, name: str) -> ElementAPI:
+        return ElementAPI(name, self._context, self)
+
+    def checkbox(self, name: str) -> ElementAPI:
+        return ElementAPI(name, self._context, self)
+
+    def dropdown(self, name: str) -> ElementAPI:
+        return ElementAPI(name, self._context, self)
+
+    # Execution (Internal or Implicit)
+    def execute(self):
+        """Forces the execution of the command queue."""
+        self._executor.execute(self._context)

flowpilot_mobile-1.1.8/flowpilot/cli/interactive.py

@@ -0,0 +1,76 @@
+import sys
+from rich.console import Console
+from rich.prompt import Prompt
+from flowpilot.api.mobile import Mobile
+from loguru import logger
+
+console = Console()
+
+class InteractiveSession:
+    """
+    A Live REPL for FlowPilot.
+    Executes commands on the mobile device line-by-line.
+    """
+
+    def __init__(self):
+        self.mobile = Mobile()
+        self.history = []
+
+    def start(self):
+        # Disable recording for interactive mode (Step Padding / User Request)
+        self.mobile._executor.config.record_video = False
+        
+        console.print("[bold magenta]📱 FlowPilot Interactive Session Started[/bold magenta]")
+        console.print("Type your commands (e.g., [cyan]tap(\"Settings\")[/cyan]) and press Enter.")
+        console.print("Type [bold red]exit[/bold red] to quit.\n")
+
+        # Start a persistent session (one recording, one initial reset)
+        self.mobile._executor.start_session()
+
+        while True:
+            try:
+                user_input = Prompt.ask("[bold green]flowpilot[/bold green]")
+                
+                if user_input.lower() in ["exit", "quit", "q"]:
+                    console.print("[yellow]Closing interactive session...[/yellow]")
+                    break
+
+                if not user_input.strip():
+                    continue
+
+                # Prepare the command execution
+                # We check if the method exists on mobile
+                method_name = user_input.split("(")[0].strip()
+                if not hasattr(self.mobile, method_name):
+                    console.print(f"[bold red]Error:[/bold red] '{method_name}' is not a valid FlowPilot command.")
+                    continue
+
+                console.print(f"[dim]Executing: {user_input}...[/dim]")
+                
+                # Execute the command
+                # We handle both fluent (returns Mobile) and non-fluent (returns value) calls
+                result = eval(f"self.mobile.{user_input}")
+                
+                # If it's a fluent method, we need to call .execute() manually 
+                # because the REPL is line-by-line.
+                from flowpilot.api.mobile import Mobile as MobileClass
+                if isinstance(result, MobileClass):
+                    result.execute()
+                else:
+                    # It was a discovery method like get_screen_text()
+                    console.print(f"[bold blue]Result:[/bold blue] {result}")
+                
+                self.history.append(user_input)
+                console.print("[bold green]✓ Done[/bold green]")
+
+            except Exception as e:
+                console.print(f"[bold red]Execution Error:[/bold red] {e}")
+
+        # Final cleanup (stop recording, final home reset)
+        self.mobile._executor.stop_session()
+        console.print("[bold magenta]Session Ended.[/bold magenta]")
+        
+        if self.history:
+            console.print(f"\n[bold blue]Summary of your session:[/bold blue]")
+            for i, cmd in enumerate(self.history, 1):
+                console.print(f"{i}. {cmd}")